diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb b/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb new file mode 100644 index 00000000..3c1ecd2a --- /dev/null +++ b/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb @@ -0,0 +1,96 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "url = \"https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv\"\n", + "weather = pd.read_csv(url,comment='#')\n", + "\n", + "# define the start and end time for the plot \n", + "start_date=pd.to_datetime('01/06/2021', dayfirst=True)\n", + "end_date=pd.to_datetime('01/10/2021', dayfirst=True)\n", + "\n", + "# The date format in the file is in a day-first format, which matplotlib does nto understand.\n", + "# so we need to convert it.\n", + "weather['Local time'] = pd.to_datetime(weather['Local time'], dayfirst=True)\n", + "# select the data\n", + "weather = weather[weather['Local time'].between(start_date,end_date)]\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, we have the data loaded, and adapted to our needs. So lets get plotting" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYUAAAEcCAYAAAAoSqjDAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAABtDElEQVR4nO2dd7gcVdnAf+/evSU9pBcggRCE0CHSpSNKERQbKkX9wM+GYPsQsWBFUSwgIgLSwYIoItKbhBJCS0JNgJBCSC83N7lt93x/zJzZs7Nnd2f7bHJ+z3Ofuzs7O/vu7Mx5z1vO+4pSCofD4XA4ABKNFsDhcDgc8cEpBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA4HA5HgFMKDkcDEZHJIqJEJNloWUpBRD4pIvc2Wg5H9XFKwWFFRDYYf2kR2WQ8/2Sj5SsHEVkgIkfV+TOnicgdIrJORDpF5CERObCeMlSKTXEppW5SSr23kXI5aoNTCg4rSqnB+g9YCJxgbLup0fKFqcdMu9TPEJEpwAxgDrAdMAG4HbhXRA6ovoR55RARcfe6IxLuQnGUhIgkROQ8EXldRFaJyF9EZIT/mp5RflpEFonIGhH5XxF5t4jMFpG1InKZcawzRGSGiFzmz6RfEZEjjdeHicjVIrJURJaIyI9EpCX03l+JyCrg+yIyRUQe9OVaKSI3ichwf/8bgG2Bf/nWzjdF5DARWRz6foE1ISLfF5G/iciNIrIeOKOQTBa+DzyhlPq2Umq1UqpTKfVb4AbgZ6F9PyMib/vH/bohz74iMktE1ovIMhG5xHhtfxF53D+vL4jIYcZrD4vIj0VkBrAR+IaIzAp913NF5A7/8XEi8pz/OYtE5PvGro/6/9f65+4A//w/ZhzrQBF52v8dnzatIV+WH/q/V6eI3Csio/zXOvzzu8r/Hk+LyNg859NRD5RS7s/9FfwDFgBH+Y+/AjwJbA20A38AbvFfmwwo4AqgA3gv0A38AxgDTASWA4f6+58B9APnAq3Ax4B1wAj/9dv94w/y3z8T+FzovV8GksAAYAfgaF+u0XiD2a9t38N/fhiwuMB3/T7QB5yEN4EaUEgmy3l7B/i0ZfvhQMo/nj5nt/jH3A1YYcjwBHCq/3gwsL//eCKwCjjWl+1o//lo//WH8Sy8XfzzMwzoBKYacjwNfNw4F7v5x9odWAacFPpdk8Z7zwAe8x+PANYAp/qfdYr/fKQhy+vAjv53fhi4yH/tc8C/gIFAC7APMLTR1/yW/OcsBUep/C/wbaXUYqVUD97A+eGQa+WHSqlupdS9QBee0liulFoC/BfYy9h3Od7A3aeU+jPwKnCcP1s8FjhHKdWllFoO/Ar4uPHet5VSlyql+pVSm5RS85VS9ymlepRSK4BLgEMr/L5PKKX+oZRKA0MjyGQyClhq2b4Ub/AdYWy70D/mHOBPeAMreEppBxEZpZTaoJR60t/+KeAupdRdSqm0Uuo+YJYvn+ZapdSL/vlZB/xTH1dEpgI7AXcAKKUeVkrN8Y81G09JRT13xwHzlFI3+J91C/AKcIKxz5+UUq8ppTYBfwH2NL7fSGAHpVRKKfWMUmp9xM911ACnFBylMgm43Tf11wIv4816TZN/mfF4k+X5YOP5EqWUWZXxLTzf+yQ862Gp8Vl/wJudaxaZgonIWBG51XfrrAduxBuYK8H8jCgymawExlu2jwfSeLNp2+focwDwWbwZ9iu+a+V4Q5aPaDl8WQ4OfV7W+QFuJqNsPgH8Qym1EUBE9hMvCL5CRNbhKf+o526CL7PJW3jWjOYd4/FGMtfADcA9wK2+++znItIa8XMdNcApBUepLALer5Qabvx1+FZAOUwUETGebwu87X9ODzDK+JyhSqldjH3DJX5/4m/bTSk1FG82LQX278JzWwDgxwZGh/Yx3xNFJpP7gY9Ytn8UzwLZaGzbxniszwFKqXlKqVPwFM/PgL+JyCBflhtCv8MgpdRFBb7vfcBoEdkTTzncbLx2M57VsI1SahieC1Cfu2KllN/GU1Im2wJFrwnfQrxQKTUNOBA4Hjit2PsctcMpBUepXAH8WEQmAYjIaBE5sYLjjQHOFpFWEfkIsDOeW2QpcC/wSxEZKl6Ae4qIFHJpDAE2AOtEZCLwjdDry4DtjeevAR1+kLUVuAAvHmGlDJkuBA70A74jRGSIiHwZb9D7v9C+3xGRgSKyC/Bp4M8AIvIpERntu6/W+vum8aygE0TkGBFp8QO2h4nI1gXk7wP+ClyM57q6z3h5CLBaKdUtIvviWRKaFf5nmufO5C5gRxH5hIgkReRjwDTgznyyaETkcBHZzVfI6/HcSeli73PUDqcUHKXyG7wZ5b0i0okXdN6vguM9BUzFc7X8GPiwUmqV/9ppQBvwEp6r5W/Y3TGaC4G98YLV/wb+Hnr9p8AFvrvl676f/QvAVXiz2i5gMYWJLJNSah6eS2cPvAD2UuBk4Bil1IzQ7o8A84EHgF/48RiA9wEvisgGvHP/cT9+sgg4ETgfb9BehKcEi93TNwNHAX9VSvUb278A/MD/Tb+L5/fX32Mj3m8zwz93+4e+5yq8Gf7X8ILd3wSOV0qtLCILwDi8c7gezxX5CJ5LydEgJNud63DUDxE5A/gfpdTBjZbF4XB4OEvB4XA4HAFOKTgcDocjwLmPHA6HwxHgLAWHw+FwBDRVud4wo0aNUpMnT260GA6Hw9FUPPPMMyuVUuE1OUCTK4XJkycza9as4js6HA6HI0BEwivQA5z7yOFwOBwBTik4HA6HI8ApBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA0HU++sYrnFq4pvqPD4SiZpl6n4Ngy+fiVXkfKBRcd12BJHI7ND2cpOBwOhyOg7krB7xA1U0ReEJEXReRCf/t2IvKUiMwXkT+LSFu9ZXM4HI4tnUZYCj3AEUqpPYA9gff5nZx+BvxKKbUDXkerzzZANofD4diiqbtSUB4b/Ket/p8CjsBrywdwHXBSvWVrVv40401+dOdLjRbD4XBsBjQkpuA3Gn8eWI7XPPx1YK3RM3YxMDHPe88SkVkiMmvFihV1kTfuXPivl7jqsTcbLYbD4dgMaIhSUEqllFJ7AlsD+wI7lfDeK5VS05VS00ePtlZ+dWyGvLWqixnzo/SBdzgcldDQlFSl1FoReQg4ABguIknfWtgaWNJI2Rzx4tCLHwZcGqrDUWsakX00WkSG+48HAEcDLwMPAR/2dzsd+Ge9ZXM4HI4tnUa4j8YDD4nIbOBp4D6l1J3A/wFfFZH5wEjg6gbI1nQ0e4/t+cs7uWvO0sj796fSweNX3+nkvpeW1UIsh2OLpe7uI6XUbGAvy/Y38OILjhJIGzohlVa0JKRxwpTBBy6bwcbeFG/85FgSEWTf2JcKHh/z60cB51JyOKqJW9Hc5PQZM+fe/nSBPePJxl5vkF/e2RNp//Wb+nK2Nbu15HDECacUmpyUYSr09KcK7BlPRg1uB2DJ2o2R9u/s7s/Z1tXbfN/b4YgrTik0Of0pUyk0n6XQnvQuwa6e3IF9fXcfk8/7N3+dtSjYtmZjb85+6yzWg8PhKA+nFJqUnv4Ui1ZvpC+dUQTdfc03Y25t8eIImyyyL169CYCrjYV5y9fnupnWbXRKweGoFk4pNCnf/Nts3vPzh+jqybhT+tPN51vXgXGbQhNL3HnZ+u6cbc3oNnM44opTCk3Kw696JT5MH3szBlyTCe8StCkF/XXMr2ULSKeb8Hs7HHHFKYUmRWdv9hrZR/98/m3e8/MHSTeRxaAthU2WYHF/OjdGsmpDrlIw4yq1ZPbitVmBfYdjc8QphSbFNphe+uB8Fq3eRFdvboZOXMnEFHIVgA6cKzIDsS37KFUHS+H5RWv5wGUz+P3D82v+WQ5HI3FKoUlJ+A73jZYZti1oG1dE8geabesubPtZDIqq8846L5Yxe/G62n+Yw9FAnFJoUrSlsNFiFdhcMXFFu2N6LIO9DiCbhoBNCdrcTNVGu+uc98ixudPQKqmO8tGWgk0B2HL+44pekd1niQtYLQXL961loHljb39gJdT6sxyOOOAshSYlYynY3EfNE1PQSsE22NoW4220fLdUDQ2FL938HEf88hHeWuWtuHZKwbG545RCkxIEmi1ulxffXl9vccpGr60opBTMV2yWQqqG7qMHX1kOwDv++gjnPnJs7jil0KRoH7ctpvDdf75YZ2k8+lNpPnj5DB55LXqb1D5/4LeletqsCJtlVEtLQbPBz3pqxrUgDkcpOKXQJOhBM51WKKWs2UeD2loA2G+7EfUXEFi7qY/nFq7l3D8/H/k9fYGlkPua/s6mwrAqhToM1Bv8lePNVprc4SgVpxSagDdXdjHl/Lv49+ylbH/+XXzr73Os6xR0sFZXHi2Xfz6/hLfXbir5fXps7iuhMJ9ummNbcJfJTCp8vHos1gtcWc5QcGzmOKXQBDz+utew/pHXPP/2rU8vsloKenVzJatue/vTfOXW5znwogcjv+eGJxZw5C8fzmQSpdOs29TH/OWdRd+rFZktpqC/R7F1F2bNp9/cP4+P/uGJyLJHpRrn1uFoBlxKahOgZ+0Thg8ItulicbaaQZVkyJRTXO47fgxDp5D2pRQf/v3jzFu+oWhXNK1Iwi6g9d19kZWCaSn86v7XShM+Ir3+eemtRwDD4WggzlJoAvS6g8HtuTq82+KqqUQp2NYLREWXoEilFfOWb4j4ebnuowdeXsbu37+XmW+uBop3lKtHTEHL0Izd7RyOUnBKoQnQVoGtNLZtJfDTC9Yw+bx/s2h1tG5mJpUMems35TbAKUQqrYIAs/nVdPbSCxFLStSjZLhWln3OUnBs5tRdKYjINiLykIi8JCIvishX/O3fF5ElIvK8/3dsvWWLK4KnFfotA5JtgZfuRPb0gtUlf1Y5SiHpB73XWJrdFErhNAdYc7avA8u6WF4xbIFm27mqBC2rsxQcmzuNsBT6ga8ppaYB+wNfFJFp/mu/Ukrt6f/d1QDZYkmikKVQYJAa0tFa8mf1pjKWR9Sc/Da/peZaS6vMQoFZ8/uk04rfPTSft9duotv33ycjKgXbZ9jcapWQiZc4peDYvKm7UlBKLVVKPes/7gReBibWW45mQruPzAFJb7O5jzRDOkrPIzCVjBlUfW1ZJ3OX2N05GaWQaynYFNmm3hSTz/s3f3z0jWDb/OUbuPieV/n8Tc8GlkLC1nqN3I5sKzf0MPm8f3P7c4uDbdVuTdrjYgqOLYSylYKITBGRdv/xYSJytogML/EYk4G9gKf8TV8Skdkico2IbJXnPWeJyCwRmbViRfSVs9Vk+fpuDrroQd5YES2YWim6vLQtX7+QpZCMsNDqV/e9xgX/mBM8Nwc9cw3Ee3/1KMdf+pj1GG0t3mW0xmIp2JSCXgj2mwfmBdu0wuvq6Q8yoPIN7K2J7Mv2jRVdAPz2gUyvg2orBa0ge+vU0MfhaBSVWAq3ASkR2QG4EtgGuDnqm0VksH+Mc5RS64HfA1OAPYGlwC9t71NKXamUmq6Umj569OgKxC+fu+YsZcnaTVz3+IK6fJ6eGdvSIQulkEaJv/7mgXnc+ORC7/j96azso+4ii8Y07a3eZbTOYin09ae54B9z+OusRcE2m7vHVEZakeT7/LBbSdclMvtVR5U9KpmYQvNUoHU4yqESpZBWSvUDHwQuVUp9Axgf5Y0i0oqnEG5SSv0dQCm1TCmVUkqlgT8C+1YgW02p+1zR/0CrpVBg8CulTs+cxevY8YL/8MDLy4JtOrX18fkrC763kKWwvLOHG59cyDf+NjvYZvPLd/lWiWAsWsvTFyJsAS1d563jGGy4y6puKRhrMByOzZlKFq/1icgpwOnACf62opFN8XwhVwMvK6UuMbaPV0ot9Z9+EJhbgWw14bzbZrNyQw8HThkFZNw6tUYPkjZLobtCS0Fzv68MHjMUgFYKr6/sKvjetqRXc8mWfbS6K6MolFLMemsNIwe15eynZ/kihb8vQGtL9lzGXjm18sHbzGoK1im4QLNjM6cSS+HTwAHAj5VSb4rIdsANEd53EHAqcEQo/fTnIjJHRGYDhwPnViBbTbj16UXc//Lyun+uHptMV1FQZ6jAzLUUS2GZ74IZYQzY+u260F6+FNF2P9CsU2FNzIykO154m49c8QR/fWZxzn5ZmUhF5A67j/RAbVpN1VjQ1pfOdWml0ipQON19Kc798/NZTXgcjmanbEtBKfUScLbx/E3gZxHe9xhgG11cCmoe9CBp+t2jTISL7WPOhPVqZDPjR4+rxWbd2ptjcx+tNrYtXuO5eQr1exCk6OclQ4FmrRjNMuKVWgr3vvgOA9vst0dfKk1LooX7XlrG7c8tobc/ze8+uXdFn+dwxIWylYKIvInFva6U2r4iiRw5BNVCDaUQpbFMsRm36QrRfY7NOkP6/fYGOClueWohB+0wKphF21JSzW3aotjQnbufRqS4iyZssejzYxYH7C/i++/pT/Hoays5aucxVjfgWTc8k/e9vak0Ha0tgRxu7YJjc6KSmMJ043EH8BGgMYX8a8zKDT0M9F0oUP9Asx6Us5VCcSmKKQVzMNODqOmf1+/Xu5mH+91Dr/NbP6V05/FD836G6VJqb/XOYaEe0qm0Klq2Itli93r2ZFlShY/xpZuf476XlnHfuYcwdeyQgvuG0aXBtcVSjzIbDke9qMR9tCq06dci8gzw3cpEih/Tf3Q/O4wZHDzXvvo6xZnLVgqFxkWlVJY7Ss+yTReMfrv2z5uHW2MEkAuVlDCP1+4P5ht6srvFtSUTgSy2Jjphoqy/KDZQP+rXVyq0ziMf2pJJOkvBsRlSifvIdKIm8CyHzbYU93xL1U+xhkaqT5CN019aIDXfbHnhqo0ccvFD/PRDuwXb9OBtWgpa+enYgxm4HjesI3hcaAA2B3kdKO8KtRBtN5RCZ3dfsEI6H8VeN2XOR6He0MUUbl+/97qOvxRzVTkczUQlg7i5uKwfWAB8tCJpHFb0GGUunErlGYhaEplAbb6x7YXFawG41FhRrAPNZkzh7bXdjBzUbh0kTXfayg09eWU3lYzuuxA+XnuyhU68z1/f3c+A1hYKUQ1LQctg28/W99pE14fScZj+CPEdh6NZqMR9dHg1BXHkJ20JNJuDWUIyCqAjmQgWginl9XPuS6ms2bVOPzV982t937+pFE67ZiZtLQm++b535chkWi1aodgo1iAHMgHoqO8JZx/ZiBKIB7tFUcyF1duvy2hn/3c4NgdKVgoi8iml1I0i8lXb6+aCtM0V7XGIElO4/6VlbD96ENuPHlx85zykrCmpmYGoLZkIyjq0t7YESiGt4Cd3vcwf//smr//kWOYuWUdnd3/Qp6CjNTO46sVj4fIQval0MKs2h76ofvQoMYL21tKWy0SpnhrVzW+zgrp6ilkK2RVTnaXg2Jwox1IY5P8vLWWjSSllAZiN/7l+FkDRtpSFyCxes1sKrS0ZpdBhzLqVUtz0lFfXqLO7jxN/NwOAHcd6CspUAIUCrrb4RdRqobYBNjw7b08WdhdpWluEvpTKm31kEnWgtimFfJZKW0uC3lQ6owx0f2mnExybESUrBaXUH/z/F1ZfnPhRKOhYbL5aqULRpG2BZsNl0Z5M0KkfG/74tIKO1hY29qaConGQSQmNWh8oE2j2Zscbe1KRq4XaLIWwAgq7j/KRTCToS6VojRBTiNqS1Kbw8hXTa096SsGVvHBszlRSOvvnIjJURFpF5AERWSEin6qmcHHA5i9WEVcqVGvQyCxeMzN5Msc2awGZA2xaqSBo+/SCNcF2nf0TVSmYX+N7d7zIHj+4t6iLRRNOP4Xc4G5kpeC7jaK4j6JmBNmUfr4eFdrN1RuyFOIWUXj0tRVByq3DUSqV1D56r1/y+ni8zKMdgG9UQ6g40VfAN1AsprCxwCKtUsisLM5sMxWOGUTuyLIUVDCQvfZOZ7B9gx8YjtqdzJxN6yqqs95aY903nC4aRXl0FMk20mjlZ7qP2vK4kiJbCtaubXmUgu/minsXttOumclp18xstBiOJqUSpaBdT8cBf1VKReuy3mTYZpzFxptnF67hhEsfY2YZPZJtFBvgzIHRDB4rRWApmGmj/RZ3VMHPNwbOYQO8Qrjv+OWqwwxqyx7gowSaB7VHUwo6FdV0H+WzMkxrpKunP2/arFUpFHAfAcxdso6P/uEJOv1yHdVyE67p6uWDl89g0eqNZR+jWrI4tlwqUQp3isgrwD7AAyIyGtjsykXaVusWu+3+M2cpc5as4/6XlhXZMxrFFlNlu4+yLQU9C1+1IbdYXeTPNwaaoM6RpSIqwKD20nMXJg4fEGk/rRRajJTUfJlL5jk75tePMv1H91v3syncfG41bQVd+uB8Zr65Oq+1VC53zn6b5xau5YpHXi/7GKa7zikIRzmUrRSUUucBBwLTlVJ9QBdwYrUEiwu2uIAecPL1U9D+/nJKKNgoVtEi231kxhTslkLJn28IEPjR88g0uAylsPVWAyPtp91GZpw5X+aSqRR0dVYbtsVreS2FkJsraiwkKvq7VHLdmDGwKFaawxGmnHUKH7JsM5/+vRKB4obNfVTMl6zr+q8vUA20FEpxH5mD5Nf/+gJ7bjMcqEwp9GcphcLffUBbNFeQyTYj8lsKOg0UMgFms7x3voE5aulsu/soX0wh+7N0sb/wzzN3yTp2mTC05CZM2uqppGuc+X16+9MMai/7UI4tlHLWKZxQ4DXF5qYULIFmrRTy3fI6S2hDgZW+pVBsgMtnKQA8v2gt4JWPKJesaqpFex2UXg9q6pj8S16SLYKe8Lb6biNzQXN49q6JqhTSSrGpN5WlzPLN1MNKYaXvkjPPzwuL1nLi72bwjWPexRcP3yGSDBqt3CuxFMwJRKEkCYcjH+WsU/h0LQSJK7aU1GIB2g1+1lHYv1vqzPGuOUuZNn5oUUvBHNDyNYapBHPQK5ZN1GJRCmYVVBtbbzWA0w6YxOD2JJc/nO1PN4+XSUXNbMtXHK+Q8jJ97W+t2sjO372bn35oN07Zd1sgvyUYdlVp68t0Mep033tefKdkpdAfpB6XP5ib37saLUkdWx6VrFMYKyJXi8h//OfTROSz1RMtHtjcR8WUwqY+b2AwawKVc6N/4aZnOfKSR4qumDVnsFEzeUrBlL2riJ/aphSKFbgTEX5w4q7sM2mrnNfMILq2QrJjCvndR/OXd7J4TW4mjzlWLvD7T//juSXBtnxKIWyF6QZC5v5a35QT2NfXVT4X3RdvepbPXPu09TWlFI+/vtIa/3E4SqGSSNm1wD3ABP/5a8A5FcoTO2yBZj1I5pvB69LKnUZMIWrQL5VWrDL8/6m0Klom23TZ1MZSiD64mJlBehY/MGKcIWFRKOZ3aw0CzYalkGedQldvP0dd8iifuuqprO0rOnuyZtBaXtOPn2/RYTIh2Lxj5vnRx0kkvHLrZ9/yHOs29vH5G58p2stZf24+g/Lfc5by4Cv2HuF/f3YJn/jjU/x11qJgm2v+4yiHSpTCKKXUX4A0gFKqH2jKdIcn31jFvS++Y33NNmvTN2++mKt+vdNwtURdAfy7h+azz4/uZ3lnZgAppRNZtTNiINNpLArJhARrFYZ2eGsaoioFWzwiy1JoybUUbIoEMhlHC1ZlLIXl67t594/v55L7Xgu2aavOrHeklXqYhEiWPJn9M+dHZy61iHDm9bO444W3ueyhefxn7jtcfM+r1uNqtKVQTp+ON32LZ6GxxiFqpViHw6SSEaRLREbip+2LyP5AUy5g+/iVT+btyWsbkINCaPksBV8pmC9HKSENMNuvYDpj/krj8wrf3MkIi7nClBLeKGXlbkKE+792KM9ccBSDfVdWVOulxSKUWdJC+/TN2Ey+wLYtyK9jPOY6AB3/MS25vN9X7DEM07IILAWRYKDW7rNiZU8CpVDkt3n1nU4mn/dvnluYWSehr1PTinIlvR3lUIlS+CpwBzBFRGYA1wNfLvYmEdlGRB4SkZdE5EUR+Yq/fYSI3Cci8/z/uQ7mOvLi29mrVk36Aksh+6bTg4DNlxs1zXDsUC+HcHVX5nOL+YbNgSp6xdHoP30pNZySCWH8sAGMHNweLGQbO7SD1hZhu1GDGDW4Le97bbN+M0ahffrmwJfIM4Laai7ZlLi24FYb7UXzKYWEiFXpmvvrEhlZ38WXsZjFle88L1vfnWVp/neeV9fon8+/HWyzTRziFmhesnZTVv0uRzypZPHas8CheAvYPgfsopSaHeGt/cDXlFLTgP2BL4rINOA84AGl1FTgAf95XTEH7h/86yVmvrmaJ9/ILVWhB4H/zM24nJ54fRWH/+Jh/vbMYuugctecd/j37KVFZdCDtSlLsdRCXXoCorWqhPy+eBtRymHosdkcxLVSGDmojbkXHsODXzuUySMH2d6e81792LYGwxxv830Nm6VgmznrwXZjb4rH5q3kpqfeyjvDFuxKN60yA7DpPgoT1VIIs99PHuB0o5aRPq9mhzibRRun2kw9/SkOuuhBvvm3KEOEo5GUrBRE5FMicip4cQSl1ItKqbnAx0XkE8Xer5Ra6isUlFKdwMvARLzV0Nf5u10HnFSqbJVizhaHdHg33jpLOQc9aJjtMXUM4Hv/nGu9+a945HW+ePOzeT978nn/5pt/eyFwh2Td8EUsBVMpRCWq8oBomVN6DUGWUvBjCW3JBO3JFkQkbwwAsmf9+jjmOoTAUrAojzDW6qyW82ju96mrn+Lbt8/l9RXZ/bi1WAmRnAwkjR6AtTI3dYKuulpMufZaLFC9ANIsqaFjNF1GwUVtBZmutafeXM3k8/4drFVpJFpJu+qt8accS+HLwO2W7X8HvlbKgURkMrAX8BQwVimlp9LvAGPzvOcsEZklIrNWrKjuBWaa6Ho2ZgZ8NWbMoLc/zezFaxnqD8xdvamig/iarl4WrspNlfzLrMVB0Nic6RaLKQw1lEJUN1VrhPLTpRxTD85Ji6VguqoKrW3LyjTyHw9ozbUURGCncUP4yD5bB9lD4e9jc/vp3som5m8+xJc3PIgGqbCJ3IquegzWA3omLpCRRyueYpZC0DfauH50cTyz0KA+9oaefr59+xy+9fc5wUTFVEY6ecKMTzUKnZ5dLD3Z0XjKUQqtSqkN4Y1KqS4g8pRVRAYDtwHn+CW4zWMp8tSdU0pdqZSarpSaPnr06NIkL4KZg6/dz+s32dwQmSYrn73uaT5w2QxWrO/Jed1GT3+Kw37xMIdc/BDg3djmYirdq8HMXOor4hs2LYVCAW1beqeNsGspiqWQGTgzn6HrILUm88cAzKfZC9U8GcxBRPvzBeHucw7h4o/sgdYFYZltloLte5h1jnbbepjlm5k9oSVHKQzyg+g6XqAHdvMa0EHsYpaCfq+pPPT1N6Qj8xvr4yjgpqcWcsvMhUGmkRk20d83X9ylnmilELVMuqNxlKMUBohIjmNYRIYA+aOI2fu24imEm5RSuizGMhEZ778+HrAnZNeQjcZAogdXW2As07A9zX/nebOwFcbagkIzwg3d/YFLav7yTnb93j38ddbi4HXdUc2cwRazFEylMKFAxVHzhiwUUwg3senuS+WUxA7T0pJrKeiso3bjs8LunnxBY30cc7W2lt9scqSVUGvIHWbTo7ZB2ZY5FMZcNBd2H+nFgvqa0GtKTKUQWAoRlUKfRSbzN9HHMX+mzGro3EZM5ZQeqTbacnNKIf6UoxSuBv4mIpP0Bt8NdKv/WkHEs32vBl5WSl1ivHQHcLr/+HTgn2XIVhFdvSmO+dWj/PSul9nUq5VC/tpH5sCzdmMmHlHIfWQOQnf7gWqz74K+uU1/cSkxhfdOG8vNZ+5n3c8c0Ap1LwtbEd19qaIlsW2WgsZ8r3Z9tFrWHNhKWnQkcy0F83wEPRYiBM5tg7Lpv8+3wFDLIpItDxiWQigeYH5WVwXuIz05MZW4HvjN8xUOdJv7mUp0eWc3LzQgxrA+sBTsv9Pxl/6Xb/19Tj1FcuShZKWglPoF3oD9qIisEpFVwCPAnUqpiyMc4iDgVOAIEXne/zsWuAg4WkTmAUf5z+tCixHcfXVZJ3949I3ghrINJDb30JqNfQVfD14zFka9scJLYR01OFPKUgcMN2S5jzLHs3kChg1o5Y4vHcRtnz8QEeHdk0dYP9ucdetB1Aw46zEm7J/v7ktblYItWyiZNVClsz4LMrNb25qDLKVgCVzrWaZpOdmylPJNjIsNynktBWMldXimO7A9ew2CbbbfVcR9lE4rb6W1xcooZCmYlpXNUtD7mROM826bw4m/m1F0dXW10d+pL6X4/I3P8EYomD93yXpumbmw6p+rlGL5+s2uzUtNKasmglLqCuAK32Wks4iivvcx8hcYPbIceSqlrSXBpnQqeyBO6ZlX7kBhm7lnWQoFYgBmsPNtv3uZmeGUsRSys49E8vcwGDagNcttFPYhtycT9PSnGdia+bn1QN3ekilW19ri7ZdMhCyF/pS1plJLQoJBUL/HNlCZA5p+vaM1wYae7MHcZilklcn2Z5lmjEW/biq3ZIu9AF8x900+S6E1kZElvE5BxzyiWAr5Jgu/eWAev3lgHkfsNMZ7r7GfthTM8iH62KYVq92O5jZtNZjXks6smr98A+OGdVjlqQV6sjNnyTrmLFnH0nXd/OOLB9X8c391/zx++8A8Zp5/JGOG1u/7NjMV1URQSnWWohDiih5slq0zS0vk3nga24zTtBQK0WtYClq5rDeUgr65zc/oT6tg8LFp03AZifBMeZAl4KsHUXPA1gO0uR94ysi2KtnMxU9aYgp6gDQHe20ZaEvBnHknsyyFTMaPRiuylNV9lPs9whQtZGgoBfN4ZhmRsMLXCxa1BagHP/P307GqfJaIdiPqqqtZ7iNfJlOe3mDWbV4j/vVqfIbNBaqvI1sgvpboa0HHpvRCtrvn2svLVIvbnvHidfX+vs1M9QvlNCF6EHnbVAqWmZfGNuMzLYVCmIOFPs7aTZn3Bi6E0OfaUvku/+Te3HzmfjklucPPtdLIKlbXkuue0cHa1kTuZWEGmvVbkhb3UYsxeH1gD69W4v7bjzT28/5rRZwvzqEVgK2khelO0zGMbEvBbogWcx9tNAZUU7EkDUtBy3X2EV5Z7PfvOj7r2P2B+ygzsOsByXTj2OTSVo+5RiWz7iHznWyDvf4Mc5tNebQ3WCloK29FZw8X/ecV/vfGZ5j5Zu4C0WpRSXOpLRWnFMj46U0/a28oxdBk2frcC21tREsh21/sPTbdR7a0RMjMqM3BYdywDg6cMqroZ+pgqDmI60F0pVHiuVDQ1owp6NdNBRAsXjPkO3CHUSy46DimjB4cbAvcPS1aKZiWQq4rybR6RgzyktvMstQtkitzvqBz1OwfsCsZEThkR+98H7LjaBZcdBzH7uYphSD5wD+GLYDdm0pbs9nCcq3v7g+26WvEjKPo68U8lr7+rJatsU1ngkUt0FgttAVlfo/X/ZhaLWXpKXAfO+xUVGdZRA4EJpvHUUpdX6FMdUdbBSs6M4N9qf0P8jWyD2PeoNpfbCoUm08a7FkbhVINj542lvteWgZkgqHmgD3csgq6NY/7yPv87HTWnv501vESlkCzjXC8w/xeNpeNub/u5Wz2SNCKyZzZt+aRoZQaTllKIYiXwIl7TmTf7UYwftiArP30jN42+Jgup66eVE6pDNuMfnVXL+OGdQTXiOl6WuNbpWamUWZbrtLpybIU/MWRdbcUvP/m6ekzYlm1xhUHjE4lTXZuAH4BHAy82/+bXiW56oq+ac21BqUW7oo6E7Hlxa+3WArhi7jDElMotCjp0lP2Ch7rhU8tFkvBJIgzWNxHNivDln5arHyGfo8+52aKZ5Yry3DZfO3oHZk8ciCTRw1EhKyOZi15As02/masBymGebzWwFLw/muFABm33hl/eppl67uLXgf2mkzZq6Eh4/bIKAVTAeRaCmv8Aoo2pdDbn2buknVZ+3dWqVVsVGw9QcK9t2uJra2uw04llsJ0YJpSRTrANAH6RjZrH22K2BSnVGyWgrmSWl+84bhFxn2U2VboZjKzZIb6dZzMsV4f58tH7MClD873jmcJ2mpMy0nP7ExFoR8VVQr+jpNGDGT+8g2csMeE4DWbC0gEvnzkVL585FQA3vzpcVnHa7G4vPKV8HjDDwpHISumYMgSxrR0Hnl1RdGGSLc+vZAJwwdw8t5bc8E/5nL+sTsF14St7Wm3xVLQ16mpKPQAa7Nwl63v5vhLH+PEPScEn9HTn+KWmQtpa0lw8j5bF5S5uy+FSPQKvDbSFmVpU4a1wlkK0alEKcwFxgHFS3/GHNssoljbyXIxb4Cevlx/px4XwlkuepDyGrDoNND8SsGMPWhLwZZKa1obgfvIMtM2ByXtXrIVsCvmCtAz+0kjBzH3wmOyAtimpaDdHLZqo1nHs7itquGOyFpbkcj9vpoBIfmLWQq6B3V7MsFtzy4mIRhKIfPeniCmkNvvYaXv5rS6iiwDrHYVPfjycnYcNwTwrgW9WMymFLr7Ulz/xAI+fdB27PSduxkzpJ2Z3z6q4HcrhO286O8dtSthJRSrCuDIUMndMwp4SUTuEZE79F+1BKsn9exla8sOMcnXLcs2A49a02bogKR/7Mz3/Mj0bdhqYCsf2ntisE3PsE33ywF+5pD5+VpBZa0/sGQB2dDvaW0RBrcn8zbMaS/gojLRSsOWuVQJ7Zbva5PEzApLtkjexkthdOB+fXefsfAsHVgj+jrRFqtZ06rTkmmksQ2+2uro7OkPZufF3Ck3PvkWP7nrFa57fAEAyzsry+KxyaVlMbOtaoVrTRqdSiyF71dLiEailKrrBVOs4mi+AHcw2JruI4vv38aIgV7WTn9a0Zb0FnZtN3IQz333vVn7BaucjQH2tAMm8cQbq/jU/pOCpi5B9pGZkmpJU7Wh1zvYBm5TQZgVUQuRsMzi87nV9HePQpYS1ArKIkw4eyrqBEOXZjd9+739KQa1JdnQ0x/4/00XUZio38VMhdXXn7leZvbitey+9fCs92il9dLbWbUqy8bmVtObamWVm8Spt0TcKVspKKUeqaYgjaLWEZFkQrKUTjGlsN5S8hnsM/CWiAE6ncrZn05z91few9+eWczwgbnZR7pm/wNGc/h9Jm3F/B+/P8t60LK0WNxHxdAz8GKzeVuXNRtJi1KwrbOA0nzX9kBz7n7todTVfJbC4PZkVsaPPl+mUuhLKYZ0ePtpZRC1jWshzM/VmW7rjLUx85ZtyFEK2gLqqtIs3mYp6HO1qYaWQkKymyA5ilOynS0ij/n/O0VkvfHXKSLVmVbUkSiXStQBz0Z41losgG0r1Q2Z/HLzaMX87d96/0588fApwYKl/pRi+9GD+eb7dspZ4GZijmsikpPNY7MU9KBcTMlqBTmgrfClZ+uyZsMWU6hGNkurNdCce1xzmyow+ITLhOjZu7lwsS+VDhYaZiyFVM6K9Sh85qDtrNv19fegofhtbsygEmuVKqzaAs16S75FfdVAy+8CzdEppyDewf7/IUqpocbfEKXU0OqLWDu+9pcXuOaxN4vuZxt8ozapCbt4is381uRZGW2zFIoNfp87dArfOGanYDYbdbZkprPaBoVM7MGiFIocWwf8ilkKZu+EQujPNQfnUrrK5cO+ornwe/rTafKNPYNCZUL0AjRzIV5/WgXuNZ2EsLqrl10mlH5bTRo50Lpdz/yz1gsYSmFFZw+ru3qDtQ1hS+1jf3giUlvZMIXcR7WMKejrwqWkRmeLXtF827OL+fFdLxfdz5bKGTU9LzyoFlMK+fLHbX7tqF2sgpLTEZWCuQLZrhDzu4+KWQq9/qhZVCn47iNVRM1oxWTuFy5al49CPSXM/gz6exZTUN+/48WsFq0mOoagWeZX7gxn3miL4qf/eZln3lrD8s4e9pk0ouDn2shnXRTrM/HuH9/P3j+8L9hmWmB9qTRPvbm6YFvZfNgshcB9VKGLLJVW1uNDRpGHu9n99K6X875nS2eLVgpRMWf72l8ddeAJB16jtssMo2eQps86asMSvV9Un7o5gInxNW/7/AF8dPrWwazXzAzSj4sN4npWWmhA9l73XV5FblxbzKEtosK2WXv6dzUbAyWKWArfev9OgFcy5Mk3Vlu/m9k5DeDttZusx+oIqq4qTv7944AX1ymVUtw+hUpjmL/xxgrcPIUshULB9ChMOf8uTv/TzKxtj7y2gvnLO4Prw7SGvnLrc/zh0Td4aWnTebvrglMKETDvLz0zjeqiKDWmkI+t/MCweQNHvfFHDfYCzflcU2GGGgOYaQ3sM2kEP//wHlY/vv6axSZfn9hvWwAOnlq4ZpNeC1FsNmc7BzaFbTtVtpXPet1BtmvM+58vDHPinhOznrdbSpLotGBNPqVgy97acexgy56FiZIFNaDAZCFo5GP2mvbdPMUUug1b8o9e92pOlMpdC6s7IGpOv2YmR13yaKAUzMmFji+4NFU7FSkFEZkkIkf5jwfo/grNQCnZCNnNX7zH0S2F0mIK+dhqYKROp1bG+WUZ8i0SuuXM/bnlzP2D56alYHNR6XHCnKUfsfNYAPYMZbGE2XvbrVhw0XEF24ZCZuApduMGv42xm01h29xVmcV6RjzCUnNJf0a+4HxY8dvO2ZD2bEshX3C1JXS9tCcTQc0nk2IDczGLDTxXVWuLFAw0m6d/nZ+5VE4g35aVlakoa1YOrnygNhWL/snMxWva+nEZSXbKTkkVkTOBs4ARwBRga+AKGtQop1RKceOYN2rQnKaIi0Kvbg3PZMs1lcM+6VIY7Oec7zrRHrA8YIq3QO2WM/fn2YVrrG4hk8BSMAaHY3YZy8l7T7T2XSgH/fsUO89W95FRhkMPPG1+o6Hs/STYvy+l+xbkZhplgtl2GcIpsOYq50FtLXT1pnJ+v748gc/wWD9l9GCrNTS4I5lVliXM8btP4Nm31tKWTHDDk29Z9xnQ1sLG3lSgAMyBM1MlOLNNp0uX0/PZNgDbij/2p9O0lTBXtR13vRGX07JmWdi++PUor9GMVHIHfxHYF3gKQCk1T0TGVEWqOlDKjN28UfVAaHMRZL/HUwrhG6hcSyGRyAxM5VjYD339sGC9Qj4OmDIyUBAFZdGriI3BMCFSNYUAsMof8EYWkVlbBeZNr624jtaWIEffNrPW7qPWZAJ6U1nvtfWOzrdmIjxzNov8DfCVwtBQVdp87p2wApiax3U0flhHQaUwsK2Fn314dy5/eH7efQa0ttCWTAQzddN6eWaht2bFtNRe8X3w5WR3FVrRbFoHff0KSjCKbfeT2dtEK3mb27UeK6mbkUrcRz1KqeDsi0iSaGn/saAUSyFrtWzEQLNWBrmWQvbnRvXPJkS46X/246GvHRZp/zDbjRrEMEu57HLIZGBlZK9ONru3ghoyN/GYoe2Fdg9iLeYAmbHmchfcmbQalkJ4P3P8179/vgly2DXVYVoKvpU2ONTjOl/zl7Di2WG0XSlsvVV+95tIxtIpdH0NH9hGm9G6tLMns3DytXe8hormYP7IayuA7J7iUbG5j/RvnNV4qsTUUdvAbvYn0fehed9lmhnVfiV1M1LJ1O4RETkfGCAiRwNfAP5VHbFqT7lKIcjRL1JiQgfoclJSQxfi0AHJrEY3+WWAg3Yo3lCnWvzuE3vn9R3r72ZmP0Wtw1SMCz+wCxd+YBdWd/UypD0ZNLHJh461rLHMDos13tGuqWIlLQL3UR7VF85iGmIoAO02GtDm+e/1rHjpOnsz+fB53Da03mCvbYfz3MK1WXGGcPkOMzhcaFY/fdJWvL12U/BeW48F01LQE/rRQ0pXCtaCeJYqqaXWITMzopat7+ampxZykGHtpizBbH1PbupN8ezCNbz2Ticf33fbkj53c6YSpfB/wP8Ac4DPAXcBVxV7k4hcAxwPLFdK7epv+z5wJrDC3+18pdRdFchWlHJ9+0HzF+NeM292TYtlgddA34drMnJQe0SlkDnOC999b9ESzZVy3O75B+NEoBQSOdsqRc9wRw5u51vH7lx0/7F+M/aJwwfwij+7zVRxzexnSz/Vvn9bsb/sQLP3P18Ji3AA2rQK9ORhcHuSViN2kY+wNTIu1Gz+L587gLfXbuK2Z5cE24YPaGV5Z0+gHMw4UCFLYfLIQbQlE7y+sosnXl+Vda3q60s3agKzblLp947t3OlN2YHm0o5tuo++cutzPPnG6qw1GtpqsN3v3f0pPnS5l/brlEKGstxHItICvKyU+qNS6iNKqQ/7j6OMVNcC77Ns/5VSak//r6YKAXKzWgqld5oKwFprx3LjtVj87kM7WukM1TYaOTiaA9Ucd4YNbC0aH6gl+iuZKZ1S1pVUOaOHtHPjZ/fjko/tGWxrswSLbb+RzhIq6j7S2SoFLu+9th0ePB5sBJW1i2TU4PZIGWRh5TpumKcUPrjXRLYdMZDWlgSTRg7K6i6nj6sHQ1tDJBsD2loY2NbCC4vWcsofn8xqAGSbsdvcPVEplOlTiVIw91+02kvzNSdeWhmYloKtkdVm0BamapR1KyulUsCrIlKyelVKPQqsLudzq0m4RHXB3gQUHlysSsESUxg7tD0rMwKi+2erNROvBmZ7Sk0j5Tt46qiseImtNpMtBqTdX+ZrrTZLQYqvmbjpf/YLHps9Inr8wWjEoLZoE4DQaZzop+7+6mN78ug3Dw+2mwp5mB9XGdia23bVphT0MaeOHZyVHNBpuI9sqcA9FVgKhcZ6c3DuT6uSjp/V6tSPL9jiNd3GMbX1YGZbVbqAbnOikvndVsCLIvJAlfopfElEZovINSKSdwmniJwlIrNEZNaKFSvy7VaUsLsnMxjk7mtbvGaLM5jYGs+PCbkCwG4p2GSoVmGyahDMpo0RLA7iTfBn1bbf0mop2NxHRvaRjgfoc18orX1gWzIIercbsZZdJg4DPKUQZQJgXlffPnbnvK1FzWtuvP+9g0G9yPc+Zd9tePrbR7HTuKFZrq7Zi9YWlC2wFCIM2nfOfpul6zIL9Ar1mTCPd+vMRex4wX9YtHpj3v1NTAtEZ32ttPR+0JZCfyoduBlNhbLzd+/mb89Eb9e6OVOJUvgOXmzgB8Avjb9y+D3eWoc98Tq55T2OUupKpdR0pdT00aNHl/lxueZxMogB2FbDGgogketesPYXsCx4sqVX2gYKe6+B3O/QKNosaZtxsGTu+sp7+PfZBwcDZsIyYzZdRQP8mIhNKYgID339MO4555DMqtgiro1tRnjBX9Py+NnJu3H7Fw5k9JB2timQMaRJCJxx4GT23nY4Zx6yfd79zGtkz22GA5kB0rRorM2ZEhIEi03/+1VFikMGMQXjPMxdso4p59+VtUK7pz/Fl25+jk9e9RQAb6zYwO3PLSEfpgvoz08vBGBhRKVg3sf6u9gshaCFaVbnw+z4ztf/+gILSmjZurkSi34KSqkgmiUifwTurNax8xGumqhdItZy1BZLwZw1mj2L9Y1pq6wZTksEu6JobcldaBWHQVdjW+AVB4YPbGP4wLZglmnOToMGQslEMKhZYwpGP+ZRg9sZNbidmW+uAmBFkYQA7dtva0lwxaf2ZurYIQxsS7LXtp7he+AOo7juCftCMk1ChO9/YJei39UMCn90+jYkRFi/qY9f3vda1gy4vUC8C6LXzwK7pXDr0wtJpRX3v7yM0w6YDGTWO7zjZ1j9o4BCgGwl0xVaL1IM01IY6BcTXLY+Vyk889YaNvb2ZykCM3XVJku9+cldL3PUzmPZd7sRDZMBKrAUQv0UukUkVW4/BRExU10+iNf/uaaELYXM7DJ3X3NAfm2ZZ3o++lrGdZW05LvbOoLpomhmUHKQRVHYXEVxUgqZqqul12GqB3qhmOki1JlS5mCjB8Tsjm+5rjGd/rl4TeHZq65w2t6a4H27js+qNgtw1M5j8/Y50ERVtNn9HoTTD5wcNE5KFbEUzN+qlFIPZvbRg68sY+abq4Pr16zuq9t/Fur5bdJncUdFLXdhrmvQSv5t322l70ftBtzQ3Z816NuUQiO58tE3+Ogfnmi0GOUrBbOfAjAAOBm4vNj7ROQW4AngXSKyWEQ+C/xcROaIyGzgcODccuWKSo6lYHE5BDIbj4+z5M3ri89abtl484hB3k07PCsomvt5tm0xGnMzdYlSuTPxOKDrDJm/sV6TYFMKJrZBdN/tRrDdqEGcfeTUgp+rg7b50kBbEsJ3T5hWMCMo6u9sXiP6mm0LlLVdKWhL1aYEo2Aqhc9cO4uP/uEJBvvfucsIUmsF0dqS4OWl65m5wMsrue3zBwb7mPeFTQF05ylBHiYVClJDJtVVTw50gccuo6QHZJTCZw/OKOpGte2MUxnvqtQl8FNR/yEi3wPOK7LvKZbNV1dDjlIIZ1cE9WuKWArH7T4hxwVguo80ZmmE+849hPXd/cxf7lkZ5ie3JBLcetb+tLYkglLJZuaSnsnFyVWjB5q4drPSmUjeIO25EoKS2IYi0IFmZXEzmdsGtSd56OuHRf7cYr9VoYE/qkVoKuGWkFLIt9+wAa1s6OnHnHOcsu+23Pr0IqaOGcy85RsKfqa+ZXqMgXNge65SyJQWEd7/m/8CsMuEoUFAHPT6HO+3sblswv7+fJj3cfYkRYIYw2BDRlMJrvWVghnXy9cjvdbEqWJrJQXxPmQ8TQDTAfsyzRiS6z7SboMMuqCaeZ/aJoHaysi6UY1A89SxXvFYPRjst91IHn51RXC8/bcfGVqan3F16JzrOFkK+nv2p9Nc9om9Ijf7qRfbjBjA147ekeP3mMDhv3gYyFhx5qCg5TbvRz2wFsqWyccn9tuW9Zv6OHLnwiXACg38UX/nrLpTCe2+LGz5jB/WwZK1m7LcR3tsM5w3f3oszy9aywf9hVzFMGfTWsH0GSdxvX8tm5bzhOEDslylxToXdvelue2ZxUwYPqBgPS7T/WXK1ZFsCVyG2n3kKa6MDPOXeUpw6piMm6+nQampcarYWomlcILxuB9YAJxYkTR1JGwmZjp9ZWhtSdCfToVmfsIZB05mx7FDOP/2Od5+Ce07zexnCzTvte1WPPKNwxg+sI2f3f0KkKnAaloZ+jjZSiE+WiFjKaQ5fvcJDZYmFxHhyyFXj3bpmBVM9QzSFpAux4swZfRgLv7IHkX3K/RbRrUIbW4fWyVd05U1YfgAeGtNTuVbEbFWo7WtwIfsgoxdltcfm+/1Nhg7tIO3VnlxmHFDO7JWwBeLQW3qS/Gtv3v314KLjsu7n+kizAqwtyaC76TdSBt7U1nZhZ2+5bCHn70FmT4S9SZO7UIrUQpXKaVmmBtE5CBgeZ79Y0VYMwc3WVZWkbCpL5x6SZAdEiiFZK6lEFQ1DX3upJGDskxtW+G8pJEpk/ncOCqF+MxuiqFlNnsl68BwltshWJNQu+9W6KeM+jPbqvSOG5a7DsZUHvr7FjueVgYD25JFi8bZCtItXuMFes1J0qjB7da+1/nIV5vsrOtnsee2w/nCYTsA2fexmTLc1pIILHitLC99cB5vr812Zuw8fmgQoIcGuo9idC9VEh28NOK2WNKXoxR8/7KxTbd1tFXMNLFlWSQN91EY23oGeyOfzE0cI50QlCYuVtY6TugByszL14Fmc2BJWmIK1cbWuU4TVfnbguQ2pWArCmgbgEzloQOzhZSIRqefmqdr3Sbv+ljZmUnhHTm4LeteiGIp2Lj3pWX8/O5XAVjR2ZP1XUxLoTelgliLVgrPLlzLO+uzlcJuE4dlnSMXUyjDUhCRA4ADgdEi8lXjpaFAvJzLBQgvRLKZ422WjCQJWQ1plfHvtkac2WeX4s4dIJKG+0gTp5RPnWUTpfdCXGi1uI+00jVN98AKquFNGvSjaJGcwSDqz9xhcfcMaU/y4X22ZvvRg4JtprWpz4Etw0afi2RCgoVe244YGLh/8qGDyuYx1/od2sxFZOG6T/naqOpBWXd5y8c9L77D5254hj22HhZsMxVEKp0pDDioQJ+PXSZkN56KGuCuNnGKKZRjKbQBg/EUyhDjbz3w4eqJVlvCsyVbgFEP8rYuXJDxSbclcwd2fQPa3BDFVj4HgeYaVCGtBh/aayJ/Pmt/PrBH/OIJ+bBZc/r8mgOz9nvbcuerhf75beXXo1sKtlXvwi8+skfgWgG7UrBl++j9WlsS/PRDuzF1zGB2mzgsd79QpkWXTSn4gWbdKOmsQ7bnmF3GZr3P9j1NhV2sn/hCX1m97JesgNz4gj7PhZo/TfRXmd/+BS9dtnGWQhPHFPyVzI+IyLVKqcLLM2NMeIamZ+UqK6aQm5FkXss7jRvKzAWrA7+rrRCZbQaQVUvJMjBkAs1mv4ICX6bOJBLCfts3h5Xw0NcP47VlncEgYvq59W9u5q4HzexrmK8uhqWQ77ViRF2J3NqSYOzQdsYO7Qi+u819pL/36QdO5uR9tubkfbbmN/fPy9lvSEcyGOwhE2jW51AplTPLP2aXsXlrOGV9p2QL4L13rXGMhas28ot7X+XnH9492Bbcv8ZX6UupoIx9Kq0CxVPIDTZykJeOuq1foqSWsaRCxMlSqCTQvFFELgZ2AQJnplLqiIqlqgNh95EtxztTW99ITzVUxG9P2YvLHprHmCEdXoqpcT8Hq34tN2Ax36reZs4G47ROoZnYbtQgths1iGtn6Lo+mfM42s9Pnz55q6BImlbEtVzElLEUyl+kWEp5isf+z7slf//w64D9u7UlE8z78futZbd1n2nwYgNZSiFkKWzsTdGbSmf1GNExChPb9Wxe72aNokMufgggyzINlJChFfpTaYZ0tLK6q5d+oz+6aYEAbD9qEG/4NY5GDfHcWnpy1p9SzFm8jjdWbuDEPSfmyFgr4hRTqCTQfBPwCrAdcCFeSurTVZCpLuQLNOdzHw0NFiZl3jNuWAc/Omm3YNGSebO1F7AUTGyzRW3uxq0KaTNjCyCPGdrB/V89lO8en6k11GaxHqqNrcd1+LVi2NxH+WhtSQR/kN8Kam1JhHpQeI/NK3hsqNKvVgr3v7ycB19ZxqlXe0XwdhqX8dWb/alP3X8SZ+Up9GcqOlv2UZeR6bSxTyuj7ECzDiqn0ir4LgNDSuHK06Zz9enTec/UUYGloJti9afTnHDZY3zl1uetMtaKzSX7aKRS6mqgTyn1iFLqM0BTWAmQ20+hcKAZdvcDWp3duSl4elGOufAlU3Kg8OBisxR0ipx5E8QpptCM5Bvsdxgz2FoltZa+Zf1b2mtcRTuGLdBcDD3I9/VHG4AyNa4U0ydtBeQWdTSv0c9cO4tnF64Fsjv3mSmfPzxpV87P01HPXG1uC/iavUi6Lamy/WkVuMF2nTA0WFhnnqs7vnQQO4wZzJE7j+WGz+6XkwnWqBl7nGIKlSgF7fRbKiLHichewIgqyFQX8gWazY5mmZIHcMlH9+QLh01hb6OYnUbfKGa9lkxmSxFLwTIK6EwNcz2DUwqVMdSfQYabHIXRA2dNLYVE9meZj6O6CcML0KJgLjosZf90WgX9wcOTp64ee7bOrhOGcekpe3HpKXtZF8bZpO8wjm1rerPeWPVvWz+RSiveNW4IXzhsCleeNt2a7m02YzLR92GqzjP27r4UP7zzJZaujU8xiEpiCj8SkWHA1/DWJwylDoXsqkV44ZW+UbYa2BY0VQ+CxUoxYlAb33zfTtZjaZN1k3GhthWIKZjYZou6WYt5wzmdUBnar93Z3YdIdkKBSRB8rmlMIXewakl4Pvha/s4f2GMC/3rhbT53qN19E8YssGdbOwOZlFSTc4/akYOnjipZviz3kWVl8XqjlW2+dQzJRCK4T7WCNedl+ZSC/i1qmYps476XlnH1Y2/y4CvxWfNblqXg92ieqpRap5Saq5Q6XCm1j1LqjirLVzPC7qNJI73c7nOOypRHCNJKi1woej/TytCDS7H1BVal4B/HvOHKmRk6Mmi/9vrufp46/0j+/oUDrfsVyuWvFvqXtBW1q6VFOHxgG3/93wODUuDFMFM537frOAA++u5tsvYJW1R/+dwBfOWowtVk82GeD2tMwbgf8rn3zCQnfcuYccIhlqA3eArEU8z1deO8tcoLeK81UnC7+1K8aqTa1puylILfo9lW7bRpCM8IthrYxoKLjuO9u4wLtpk+1UKM8btYnbJvpmV1Ju+7dKWwna+gzCJ5TidUxtZ+PvrR08YyZkgHe/uNb8JM8PsXv3faOOvr1UAslkKm/0bNPrZkhhjxg6ljh7DgouOs7lOzKYytkZSNsO7zFoJm7jOb+2hTb2ZbvomabQ2QmexRaJKWTAidhjVSy1Xtmk1Bm9DMZ512zUyO+fWjDSvjXYn7aIaIXAb8GQh62Cmlnq1YqjrQn0pnuRFsEzRtzhb7cSaPGsTz3z2a4QPbuOAfXn8grRSK5WfbMlB0L+fJIweywM+vz2f2OqIxfGAbs7//3qD+fz5GDW7nhe+9N2tArBXmtWFbxNhobA2gbPKZcYaoSiGMWSYe7JaCWWcp33oCU77vnbALHckWjp421rpvmGRCWLfJ/AwoMqerGJ2cssH4bjPf9PpPbOjuD7wG9aSSK39P//8PjG2KJslA6k8r2oy2l7YJhE77i5IuNnyg/ccrxVIY3J706t0nhPu/eihbDWxlnx/dDxRelemIhi1fXnP2kVN5eel6oPYKWP/iZpJBog7uo1IZbKm6aqO1JcHQjiTru/utlVoL0dbitUdNiGQN9Db3kKko8t2S5gLSsUM7uORje0aWpSUhWW6cvlSalkRtK/fo2IlNx23o6Wfh6o1MHjmIYQPrNymspEfz4dUUpN70pxRtSbMXsmUxjV7IVEa6mDZvi3UkMweGoR2eUhC8VEnwUug2FalU6aicrx69Y90/096UKfr7p40fyivvrK+2WAFRraXWFm8S8/CrKyLPbPXY3e73zG5JSNHKqWZwOZ9rpxL3W7IlkbWSuh7pqYX6NyxZu4mPX/kkR08byx9Pm15zWTSVNNkZC/wEmKCUer+ITAMO8NcuxJ7+dJr2ZAIdzinoPoqY1519/GhKwbQUhg5o5e113VkB5t23Hl7yZzuaA3PhYjmB5ju/fHDVZTLJF5S95KN7MGP+Km57djHgVRMeM7QjJwgdhfbWBJ093vcOrzwOY8YZ8i0KrSQhI5mQrGB2uOpBLegukPo8w+9LoUuR14tK1ilcC9wD6LXnrwHnVChP3ehLqaziXrabMSiOVsbFoW+oSSMKZ3qYs6Mff3BXdho3JKfhu2PzpM0aU4j+/kRCapqVlm+Q/tDeW/OLj2TqEBVzkRZCp7gmpHjpjiz3Ub5AcwXut2RCsj6jPpZCfi/Ayg2eK6ve7c8r+bhRSqm/AGkApVQ/0DR+jlRaZa1ktV1KA3w/fjk56wfvMIrffWJvvvG+dxXcz7QU9pk0grvPOaTojMmxeWDrlxGnmALAf77yHqtFIiLBpClcOTUKuoSLrlTbkhBG5InLaUz3Ub6U1HxKctTgdg7dcXTB47e0SNbM3RZL7Eulg+KKS9dtsjYZCvP22k15XcCFLAXtMdjUm+KR11bw+RufKZoeXw0qUQpdIjISvzSKiOwPrIvyRhG5RkSWi8hcY9sIEblPROb5/+05g1Wgpz/FwtUbs5WC5VrSi8jKqUvSkvCW+ttWc5rEKdvEUV/M668cS6Ee7Dx+KLtaSmhDZmZvKyYZFX1/tCSEc47ekS8enl01YOzQ9uBxdxSlkOcEzrrgKK77zL4FZUkmElmDd18qnTMIX/ivFznk4odY09XLAT99kNOunlnwmAAHXvQgn7nWXhaukKWg3VfdfWm+cutz/GfuO9z69KKin1cplSiFrwJ3AFNEZAZwPfDliO+9FnhfaNt5wANKqanAA/7zmnD9428xf/mGrIU3tmtJ12wpry5JzO5uR2zQFTqzS6jHL/uoGLrOUDmWgo6nmIX9Brcn+cYxO2Vl2n3n+GnBY3PAztdLuRJXSzIhWSupr/rvG2x//l1Z64UeeNlbebzaz1Ka9daagsfUAfEn3lhlfb2QpaDdV5v6Uozz09Qfea32K58ryT56VkQOBd6FNwK+qpQq3C4p895HRWRyaPOJwGH+4+uAh4H/K1e+QuhyuWYdHNuMXaeZltOLuInubUeDMK8r07feLOj1CQPLWJugu6FlmlFlXusI9YvWmANovqydSpRqS0KyUkOve+ItwHMT6TRlnTa7JGLwt5jrOYqlsLG3n1Vd3vd6Z31P3v2rRdl6VUQ6gLOBH+KVzv6iv61cxiqllvqP3wGsK05E5CwRmSUis1asWFHWB43y6+ibBbZsl5IuohYuvRuF4W6xmSMPB/gNisxeANq33ozuxHLuDx030wFjc42CGXAe0JpROKZlb7qPLjguU3W1EqUQLmOvD2UW39Nj/KI1hduUamwrs00KVePVlkJ3X5oVnZ4yeGHRWn5450s1bcpTifvoerwGO5cCl/mPb6iGUMqzuazfWil1pVJqulJq+ujRhQNH+dA11M3sAtvNuO2IQXxor4nc8aWDSv6MEU3U1N5RXw7fybtuzVmpnnU3k/tI3z6DylAK+j06s8/03ZtKJp/C6elPsc2IAZy6/ySmGX2WKzl/4XLk+ljmgjbtDlq4OppSMN1cvf1prnz09azj9fSlGJlnrAhnPW4/yit/c/Vjb3LBP+ZE+vxyqEQp7KqU+qxS6iH/70w8xVAuy0RkPID/v2bOs0kjBzJ55EDOPSqzYMl2KbUlE1zysT3ZYcyQkj+jGWd8jvrQZpRkD7Y1oftIz+4HlLHaXruc9OzfnPgOMCyF9jzNhHr60+w0big/PGnXrDIblcQUwqux9U+xpquPuUvWsXJDT2DF5Ct1PXvxWlZ3mYN+ZmC/7vEF/OSuV7hlZiZY3N2fDvpEhwknuJy8z9bB41tmLsqKdVSTSpTCs37GEQAish8wq4Lj3QGc7j8+HfhnBccqyKD2JA9/4/Csao7mDOM9ZZT91dx9znu45cz9i+/o2GLRHf1Ml0kzWgpa/HLcR+/3q67qYnpmMseAIN4geYPYvf3pYE2CWT+sknUbr4Qqk2pPwsa+FMdf+hgn//7xwO21qsvu2//AZTM48XePBc+1pdCSEF5d5h3fHMx7+lJBscYw4aKdU8cMZsFFx3H5J/cGvFTXWlBJQZ19gMdFZKH/fFvgVRGZg+cB2j3fG0XkFryg8igRWQx8D7gI+IuIfBZ4C/hoBbKVjHkvXl8kda0QZhtCh8NGYCkY27RSaCKdYFgKpSuF90wdzRs/OZY75yzl+ifeygq6a0tBkILprloXmLGASpSqrTcEwKoNngJ4a9VGdh4/1N/Wm7VPXyodWBaLVmcGax1TaEkIC/ysM3Mw7+5PM2FYPkvB3kdeN+Fas7E35z3VoBKlEE4pjYxSKl/Z7SPLPWalmJeSc/04aom+ubPdR7mKIu7okhBbFVl0lo9EQoJuaylLTKE3lS6Y7qoVgK0vRVny5HnvW6sy8QPdh2WloRT+8dwSzvnz88EM3kRbCsmEBGmsnd19nHfbbB6bv5JUWmX1sDbJ1x1yq0He/mu6YuY+Ukq9BawHhgEj9Z9S6i3/tabCKQJHvcj4wDM3va7gum5jbW70WqBTurctUsqlELbSFgPbM9sKWgoF+lKUw5eP2MG6Xc/sE5JJIzbdR7pr2pwluWt3A0tBJMh27OpNcevTi4KaRh154ibhQHN7nSyFSlJSfwjMBn4L/NL/+0WV5Ko7Tic46oWe2ZqzY10VVy9sawZ0n4KtKijrbFMKZonzQgUltTJoNWMKFdzH//Mee5tSHQNIq8xAbVp5Ol1U/zcxMxz1cbpCbqp8VQ/C1ZnbWrz9hg9s5QN7TGCbCpRxISpxH30UmKKUqo26qjNOJzjqxUE7jOKIncZwwXE789CrjwBw0l4TeWzeSv43Yv/kOHDZJ/aiqydVkZVtmyWb/SwKWQr6Y7OqzdYgfctcz2QrjjnXtxCWW5SCTrXt6u0PMqwWrspOZx2eR6nmcx+1J1v47Sl7RZS+dCpRCnOB4dQwdbSe1Nt9NOO8I1yfhC2UjtYWrjnj3VnbBrcnueLUfRokUXm0J1uK1vYqhs1SMJVCoR4LQfaRoRRqcR+b2UK2Omid/sx/+fpMmuqm3hRvrNwQBOPNRKLOkKWQb8YfrqTQXkGNqVKo5FN+CjwnIveIyB36r1qC1Zt654dPHD4gcBk4HFsq4QVjkK0URIRff2xPa4XTINCcqE6gGeChrx/GN47JrmzcZUzeCpWtMN1HX//bCxz328dy1hKY7UpP3ttbd6B7socJ11yrpPBgKVTyKdcBP8NLJf2l8deUuJiCw1F/bOms4TagJ+01kR3H5k6gdFC5Jct9VJk8240axEl7Tcz7eqGKyauMRWtPveH1WTYXsgFMGJ6pBPTDk3Zh9vffm7dbXSqP+6jWVPIpG5VSv/VXMz+i/6omWd1xWsHhqDe2cjC2xXA2N5W27k1LoRruo9YCboNNfamssh75elJrMVaG1jPsMiFThnxgWzIIqn/T0nclHGgeXEbhwXKoRCn8V0R+KiIHiMje+q9qktWZZiov4HBsLtgCwzaXki0grd9ra2taCcki5sZ+fkFDgMPeNca6jw4w64Vvmn0m2dvEfOGwHfjRSbtmbQtbJcU601WLSlSPDn+bNR0UcEQFx2wYbp2Cw9EYfvPxPbN6KNjWGtgtBV3mwlynULk8xTKYRg+2N/4x0VlKYffRiEFtXHDczllF/DThxXP1aAdqo5J+CodXU5BG41SCw9EYTtwzvw9fM3ZYblV+PYiaE7pq1I4q1nPaTCE996gd6e5L0duf5qk3VwfbdbntcGC6JSF510Pk00X7Th7BAVNG2l+sAZUsXhsrIleLyH/859P8ukVNiTMUHI74stc2w3O22QbRaqxTSFrMjW1GZOoTjTIshWkThnLDZ/dj1JD2rP31LL831C+hUIptPoV285n7ce7RO1pfqwWVGFvXAvcAE/znrwHnVChPw2im6pQOx5aGLchqUwDVuI9tA/f2owYH/aJtqeT5ekqEF7sVUlr5RK/32FSyUhAR/euMUkr9BUgDKKX6gaZdjeV0gsMRX2xBVlscsBoDaCIhweCtlVFLQjhyZ6+sh2k1aAbm6SkRXoBms0KCz80je73HpnJiCjOBvYEuERmJX9XL762QWxGqSTBNQoejXjx1/pF0djdPEbx68dDXD8vy7ZureVtbhL6Usq5JqFaZi9YWIZVWnLDHeB59bSVnHzmVaeOHcvzu461Nt/L1lAi7jwrJZ9MXIvVPgilHKWgJv4rXGGeKiMwARgMfrpZg9cYpBUcjGDu0g7FDK2ltvnmy3ajsVb5mRlIykaAvlbLOrKuVWt6aSNBNmonDBzDjvExC5YFTvAZcV58+nQnDMxbDYe8aw+UPv55znLD7KNwHOus1i1ZohFu7HKUwWkS+6j++HbgLT1H0AEfhVU5tGiYOH8CStZtqUkjL4XBUn2SLQF/2rDuZEPrTqqLS2SZ6lXRLHnePdiVp9t1uBOccNZX+lOKyh+YH23tKsBRstY0aMSyVoxRagMHkZnHWpo5rjfn32QfT2W3vuORwOOJHsGjNGDE7WlvY0NNftZl1poFP9OOdc9SOvPpOZ5ZSyLEUCozytjIWjVg/VY5SWKqU+kHVJWkQwwe2MbzMzlEOh6P+BIvWjKBCezLBhp7qrGg2KXUVcbjsRSnZRzal0AhLoZyUVOdncTgcDcO2klkP3tVY0Qyg/JLXlSqF3HUK+QUstGq7npRzChvWR9nhcGy5nHXI9px/7E5B1pGpFNr92kjVGkR1Imm+Vpn5GNyezFrxHE5JLT2m0ARKQSm1uvheDofDUV3OP3ZnzjpkitFcx3QfebPsaiWM6HabtuJ8hRAR9t42U/QuXOai1JhCswSaa4qILAA68RbC9SulpjdWIofDESfEEgTWM/pqj6HlVCbdeqvcxW2aki2FBmiF2CkFn8OVUisbLYTD4YgfemA100X1jD6cAlouetZeqvsIYPyw/Eqh0DoFu6XQBO4jh8PhaCRaKWStePYH73ylrEtluN8StJxuZ/l6JkDhQHObZYl2s2Qf1RoF3Csiz4jIWeEXReQsEZklIrNWrFjRAPEcDkcj0QNl0mIpdPdVx1IY7Vc9Led47568FT87eTerq6hQ97T2iPWdak0clcLBSqm9gfcDXxSRQ8wXlVJXKqWmK6Wmjx6d28zb4XBs3mTcR5kBc/pkb3Y+blh1ytX88qN7cOr+k9hr2+Elv1dE+Ni7t2WcpXxJIXdUXCyF2MUUlFJL/P/LReR2YF/g0cZK5XA44oK2EEz30WcP3o4Dp4yydjQrh/HDBvDDUHvMUrFZCoVm/ub3EfEyoKQBy8JiZSmIyCARGaIfA+8F5jZWKofDESf0bNtMSRWRqimEalEo/dSGqTAG+aW4W5Mu+2gscLt/cpLAzUqpuxsrksPhiBPB6uWY11YoJ0itGdjm1XKyuZRqTayUglLqDWCPRsvhcDjii1YKPVUKKteK7UcP4pV3Ost676D2JHT20NoApRAr95HD4XAUQy/yqtaahFoxeeSg4jvlYahfQ6kSa6NcnFJwOBxNxYBWnX4a7+6/lQzoQwe0Ft+pRsTKfeRwOBzFOO/YnUgpxft3G9doUQpSietnmK8UwgX16oFTCg6Ho6kYM6SD33x8r0aLUZRwg55SivVllEL9XWTOfeRwOBw1IFzSohyl0O+UgsPhcGwehC2FI941JvJ7hzr3kcPhcGxe6MV1yYRw31cPZfyw3LIX+Wik+8gpBYfD4agB5orm7UZFS09tSybo7U+zzVYDAVjV1VsT2Qrh3EcOh8NRA8rJPhriV1GdNNJTCql0/d1HTik4HA5HDdBKoZRhXVd7bU8m+OR+23LVafVvPOncRw6Hw1EDCnVZy8evPrYnzy9ay5ihHfz4g7vVQKriOEvB4XA4akA4+ygKA9uSHDhlVA2kiY5TCg6Hw1EDCrXejDPNKbXD4XDEHO0+Uqr+weJKcErB4XA4akAjeiFUg+aU2uFwOGKOzj5qQFZpRTil4HA4HDVgSEdzJnc6peBwOBw1YFgDeyJUglMKDofDUQMa2SinEpxScDgcjhrQiP7K1SBWUovI+0TkVRGZLyLnNVoeh8PhqISJwwfwuUO3b7QYJRGbSIiItAC/A44GFgNPi8gdSqmXGiuZw+FwlMeM845otAglEydLYV9gvlLqDaVUL3ArcGKDZXI4HI4tijgphYnAIuP5Yn9bFiJylojMEpFZK1asqJtwDofDsSUQJ6UQCaXUlUqp6Uqp6aNHj260OA6Hw7FZESelsATYxni+tb/N4XA4HHUiTkrhaWCqiGwnIm3Ax4E7GiyTw+FwbFHEJvtIKdUvIl8C7gFagGuUUi82WCyHw+HYooiNUgBQSt0F3NVoORwOh2NLRZqt1reJiKwA3irz7aOAlVUUpxLiJIuNOMkXJ1mKERdZ4yJHFOIka5xksVGJfJOUUtZMnaZWCpUgIrOUUvXvim0hTrLYiJN8cZKlGHGRNS5yRCFOssZJFhu1ki9OgWaHw+FwNBinFBwOh8MRsCUrhSsbLYBBnGSxESf54iRLMeIia1zkiEKcZI2TLDZqIt8WG1NwOBwORy5bsqXgcDgcjhBOKTgcDocjwCkFh8PhcAQ4pVAnRORDIrJVo+VoBty5Kh0ROUJEBjVajmbCXWd2NkulICJnisjlIjIlBrJ8SkSeBA4GuhstTxh3rkrH7+nxQxEZEANZPikizwCHA32Nlicf7jqLTqPPVaxqH1WCiAiekvsw8E1gKbCfiCxRStX9h/flOQO4CjhQKfVUvWXIhztXpePLmAT+B/g/vMHkXuC/DZInCZwDfBt4v1LqyUbIUQh3nUUnTudqs7AURKRDeaSAZ4H9gN8DhwA7N0Im5eX6Pg3cAvSISEJETheRhsijceeqdESkzT9nfXjnbGfgD8CnRWRkI2RSSvUD84AbgbdEpE1EThaRCY2QJ4y7zqITt3PV9EpBRL4D3C0iXxaRXZRS85RSq4G/AQK8p15+QxG5UESOMzbNxysFfifwAnAAcI2I/NTfv67n352r0hGR7wE3i8gZIjJCKfWUUmoT3k27NXBUvWQTkfNFZD9j0xN4BSH/gzeYfBC4TkS+7e/fqHPmrrPo8sXmXAUopZr2D/gM8DCeZv0B8A9gsvH6e4HrgCND75MqyzECb3XhGrwLrdV4bWvgAmCK/3wHPNNwgjtX8TxXhjzn4rmIjgRuAH4DjDdePwX4J7B9jeUYD9wGrAXmhV47APgJsLX/fFf/3I5s0Dlz11mTnavwX9NaCr4PbhvgcuX5Bn8OzAV+qvdRSt0LLAB2E5HjROSL/vZqL+PuAv6hlNoKr4XoV43X3gZ+ppR63f/s+cDjwKQqy5AXd65KR0RagL2AC5VSDwA/BDbi+fHx5bsFWA8cKiLvFpFP1kicdcBflVLDgbUiYp6zp30ZF/syzQXuxiurXFfcdRadmJ2rbOqpGWugab8H3Gk8Hw3MBA4zth0ALMe7EM6toSyD/f/vxjNRx1v2GQD8GngIGObOVWzPlS7/cjHwJ/9xwpf3DmAfY9+jgU3AIuCzNZRpiP//YGAV0KblMvZpBS4F/g101OMcxeE6KyBLLK6zOJ2rSPLW40OqcFKPAMaFTzLQDrwEHKK3A2cDPzFO8n+Bq4GBtZDF9uP7n3dV6LXD8GYjv66WLHlk+ASwh3E+GnmusmSJ27kyPm+48dgcZKcC9+ErAf8cXYA/+OO5HZ4E/ljFc2aVJXTO/o7XrtZ87URgVh3PWUse2RpxnbUUeK3h1xkwwJSnkecqkrz1+qAyT+aBwIvA9cAOoROb9B9/EXjKeO2LwNeMk14V32oRWRL+Yy3TaOAVf1A5ANgdGApMrOG5Osq/gJYDZzT4XBWSpeHnypDn/cAjwE3At4ztLf7/Nrz0wD8br/2WjFIYQZ4JQhVlSRiDiD5nY4HVeC6iXYBt8fzkk+twzo7DC9L+BDjIPGcNuM4KydLw6wwvJvA43qD+SWN7st7nqiS56/2BJZzQFuBPwCdC282Z3Hj//4PARXim9T3ANxohC4Y2xwtKpoHngXfX6BwJnvn7F7yA1THA5cAX9MVXr3NVqiz1PlcWefcFngI+ABwK/BXYNbTPaF/W+/HWA0zxz9npDZKlw3h+lX/Ongam1emc7YPn3jgW+DheIPeM0D71uicjydKo68z/vZ4ETsLzLtyBoezrea5Klr2RH17kpG4FXAsMx5uxnYpnrnf4r1+Cp4UnA9sD/4s30/p2g2R5FM93KcDxwJvAN+t0rk40Hn8KeMJ4nsQLYtXrXEWRpWHnypDlXOBi//H2wK14Sk3PMC/Hyywahzcb/zGee+a7DZDld3iZKdPwLIdT8QKQdR088Bbt/dJ/PAAvY+ZZfJcX8Ms6XmdRZGnIdeZ/3q7AH4xt0/Csu9H+87qNXyXL32gBjJN2Np5vVpvmI/0f9VD/5vwL8Ge8RUOD8Mz4rULHaIuDLHgm6rA6nKszQ9tbgIPwZpHb+Nve5V+AtT5XZclS63OVT05gN7yslEuBxf7vey3wHTz3zPWWc9YeB1mA6Rixhzqes32B14AR/vPv4AVov+/fI7+u13VWqix1uCdPB442nk8G5mC4f4Ar8FJMh+BZLTU5VxV/l0YL4J+MM/BMrffhacsL8LT/RXhZAx/19xuCl3mxh/HevEGmBsiSrKYsEeX7FkaePJ6v9Gn8bJXQe2t9rkqRpebnqoCc38Gz+rYCfgWc4O83DS/wt2Mdz1kpsjTynH0bGIOnuO7Eixn9Cc9NeAWGwqzDOStFlpqeM/93+xveOofZ5nfHU+bXGc9H+PfDNrU6V9X4i8s6hSPx8obvBr4GdABfAL6LN/gOAVBKdQI3482eEBFR3tLwuMjSX2VZosjXjuemwZdrNl5dno9puQz5an2uSpGlHucqn5ytwJeVUmvwZpBv+fu9AszA/41FJFGHc1aKLI08Zx3AaUqpL+PdDz9QSn0a6MGb4fb4ctbrnowqS03Pmf+73YtXjuIZvHFC8yXgWBF5t/98A/AcoAz5qn2uKqahSsFYUv4cns8PpdQs4DE8P+544BvAMSJygohcgOeSeMnfV22OspQo35PARBE52N9P8IJVA/yLTlVbvjjJUqacjwOTRGQaXpDvKhEZiDcD3RVvzQFKqfTmKEuZcs4AdhSR9yilFiql7vP3OxZ4Q7+/TtdZ3WXJI5/4D69XSq3Fi0N9SEQm+Z+/HrgQ+I6InI7nddgF6KyHfOVSd6Vg1hYxLvQZQEJEDvGfz8W7GfZRSl2PZxIejJd6d7zyV29uTrJUKN/beEpLX2hjgK4a3aANl6VKci4GdlJKXQK8iucCmAZ8SCm1fHOTpUpyvo0XeEdEDhGRR/Csmys2R1kiyKcnOd3+/6fx6lD92NjnMrz4xj54K6Y/opRaV0sZK6UupbNFZF9gf6XUb80Zj28Sp/GqPb4IfExEZiilFovIGLwfGaXUgyLycDVmS3GSpYryjcMrwaD5ulKqd3OSpQZyjsULfAN8Fi91ce3mJEuN5NS/7QK8dOMXNydZSpRPL0Qzx4LLgL+IyC7ASrx42oMi8kgcXUU2am4piMg5wO3ABSLyfn9bC2TNBDrxgkXtwC9EpBUvgLNCH6dKCiE2stRAvlWGfNVQCLGRpYZyLtMyVkkhxEaWGsq50t9vYZUUQmxkKUM+pZRKi8gAERmsZfH3n4MXFB/qb28KhQDUPvsIb/n9XsDJwCOW1y/EW6yzE57b4Vo83/QfqH4WQ2xkibt8cZKlWeSMkyzNImecZClTvu/hlR3Z3X9+Cl6ywM8xKrM2018tTuIJeFH3/f3nLf5fB3AXcLa/PYGXn30zfglbY3tOCmOzyxJ3+eIkS7PIGSdZmkXOOMlSI/n2B7ar9W9a0+uliidzPPAvPDPvO8DLwDH+a7p2y5F4tc1HWd6f2Bxlibt8cZKlWeSMkyzNImecZKmRfLFbb1D2uajiST0BYwk58Dng9vAPi2f2Xeg/39c86ZujLHGXL06yNIuccZKlWeSMkyzNKF89/yo9kafhlZ9tBwaS3ZXqI2RKwJqF47bBW9C0Dq/eR1VOaJxkibt8cZKlWeSMkyzNImecZGlG+Rr1V3JKqp+GNQ7Pl5YGXgfOBL6ilFoqIq3Ka3A+Hi9DAOVF6AWvyuSf8PKOz1FKzSn18+MqS9zli5MszSJnnGRpFjnjJEszyhcLStSsus78jsCNehteDZK/h/b5F3CU/1gXrRoDHF4NbRYnWeIuX5xkaRY54yRLs8gZJ1maUb64/EWyFPy83B8CLSJyF17ubQq8/FsR+QrwtogcqpR6RETa8PL6XxORHwPHi8jhyludWdEKzTjJEnf54iRLs8gZJ1maRc44ydKM8sWNoovXRORQvEJPW+FVCf0h0AccLt5KP5S3yOT7eDnF4KVvnQE8gFfQ6yil1OpKhY2TLHGXL06yNIuccZKlWeSMkyzNKF8siWByvQc41Xh+OfB5vJP2jL8tgeen+wteW8B98crG7llNsyZOssRdvjjJ0ixyxkmWZpEzTrI0o3xx/ItyUgfiRee1r+2TwE/9x8/jlf0Fr/HHrTX+gWMjS9zli5MszSJnnGRpFjnjJEszyhfHv6LuI6XURqVUj8rU7jiaTB2gTwM7i8idwC14ZppZUraqxEmWuMsXJ1maRc44ydIscsZJlmaUL45ETkn1gzUKr6nMHf7mTuB8vLrvbyqllkBd6pjHRpa4yxcnWQoRJznjJEsh4iRnnGRpRvniRClVUtN4XaJWArv72vU7QFop9Zg+oXUiTrLYiJN8cZKlEHGSM06yFCJOcsZJFhtxly8+lOJrwiv2lMbrRvbZRvq94iRL3OWLkyzNImecZGkWOeMkSzPKF5c/XegpEiKyNXAqcIny+6A2ijjJYiNO8sVJlkLESc44yVKIOMkZJ1lsxF2+uFCSUnA4HA7H5k3dezQ7HA6HI744peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwqOWCIiKRF5XkReFJEXRORrIlLwehWRySLyiSrKcLaIvCwiN0Xc/wwRuaxan18uInKSiEwznv9ARI5qpEyO5qHkzmsOR53YpJTaE0BExuB1yhoKfK/AeyYDn/D3rQZfwCubvLhKxysZEUkqpfpLfNtJwJ3ASwBKqe9WWy7H5ouzFByxR3nNTc4CviQek0XkvyLyrP93oL/rRcB7fAvjXBFpEZGLReRpEZktIp+zHV9Evioic/2/c/xtVwDbA/8RkXND+3eIyJ9EZI6IPCcihxsvbyMiD4vIPBH5nr//IBH5t2/xzBWRj/nb9xGRR0TkGRG5R0TG+9sfFpFfi8gs4Nsi8pa2kvxjLRKRVhE50/9uL4jIbSIy0D8XHwAu9s/DFBG5VkQ+7L//SF/mOSJyjYi0+9sXiMiF/vmcIyI7VfzDOZqTRi+pdn/uz/YHbLBsW4tX0Gwg0OFvmwrM8h8fBtxp7H8WcIH/uB2YBWwXOuY+wBxgEDAYeBHYy39tATDKIsfXgGv8xzsBC8k0ZlkKjAQGAHPxSjKfDPzReP8wvDo8jwOj/W0fM475MHC5sf8/8dtA+vtd5T8eaezzIzJloK8FPmy8di3wYV/GRcCO/vbr8XoN6++q3/8F/Rnub8v7c5aCoxlpBf4oInOAvwLT8uz3XuA0EXkeeApvsJ4a2udg4HalVJdSagPwd7zGLIU4GLgRQCn1CvAWXt9fgPuUUquUUpv8Yx2Mp3SOFpGfich7lFLrgHfhVee8z5fvArwGL5o/hx5/zH/8ceO1XX2LaQ5en4Bdisj9LrxqoK/5z68DDjFe/7v//xk8V5xjC8TFFBxNgYhsj9dXdzleXGEZsAeeC7Q739vwZr/31EVIj3DdGKWUek1E9gaOBX4kIg8AtwMvKqUOyHOcLuPxHcBPRGQEnmXzoL/9WuAkpdQLInIGnqVUCboeUAo3NmyxOEvBEXtEZDRwBXCZUkrhuV+WKq+37qlAi79rJ15PXc09wOdFpNU/zo4iMih0+P8CJ/n++EHAB/1thfgv3swcEdkR2BZ41X/taBEZISID8AK+M0RkArBRKXUjcDGwt7//aBE5wD9Oq4hYZ/q+BfM08Bs895huGDMEWOp/v08abwmfB82rwGQR2cF/firwSJHv6tjCcLMBR1wZ4LtVWoF+4AbgEv+1y4HbROQ04G4ys+rZQEpEXsCbRf8Gzw3yrIgIXsetk8wPUUo9KyLXAjP9TVcppZ4rItvlwO99t00/cIZSqsf7CGYCt+G5gm5USs0SkWPwAr9pvKbxn1dK9frB39+KyDC8e/HXeDENG3/Gc5UdZmz7Dp5bbIX/XyuCW/Hca2fjxRL0d+0WkU8DfxWRJJ6iuaLId3VsYbgqqQ6Hw+EIcO4jh8PhcAQ4peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwoOh8PhCHBKweFwOBwB/w9rIgmvO/MuNQAAAABJRU5ErkJggg==\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "# start the figure.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(weather['Local time'], weather['T'])\n", + "# label the axes\n", + "ax.set_xlabel(\"Date of observation\")\n", + "ax.set_ylabel(\"Temperature in Celsius\")\n", + "ax.set_title(\"Temperature Observations\")\n", + "# adjust the date labels, so that they look nicer\n", + "fig.autofmt_xdate()\n", + "# save the figure\n", + "fig.savefig('weather.png')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py b/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py new file mode 100644 index 00000000..8742b5f6 --- /dev/null +++ b/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py @@ -0,0 +1,38 @@ +import yaml + +def get_parameters(config_file, required, defaults): + ''' + Parameters: + Optionfile: FileName of the yaml file containing the options + required: Dict of required argument names and their object types. + defaults: Dict of default parameters mapping to their default values + + Returns: An object with fields named according to required and optional values. + ''' + f = open(config_file) + options = yaml.safe_load(f) + # create a parameters object that allows setting attributes. + parameters = type('Options', (), {})() + # check required arguments + for arg in required: + if not arg in options: + raise Exception("Could not find required Argument " + arg + " aborting...") + else: + if not isinstance(options[arg],required[arg]): + raise Exception("Expected input of type " + str(required[arg]) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + # check the default values. + for arg in defaults: + if arg in options: + if not isinstance(options[arg],type(defaults[arg])): + #Wrong type for the parameter + raise Exception("Expected input of type " + str(type(defaults[arg])) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + else: + print( arg + " not found in option file. Using default: " +str(defaults[arg])) + setattr(parameters,arg,defaults[arg]) + return parameters + + diff --git a/_images/01_memory_layout.svg b/_images/01_memory_layout.svg new file mode 100644 index 00000000..93da7c68 --- /dev/null +++ b/_images/01_memory_layout.svg @@ -0,0 +1,584 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How you see a matrix: + How NumPy sees a matrix: + [0,] + [1,] + [2,] + [3,] + [,0] + [,1] + [,2] + [,3] + [0] + [1] + [2] + [3] + [4] + [5] + [6] + [7] + [8] + [9] + [10] + [11] + [12] + [13] + [14] + [15] + + + + diff --git a/_images/01_table_dataframe.svg b/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/_images/02_views.svg b/_images/02_views.svg new file mode 100644 index 00000000..925354e0 --- /dev/null +++ b/_images/02_views.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + array "a" + array "b" + .shape.strides + .shape.strides + + + + + data pointer + data pointer + memory buffer + + diff --git a/_images/anaconda-navigator-jupyterlab.png b/_images/anaconda-navigator-jupyterlab.png new file mode 100644 index 00000000..4ea0854f Binary files /dev/null and b/_images/anaconda-navigator-jupyterlab.png differ diff --git a/_images/anaconda-prompt.png b/_images/anaconda-prompt.png new file mode 100644 index 00000000..e4fcf79b Binary files /dev/null and b/_images/anaconda-prompt.png differ diff --git a/_images/binder.jpg b/_images/binder.jpg new file mode 100644 index 00000000..d04c467d Binary files /dev/null and b/_images/binder.jpg differ diff --git a/_images/chatgpt.png b/_images/chatgpt.png new file mode 100644 index 00000000..67948010 Binary files /dev/null and b/_images/chatgpt.png differ diff --git a/_images/code-completion.gif b/_images/code-completion.gif new file mode 100644 index 00000000..e0bed42f Binary files /dev/null and b/_images/code-completion.gif differ diff --git a/_images/exercise.png b/_images/exercise.png new file mode 100644 index 00000000..6bfedfb4 Binary files /dev/null and b/_images/exercise.png differ diff --git a/_images/exercise1.png b/_images/exercise1.png new file mode 100644 index 00000000..ddfe4352 Binary files /dev/null and b/_images/exercise1.png differ diff --git a/_images/gapminder-larger-font.png b/_images/gapminder-larger-font.png new file mode 100644 index 00000000..cf7270ef Binary files /dev/null and b/_images/gapminder-larger-font.png differ diff --git a/_images/gapminder-linear.png b/_images/gapminder-linear.png new file mode 100644 index 00000000..78b30e77 Binary files /dev/null and b/_images/gapminder-linear.png differ diff --git a/_images/gapminder-log.png b/_images/gapminder-log.png new file mode 100644 index 00000000..7b6c3208 Binary files /dev/null and b/_images/gapminder-log.png differ diff --git a/_images/getting-started.png b/_images/getting-started.png new file mode 100644 index 00000000..8690a86f Binary files /dev/null and b/_images/getting-started.png differ diff --git a/_images/jupyterlab-notebook.png b/_images/jupyterlab-notebook.png new file mode 100644 index 00000000..900fdfd9 Binary files /dev/null and b/_images/jupyterlab-notebook.png differ diff --git a/_images/jupyterlab-terminal.png b/_images/jupyterlab-terminal.png new file mode 100644 index 00000000..33a6b02a Binary files /dev/null and b/_images/jupyterlab-terminal.png differ diff --git a/_images/main-ui.png b/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/_images/main-ui.png differ diff --git a/_images/notebook-ui.png b/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/_images/notebook-ui.png differ diff --git a/_images/precipitation-on-top-yearmonth.svg b/_images/precipitation-on-top-yearmonth.svg new file mode 100644 index 00000000..40a99519 --- /dev/null +++ b/_images/precipitation-on-top-yearmonth.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)050100150200250300350precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/precipitation-on-top.svg b/_images/precipitation-on-top.svg new file mode 100644 index 00000000..a977ebc6 --- /dev/null +++ b/_images/precipitation-on-top.svg @@ -0,0 +1 @@ +OctoberNovemberDecember2023FebruaryMarchAprilMayJuneJulyAugustSeptemberOctoberdate050100150200250300350precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/precipitation-side.svg b/_images/precipitation-side.svg new file mode 100644 index 00000000..095c23bd --- /dev/null +++ b/_images/precipitation-side.svg @@ -0,0 +1 @@ +name050100150200250precipitationOslo - BlindernTromso - LangnesOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/precipitation-stacked-x.svg b/_images/precipitation-stacked-x.svg new file mode 100644 index 00000000..c0992433 --- /dev/null +++ b/_images/precipitation-stacked-x.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)050100150200250precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/precipitation-stacked-y.svg b/_images/precipitation-stacked-y.svg new file mode 100644 index 00000000..78092adf --- /dev/null +++ b/_images/precipitation-stacked-y.svg @@ -0,0 +1 @@ +050100150200250precipitationOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/python_unmasked.jpg b/_images/python_unmasked.jpg new file mode 100644 index 00000000..57e3cc47 Binary files /dev/null and b/_images/python_unmasked.jpg differ diff --git a/_images/snow-depth-circles.svg b/_images/snow-depth-circles.svg new file mode 100644 index 00000000..c54504ed --- /dev/null +++ b/_images/snow-depth-circles.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - Langnes2023FebruaryMarchAprildate2023FebruaryMarchAprildate−5051015max temperature \ No newline at end of file diff --git a/_images/snow-depth-color.svg b/_images/snow-depth-color.svg new file mode 100644 index 00000000..7a821dd4 --- /dev/null +++ b/_images/snow-depth-color.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate−5051015max temperature \ No newline at end of file diff --git a/_images/snow-depth-plasma.svg b/_images/snow-depth-plasma.svg new file mode 100644 index 00000000..d5ec8d5e --- /dev/null +++ b/_images/snow-depth-plasma.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate−5051015max temperature \ No newline at end of file diff --git a/_images/snow-depth.svg b/_images/snow-depth.svg new file mode 100644 index 00000000..75581931 --- /dev/null +++ b/_images/snow-depth.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate \ No newline at end of file diff --git a/_images/temperature-ranges-combined.svg b/_images/temperature-ranges-combined.svg new file mode 100644 index 00000000..abc39623 --- /dev/null +++ b/_images/temperature-ranges-combined.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)−20−15−10−505101520253035max temperature, min temperatureOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/temperature-ranges-side.svg b/_images/temperature-ranges-side.svg new file mode 100644 index 00000000..aa67e29e --- /dev/null +++ b/_images/temperature-ranges-side.svg @@ -0,0 +1 @@ +name−20−15−10−505101520253035max temperature, min temperatureOslo - BlindernTromso - LangnesOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/_images/tidy_data.png b/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/_images/tidy_data.png differ diff --git a/_images/xarray_1d_plot.png b/_images/xarray_1d_plot.png new file mode 100644 index 00000000..0e0b6a79 Binary files /dev/null and b/_images/xarray_1d_plot.png differ diff --git a/_images/xarray_2d_plot.png b/_images/xarray_2d_plot.png new file mode 100644 index 00000000..15afca26 Binary files /dev/null and b/_images/xarray_2d_plot.png differ diff --git a/_images/xarray_dataset_image.png b/_images/xarray_dataset_image.png new file mode 100644 index 00000000..e3556dea Binary files /dev/null and b/_images/xarray_dataset_image.png differ diff --git a/_images/xarray_hist.png b/_images/xarray_hist.png new file mode 100644 index 00000000..de6b24b6 Binary files /dev/null and b/_images/xarray_hist.png differ diff --git a/_sources/binder.rst.txt b/_sources/binder.rst.txt new file mode 100644 index 00000000..57b1aa42 --- /dev/null +++ b/_sources/binder.rst.txt @@ -0,0 +1,200 @@ +Binder +====== + +.. questions:: + + - Why sharing code alone may not be sufficient. + - How to share a computational environment? + - What is Binder? + - How to binderize my Python repository? + - How to publish my Python repository? + +.. objectives:: + + - Learn about reproducible computational environments. + - Learn to create and share custom computing environments with Binder. + - Learn to get a DOI from Zenodo for a repository. + + +Why is it sometimes not enough to share your code? +-------------------------------------------------- + +.. image:: img/binder/python_unmasked.jpg + + +Exercise 1 +~~~~~~~~~~ + +.. challenge:: Binder-1: Discuss better strategies than only code sharing (10 min) + + Lea is a PhD student in computational biology and after 2 years of intensive + work, she is finally ready to publish her first paper. The code she has used + for analyzing her data is available on GitHub but her supervisor who is an + advocate of open science told her that sharing code is not sufficient. + + **Why is it possibly not enough to share "just" your code? + What problems can you anticipate 2-5 years from now?** + + We form small groups (4-5 persons) and discuss in groups. If the workshop is + online, each group will join a breakout room. + If joining a group is not possible or practical, we use the shared document + to discuss this collaboratively. + + Each group write a summary (bullet points) of the discussion in the workshop + shared document (the link will be provided by your instructors). + + +Sharing a computing environment with Binder +------------------------------------------- + +`Binder `__ allows you to create +custom computing environments that can be shared and used by many remote users. +It uses `repo2docker `__ to +create a container image (`docker `__ image) of a +project using information contained in included configuration files. + +Repo2docker is a standalone package that you can install locally on your laptop +but an `online Binder `__ service is freely available. +This is what we will be using in the tutorial. + +The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder. + +.. image:: https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png + +Credit: `Juliette Taka, Logilab and the OpenDreamKit project (2017) `_ + + +Binder exercise/demo +~~~~~~~~~~~~~~~~~~~~ + +In an earlier episode (Data visualization with Matplotlib) we have created this notebook: + +.. code-block:: python + + import pandas as pd + import matplotlib.pyplot as plt + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + data_2007 = data[data["year"] == 2007] + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xscale("log") + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + +We will now first share it via `GitHub `__ "statically", +then using `Binder `__. + +.. challenge:: Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min) + + Instructor demonstrates this. **This exercise (and all following) + requires git/GitHub knowledge and accounts, which wasn't a + prerequisite of this course. Thus, this is a demo (and might even + be too fast for you to type-along). Watch the video if you + are reading this later on**: + + - Creates a GitHub repository + - Uploads the notebook file + - Then we look at the statically rendered version of the notebook on GitHub + - Create a ``requirements.txt`` file which contains: + + .. code-block:: none + + pandas==1.2.3 + matplotlib==3.4.2 + + - Commit and push also this file to your notebook repository. + - Visit https://mybinder.org and copy paste the code under "Copy the text below ..." into your `README.md`: + + .. image:: img/binder/binder.jpg + + - Check that your notebook repository now has a "launch binder" + badge in your `README.md` file on GitHub. + - Try clicking the button and see how your repository is launched + on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud. + - Enjoy being fully reproducible! + + +How can I get a DOI from Zenodo? +--------------------------------- + +`Zenodo `__ is a general purpose open-access +repository built and operated by `CERN `__ and `OpenAIRE +`__ that allows researchers to archive and get a +`Digital Object Identifier (DOI) `__ to data that they +share. + +.. challenge:: Binder-3: Link a Github repository with Zenodo (optional) + + **Everything you deposit on Zenodo is meant to be kept (long-term archive). + Therefore we recommend to practice with the Zenodo "sandbox" (practice/test area) + instead:** https://sandbox.zenodo.org + + 1. **Link GitHub with Zenodo**: + + - Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing). + - Log in to Zenodo with your GitHub account. Be aware that you may need to + authorize Zenodo application (Zenodo will redirect you back to GitHub for + Authorization). + - Choose the repository webhooks options. + - From the drop-down menu next to your email address at the top of the page, select GitHub. + - You will be presented with a list of all your Github repositories. + + 2. **Archiving a repo**: + + - Select a repository you want to archive on Zenodo. + - Toggle the "on" button next to the repository ou need to archive. + - Click on the Repo that you want to reserve. + - Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release. + + 3. **Trigger Zenodo to Archive your repository** + + - Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI. + - If this is the first release of your code then you should give it a + version number of v1.0.0. Add description for your release then click the + Publish release button. + - Zenodo takes an archive of your GitHub repository each time you create a new Release. + + 4. **To ensure that everything is working**: + + - Go to https://zenodo.org/account/settings/github/ (or the corresponding + sandbox at https://sandbox.zenodo.org/account/settings/github/), or the + Upload page (https://zenodo.org/deposit), you will find your repo is + listed. + - Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo. + - You can edit the archive on Zenodo and/or publish a new version of your software. + - It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata + manually, you can also add a ``.zenodo.json`` or a ``CITATION.cff`` file to your repo and Zenodo will infer the metadata from this file. + - Your code is now published on a Github public repository and archived on Zenodo. + - Update the README file in your repository with the newly created zenodo badge. + + +Create a Binder link for your Zenodo DOI +---------------------------------------- + +Rather than specifying a GitHub repository when launching binder, you can instead use a Zenodo DOI. + +.. challenge:: Binder-4: Link Binder with Zenodo (10 min) + + We will be using an existing Zenodo DOI `10.5281/zenodo.3886864 `_ to start Binder: + + - Go to `https://mybinder.org `__ and fill information using Zenodo DOI (as shown on the animation below): + + .. image:: https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif + + - You can also get a Binder badge and update the README file in the + repository. It is good practice to add both the Zenodo badge and the + corresponding Binder badge. + +.. keypoints:: + + - It is easy to sharing reproducible computational environments + - Binder provides a way for anyone to test and run code - without + you needing to set up a dedicated server for it. + - Zenodo provides permanent archives and a DOI. diff --git a/_sources/data-formats.rst.txt b/_sources/data-formats.rst.txt new file mode 100644 index 00000000..1c7f3839 --- /dev/null +++ b/_sources/data-formats.rst.txt @@ -0,0 +1,549 @@ +In depth analysis of some selected file formats +=============================================== + +Here is a selection of file formats that are commonly used in data science. They are somewhat ordered by their intended use. + +Storing arbitrary Python objects +-------------------------------- + + +.. _pickle: + +Pickle +****** + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** None (:mod:`pickle`-module is included with Python). + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** 🟨 + - **Array data:** 🟨 + - **Long term archival/sharing:** ❌! See warning below. + - **Best use cases:** Saving Python objects for debugging. + +.. warning:: + + Loading pickles that you have not created is + risky as they can contain arbitrary executable code. + + Do not unpickle objects from sources that you do not trust! + +:mod:`Pickle ` is Python's own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:: + + import pickle + + with open('data_array.pickle', 'wb') as f: + pickle.dump(data_array, f) + + with open('data_array.pickle', 'rb') as f: + data_array_pickle = pickle.load(f) + + +Exercise 1 +---------- + +.. challenge:: + + - Create an arbitrary python object (for example, a string or a list). Pickle it. + + Read the pickled object back in and check if it matches the original one. + +.. solution:: + + .. code-block:: python + + import pickle + + my_object=['test', 1, 2, 3] + + with open('string.pickle', 'wb') as f: + pickle.dump(my_object, f) + + + with open('string.pickle', 'rb') as f: + my_pickled_object = pickle.load(f) + + print(my_object, my_pickled_object) + print(my_object == my_pickled_object) + + +Storing tidy data +----------------- + +.. _csv: + +CSV (comma-separated values) +**************************** + +.. admonition:: Key features + + - **Type:** Text format + - **Packages needed:** numpy, pandas + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data. Small data. Data that needs to be human-readable. + +CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you're working with big data. + +Pandas has a very nice interface for writing and reading CSV files with `to_csv `__- and `read_csv `__-functions:: + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + +Numpy has `routines `__ for saving and loading arrays as CSV files as well:: + + np.savetxt('data_array.csv', data_array) + + data_array_csv = np.loadtxt('data_array.csv') + +.. admonition:: Storing data in CSVs can reduce data precision + :class: dropdown + + When working with floating point numbers you should be careful to save the data with enough decimal places so that you won't lose precision. + + For example, double-precision floating point numbers have `~16 decimal places of precision `__, but if you use normal Python to write these numbers, you can easily lose some of that precision. + Let's consider the following example: + + .. code-block:: python + + import numpy as np + test_number = np.sqrt(2) + # Write the number in a file + test_file = open('sqrt2.csv', 'w') + test_file.write('%f' % test_number) + test_file.close() + # Read the number from a file + test_file = open('sqrt2.csv', 'r') + test_number2 = np.float64(test_file.readline()) + test_file.close() + # Calculate the distance between these numbers + print(np.abs(test_number - test_number2)) + + CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. + We can check whether our written data matches the generated data: + + .. code-block:: python + + dataset.compare(dataset_csv) + + np.all(data_array == data_array_csv) + + In our case some rows of ``dataset_csv`` loaded from CSV do not match the original ``dataset`` as the last decimal can sometimes be rounded due to `complex technical reasons `__. + + Storage of these high-precision CSV files is usually very inefficient storage-wise. + + Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems. + + +.. _feather: + + +Feather +******* + +.. admonition:: Requires additional packages + :class: dropdown + + + Using Feather requires `pyarrow-package `__ to be installed. + + You can try installing pyarrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** ❌ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Temporary storage of tidy data. + +`Feather `__ is a file format for storing data frames quickly. +There are libraries for Python, R and Julia. + +We can work with Feather files with :external+pandas:ref:`to_feather- and read_feather-functions `:: + + dataset.to_feather('dataset.feather') + dataset_feather = pd.read_feather('dataset.feather') + +Feather is not a good format for storing array data, so we won't present an example of that here. + + +.. _parquet: + + +Parquet +******* + +.. admonition:: Requires additional packages + :class: dropdown + + Using Parquet requires `pyarrow-package `__ to be installed. + + You can try installing PyArrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** 🟨 + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in tidy data format. Archival of said data. + +`Parquet `__ is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.). + +We can work with Parquet files with :external+pandas:ref:`to_parquet- and read_parquet-functions `:: + + dataset.to_parquet('dataset.parquet') + dataset_parquet = pd.read_parquet('dataset.parquet') + +Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won't do that here. + + +Exercise 2 +---------- + +.. challenge:: + + - Create the example ``dataset``: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + - Save the dataset ``dataset`` as CSV. Load the dataset into a variable ``dataset_csv``. + - Use ``dataset.compare(dataset_csv)`` to check if loaded dataset matches the original one. + +.. solution:: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + + print(dataset.compare(dataset_csv)) + + Dataset might not be completely the same. Sometimes the CSV format cannot + fully represent a floating point value, which will result in rounding errors. + +Storing array data +------------------ + + +.. _npy: + + +npy (numpy array format) +************************ + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** numpy + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Saving numpy arrays temporarily. + +If you want to temporarily store numpy arrays, you can use the :func:`numpy.save`- and :func:`numpy.load`-functions:: + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + +There also exists :func:`numpy.savez`-function for storing multiple datasets in a single file:: + + np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array) + data_arrays = np.load('data_arrays.npz') + data_arrays['data_array0'] + +For big arrays it's good idea to check other binary formats such as HDF5 or NetCDF4. + +``np.save``- and ``np.savez``-functions work with +`sparse matrices `__, +but one can also use dedicated +`scipy.sparse.save_npz `__- and +`scipy.sparse.load_npz `__-functions. +Storing sparse matrices using these functions can give huge storage savings. + + +.. _hdf5: + + +HDF5 (Hierarchical Data Format version 5) +***************************************** + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** numpy, pandas, PyTables, h5py + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. + +HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences. + +Pandas allows you to store tables as HDF5 with `PyTables `_, which uses HDF5 to write the files. +You can create a HDF5 file with :external+pandas:ref:`to_hdf- and read_parquet-functions `:: + + dataset.to_hdf('dataset.h5', key='dataset', mode='w') + dataset_hdf5 = pd.read_hdf('dataset.h5') + +For writing data that is not a table, you can use the excellent `h5py-package `__:: + + import h5py + + # Writing: + + # Open HDF5 file + h5_file = h5py.File('data_array.h5', 'w') + # Write dataset + h5_file.create_dataset('data_array', data=data_array) + # Close file and write data to disk. Important! + h5_file.close() + + # Reading: + + # Open HDF5 file again + h5_file = h5py.File('data_array.h5', 'r') + # Read the full dataset + data_array_h5 = h5_file['data_array'][()] + # Close file + h5_file.close() + + +.. _netcdf4: + + +NetCDF4 (Network Common Data Form version 4) +******************************************** + +.. admonition:: Requires additional packages + :class: dropdown + + Using NetCDF4 requires `netCDF4 `__- or `h5netcdf `__-package to be installed. + h5netcdf is often mentioned as being faster to the official netCDF4-package, so we'll be using it in the example. + + A great NetCDF4 interface is provided by a `xarray-package `__. + + You can try installing these packages with + + .. code-block:: bash + + !pip install h5netcdf xarray + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** pandas, netCDF4/h5netcdf, xarray + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets. + +NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs. + +NetCDF4 is a common format for storing large data from big simulations in physical sciences. + +Using interface provided by ``xarray``:: + + # Write tidy data as NetCDF4 + dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf') + # Read tidy data from NetCDF4 + import xarray as xr + dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf') + dataset_netcdf4 = dataset_xarray.to_pandas() + dataset_xarray.close() + +Working with array data is easy as well:: + + # Write array data as NetCDF4 + xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf') + # Read array data from NetCDF4 + data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf') + data_array_netcdf4 = data_array_xarray.to_numpy() + data_array_xarray.close() + +The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (``x``, ``y``, ``z``) or timestamps (``t``) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis. + +Exercise 3 +---------- + +.. challenge:: + + - Create an example numpy array: + + .. code-block:: python + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + - Store the array as a npy. + - Read the dataframe back in and compare it to the original one. Does the data match? + +.. solution:: + + .. code-block:: python + + import numpy as np + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + np.all(data_array == data_array_npy) + + +Other file formats +------------------ + + +.. _json: + +JSON (JavaScript Object Notation) +********************************* + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** None (:mod:`json`-module is included with Python). + - **Space efficiency:** ❌ + - **Arbitrary data:** 🟨 + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Saving nested/relational data, storing web requests. + +JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.). + +You rarely want to keep your data in this format, unless you're working with +nested data with multiple layers or lots of interconnections. + +Similarly to other popular files, Pandas can write and read json files with :meth:`~pandas.DataFrame.to_json`- and :func:`~pandas.read_json`-functions:: + + dataset.to_json('dataset.json') + dataset_json = pd.read_json('dataset.json') + + +.. _excel: + +Excel +***** + +.. admonition:: Requires additional packages + :class: dropdown + + Using Excel files with Pandas requires `openpyxl `__-package to be installed. + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** `openpyxl `__ + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** 🟨 + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data in many fields. Quick data analysis. + +Excel is very popular in social sciences and economics. +However, it is `not a good format `__ for data science. + +See Pandas' documentation on :external+pandas:ref:`working with Excel files `. + + +.. _graph: + +Graph formats (adjency lists, gt, GraphML etc.) +*********************************************** + +.. admonition:: Key features + + - **Type**: Many different formats + - **Packages needed:** Depends on a format. + - **Space efficiency:** 🟨 + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** 🟨 + - **Best use cases:** Saving graphs or data that can be represented as a graph. + +There are plenty of data formats for storing graphs. +We won't list them here as optimal data format depends heavily on the graph structure. + +One can use functions in libraries such as +`networkx `__, +`graph-tool `__, +`igraph `__ +to read and write graphs. + diff --git a/_sources/dependencies.rst.txt b/_sources/dependencies.rst.txt new file mode 100644 index 00000000..0081116f --- /dev/null +++ b/_sources/dependencies.rst.txt @@ -0,0 +1,767 @@ +.. _dependency_management: + +Dependency management +===================== + +.. questions:: + + - Do you expect your code to work in one year? Five? What if it + uses ``numpy`` or ``tensorflow`` or ``random-github-package`` ? + - How can my collaborators easily install my code with all the necessary dependencies? + - How can I make it easy for my others (and me in future) to reproduce my results? + - How can I work on two (or more) projects with different and conflicting dependencies? + +.. objectives:: + + - Learn how to record dependencies + - Be able to communicate the dependencies as part of a report/thesis/publication + - Learn how to use isolated environments for different projects + - Simplify the use and reuse of scripts and projects + + +How do you track dependencies of your project? +---------------------------------------------- + +* **Dependency**: Reliance on a external component. In this case, a + separately installed software package such as ``numpy``. + + + +Exercise 1 +---------- + +.. challenge:: Dependencies-1: Discuss dependency management (5 min) + + Please discuss and answer via **collaborative document** the + following questions: + + - How do you install Python packages (libraries) that you use in your work? + From PyPI using pip? From other places using pip? Using conda? + - How do you track/record the dependencies? Do you write them into a file or README? Into + ``requirements.txt`` or ``environment.yml``? + - If you track dependencies in a file, why do you do this? + - Have you ever experienced that a project needed a different version of a Python + library than the one on your computer? If yes, how did you solve it? + + +.. _pypi: + +PyPI (The Python Package Index) and conda ecosystem +--------------------------------------------------- + +PyPI (The Python Package Index) and conda are popular packaging/dependency +management tools: + +- When you run ``pip install`` you typically install from `PyPI + `__, but you can also ``pip install`` from a GitHub + repository and similar. + +- When you run ``conda install`` you typically install from `Anaconda Cloud + `__ where there are conda channels maintained + by Anaconda Inc. and by various communities. + + +Why are there two ecosystems? + + +.. admonition:: PyPI + + - **Installation tool:** ``pip`` + - **Summary:** PyPI is traditionally used for Python-only packages or + for Python interfaces to external libraries. There are also packages + that have bundled external libraries (such as numpy). + - **Amount of packages:** Huge number. Old versions are supported for + a long time. + - **How libraries are handled:** If your code depends on external + libraries or tools, these things need to be either included in the + pip-package or provided via some other installation system (like + operating system installer or manual installation). + - **Pros:** + - Easy to use + - Package creation is easy + - **Cons:** + - Installing packages that need external libraries can be complicated + +.. admonition:: Conda + + - **Installation tool:** ``conda`` or ``mamba`` + - **Summary:** Conda aims to be a more general package distribution tool + and it tries to provide not only the Python packages, but also libraries + and tools needed by the Python packages. Most scientific software written + in Python uses external libraries to speed up calculations and installing + these libraries can often become complicated without conda. + - **Amount of packages:** Curated list of packages in defaults-channel, huge + number in community managed channels. Other packages can be installed via pip. + - **How libraries are handled:** Required libraries are installed as separate + conda packages. + - **Pros:** + - Quite easy to use + - Easier to manage packages that need external libraries + - **Cons:** + - Package creation is harder + + +Conda ecosystem explained +------------------------- + +.. warning:: + + Anaconda has recently changed its licensing terms, which affects its + use in a professional setting. This caused uproar among academia + and Anaconda modified their position in + `this article `__. + + Main points of the article are: + + - conda (installation tool) and community channels (e.g. conda-forge) + are free to use. + - Anaconda repository and **Anaconda's channels in the community repository** + are free for universities and companies with fewer than 200 employees. + Non-university research institutions and national laboratories need + licenses. + - Miniconda is free, when it does not download Anaconda's packages. + - Miniforge is not related to Anaconda, so it is free. + + For ease of use on sharing environment files, we recommend using + Miniforge to create the environments and using conda-forge as the main + channel that provides software. + +- Package repositories: + + - `Anaconda Community Repository (anaconda.org) `__ + aka. Anaconda Cloud is a package cloud maintained by Anaconda Inc. + It is a repository that houses mirrors of Anaconda's channels and + community maintained channels. + - `Anaconda Repository (repo.anaconda.com) `__ + houses Anaconda's own proprietary software channels. + +- Major package channels: + + - Anaconda's proprietary channels: ``main``, ``r``, ``msys2`` and ``anaconda``. + These are sometimes called ``defaults``. + - `conda-forge `__ is the largest open source + community channel. It has over 27,000 packages that include open-source + versions of packages in Anaconda's channels. + +- Package distributions and installers: + + - `Anaconda `__ is a distribution of conda packages + made by Anaconda Inc.. When using Anaconda remember to check that your + situation abides with their licensing terms. + - `Miniconda `__ is a minimal installer + maintained by Anaconda Inc. that has conda and uses Anaconda's channels + by default. Check licensing terms when using these packages. + - `Miniforge `__ is an open-source + Miniconda replacement that uses conda-forge as the default channel. + Contains mamba as well. + - `micromamba `__ + is a tiny stand-alone version of the mamba package manager written in C++. + It can be used to create and manage environments without installing + base-environment and Python. It is very useful if you want to automate + environment creation or want a more lightweight tool. + +- Package managers: + + - `conda `__ is a package and environment management system + used by Anaconda. It is an open source project maintained by Anaconda Inc.. + - `mamba `__ is a drop in + replacement for conda. It used be much faster than conda due to better + dependency solver but nowadays conda + `also uses the same solver `__. + It still has some UI improvements. + +Exercise 2 +---------- + +.. challenge:: Dependencies-2: Package language detective (5 min) + + Think about the following sentences: + + 1. Yes, you can install my package with pip from GitHub. + 2. I forgot to specify my channels, so my packages came from the defaults. + 3. I have a Miniforge installation and I use mamba to create my environments. + + What hidden information is given in these sentences? + + .. solution:: + + 1. The package is provided as a pip package. However, it is most likely + not uploaded to PyPI as it needs to be installed from a repository. + 2. In this case the person saying the sentence is most likely using + Anaconda or Miniconda because these tools use the ``defaults``-channel + as the default channel. They probably meant to install software from + conda-forge, but forgot to specify the channel. + 3. Miniforge uses conda-forge as the default channel. So unless some + other channel has been specified, packages installed with these + tools come from conda-forge as well. + +Python environments +------------------- + +An **environment** is a basically a folder that contains a Python +interpreter and other Python packages in a folder structure similar +to the operating system's folder structure. + +These environments can be created by the +`venv-module `__ in base +Python, by a pip package called +`virtualenv `_ +or by conda/mamba. + +Using these environments is highly recommended because they solve the +following problems: + +- Installing environments won't modify system packages. + +- You can install specific versions of packages into them. + +- You can create an environment for each project and you won't encounter any + problems if different projects require different versions of packages. + +- If you make some mistake and install something you did not want or need, you + can remove the environment and create a new one. + +- Others can replicate your environment by reusing the same specification + that you used to create the environment. + + +Creating Python environments +---------------------------- + +.. tabs:: + + .. group-tab:: Creating conda environment from environment.yml + + Record channels and packages you need to a file called + ``environment.yml``: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + - python + - numpy + - matplotlib + - pandas + + The ``name`` describes the name of the environment, + ``channels``-list tells which channels should be search for packages + (channel priority goes from top to bottom) and ``dependencies``-list + contains all packages that are needed. + + Using this file you can now create an environment with: + + .. code-block:: console + + $ conda env create --file environment.yml + + .. admonition:: You can also use mamba + + If you have mamba installed, you can replace conda + with mamba in each command. + + You can then activate the environment with: + + .. code-block:: console + + $ conda activate my-environment + + .. callout:: conda activate versus source activate + + ``conda activate`` will only work if you have run ``conda init`` + in the past. Running ``conda init`` will make loading environments + easier as you will always have a conda environment loaded. + + However, this can also cause problems as programs in the + main environment will be constantly loaded and they might be used + even when they're not supposed to be used. A common example is + not having ``pip`` installed in a conda environment which results + ``pip`` from main environment to be used instead. + + You can then check e.g. installed versions of Python and ``numpy``: + + .. code-block:: console + + $ python -c 'import sys; import numpy; print(f"Python version: {sys.version}\nNumPy version: {numpy.__version__}")' + Python version: 3.13.0 | packaged by conda-forge | (main, Oct 8 2024, 20:04:32) [GCC 13.3.0] + NumPy version: 2.1.2 + + To deactivate the environment, you can run: + + .. code-block:: console + + $ conda deactivate + + .. group-tab:: Creating virtual environment from requirements.txt + + Record packages you need to a file called + ``requirements.txt``: + + .. code-block:: text + + numpy + matplotlib + pandas + + This is simply a text file that lists all of the packages that + you need. It is usually called ``requirements.txt``. + + Now you can create a virtual environment with: + + .. code-block:: console + + $ python -m venv my-environment + + You can then activate the environment by sourcing a file called + ``activate``. + + - **Linux/Mac OSX**: + .. code-block:: console + + $ source my-environment/bin/activate + + - **Windows**: most likely you can find it in the Scripts folder. + + Now the environment should be active. You can then install packages + listed in ``requirements.txt`` with + + .. code-block:: console + + $ python -m pip install -r requirements.txt + + You can then check e.g. installed versions of Python and ``numpy``: + + .. code-block:: console + + $ python -c 'import sys; import numpy; print(f"Python version: {sys.version}\nNumPy version: {numpy.__version__}")' + Python version: 3.10.12 (main, Sep 11 2024, 15:47:36) [GCC 11.4.0] + NumPy version: 2.1.2 + + To deactivate the environment, you can run: + + .. code-block:: console + + $ deactivate + + +.. admonition:: Creating environments without environment.yml/requirements.txt + + It is possible to create environments with manual commands, but this + is highly discouraged for continuous use. + + Firstly, replicating the environment becomes much harder. + + Secondly, running package installation commands manually in an + environment can result in unexpected behaviour such as: + + - Package manager might remove an already installed packages or update them. + - Package manager might not find a package that works with already + installed packages. + + The reason for this behavior is that package managers does not know what + commands you ran in the past. It only knows the state of your environment + and what you're currently telling it to install. + + These kinds of problems can be mitigated by recording dependencies in an + ``environment.yml`` or ``requirements.txt`` and using the relevant + package manager to update / recreate the environment. + + +Exercise 3 +---------- + +.. challenge:: Dependencies-3: Create a Python environment (15 min) + + Use conda or venv to create the environment presented in the + example. + + +Adding more packages to existing environments +--------------------------------------------- + +Quite often when you're creating a new environment you might forget +to add all relevant packages to ``environment.yml`` or +``requirements.txt``. + +In these cases the best practice is to add missing packages to +``environment.yml`` or ``requirements.txt`` and to update the environment. + +.. tabs:: + + .. group-tab:: Adding new packages to a conda environment + + Add new packages that you want to install to + ``dependencies`` in + ``environment.yml``. + + Afterwards, run + + .. code-block:: console + + $ conda env update --file environment.yml + + to update the environment. + + .. group-tab:: Adding new packages to a virtual environment + + Add new packages that you want to install to + ``requirements.txt``. + + Afterwards, activate the environment and re-run + + .. code-block:: console + + $ pip install -r requirements.txt + + to update the environment. + +Sometimes the new packages are incompatible with the ones already +in the environment. Maybe they have different dependencies that are +not satisfied with the current versions, maybe the package you're installing +is incompatible with the ones installed. In these cases the safest approach +is to re-create the environment. This will let the dependency solvers +to start from clean slate and with a full picture of what packages +need to be installed. + + +Pinning package versions +------------------------ + +Sometimes your code will only work with a certain range of dependencies. +Maybe you use a function or a class that was introduced in a later version +or a newer version has modified its API. + +In these situations, you'll want to **pin the package versions**. + +For example, there is usually a delay between doing research and that +research being published. During this time packages used in the research +might update and reviewers or interested researchers might not be able +to replicate your results or run your code if new versions are not +compatible. + +.. tabs:: + + .. group-tab:: environment.yml with pinned versions + + When pinning versions in ``environment.yml`` one can use a + variety of comparison operators: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + # Use python 3.11 + - python=3.11 + # numpy that is bigger or equal than version 1, but less than version 2 + - numpy>=1,<2 + # matplotlib greater than 3.8.2 + - matplotlib>3.8.2 + # pandas that is compatible with 2.1 + - pandas~=2.1 + + .. group-tab:: requirements.txt with pinned versions + + When pinning versions in ``requirements.txt`` one can use a + variety of comparison operators: + + .. code-block:: text + + # numpy that is bigger or equal than version 1, but less than version 2 + numpy>=1,<2 + # matplotlib greater than 3.8.2 + matplotlib>3.8.2 + # pandas that is compatible with 2.1 + pandas~=2.1 + +For more information on all possible specifications, see +`this page `__ +from Python's packaging guide. + +See also: https://coderefinery.github.io/reproducible-research/dependencies/ + +.. admonition:: To pin or not to pin? That is the question. + + Pinning versions means that you pin the environment to + **that instance in time** when these specific versions of the + dependencies were being used. + + This can be good for single-use applications, like replicating a research + paper, but it is usually bad for the long-term maintainability of the software. + + Pinning to major versions or to compatible versions is usually the best + practice as that allows your software to co-exist with other packages even + when they are updated. + + Remember that at some point in time you **will** face a situation where + newer versions of the dependencies are no longer compatible with your + software. At this point you'll have to update your software to use the newer + versions or to lock it into a place in time. + + +Exporting package versions from an existing environment +------------------------------------------------------- + +Sometimes you want to create a file that contains the exact versions +of packages in the environment. This is often called *exporting* or +*freezing* and environment. + +Doing this will create a file that does describe the installed +packages, but it won't tell which packages are **the most important +ones** and which ones are just dependencies for those packages. + +Using manually created ``environment.yml`` or ``requirements.txt`` +are in most cases better than automatically created ones because they +shows which packages are the important packages needed by the software. + +.. tabs:: + + .. group-tab:: Exporting environment.yml from a conda environment + + Once you have activated the environment, you can run + + .. code-block:: console + + $ conda env export > environment.yml + + If package build versions are not relevant for the use case, + one can also run + + .. code-block:: console + + $ conda env export --no-builds > environment.yml + + which leaves out the package build versions. + + Alternatively one can also run + + .. code-block:: console + + $ conda env export --from-history > environment.yml + + which creates the ``environment.yml``-file based on + what packages were asked to be installed. + + .. admonition:: conda-lock + + For even more reproducibility, you should try out + `conda-lock `__. + It turns your ``environment.yml`` into a ``conda.lock`` + that has all information needed to **exactly** create + the same environment. You can use ``conda.lock``-files + in same way as ``environment.yml`` when you create + an environment: + + .. code-block:: console + + $ conda env create --file conda.lock + + .. group-tab:: Exporting requirements.txt from a virtual environment + + Once you have activated the environment, you can run + + .. code-block:: console + + $ pip freeze > requirements.txt + + + +Exercise 4 +---------- + +.. challenge:: Dependencies-4: Export an environment (15 min) + + Export the environment you previously created. + + +Additional tips and tricks +-------------------------- + +.. tabs:: + + .. group-tab:: Creating a conda environment from requirements.txt + + conda supports installing an environment from ``requirements.txt``. + + .. code-block:: console + + $ conda env create --name my-environment --channel conda-forge --file requirements.txt + + To create an ``environment.yml`` from this environment that mimics + the ``requirements.txt``, activate it and run + + .. code-block:: console + + $ conda env export --from-history > environment.yml + + .. group-tab:: Adding pip packages into conda environments + + conda supports installing pip packages in an ``environment.yml``. + + Usually this is done to add those packages that are missing + from conda channels. + + To do this you'll want to install ``pip`` into the environment + and then add pip-installed packages to a list called ``pip``. + + See this example ``environment.yml``: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + - python + - pip + - pip: + - numpy + - matplotlib + - pandas + + One can even add a full ``requirements.txt`` to the environment: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + - python + - pip + - pip: + - "-r requirements.txt" + + Do note that in both methods the pip-packages come from PyPI + and not from conda channels. The installation of these packages + is done after conda environment is created and this can also + remove or update conda packages installed previously. + + .. group-tab:: Installing pip packages from GitHub + + Packages available in GitHub or other repositorios + can be given as a URL in ``requirements.txt``. + + For example, to install a development version of the + `black code formatter `__, one can + write the following ``requirement.txt``. + + .. code-block:: text + + git+https://github.com/psf/black + + or + + .. code-block:: text + + https://github.com/psf/black/archive/master.zip + + First one would use git to clone the repository, second would + download the zip archive of the repository. + + +How to communicate the dependencies as part of a report/thesis/publication +-------------------------------------------------------------------------- + +Each notebook or script or project which depends on libraries should come with +either a ``requirements.txt`` or a ``environment.yml``, unless you are creating +and distributing this project as Python package (see next section). + +- Attach a ``requirements.txt`` or a ``environment.yml`` to your thesis. +- Even better: put ``requirements.txt`` or a ``environment.yml`` in your Git repository along your code. +- Even better: also binderize your analysis pipeline (more about that in a later session). + + +.. _version_pinning: + +Version pinning for package creators +------------------------------------ + +We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in ``pyproject.toml`` (or ``setup.py``) +(PyPI) or ``meta.yaml`` (conda). + +These dependencies will then be used by either other libraries (who in turn +write their own ``setup.py`` or ``pyproject.toml`` or ``meta.yaml``) or by +people directly (filling out ``requirements.txt`` or a ``environment.yml``). + +Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from ``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy==1.19.2', + 'matplotlib==3.3.2' + 'pandas==1.1.2' + 'scipy==1.5.2' + ] + # ... + +or you can define a range or keep them undefined like here (example taken from +``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy', + 'matplotlib' + 'pandas' + 'scipy' + ] + # ... + +Should we pin the versions here or not? + +- Pinning versions here would be good for reproducibility. + +- However pinning versions may make it difficult for this library to be used in a project alongside other + libraries with conflicting version dependencies. + +- Therefore **as library creator make the version requirements as wide as possible**. + + - Set minimum version when you know of a reason: ``>=2.1`` + + - Sometimes set maximum version to next major version (``<4``) (when + you currently use ``3.x.y``) when you expect issues with next + major version. + +- As the "end consumer" of libraries, define your dependencies as narrowly as possible. + + +See also +-------- + +Other tools for dependency management: + +- `Poetry `__: dependency management and packaging +- `Pipenv `__: dependency management, alternative to Poetry +- `pyenv `__: if you need different Python versions for different projects +- `micropipenv `__: lightweight tool to "rule them all" +- `mamba `__: a drop in replacement for + conda that does installations faster. +- `miniforge `__: Miniconda alternative with + conda-forge as the default channel and optionally mamba as the default installer. +- `micromamba `__: + tiny version of Mamba as a static C++ executable. Does not need base environment or + Python for installing an environment. +- `pixi `__: a package management tool which builds upon the foundation of the conda ecosystem. + +Other resources: + +- https://scicomp.aalto.fi/scicomp/packaging-software/ + + +.. keypoints:: + + - If somebody asks you what dependencies your code has, you should be able to answer this question **with a file**. + - Install dependencies by first recording them in ``requirements.txt`` or + ``environment.yml`` and install using these files, then you have a trace. + - Use isolated environments and avoid installing packages system-wide. diff --git a/_sources/exercises.md.txt b/_sources/exercises.md.txt new file mode 100644 index 00000000..61028b90 --- /dev/null +++ b/_sources/exercises.md.txt @@ -0,0 +1,12 @@ +# List of exercises + +## Full list + +This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests. + +```{exerciselist} +``` diff --git a/_sources/guide.rst.txt b/_sources/guide.rst.txt new file mode 100644 index 00000000..3dc6f602 --- /dev/null +++ b/_sources/guide.rst.txt @@ -0,0 +1,125 @@ +Instructor's guide +================== + +Learner personas +---------------- + +A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don't know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren't sure if they +are going in the right direction. + +A2 can use numpy and pandas, but have learned little bits here and +there and hasn't had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages) + +B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves. + + +Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren't familiar. + +Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter + + + +About each section +------------------ + +In general, "Python for Scientific Computing could be a multi-year +course. We can't even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path. + +* **Python intro:** We can't really replace a Python tutorial, but + here we try to outline some of the main points. We don't go over + this in the course. + +* **Jupyter:** Jupyter is somewhat useful, but the main reason we go + over it is that it provides a convenient user interface for the + other programming lessons (it's easier to spend a bit of time with + Jupyter than expect people to be able to use some + editor/IDE/shell/etc). So, we do start from the beginning, so that + people can do the other lessons, but also try to teach some advanced + tips and tricks. + +* **Numpy:** The basic of much of the rest of scipy, so we need to + cover it. We try to get the main principles out, but if someone + already knows it this can be a bit boring. We try to make sure + everyone comes out with an appreciation for vectorization and + broadcasting. + +* **Pandas:** A lot of similar goals to the Numpy section, especially + the concepts behind Dataframes that one needs to know in order to + read other documentation. + +* **Visualization:** Matplotlib is getting a bit old, but is still the + backbone of other plotting packages. We try to get forth the ideas + of the matplotlib API that can be seen in other packages and the + importance of scripted plots. + +* **Data formats:** Input/output/storage is a common task, and can + easily either be a bottleneck or a huge mess. This lessons tries to + show some best practices with data formats and, as usual, get the + idea to not "do it yourself". Pandas is used as a common framework, + but we should point out there are plenty of other options. + +* **Scripts:** The most important lesson here is to break out of + Jupyter/run buttons of editors. If you can't make actual programs + with an actual interface, you can't scale up. + + * This is the first lesson to introduce the command line. We + recommend being as simple as possible: at least demonstrate the + JupyterLab terminal and discuss the bigger picture behind what it + means and why. + + * This is also the first lesson to use non-Jupyter code editor. We + recommend again being simple: use the JupyterLab code editor to + start off, and carefully explain what is going on. + +* **Scipy:** We don't cover much here (this is super short), but the + point is scipy exists and the concept of wrapping existing C/fortran + libraries and so on. + +* **Library ecosystem:** This was an overview of the types of packages + available in the "scipy ecosystem", which is a large and ill-defined + thing. But there is another point: choosing what to use. Do you + trust a half-done thing published on someone's personal webpage? If + it's on Github? How do you make your code more reusable? When + coming from academic courses, you get a "build it yourself" idea, + which isn't sustainable in research. + +* **Parallel programming:** + +* **Dependencies:** The main point here is environments, another thing + you often don't learn in courses. + + * There is a lot of material here. Consider what you will demo, + what will be done as exercises, and what is advanced/optional. + However, it is the fourth-day lesson that is most interactive, so + it is OK if it take a while to go through everything. + + * If someone else installs Anaconda for a user (e.g. admin-managed + laptop), the conda environment creations (with ``--name``, + possibly with ``--prefix`` too?) may not work. Be prepared for + this and mention it. You don't need to solve the problem but + acknowledge that the lesson becomes a demo. The virtualenv part + should hopefully work for them. + +* **Binder:** Binder exists and can help make code + reproducible/reusable by others. + +* **Packaging:** How to make your code reusable by others. By the + time we get here, people are tired and the topics get involved. We + more explicitly say "you might want to watch and take this as a + demo". + diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 00000000..ac71a0a0 --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,238 @@ +=============================== +Python for Scientific Computing +=============================== + +.. admonition:: Attending the course 5-7 November, 2024? + + `See the course page here + `__ + and watch at https://twitch.tv/coderefinery. + Whether you are or aren't, the course material is below. Videos + will appear in `this playlist `__ (Last year's videos: `playlist `__). + + +Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, Matplotlib for visualization, and so on. In +addition, it talks about *how* python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write. + +This course (like any course) can't teach you Python... it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to. + +.. _prerequisites: + +.. prereq:: + + - Knowing basic Python syntax. We assume that you can do some + Python programming, but not much more that that. We don't cover + standard Python programming. `Here a short course on basic Python + syntax, with further references `__. + - Watch or read the `command line crash course + `__, if you aren't + familiar. + - You should be able to use a text editor to edit files some. + - The :doc:`software installation ` described below + (basically, anaconda). + + These are not prerequisites: + + - Any external libraries, e.g. numpy + - Knowing how to make scripts or use Jupyter + + +.. admonition:: Videos and archived Q&A + + Videos and material from past instances: + + * 2021: `this YouTube playlist + `__. + * 2022: `here + `__, + Q&A: `days 1-2 + `__, `days 3-4 + `__ + + * 2023: `Videos + `__ + + * 2024 (Please contact us if you would like to help to process the videos): `Videos `__ + + +.. csv-table:: + :widths: auto + :delim: ; + + (prereq) ; :doc:`python` + 30 min ; :doc:`jupyter` + 60 min ; :doc:`numpy` or :doc:`numpy-advanced` + 60 min ; :doc:`pandas` + 30 min ; :doc:`xarray` + 60 min ; :doc:`plotting-matplotlib` + 60 min ; :doc:`plotting-vega-altair` + 30 min ; :doc:`work-with-data` + 60 min ; :doc:`scripts` + 40 min ; :doc:`profiling` + 20 min ; :doc:`productivity` + 30 min ; :doc:`web-apis` + 15 min ; :doc:`scipy` + 30 min ; :doc:`libraries` + 45 min ; :doc:`parallel` + 45 min ; :doc:`dependencies` + 30 min ; :doc:`binder` + 60 min ; :doc:`packaging` + + +.. toctree:: + :maxdepth: 1 + :caption: The lesson + :hidden: + + python + jupyter + numpy + numpy-advanced + pandas + xarray + plotting-matplotlib + plotting-vega-altair + work-with-data + scripts + profiling + productivity + scipy + libraries + dependencies + binder + parallel + packaging + web-apis + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + installation + quick-reference + exercises + guide + data-formats + + +.. _learner-personas: + +Who is the course for? +====================== + +The course is targeted towards these learner personas: + +* A is a early career PhD researcher who has been using Python a bit, + but is not sure what they know or don't know. They want to be able + to do their research more efficiently and make sure that they are + using the right tools. A may know that numpy exists, etc. and could + theoretically read some about it themselves, but aren't sure if they + are going in the right direction. + +* A2 can use numpy and pandas, but have learned little bits here and + there and hasn't had a comprehensive introduction. They want to + ensure they are using best practices. (Baseline of high-level + packages) + +* B is a mid-to-late undergraduate student who has used Python in some + classes. They have possibly learned the syntax and enough to use it + in courses, but in a course-like manner where they are expected to + create everything themselves: they want to know how to reuse tools + that already exist. + + +Motivation +========== + +Why Python +---------- + +Python has become popular, largely due to good reasons. It's very easy +to get started, there's lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities. + + +Why not Python for Scientific Computing +--------------------------------------- + +While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools. + +- Implementing performance-critical kernels. Python is a **very** + slow language, which often doesn't matter if you can offload the + heavy lifting to fast compiled code, e.g. by using Numpy array + operations. But if what you're trying to do isn't *vectorizable* + then you're out of luck. An alternative to Python, albeit much less + mature and with a smaller ecosystem, but which provides very fast + generated code, is *Julia*. + +- Creating libraries that can be called from other languages. In this + case you'll often want to create a library with a C interface, which + can then be called from most languages. Suitable languages for this + sort of task, depending on what you are doing, could be Rust, C, + C++, or Fortran. + +- You really like static typing, or functional programming + approaches. *Haskell* might be what you're looking for. + + +Python 2 vs Python 3 +-------------------- + +Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard. + +At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2. + + + +Credits +======= + +This course was originally designed by Janne Blomqvist. + +In 2020 it was completely redesigned by a team of the following: + +* Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, ... +* Editor: +* Testers and advisors: Enrico Glerean + +We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html + + +See also +======== + +* `High Performance Data Analytics in Python + `__ is a logical follow-up to + this lesson that goes more in-depth to tools of high-performance + and large-scale Python. diff --git a/_sources/installation.rst.txt b/_sources/installation.rst.txt new file mode 100644 index 00000000..9232223b --- /dev/null +++ b/_sources/installation.rst.txt @@ -0,0 +1,444 @@ +Software installation +===================== + +This course is interactive and demonstrates many different tools. +Thus, even beyond Python, extra software (Python libraries) needs to +be installed. This page contains the instructions. + +**Once the course starts, we don't have time to stop for installing +software.** + +Please make sure before the course that you have all the required +software installed or some other way access to it. For example, the +workshop could be done with a remote Jupyter server, as long as you +can use the terminal from the Jupyter (you need to be able to access +the command line for some lessons). + +.. admonition:: Do you need help? + :class: important + + Participants from a partner institution are invited to install help + sessions. (Hint: ask your institution to become a partner if it + isn't already!) + + Otherwise, if you need installation help, show this page to someone + around you and they can probably help. These are relatively + standard tools. + + Don't be afraid to ask for help. Installing scientific software is + *harder than it should be* and it helps to have someone guide you + through it. + +.. highlight:: console + + + +Python +------ + +We expect you to have a working Python installation with some common +libraries. **We currently recommend Miniforge, which includes the base and +packages through a different, freely usable channel.** You can +explore the options in the tabs below. + +.. admonition:: Python, conda, anaconda, miniforge, etc? + :class: dropdown + + Unfortunately there's a lot of jargon. We'll go over this in the + course but here is a crash course: + + * **Python** is a programming language very commonly used in + science, it's the topic of this course. + * **Conda** is a package manager: it allows distributing and + installing packages, and is designed for complex scientific + code. + * **Mamba** is a re-implementation of Conda to be much faster with + resolving dependencies and installing things. + * An **Environment** is a self-contained collections of packages + which can be installed separately from others. They are used so + each project can install what it needs without affecting others. + * **Anaconda** is a commercial distribution of Python+Conda+many + packages that all work together. It used to be freely usable for + research, but since ~2023-2024 it's more limited. Thus, we don't + recommend it (even though it has a nice graphical user interface). + * **conda-forge** is another channel of distributing packages that + is maintained by the community, and thus can be used by anyone. + (Anaconda's parent company also hosts conda-forge packages) + * **miniforge** is a distribution of conda pre-configured for + conda-forge. It operates via the command line. + * **miniconda** is a distribution of conda pre-configured to use + the Anaconda channels. + +.. tabs:: + + .. group-tab:: Miniforge + + This is our recommended method - it can be used for any purpose + and makes a strong base for the future. + + Follow the `instructions on the miniforge web page + `__. This installs + the base, and from here other packages can be installed. + + .. + You can read how to install miniconda from the `CodeRefinery + installation instructions + `__. + + Miniforge uses the command line - this gives you the most power + but can feel unfamiliar. See the `command line crash course + `__ for an intro. + + .. group-tab:: Anaconda + + Anaconda is easier to get started with, but may be more limiting + in the future. The Anaconda Navigator provides a graphical + interface to most of what you would need. + + The `Anaconda Python distribution + `__ conveniently packages + everything, but its license has does not allow large organizations to + use it for free (and has actually been enforced against + universities). + + Note the license of Anaconda - there were recently issues with + it being used by large universities for free, and this is not + yet fully resolved. + + .. group-tab:: Other options + + There are many ways to install Python. Other methods can work, + as long as you can install the libraries from the + ``environment.yml`` file mentioned in the Miniforge + instructions. + + We don't currently provide a ``requirements.txt`` for installing + the required packages without Conda/Mamba, though. + + + +Starting Python +--------------- + +You need to Python in a way that activates conda/mamba. + +.. tabs:: + + .. group-tab:: Miniforge + + .. tabs:: + + .. group-tab:: Linux / MacOS + + Linux/MacOS: Each time you start a new command line terminal, + you can activate Miniforge by running. This is needed so that + Miniforge is usable wherever you need, but doesn't affect any + other software on your computer (this is not needed if you + choose "Do you wish to update your shell profile to + automatically initialize conda?", but then it will always be + active):: + + $ source ~/miniforge3/bin/activate + + .. group-tab:: Windows + + Windows: Use the "Miniforge Prompt" to start Miniforge. This + will set up everything so that ``conda`` and ``mamba`` are + available. + + .. group-tab:: Anaconda + + The `Anaconda Navigator + `__ provides a convenient + way to access the software. It can be installed from that page. + + + .. group-tab:: Other options + + You are on your own here. + + +Python for SciComp software environment +--------------------------------------- + +Once Python and conda/mamba are installed, you can use it to install +an environment. An **environment** is a self-contained set of extra +libraries - different projects can use different environments to not +interfere with each other. This environment will have all of the +software needed for this particular course. + +.. tabs:: + + .. group-tab:: Miniforge + + This `environment file + `__ + contains all packages needed for the course, and can be + installed with. The following command will install an + environment named ``python-for-scicomp`` (there may be lots of + warning messages: this is OK if it still goes through): + + .. tabs:: + + .. group-tab:: Linux / MacOS + + :: + + $ mamba env create -n python-for-scicomp -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + .. group-tab:: Windows + + :: + + $ mamba env create -n python-for-scicomp -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + Each time you start a new command line, you need to activate + miniforge and this environment: + + .. tabs:: + + .. group-tab:: Linux / MacOS + + :: + + $ source ~/miniforge3/bin/activate + $ conda activate python-for-scicomp + + .. group-tab:: Windows + + :: + + $ # Start the Miniforge Prompt. + $ conda activate python-for-scicomp + + .. group-tab:: Anaconda + + Anaconda includes most of the things needed for the course + automatically, but as of 2024 not everything. You can use the + navigator to create new environments from this `this environment + file + `__. + You'll have to download it and then `import it + `__. + + When running this course's exercise, make sure the + ``python-for-scicomp`` environment is activated before starting + JupyterLab or any code. You need to start termnials or + JupyterLab from the Anaconda Navigator for the + ``python-for-scicomp`` environment to be used. + + .. group-tab:: Other options + + **Minoconda, Anaconda command line, other conda/mamba command + line tools**: see "Miniforge" instructions. + + Virtual environments: we don't currently provide a + ``requirements.txt`` but many package names can probably be + copied from the ``environment.yml`` file. We really recommend + conda/mamba based systems: it's designed for complex scientific + software. + + Any other Python distribution which you can install libraries into + would work, but because there are so many different ways to do this, + we don't support them. You would need the extra libraries mentioned + in the Miniforge instructions. + + Remember you need to activate the environment each time you use it. + + + +JupyterLab +---------- + +We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). + +.. tabs:: + + .. group-tab:: Miniforge + + JupyterLab was instaled in the previous step. To run it, first, + start the Miniforge command line interface. Remember, you may + need to activate Miniforge and the environment first. + + .. tabs:: + + .. group-tab:: Linux / MacOS + + :: + + $ source ~/miniforge3/bin/activate + $ conda activate python-for-scicomp + $ jupyter-lab + + .. group-tab:: Windows + + :: + + $ # Start the Miniforge Prompt. + $ conda activate python-for-scicomp + $ jupyter-lab + + .. group-tab:: Anaconda + + If you install the full Anaconda distribution, this will be + available and can be started either through Anaconda Navigator + or command line. + + Make sure the ``python-for-scicomp`` environment is selected and + you can start JupyterLab. + + + +Verification of Python and JupyterLab +------------------------------------- + +.. admonition:: Watch the video + + See this `verification in video form + `__ - if you can do this, you are + ready to go for day one. Your exact steps may be a bit different. + + Remember that you need to activate the environment first - see the + step above. + +.. tabs:: + + .. group-tab:: Miniforge + + You can start JupyterLab from the command line:: + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + .. group-tab:: Anaconda + + **You should be able to start JupyterLab.** You can do this from the + `Anaconda Navigator `__ (recommended if you have it): + + .. figure:: img/installation/anaconda-navigator-jupyterlab.png + :class: with-border + + Starting JupyterLab from the Anaconda Navigator. + + ... or you can start JupyterLab from the command line:: + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + +**Verify that you can start a Jupyter notebook.** We will learn how to +do this in day 1, but you can try running ``print("Hello, world!")`` +if you want. + +.. figure:: img/installation/jupyterlab-notebook.png + :class: with-border + + Starting a Jupyter Notebook from JupyterLab. + + + +Text editor +----------- + +For one portion of the course, you will need a text editor. **If you +don't know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.** + +.. admonition:: Other editors + :class: toggle + + Because we need to be simple in our teaching, we only teach the + most basic editors. We encourage you to try out more advanced ones + yourself. + + For other editors, see the `CodeRefinery instructions + `__. You don't + exactly need a terminal editor - the graphical ones, such as VSCode or + whatever you use now, will work as well. + + + +Command line +------------ + +**You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed.** If you want to +test in advance: + +* You can start it from JupyterLab (recommended): + + .. figure:: img/installation/jupyterlab-terminal.png + :class: with-border + :scale: 75% + + From the JupyterLab launcher, select "Terminal". + +.. admonition:: Other ways to access the command line + :class: toggle + + * From the Anaconda Navigator: + + .. figure:: img/installation/anaconda-prompt.png + :class: with-border + + From the Anaconda Navigator, you can select "environments" on the + left, then click on one, then the arrow, then "Open terminal". + + * From your operating system's terminal applications, if you activate + Anaconda. + + + +Verification of the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify command line usage, type the following commands (without the +``$``), and you should see the corresponding output that lists the +Python version: + +.. code-block:: console + + $ python3 -V + Python 3.8.3 + + ## Or python... if it's installed as that + $ python -V + Python 3.8.3 + +Any recent version of Python 3 should work for the course (for example +3.8 or higher). + + + +Zoom +---- + +If this is an online workshop, it might use Zoom. You can see +`CodeRefinery instructions for it +`__. + + + +Need help? +---------- + +If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up! + + + +See also +-------- + +* `Research Software Hour on conda + `__ +* `Conda manual `__ (technical) +* `Anaconda individual edition home + `__ +* `Anaconda getting started + `__ diff --git a/_sources/jupyter.ipynb.txt b/_sources/jupyter.ipynb.txt new file mode 100644 index 00000000..16aa6435 --- /dev/null +++ b/_sources/jupyter.ipynb.txt @@ -0,0 +1,471 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter\n", + "\n", + "\n", + "```{questions}\n", + "\n", + " - What is the purpose of a \"Computational narrative\"?\n", + " - What role does Jupyter play in development?\n", + " - When is Jupyter not a good tool?\n", + "```\n", + "\n", + "```{objectives}\n", + "\n", + " This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.\n", + "\n", + " - Be able to use Jupyter to run examples for the rest of the course.\n", + " - Be able to run Jupyter in a directory do your own work.\n", + " - You won't be a Jupyter expert after this, but should be able to do the rest of the course.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is Jupyter?\n", + "\n", + "Jupyter is a web-based interactive computing system. It is most well known for having the *notebook file format* and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a *computational narrative*.\n", + "\n", + "Jupyter is good for data exploration and interactive work.\n", + "\n", + "**We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.**\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting started with Jupyter\n", + "\n", + "* Start JupyterLab: there are different ways, depending on how you installed it. See the [installation instructions](https://aaltoscicomp.github.io/python-for-scicomp/installation/). If JupyterLab isn't working yet, you have some time to try to follow the installation instructions now.\n", + "\n", + "```````{tabs}\n", + "``````{group-tab} Miniforge\n", + "This is the command line method we went though in our installation instructions.\n", + "`````{tabs}\n", + "````{group-tab} Linux / MacOS\n", + "```console\n", + "$ source ~/miniforge3/bin/activate\n", + "$ conda activate python-for-scicomp\n", + "$ jupyter-lab\n", + "```\n", + "````\n", + "````{group-tab} Windows\n", + "Start the Miniforge Prompt applicaiton first, then:\n", + "```console\n", + "$ conda activate python-for-scicomp\n", + "$ jupyter-lab\n", + "```\n", + "````\n", + "``````\n", + "``````{group-tab} Anaconda\n", + "If you install the full Anaconda distribution, start the Anaconda Navigator. Make sure the ``python-for-scicomp`` environment is selected and you can start JupyterLab.\n", + "``````\n", + "``````{group-tab} Other\n", + "If you have installed Python and the workshop's requiremnts some other way, you hopefully know how to activate that Python and the Python for SciComp software environment and start JupyterLab.\n", + "\n", + "If not, see the [installation instructions](https://aaltoscicomp.github.io/python-for-scicomp/installation/).\n", + "``````\n", + "```````\n", + "\n", + "\n", + "For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here, we see a tour of the JupyterLab interface:\n", + "\n", + "![Main UI tour](img/jupyter/main-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 1\n", + "```{challenge} Exercises: Jupyter-1\n", + "\n", + " If you aren't set up with JupyterLab yet or these things don't work, use this time to see the [installation instructions](https://aaltoscicomp.github.io/python-for-scicomp/installation/) and ask us any questions you may have.\n", + "\n", + " 1. Start Jupyter in the directory you want to use for this course.\n", + " - If you are using Miniforge from the command line, you can navigate with `cd` to a directory of your choice.\n", + " - If you are starting from the Anaconda Navigator, change to the directory you want to use.\n", + "\n", + " 2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.\n", + "\n", + " 4. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.\n", + "\n", + " 5. (optional, advanced) Look at the notebook file in a text\n", + " editor. How does it work?\n", + "\n", + "If everything works for you, this will end very quickly. You can begin reading the next sections independently.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Running code in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A notebook is divided into **cells**. Each cell has some **input**, and when it is executed an **output** appears right below it.\n", + "\n", + "There are different types of cells: primarily **code** cells and **markdown** cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/). For example the previous sentence is:\n", + "\n", + "```none\n", + "Markdown is a lightweight way of giving *style* to `text` - you \n", + "can check out [this reference](https://commonmark.org/help/).\n", + "```\n", + "\n", + "![notebook UI](img/jupyter/notebook-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When using keyboard shortcuts, you can switch between edit mode and command mode with `Enter` and `Esc`. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:\n", + "* `Ctrl-Enter`: Run cell\n", + "* `Shift-Enter`: Run cell and select cell below\n", + "* `Alt-Enter`: Run cell and insert new cell below\n", + "* `a` / `b`: insert new cell above/below\n", + "* `m` / `y`: markdown cell / code cell\n", + "* `x`: cut cell\n", + "* `c`: copy cell\n", + "* `v`: paste cell\n", + "* `d, d`: delete cell" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, let's look at some code samples:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0\n", + "1\n", + "2\n" + ] + } + ], + "source": [ + "for i in range(3):\n", + " print(i)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "10\n" + ] + } + ], + "source": [ + "print(sum(range(5)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By convention, if the last thing in a cell is an object, that object gets printed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "45" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sum(range(5))\n", + "sum(range(10))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to raw cells, there are **magics**, which exist outside of Python. They are a property of the runtime itself (in Python's case, they come from **IPython**. For example, the following cell magic [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) will use the {py:mod}`timeit` module to time a cell by running it multiple times):" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "54.1 ms ± 993 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "for x in range(1000000):\n", + " x**2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Another example is [%%bash](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-bash) which will turn the cell into a shell script (This will only work on operating systems with the Bash shell installed - MacOS and Linux at least):" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1\n", + "2\n", + "3\n" + ] + } + ], + "source": [ + "%%bash\n", + "for x in $(seq 3) ; do\n", + " echo $x\n", + "done" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "* A **cell magic** starts with `%%`, goes on the first line of a cell, and applies to the whole cell\n", + "* A **line magic** starts with `%`, goes on any line, and applies to that line." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "```{challenge} Exercises: Jupyter-2\n", + "\n", + " 1. Run some trivial code, such as ``print(1)``.\n", + "\n", + " 2. Run some slightly less trivial code, like print out the first\n", + " ten [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number).\n", + "\n", + " 3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the [reference](https://commonmark.org/help/) to add a heading, bullet list, and some (bold, italic, or inline code)\n", + "\n", + " 4. Use the [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) magic function to time your Fibonacci\n", + " function.\n", + "\n", + " 5. Again using ``%%timeit``, figure out the fastest way to sum the\n", + " numbers 0 to 1000000.\n", + " \n", + " 6. Once you are done, close your notebooks and other tabs you don't need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.\n", + "```\n", + "\n", + "`````{solution} Solutions: Jupyter-2\n", + "\n", + "1. --\n", + "\n", + "2. Simple fibonacci code\n", + "\n", + " ```python\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " print(a)\n", + " a, b = b, a+b\n", + " ```\n", + "\n", + "3. Markdown description\n", + "\n", + " ```md\n", + " # Fibonacci\n", + " * Start with two variables `a` and `b`\n", + " * Repeat 10 times\n", + " * Print old `a`, then increment both\n", + " * Makes use of the Python *tuple assignment*: `a, b = new_a, new_b`\n", + " ```\n", + "\n", + "4. In this case, the print() statements get out of hand, so we comment that out. In general, writing output usually takes a lot of time reletive to the computation, so we don't want to time that (unless output is the main point of the code, then we do have to time it!\n", + "\n", + " ```ipython\n", + " %%timeit\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " #print(a)\n", + " a, b = b, a+b\n", + " ```\n", + " ```none\n", + " 395 ns ± 10.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n", + " ```\n", + "\n", + "5. --\n", + "\n", + "6. --\n", + "\n", + "`````" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why Jupyter?\n", + "\n", + "- Being able to **edit, check, re-edit** quickly is great for **prototyping and testing new ideas**\n", + " - Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.\n", + "- You can make a **complete story** - in one place. No more having code, figures, and description in different places.\n", + " - Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.\n", + "- Notebook as an interactive publication itself - for example the discovery of gravitational waves data is [released as a notebook](https://www.gw-openscience.org/tutorials/).\n", + "- Jupyter Notebooks display on Github - low-barrier way to share your analysis.\n", + "- Teaching - great for getting difficult software distribution out of the way." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why not Jupyter?\n", + "\n", + "Jupyter is great for many things, but there are some problems if not used well:\n", + "\n", + "- They **don't promote modularity**, and once you get started in a\n", + " notebook it can be hard to migrate to modules.\n", + "- They are **difficult to test**. There are things to run notebooks as\n", + " unit tests like [nbval](https://nbval.readthedocs.io/), but it's not\n", + " perfect.\n", + "- Notebooks can be **version controlled**\n", + " ([nbdime](https://nbdime.readthedocs.io/) helps with that), but\n", + " there are **still limitations**.\n", + "- You can **change code after you run it** and run code out of order.\n", + " This can make debugging hard and results irreproducible if you\n", + " aren't careful.\n", + "- Notebooks **aren't named by default** and tend to **acquire a bunch of\n", + " unrelated stuff**. Be careful with organization!\n", + "- Once lots of code is in notebooks, it can be **hard to change to\n", + " proper programs that can be scripted**.\n", + "\n", + "You can read more about these downsides .\n", + "\n", + "**But these downsides aren't specific to Jupyter!** They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "```{challenge} Exercises: Jupyter-3\n", + "\n", + " (optional) Discuss the following in groups:\n", + "\n", + " 1. Have any of you used Jupyter in a way that became impossible to\n", + " maintain: too many files, code all spread out, not able to find\n", + " your code and run it in the right order. How did you solve that?\n", + "\n", + " 2. On the other hand, what are your successes with Jupyter?\n", + " \n", + " 3. How can you prevent these problems by better development strategies?\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## See also\n", + "\n", + "- The [CodeRefinery Jupyter lesson](https://coderefinery.github.io/jupyter/) has much more, and the source of some of the content above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{keypoints}\n", + "\n", + " - Jupyter is powerful and can be used for interactive work\n", + " - ... but not the end solution when you need to scale up.\n", + "```" + ] + } + ], + "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.12.7" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/_sources/libraries.rst.txt b/_sources/libraries.rst.txt new file mode 100644 index 00000000..72473aa8 --- /dev/null +++ b/_sources/libraries.rst.txt @@ -0,0 +1,353 @@ +Library ecosystem +================= + +.. questions:: + + - What happens when you need some method beyond what we discuss in this course, what is available? + - How do you decide what to build on for your work? + +.. objectives:: + + - Know of some other available packages, but don't necessarily know + how to use them. + - Be able to evaluate what you should reuse and what you should + develop yourself. + +You can't do everything yourself. In fact, once we heard a quote such +as this: + + When you are a student, you are expected to do everything + yourself, and that is how you are evaluated. When you become a + researcher, you *have* to be able to reuse what others have done. + We don't have much practice in doing this. + -- A student + +In this lesson, we'll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types: + +- Well-maintained libraries that are used by many others. +- A wide variety of public code that might work but isn't necessarily + well-maintained (for example, code from articles). + +We'll start with the first then go to the second. + + + +Glossary +-------- + +Library + A collection of code used by a program. + +Package + A library that has been made easily installable and reusable. + Often published on public repositories such as the `Python Package + Index `__ + +Dependency + A requirement of another program, not included in that program. + + + +The Python/SciPy ecosystem +-------------------------- + +This section is nothing more than a tour of what exists in Python. +You aren't expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work. + +The "core" packages `could be considered +`__. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy): + +* Python +* Numpy - arrays, everything builds on this +* Scipy - scientific functions (not necessarily a lot builds on this) +* matplotlib - plotting, many other plotting tools build on this +* pandas - data structures +* IPython / Jupyter: interactive work + + + +Core numerics libraries +~~~~~~~~~~~~~~~~~~~~~~~ + +* `numpy `__ - arrays and array math. +* `scipy `__ - software + for math, science, and engineering. + + + +Plotting +~~~~~~~~ + +* `matplotlib `__ - base plotting package, + somewhat low level but almost everything builds on it. +* `seaborn `__ - higher level plotting + interface; statistical graphics. +* `mayavi `__ - 3D plotting +* `PIL `__ - image manipulation. The + original PIL is no longer maintained, the new "Pillow" is a drop-in + replacement. + + + +Data analysis and other important core packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `pandas `__ - columnar + data analysis +* `statsmodels `__ - just what it says +* `SymPy `__ - symbolic math +* `networkx `__ - graph and network analysis +* `h5py `__ and `PyTables `__ - interfaces to + the `HDF5 `__ on-disk file format +* `dateutil `__ and `pytz + `__ - date arithmetic and handling, + timezone database and conversion + + + +Interactive computing and human interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Interactive computing + + * `IPython `__ - nicer interactive interpreter + * `Jupyter `__ (notebook, lab, hub, ...) - + web-based interface to IPython and other languages + +* Testing + + * `pytest `__ - automated testing interface + +* Documentation + + * `Sphinx `__ - documentation generator + (also used for this lesson...) + +* Development environments + + * `Spyder `__ - interactive Python + development environment. + +* `Binder `__ - load any git repository in + Jupyter automatically, good for reproducible research + + + +Speeding up code and parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `PyMPI `__ - Message + Passing Interface (MPI) in Python for parallelizing jobs. +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `numba `__ - just in time compiling of + functions for speed-up +* `PyPy `__ - Python written in Python so that + it can internally optimize more. +* `Dask `__ - distributed array data structure for + distributed computation +* `Joblib `__ - easy embarrassingly + parallel computing +* `IPyParallel `__ - easy + parallel task engine +* `numexpr `__ - Fast evaluation of + array expressions by automatically compiling the arithmetic. + + + +Machine learning +~~~~~~~~~~~~~~~~ + +If you need some machine learning, you probably already know what you +need and this list is short and irrelevant. + +- `tensorflow `__ +- `pytorch `__ +- `nltk `__ - natural language processing +- `scikit-learn `__ - simple tools for + predictive data analysis + + + +Connecting Python to other languages +------------------------------------ + +As we discussed with Scipy, very many of the above packages aren't +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things: + +* **Extending Python** by writing your own modules in C. + + * It's actually common to first have (or write) an analysis package + in C or C++, then make the Python interface. Then it can be + supported by other languages, too. + + * Or one starts an analysis package in Python, and slowly moves bits + of it to C over time as there is need. + +* **Embedding Python**, where you have another primary application + that uses Python under the hood as an internal scripting language. + +These features aren't exactly unique to Python, but Python does +support them very well. Read more: `Extending and embedding Python +`__. + + + +Tools for interfacing with other languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These days, one rarely directly extends the Python interpreter, but uses + +* `cffi `__ and `ctypes + `__ - interface to C + and compatible libraries +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `f2py `__ - interface to Fortran + code +* `swig `__ - connect to a variety of programming languages. +* ``Boost.python`` - Another Python/C++ interface +* TODO: Julia modules for Python? + + + +Evaluating Python packages for reuse +------------------------------------ + +Above, we talked about well-maintained mainstream packages. **Do you +trust random code you find online (for example included in a paper)?** + +Especially consider scientific results, which *have* to be correct. +Still, you also *can't* build everything yourself, so you have to +carefully evaluate the situation. + +Below are some things to consider: + +* Are there releases? Have they been going on for a while? + +* Are releases installable without copy-paste? + +* Are dependencies handled well? + +* Does the code randomly change, so that it no longer works with your + code. Is this relevant? + +* Is there good documentation, that not just tells how to use it but + how it works? + +* Is there automated testing? What's your evaluation of the risk of + undetectable scientific errors? + +* Is there a community, or is it one person? Is it backed by some + organization? Does it have a permanent home? + +* Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) + where a community *could* form? + +* Do others post issues and make contributions? Are these issues + dealt with in a timely manner? Can you search past bug reports? + +* Is the software citeable? + + + +Is your work reuseable? +----------------------- + +Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a `CodeRefinery workshop `__ will make +sure you have the tools to produce high-quality, reusable code. + + + +What's next? +------------ + +* The `CodeRefinery workshop `__ mentioned + above will prepare you for others to reuse your code and for you to + contribute to other code. +* The upcoming :doc:`dependencies` lesson will teach you how to + record and manage dependencies so that anyone can seamlessly reuse + your code. + + + +Exercises +--------- + +.. exercise:: Libraries 1.1: Libraries in your work + + What libraries do you use in your work? What have you made, which + you could have reused from some other source. What have you used + from some other source that you wished you had re-created? + + Discuss in your groups or HackMD. + +.. solution:: Libraries 1.1 + + ... is there anything to say here? + + +.. exercise:: Libraries 1.2: Evaluating packages + + Below are some links to some packages, both public and made by the + authors of this lesson. Evaluate them, considering "would I use + this in my project?" + + a) https://github.com/networkx/networkx/ + b) some code on webpage in a paper's footnote + c) https://github.com/rkdarst/pcd + d) https://github.com/dftlibs/numgrid + e) https://github.com/rkdarst/dynbench + f) https://vpython.org/ + +.. solution:: Libraries 1.2 + + a) networkx: This seems to be a relatively large, active project + using best practices. Probably usable. + b) I would probably use it if I had to, but would prefer not to. + c) This (written by one of the authors of this lesson) has no + documenting, no community, no best practices, and is very old. + Probably not a good idea to try to use it + d) This project uses best practices, but doesn't seem to have a big + community. It's probably fine to use, but who knows if it will + be maintained 10 years from now. It does have automated tests + via Github Actions (``.github/workflows`` and the green checks), + so the authors have put some work into making it correct. + e) This (also written by one of the authors) looks like it was made + for a paper of some sort. It has some minimal documentation, + but still is missing many best practices and is clearly not + maintained anymore (look at the ancient pull request). Probably + not a good idea to use unless you have to. + f) This project has a pretty website, and some information. But + seems to not be using best practices of an open repository, and + custom locations which could disappear at any time. + + You notice that several of the older projects here were written by + one of the authors of this lesson. It goes to show that everyone + starts somewhere and improves over time - don't feel bad if your + work isn't perfect, as long as you keep trying to get better! + + + +See also +-------- + +* `Topical Software in the SciPy ecosystem + `__ - relatively + detailed (but not comprehensive) list of projects + + +.. keypoints:: + + - Almost everything you need can already be found, except your + incremental work. + - When do you build on that other work, and when do you create + things yourself? diff --git a/_sources/numpy-advanced.rst.txt b/_sources/numpy-advanced.rst.txt new file mode 100644 index 00000000..8df6552c --- /dev/null +++ b/_sources/numpy-advanced.rst.txt @@ -0,0 +1,407 @@ +Advanced NumPy +============== + +.. questions:: + + - How can NumPy be so fast? + - Why are some things fast and some things slow? + - How can I control whether NumPy makes a copy or operates in-place? + +.. objectives:: + + - Understand why NumPy has so many specialized functions for specific operations + - Understand the underlying machinery of the Numpy :class:`~numpy.ndarray` object + - Understand when and why NumPy makes a copy of the data rather than a view + + This is intended as a follow-up to the :doc:`basic NumPy lesson `. The intended + audience for this advanced lesson is those who have used NumPy before and + now want to learn how to get the most out of this amazing package. + + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +`Guide to NumPy `_ by +Travis E. Oliphant, its initial creator. + + + +NumPy can be really fast +------------------------ + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast. + +.. highlight:: c + +How fast can NumPy be? Let's race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:: + + #include + #include + #define N_ELEMENTS 100000000 + int main(int argc, char** argv) { + double* a = (double*) malloc(sizeof(double) * N_ELEMENTS); + int i; + for(i=0; i` before continuing with this + advanced lesson. If you are taking a live course - don't + worry, watch and learn and explore some during the exercises! + +.. solution:: Solutions: Numpy-Advanced-1 + + The script can be implemented like this:: + + import numpy as np + print(np.random.rand(100_000_000).sum()) + + +.. highlight:: python + +The libraries behind the curtain: MKL and BLAS +---------------------------------------------- + +NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel's `Math Kernel Library (MKL) `_, +which are in turn derived from a Fortran library called +`Basic Linear Algebra Subprograms (BLAS) `_. +BLAS for Fortran was `published in 1979 `_ +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +`specialized CPU instructions for manipulating arrays `_. +In other words, they are *fast*. + +One of the functions inside the BLAS library is a +`function `_ +to compute the "norm" of a vector, which is the same as computing its length, using the +`Pythagorean theorem `_: +:math:`\sqrt(a[0]^2 + a[1]^2 + \ldots)`. + +Let's race the BLAS function versus a naive "manual" version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:: + + import numpy as np + rng = np.random.default_rng(seed=0) + a = rng.random(100_000_000) + +We now implement the Pythagorean theorem using basic NumPy functionality and +use ``%%timeit`` to record how long it takes to execute:: + + %%timeit + l = np.sqrt(np.sum(a ** 2)) + print(l) + +And here is the version using the specialized BLAS function :func:`~numpy.linalg.norm`:: + + %%timeit + l = np.linalg.norm(a) + print(l) + + +NumPy tries to avoid copying data +---------------------------------- + +Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy's +:class:`numpy.ndarray` datastructure works behind the scenes. + + +An example: matrix transpose +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let's see how long NumPy's +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +:func:`~numpy.random.rand` matrix:: + + import numpy as np + a = np.random.rand(10_000, 20_000) + print(f'Matrix `a` takes up {a.nbytes / 10**6} MB') + +Let's time the :meth:`~numpy.ndarray.transpose` method:: + + %%timeit + b = a.transpose() + +It takes mere nanoseconds to transpose 1600 MB of data! How? + + +The ndarray exposed +~~~~~~~~~~~~~~~~~~~ +The first thing you need to know about :class:`numpy.ndarray` is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector. + +.. image:: img/numpy-advanced/01_memory_layout.svg + +NumPy is faking the second dimension behind the scenes! When we request the +element at say, ``[2, 3]``, NumPy converts this to the correct index in the +long 1D array ``[11]``. + + * Converting ``[2, 3]`` → ``[11]`` is called "raveling" + * The reverse, converting ``[11]`` → ``[2, 3]`` is called "unraveling" + +The implications of this are many, so take let's take some time to understand +it properly by writing our own ``ravel()`` function. + +Exercise 2 +---------- + +.. challenge:: Exercises: Numpy-Advanced-2 + + Write a function called ``ravel()`` that takes the row and column of an + element in a 2D matrix and produces the appropriate index in an 1D array, + where all the rows are concatenated. See the image above to remind yourself + how each row of the 2D matrix ends up in the 1D array. + + The function takes these inputs: + + - ``row`` The row of the requested element in the matrix as integer index. + - ``col`` The column of the requested element in the matrix as integer index. + - ``n_rows`` The total number of rows of the matrix. + - ``n_cols`` The total number of columns of the matrix. + + Here are some examples of input and desired output: + + - ``ravel(2, 3, n_rows=4, n_cols=4)`` → ``11`` + - ``ravel(2, 3, n_rows=4, n_cols=8)`` → ``19`` + - ``ravel(0, 0, n_rows=1, n_cols=1)`` → ``0`` + - ``ravel(3, 3, n_rows=4, n_cols=4)`` → ``15`` + - ``ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000)`` → ``69_318_923`` + +.. solution:: Solutions: Numpy-Advanced-2 + + The function can be implemented like this:: + + def ravel(row, col, n_rows, n_cols): + return row * n_cols + col + +Strides +------- + +As seen in the exercise, to get to the next row, we have to skip over +``n_cols`` indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of "strides":: + + np.zeros((4, 8)).strides # (64, 8) + np.zeros((4, 5, 6, 7, 8)).strides # (13440, 2688, 448, 64, 8) + +The :attr:`~numpy.ndarray.strides` attribute contains for each dimension, the number of *bytes* (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes. + +So now we know the mystery behind the speed of :meth:`~numpy.ndarray.transpose`. NumPy can avoid +copying any data by just modifying the :attr:`~numpy.ndarray.strides` of the array:: + + import numpy as np + + a = np.random.rand(10_000, 20_000) + b = a.transpose() + + print(a.strides) # (160000, 8) + print(b.strides) # (8, 160000) + +Another example: reshaping +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modifying the shape of an array through :func:`numpy.reshape` is also +accomplished without any copying of data by modifying the :attr:`~numpy.ndarray.strides`:: + + a = np.random.rand(20_000, 10_000) + print(f'{a.strides=}') # (80000, 8) + b = a.reshape(40_000, 5_000) + print(f'{b.strides=}') # (40000, 8) + c = a.reshape(20_000, 5_000, 2) + print(f'{c.strides=}') # (80000, 16, 8) + + +Exercises 3 +----------- + +.. challenge:: Exercises: Numpy-Advanced-3 + + A little known feature of NumPy is the ``numpy.stride_tricks`` module + that allows you to modify the :attr:`~numpy.ndarray.strides` attribute directly. Playing + around with this is very educational. + + 1. Create your own ``transpose()`` function that will transpose a 2D matrix + by reversing its :attr:`~numpy.ndarray.shape` and :attr:`~numpy.ndarray.strides` attributes using + :func:`numpy.lib.stride_tricks.as_strided`. + + 2. Create a (5 ✕ 100 000 000 000) array containing on the first row all + 1's, the second row all 2's, and so on. Start with an 1D array + ``a = np.array([1., 2., 3., 4., 5.])`` + and modify its ``shape`` and ``strides`` attributes using + :func:`numpy.lib.stride_tricks.as_strided` to obtain the desired 2D + matrix:: + + array([[1., 1., 1., ..., 1., 1., 1.], + [2., 2., 2., ..., 2., 2., 2.], + [3., 3., 3., ..., 3., 3., 3.], + [4., 4., 4., ..., 4., 4., 4.], + [5., 5., 5., ..., 5., 5., 5.]]) + + +.. solution:: Solutions: Numpy-Advanced-3 + + 1. The ``transpose()`` function can be implemented like this:: + + from numpy.lib.stride_tricks import as_strided + def transpose(a): + return as_strided(a, shape=a.shape[::-1], strides=a.strides[::-1]) + + # Testing the function on a small matrix + a = np.array([[1, 2, 3], + [4, 5, 6]]) + print('Before transpose:') + print(a) + print('After transpose:') + print(transpose(a)) + + 2. By setting one of the ``.strides`` to `0`, we can repeat a value + infinitely many times without using any additional memory:: + + from numpy.lib.stride_tricks import as_strided + a = np.array([1., 2., 3., 4., 5.]) + as_strided(a, shape=(5, 100_000_000_000), strides=(8, 0)) + + +A fast thing + a fast thing = a fast thing? +------------------------------------------- + +If :func:`numpy.transpose` is fast, and :func:`numpy.reshape` is fast, then +doing them both must be fast too, right?:: + + # Create a large array + a = np.random.rand(10_000, 20_000) + +Measuring the time it takes to first transpose and then reshape:: + + %%timeit -n 1 -r 1 + a.T.reshape(40_000, 5_000) + +In this case, the data actually had to be copied and it's super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the :attr:`~numpy.ndarray.strides`:: + + a = np.array([[1, 2, 3], [4, 5, 6]]) + + print('Original array:') + print(a) + + print('\nTransposed:') + print(a.T) + + print('\nTransposed and then reshaped:') + print(a.T.reshape(2, 3)) + + +Copy versus view +---------------- + +Whenever NumPy constructs a new array by modifying the :attr:`~numpy.ndarray.strides` instead of +copying data, we way it created a "view". This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +:class:`numpy.ndarray` object will have a reference to the original array in +its :attr:`~numpy.ndarray.base` attribute:: + + a = np.zeros((5, 5)) + print(a.base) # None + b = a[:2, :2] + print(b.base.shape) # (5, 5) + +.. warning:: + When you create a large array and select only a portion of it, the large + array will stay in memory if a view was created! + +The new array ``b`` object has a pointer to the same memory buffer as the array +it has been derived from:: + + print(a.__array_interface__['data']) + print(b.__array_interface__['data']) + +Views are created by virtue of modifying the value of the :attr:`~numpy.ndarray.shape` attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:: + + b = a[1:3, 1:3] # This view does not start at the beginning + offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0] + print('Offset:', offset, 'bytes') # Offset: 48 bytes + +.. image:: img/numpy-advanced/02_views.svg + +Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:: + + b[0, 0] = 1. + print(a) # Original matrix was modified + +Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:: + + c = a[[0, 2]] # Select rows 0 and 2 + print(c.base) # None. So not a view. + + +See also +-------- + +* `Guide to Numpy `__ +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + * `Advanced NumPy: Master stride tricks with 25 illustrated exercises `__ + + + +.. keypoints:: + + - The best way to make your code more efficient is to learn more about the + NumPy API and use specialized functions whenever possible. + - NumPy will avoid copying data whenever it can. Whether it can depends on + what kind of layout the data is currently in. diff --git a/_sources/numpy.rst.txt b/_sources/numpy.rst.txt new file mode 100644 index 00000000..05daa11e --- /dev/null +++ b/_sources/numpy.rst.txt @@ -0,0 +1,519 @@ +.. _numpy: + +NumPy +===== + +.. questions:: + + - Why use NumPy instead of pure python? + - How to use basic NumPy? + - What is vectorization? + +.. objectives:: + + - Understand the Numpy array object + - Be able to use basic NumPy functionality + - Understand enough of NumPy to seach for answers to the rest of your questions ;) + + We expect most people to be able to do all the basic exercises + here. It is probably quite easy for many people; we have advanced + exercises at the end in that case. + + + +So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible. + +.. highlight:: python + +What is an array? +----------------- + +For example, consider ``[1, 2.5, 'asdf', False, [1.5, True]]`` - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately. + +NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it. + +An array is a 'grid' of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has: + +* :ref:`dtype ` - data type. Arrays always contain one type +* :term:`shape` - shape of the data, for example ``3×2`` or ``3×2×500`` or even + ``500`` (one dimensional) or ``[]`` (zero dimensional). +* :attr:`data ` - raw data storage in memory. This can be passed to C or + Fortran code for efficient calculations. + + +To test the performance of pure Python vs NumPy we can write in our jupyter notebook: + +Create one list and one 'empty' list, to store the result in :: + + a = list(range(10000)) + b = [ 0 ] * 10000 + +In a new cell starting with ``%%timeit``, loop through the list ``a`` and fill the second list ``b`` with ``a`` squared :: + + %%timeit + for i in range(len(a)): + b[i] = a[i]**2 + +That looks and feels quite fast. But let's take a look at how NumPy performs for the same task. + +So for the NumPy example, create one array and one 'empty' array to store the result in :: + + import numpy as np + a = np.arange(10000) + b = np.zeros(10000) + +In a new cell starting with ``%%timeit``, fill ``b`` with ``a`` squared :: + + %%timeit + b = a ** 2 + +We see that compared to working with numpy arrays, working with traditional python lists is actually slow. + + +Creating arrays +--------------- + +There are different ways of creating arrays (:func:`numpy.array`, :attr:`numpy.ndarray.shape`, :attr:`numpy.ndarray.size`):: + + a = np.array([1,2,3]) # 1-dimensional array (rank 1) + b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2) + + b.shape # the shape (rows,columns) + b.size # number of elements + +In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (:func:`numpy.zeros`, :func:`numpy.ones`, :func:`numpy.full`, :func:`numpy.eye`, :func:`numpy.arange`, :func:`numpy.linspace`):: + + np.zeros((2, 3)) # 2x3 array with all elements 0 + np.ones((1,2)) # 1x2 array with all elements 1 + np.full((2,2),7) # 2x2 array with all elements 7 + np.eye(2) # 2x2 identity matrix + + np.arange(10) # Evenly spaced values in an interval + np.linspace(0,9,10) # same as above, see exercise + + c = np.ones((3,3)) + d = np.ones((3, 2), 'bool') # 3x2 boolean array + +Arrays can also be stored and read from a (.npy) file (:func:`numpy.save`, :func:`numpy.load`):: + + np.save('x.npy', a) # save the array a to a .npy file + x = np.load('x.npy') # load an array from a .npy file and store it in variable x + +In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (:attr:`numpy.ndarray.dtype`, :meth:`numpy.ndarray.astype`):: + + d.dtype # datatype of the array + d.astype('int') # change datatype from boolean to integer + +In the last example, ``.astype('int')``, it will make a **copy** of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed. + + + +Exercises 1 +----------- + +.. challenge:: Exercises: Numpy-1 + + 1. **Datatypes** Try out :func:`np.arange(10) ` and :func:`np.linspace(0,9,10) `, what is the difference? Can you adjust one to do the same as the other? + + 2. **Datatypes** Create a 3x2 array of random float numbers (check :func:`numpy.random.random`) between 0 and 1. Now change the arrays datatype to int (:meth:`array.astype `). How does the array look like? + + 3. **Reshape** Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check :meth:`array.reshape `) in any way possible. What is not possible? + + 4. **NumPyI/O** Save above array to .npy file (:func:`numpy.save`) and read it in again. + +.. solution:: Solutions: Numpy-1 + + 1. **Datatypes** + + - ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**, + - while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**. + + Both ``np.linspace`` and ``np.arange`` take dtype as an argument and can be adjusted to match each other in that way. + + 2. **Datatypes** eg ``a = np.random.random((3,2))``. ``a.astype('int')`` results in an all zero array, not as maybe expected the rounded int (all numbers [0, 1) are cast to 0). + + 3. **Reshape** eg ``b = np.random.randint(0,10,(3,2))``. + + ``b.reshape((6,1))`` and ``b.reshape((2,3))`` possible. + + It is not possible to reshape to shapes using more or less elements than ``b.size = 6``, so for example ``b.reshape((12,1))`` gives an error. + + 4. **NumPyI/O** ``np.save('x.npy', b)`` and ``x = np.load('x.npy')`` + + + +Array maths and vectorization +----------------------------- + +Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do. + +By default, basic arithmetic (``+``, ``-``, ``*``, ``/``) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is "vectorized" +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop. + +Note that unlike Matlab, where ``*`` means matrix multiplication, NumPy uses +``*`` to perform element-by-element multiplication and uses the ``@`` symbol to +perform matrix multiplication:: + + a = np.array([[1,2],[3,4]]) + b = np.array([[5,6],[7,8]]) + + # Addition + c = a + b + d = np.add(a,b) + + # Matrix multiplication + e = a @ b + f = np.dot(a, b) + +Other common mathematical operations include: ``-`` (:data:`numpy.subtract`), ``*`` (:data:`numpy.multiply`), ``/`` (:data:`numpy.divide`), ``.T`` (:func:`numpy.transpose`), :data:`numpy.sqrt`, :func:`numpy.sum`, :func:`numpy.mean`, ... + + + +Exercises 2 +----------- + +.. challenge:: Exercises: Numpy-2 + + - **Matrix multiplication** What is the difference between :data:`numpy.multiply` and :func:`numpy.dot` ? Try it. + - **Axis** What is the difference between :func:`np.sum(axis=1) ` vs + :func:`np.sum(axis=0) ` on a two-dimensional array? What if you leave out the axis parameter? + + +.. solution:: Solutions: Numpy-2 + + - **Matrix multiplication** ``np.multiply`` does elementwise multiplication on two arrays, while ``np.dot`` enables matrix multiplication. + - **Axis** ``axis=1`` does the operation (here: ``np.sum``) over each row, while axis=0 does it over each column. If axis is left out, the sum of the full array is given. + + + +Indexing and Slicing +-------------------- + +.. seealso:: + + :ref:`Numpy basic indexing docs ` + +NumPy has many ways to extract values out of arrays: + +- You can select a single element +- You can select rows or columns +- You can select ranges where a condition is true. + +Clever and efficient use of these operations is a key to NumPy's +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C. + +:: + + a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15 + a[0] # first row + a[:,0] # first column + a[1:3,1:3] # middle 2x2 array + + a[(0, 1), (1, 1)] # second element of first and second row as array + +Boolean indexing on above created array:: + + idx = (a > 0) # creates boolean matrix of same size as a + a[idx] # array with matching values of above criterion + + a[a > 0] # same as above in one line + + + +Exercises 3 +----------- + +.. challenge:: Exercise: Numpy-3 + + :: + + a = np.eye(4) + b = a[:,0] + b[0] = 5 + + - **View vs copy** Try out above code. How does ``a`` look like before ``b`` has changed and after? How could it be avoided? + +.. solution:: Solution: Numpy-3 + + - **View vs copy** The change in ``b`` has also changed the array ``a``! + This is because ``b`` is merely a view of a part of array ``a``. Both + variables point to the same memory. Hence, if one is changed, the other + one also changes. If you need to keep the original array as is, use + ``np.copy(a)``. + + +Types of operations +------------------- + +There are different types of standard operations in NumPy: + +**ufuncs**, ":ref:`universal functions `": These are element-by-element +functions with standardized arguments: + +- One, two, or three input arguments +- For example, ``a + b`` is similar to :data:`np.add(a, b) ` but the ufunc + has more control. +- ``out=`` output argument, store output in this array (rather than + make a new array) - saves copying data! +- See the `full reference + `__ + +- They also do **broadcasting** (:ref:`ref `). Can you add a 1-dimensional array of shape `(3)` + to an 2-dimensional array of shape `(3, 2)`? With broadcasting you + can! + + :: + + a = np.array([[1, 2, 3], + [4, 5, 6]]) + b = np.array([10, 10, 10]) + a + b # array([[11, 12, 13], + # [14, 15, 16]]) + + Broadcasting is smart and consistent about what it does, which I'm + not clever enough to explain quickly here: `the manual page on + broadcasting + `__. + The basic idea is that it expands dimensions of the smaller array so + that they are compatible in shape. + +**Array methods** do something to one array: + +- Some of these are the same as ufuncs:: + + x = np.arange(12) + x.shape = (3, 4) + x # array([[ 0, 1, 2, 3], + # [ 4, 5, 6, 7], + # [ 8, 9, 10, 11]]) + x.max() # 11 + x.max(axis=0) # array([ 8, 9, 10, 11]) + x.max(axis=1) # array([ 3, 7, 11]) + +**Other functions**: there are countless other functions covering +linear algebra, scientific functions, etc. + + + +Exercises 4 +----------- + +.. challenge:: Exercises: Numpy-4 + + - **In-place addition**: Create an array, add it to itself using a + ufunc. + + - **In-place addition** (advanced): Create an array of + ``dtype='float'``, and an array of ``dtype='int'``. Try to use the + int array is the output argument of the first two arrays. + + - **Output arguments and timing** Repeat the initial ``b = a ** + 2`` example using the output arguments and time it. Can you make + it even faster using the output argument? + +.. solution:: Solution: Numpy-4 + + - **in-place addition**:: + + x = np.array([1, 2, 3]) + id(x) # get the memory-ID of x + np.add(x, x, x) # Third argument is output array + np.add(x, x, x) + print(x) + id(x) # get the memory-ID of x + # - notice it is the same + + You note that ``np.add()`` has a third argument that is the + output array (same as ``out=``), *and* the function returns that + same array. + + + - **Output arguments and timing** In this case, on my computer, it was + actually slower (this is due to it being such a small array!):: + + a = np.arange(10000) + b = np.zeros(10000) + + :: + + %%timeit + numpy.square(a, out=b) + + This is a good example of why you always need to time things + before deciding what is best. + + +Linear algebra and other advanced math +-------------------------------------- + +In general, you use :class:`arrays ` (n-dimensions), not :class:`matrixes ` +(specialized 2-dimensional) in NumPy. + +Internally, NumPy doesn't invent its own math routines: it relies on +`BLAS +`__ +and `LAPACK `__ to do this kind +of math - the same as many other languages. + +- `Linear algebra in numpy + `__ + +- `Many, many other array functions + `__ + +- `Scipy `__ has even + more functions + +- Many other libraries use NumPy arrays as the standard data + structure: they take data in this format, and return it similarly. + Thus, all the other packages you may want to use are compatible + +- If you need to write your own fast code in C, NumPy arrays can be + used to pass data. This is known as `extending Python + `__. + + + + +Additional exercises +-------------------- + +.. challenge:: Numpy-5 + + If you have extra time, try these out. These are advanced and + optional, and will not be done in most courses. + + 1. Reverse a vector. Given a vector, reverse it such that the last + element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]`` + + 2. Create a 2D array with zeros on the borders and 1 inside. + + 3. Create a random array with elements [0, 1), then add 10 to all + elements in the range [0.2, 0.7). + + 4. What is :func:`np.round(0.5) `? What is ``np.round(1.5)``? Why? + + 5. In addition to ``np.round``, explore :data:`numpy.ceil`, :data:`numpy.floor`, + :data:`numpy.trunc`. In particular, take note of how they behave with + negative numbers. + + 6. Recall the identity :math:`\sin^2(x) + \cos^2(x) = 1`. Create a + random 4x4 array with values in the range [0, 10). Now test the + equality with :data:`numpy.equal`. What result do you get with + :func:`numpy.allclose` instead of ``np.equal``? + + 7. Create a 1D array with 10 random elements. Sort it. + + 8. What's the difference between :meth:`np_array.sort() ` and + :func:`np.sort(np_array) `? + + 9. For the random array in question 8, instead of sorting it, perform + an indirect sort. That is, return the list of indices which would + index the array in sorted order. + + 10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next + combine them into a single 8x4 array with the content of the zeros + array on top and the ones on the bottom. Finally, do the same, + but create a 4x8 array with the zeros on the left and the ones on + the right. + + 11. NumPy functionality Create two 2D arrays and do matrix multiplication + first manually (for loop), then using the np.dot function. Use %%timeit + to compare execution times. What is happening? + + +.. solution:: Solution Numpy-5 + + 1. One solution is:: + + a = np.array([1, 2, 3]) + a[::-1] + + 2. One solution is:: + + b = np.ones((10,10)) + b[:,[0, -1]]=0 + b[[0, -1],:]=0 + + 3. A possible solution is:: + + x = np.random.rand(100) + y = x + 10*(x >= 0.2)*(x < 0.7) + + 4. For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. + + 5. Let's test those functions with few negative and positive values:: + + a = np.array([-3.3, -2.5, -1.5, -0.75, -0.5, 0.5, 0.75, 1.5, 2.5, 3]) + np.round(a) # [-3. -2. -2. -1. -0. 0. 1. 2. 2. 3.] + np.ceil(a) # [-3. -2. -1. -0. -0. 1. 1. 2. 3. 3.] + np.floor(a) # [-4. -3. -2. -1. -1. 0. 0. 1. 2. 3.] + np.trunc(a) # [-3. -2. -1. -0. -0. 0. 0. 1. 2. 3.] + + + 6. One solution is:: + + x = 10*np.random.rand(4,4) + oo = np.ones((4,4)) + s2c2 = np.square(np.sin(x))+np.square(np.cos(x)) + np.equal(oo,s2c2) + np.allclose(oo,s2c2) + + 7. Sorting the array itself, without copying it:: + + x = np.random.rand(10) + x.sort() + + 8. NumPy.sort() returns a sorted copy of an array. + + 9. ``np.argsort(x)`` + + 10. One solution is:: + + z = np.zeros((4,4)) + o = np.ones((4,4)) + np.concatenate((z,o)) + np.concatenate((z,o),axis=1) + + 11. Using numpy without numpy functionality (np.dot) in this case, is still slow. + + + +See also +-------- + +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + +* `2020 Nature paper on NumPy's role and basic concepts `__ + + + +.. keypoints:: + + - NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally. + - Be aware of some NumPy specific peculiarities diff --git a/_sources/packaging.rst.txt b/_sources/packaging.rst.txt new file mode 100644 index 00000000..7b795f1f --- /dev/null +++ b/_sources/packaging.rst.txt @@ -0,0 +1,324 @@ +Packaging +========= + +.. questions:: + + - How to organize Python projects larger than one script? + - What is a good file and folder structure for Python projects? + - How can you make your Python functions most usable by your collaborators? + - How to prepare your code to make a Python package? + - How to publish your Python package? + +.. objectives:: + + - Learn to identify the components of a Python package + - Learn to create a Python package + - Learn to publish a Python package + + +Organizing Python projects +-------------------------- + +Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file. + +In the :ref:`scripts` episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further. + +**Recommendations**: + +- Collect related functions into modules (files). +- Collect related modules into packages (we will show how). +- Add a ``LICENSE`` file to your code + (see `Software Licensing and Open source explained with cakes `__). +- Write a ``README.md`` file describing what the code does and how to use it. +- It is also recommended to `document your package `__. +- When the project grows, you might need `automated testing `__. + +To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: ``scipy``. + +These are the 3 files: + +.. literalinclude:: packaging-example-project/calculator/adding.py + :caption: adding.py + +.. literalinclude:: packaging-example-project/calculator/subtracting.py + :caption: subtracting.py + +.. literalinclude:: packaging-example-project/calculator/integrating.py + :caption: integrating.py + +We will add a fourth file: + +.. literalinclude:: packaging-example-project/calculator/__init__.py + :caption: __init__.py + +This ``__init__.py`` file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using *relative imports* +(with the dot). + +This is how we will arrange the files in the project folder/repository: + +.. code-block:: none + :emphasize-lines: 3-6 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + └── README.md + +Now we are ready to test the package. For this we need to be in the "root" +folder, what we have called the *project-folder*. We also need to have +``scipy`` available in our environment: + +.. literalinclude:: packaging-example-project/test.py + +The package is not yet pip-installable, though. We will make this possible in +the next section. + + +Testing a local pip install +--------------------------- + +To make our example package pip-installable we need to add one more file: + +.. code-block:: none + :emphasize-lines: 9 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + ├── README.md + └── pyproject.toml + +This is how ``pyproject.toml`` looks: + +.. literalinclude:: packaging-example-project/pyproject.toml + :caption: pyproject.toml + :emphasize-lines: 13-15 + +Note how our package requires ``scipy`` and we decided to not pin the version +here (see :ref:`version_pinning`). + +Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see :ref:`pypi`) + + + +Exercises 1 +----------- + +.. challenge:: Packaging-1 + + To test a local pip install: + + - Create a new folder outside of our example project + - Create a new virtual environment (:ref:`dependency_management`) + - Install the example package from the project folder + into the new environment: ``$ pip install /path/to/project-folder/`` + - Test the local installation: + + .. literalinclude:: packaging-example-project/test.py + + +Sharing packages via PyPI +------------------------- + +Once we are able to pip-install the example package locally, we are ready for +upload. + +We exercise by uploading to `test-PyPI `__, not the +real `PyPI `__, so that if we mess things up, nothing bad +happens. + +We need two more things: + +- We will do this using `Twine `__ so you need + to pip install that, too. +- You need an account on `test-PyPI `__. + +.. highlight:: console + +Let's try it out. First we create the distribution package:: + + $ python3 -m build + +We need twine:: + + $ pip install twine + +And use twine to upload the distribution files to test-PyPI:: + + $ twine upload -r testpypi dist/* + + Uploading distributions to https://test.pypi.org/legacy/ + Enter your username: + Enter your password: + +Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt "myname"):: + + $ pip install -i https://test.pypi.org/simple/ calculator-myname + + +Tools that simplify sharing via PyPI +------------------------------------ + +The solution that we have used to create the example package (using +``setuptools`` and ``twine``) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using ``pyproject.toml`` as more general +alternative to the previous ``setup.py``. + +There are at least two tools which try to make the packaging and PyPI interaction easier: + +- `Poetry `__ +- `Flit `__ + + +Building a conda package and share it +------------------------------------- + +.. demo:: + + Most people will watch and observe this, due to speed which we will + move. + +.. callout:: Prerequisites + + To create a conda package, `conda-build` package is required. You may install it with **Anaconda Navigator** or from the command line:: + + $ conda install conda-build + + +The simplest way for creating a conda package for your python script is to +first publish it in `PyPI `__ following the steps explained +above. + + +Building a python package with conda skeleton pypi +*************************************************** + +Once build, the conda package can be installed locally. For this example, we +will use `runtest `__. `runtest +`__ is a numerically tolerant end-to-end test +library for research software. + +1. Create pypi skeleton:: + + $ conda skeleton pypi runtest + + The command above will create a new folder called `runtest` containing a file `meta.yaml`, the conda recipe for `runtest`. + +2. Edit `meta.yaml` and update requirements: + + .. code-block:: yaml + + requirements: + host: + - pip + - python + - flit + run: + - python + - flit + + In the requirements above, we specified what is required for the `host `__ and for `running `__ the package. + + .. callout:: Remark + + For pure python recipes, this is all you need for building a python package with conda. + If your package needs to be built (for instance compilation), you would need additional files e.g. `build.sh` (to build on Linux/Mac-OSX) and `bld.bat` (to build on Windows systems). You can also add test scripts for testing your package. See `documentation `__ + + +3. Build your package with conda + + Your package is now ready to be build with conda:: + + $ conda-build runtest + + + .. callout:: Conda package location + + Look at the messages produced while building. The location of the local conda package is given (search for `anaconda upload`): + + .. code-block:: none + + ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2 + + The prefix `~/anaconda3/` may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder `win-64` differs too (for instance `linux-64` on Linux machines). + + The conda package we have created is specific to your platform (here `win-64`). It can be converted to other platforms using `conda convert `__. + +4. Check within new environment + + It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments. + + :: + + $ conda create -n local-runtest --use-local runtest + + We can then check `runtest` has been successfully installed in `local-runtest` conda environment. Open a new Terminal with `local-runtest` environment (either from the command line:: + + $ conda activate local-runtest + + or via **Anaconda Navigator** (Open Terminal), import runtest and + check its version: + + .. code-block:: python + + import runtest + print(runtest.__version__) + + +.. callout:: Building a conda package from scratch + + It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the `conda-build documentation `__ for more information. + +To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a `conda channel `__ (see below). + + + +Publishing a python package +*************************** + +- Upload your package to *Anaconda.org*: see instructions `here + `__. + Please note that you will have to create an account on Anaconda. + +- Upload your package to `conda-forge `__: + conda-forge is a conda channel: it contains community-led collection of + recipes, build infrastructure and distributions for the conda package + manager. Anyone can public conda packages to conda-forge if certain + `guidelines `__ are respected. + +- Upload your package to `bioconda `_: bioconda is + a very popular channel for the conda package manager specializing in + bioinformatics software. As for conda-forge, you need to follow their + `guidelines `__ when + building conda recipes. + +You can also `create your own conda channel +`__ +for publishing your packages. + + +.. keypoints:: + + - It is worth it to organize your code for publishing, even if only + you are using it. + - PyPI is a place for Python packages + - conda is similar but is not limited to Python diff --git a/_sources/pandas.rst.txt b/_sources/pandas.rst.txt new file mode 100644 index 00000000..0fa04fd2 --- /dev/null +++ b/_sources/pandas.rst.txt @@ -0,0 +1,623 @@ +.. _pandas: + +Pandas +====== + +.. questions:: + + - How do I learn a new Python package? + - How can I use pandas dataframes in my research? + +.. objectives:: + + - Learn simple and some more advanced usage of pandas dataframes + - Get a feeling for when pandas is useful and know where to find more information + - Understand enough of pandas to be able to read its documentation. + +.. default-domain:: py + + +Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including: + +- A `Getting started guide `__ + (including tutorials and a 10 minute flash intro) +- A `"10 minutes to Pandas" `__ + tutorial +- Thorough `Documentation `__ containing a user guide, + API reference and contribution guide +- A `cheatsheet `__ +- A `cookbook `__ + +A quick Pandas preview +---------------------- + +.. thebe-button:: + +Let's get a flavor of what we can do with pandas (you won't be able to follow everything yet). We will be working with an example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:: + + import pandas as pd + +We can download the data from `this GitHub repository `__ +by visiting the page and saving it to disk, or by directly reading into +a :class:`~pandas.DataFrame`:: + + url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv" + titanic = pd.read_csv(url, index_col='Name') + +We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:: + + # print the first 5 lines of the dataframe + titanic.head() + +:: + + # print summary statistics for each column + titanic.describe() + +Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38\% of passengers survived, etc. + +Let's say we're interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn't survive, and plot corresponding histograms of +the age distribution (:meth:`pandas.DataFrame.groupby`, :meth:`pandas.DataFrame.hist`):: + + print(titanic.groupby("Survived")["Age"].mean()) + +:: + + titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10), + layout=(2,1), zorder=2, sharex=True, rwidth=0.9); + + +Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let's get back to basics. + +.. callout:: Getting help + + Series and DataFrames have a lot functionality, but + how can we find out what methods are available and how they work? One way is to visit + the `API reference `__ + and reading through the list. + Another way is to use the autocompletion feature in Jupyter and type e.g. + ``titanic["Age"].`` in a notebook and then hit ``TAB`` twice - this should open + up a list menu of available methods and attributes. + + Jupyter also offers quick access to help pages (docstrings) which can be + more efficient than searching the internet. Two ways exist: + + - Write a function name followed by question mark and execute the cell, e.g. + write ``titanic.hist?`` and hit ``SHIFT + ENTER``. + - Write the function name and hit ``SHIFT + TAB``. + - Right click and select "Show contextual help". This tab will + update with help for anything you click. + + +What's in a dataframe? +---------------------- + +As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +:class:`pandas.DataFrame` +is composed of rows and columns: + +.. image:: img/pandas/01_table_dataframe.svg + +Each column of a dataframe is a :class:`pandas.Series` object +- a dataframe is thus a collection of series:: + + # print some information about the columns + titanic.info() + +Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type ``int64`` or of type ``object``. + +Let's inspect one column of the Titanic passenger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):: + + titanic["Age"] + titanic.Age # same as above + +:: + + type(titanic["Age"]) # a pandas Series object + +The columns have names. Here's how to get them (:attr:`~pandas.DataFrame.columns`):: + + titanic.columns + +However, the rows also have names! This is what Pandas calls the :obj:`~pandas.DataFrame.index`:: + + titanic.index + +We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and +values. We can refer to columns and rows either by their name +(:attr:`~pandas.DataFrame.loc`, :attr:`~pandas.DataFrame.at`) or by +their index (:attr:`~pandas.DataFrame.iloc`, +:attr:`~pandas.DataFrame.iat`):: + + titanic.loc['Lam, Mr. Ali',"Age"] # select single value by row and column + titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"] # slice the dataframe by row and column *names* + titanic.iloc[0:2,3:6] # same slice as above by row and column *numbers* + + titanic.at['Lam, Mr. Ali',"Age"] = 42 # set single value by row and column *name* (fast) + titanic.at['Lam, Mr. Ali',"Age"] # select single value by row and column *name* (fast) + titanic.iat[0,5] # select same value by row and column *number* (fast) + + titanic["is_passenger"] = True # set a whole column + +Dataframes also support boolean indexing, just like we saw for ``numpy`` +arrays:: + + titanic[titanic["Age"] > 70] + # ".str" creates a string object from a column + titanic[titanic.index.str.contains("Margaret")] + +What if your dataset has missing data? Pandas uses the value :py:data:`numpy.nan` +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:: + + titanic.isna() # returns boolean mask of NaN values + titanic.dropna() # drop missing values + titanic.dropna(how="any") # or how="all" + titanic.dropna(subset=["Cabin"]) # only drop NaNs from one column + titanic.fillna(0) # replace NaNs with zero + titanic.fillna(method='ffill') # forward-fill NaNs + + + +Exercises 1 +----------- + +.. challenge:: Exploring dataframes + + - Have a look at the available methods and attributes using the + `API reference `__ + or the autocomplete feature in Jupyter. + - Try out a few methods using the Titanic dataset and have a look at + the docstrings (help pages) of methods that pique your interest + - Compute the mean age of the first 10 passengers by slicing and the :py:meth:`pandas.DataFrame.mean` method + - (Advanced) Using boolean indexing, compute the survival rate + (mean of "Survived" values) among passengers over and under the average age. + + .. solution:: + + - Mean age of the first 10 passengers:: + + titanic.iloc[:10,:]["Age"].mean() + + or:: + + titanic.loc[:"Nasser, Mrs. Nicholas (Adele Achem)","Age"].mean() + + or:: + + titanic.iloc[:10,4].mean() + + - Survival rate among passengers over and under average age:: + + titanic[titanic["Age"] > titanic["Age"].mean()]["Survived"].mean() + + and:: + + titanic[titanic["Age"] < titanic["Age"].mean()]["Survived"].mean() + + +Tidy data +--------- + +The above analysis was rather straightforward thanks to the fact +that the dataset is *tidy*. + +.. image:: img/pandas/tidy_data.png + +In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data. + +What would untidy data look like? Here's an example from +some run time statistics from a 1500 m running event:: + + runners = pd.DataFrame([ + {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240}, + {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300}, + {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360}, + ]) + +What makes this data untidy is that the column names `400, 800, 1200, 1500` +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row. + +To make untidy data tidy, a common operation is to "melt" it, +which is to convert it from wide form to a long form:: + + runners = pd.melt(runners, id_vars="Runner", + value_vars=[400, 800, 1200, 1500], + var_name="distance", + value_name="time" + ) + +In this form it's easier to **filter**, **group**, **join** +and **aggregate** the data, and it's also easier to model relationships +between variables. + +The opposite of melting is to *pivot* data, which can be useful to +view data in different ways as we'll see below. + +For a detailed exposition of data tidying, have a look at +`this article `__. + + + +Working with dataframes +----------------------- + +We saw above how we can read in data into a dataframe using the :func:`~pandas.read_csv` function. +Pandas also understands multiple other formats, for example using :obj:`~pandas.read_excel`, +:obj:`~pandas.read_hdf`, :obj:`~pandas.read_json`, etc. (and corresponding methods to write to file: +:obj:`~pandas.DataFrame.to_csv`, :obj:`~pandas.DataFrame.to_excel`, :obj:`~pandas.DataFrame.to_hdf`, :obj:`~pandas.DataFrame.to_json`, etc.) + +But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +:class:`~pandas.DataFrame` docs):: + + import numpy as np + dates = pd.date_range('20130101', periods=6) + df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD')) + df + +or a dictionary (see same docs):: + + df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'], + 'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'], + 'C': np.array([3] * 8, dtype='int32'), + 'D': np.random.randn(8), + 'E': np.random.randn(8)}) + df + +There are many ways to operate on dataframes. Let's look at a +few examples in order to get a feeling of what's possible +and what the use cases can be. + +We can easily split and :func:`concatenate ` dataframes:: + + sub1, sub2, sub3 = df[:2], df[2:4], df[4:] + pd.concat([sub1, sub2, sub3]) + +When pulling data from multiple dataframes, a powerful :obj:`pandas.DataFrame.merge` method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:: + + age = pd.DataFrame([ + {"Runner": "Runner 4", "Age": 18}, + {"Runner": "Runner 2", "Age": 21}, + {"Runner": "Runner 1", "Age": 23}, + {"Runner": "Runner 3", "Age": 19}, + ]) + +We now want to use this table to annotate the original ``runners`` table from +before with their age. Note that the ``runners`` and ``age`` dataframes have a +different ordering to it, and ``age`` has an entry for ``Dave`` which is not +present in the ``runners`` table. We can let Pandas deal with all of it using +the :obj:`~pandas.DataFrame.merge` method:: + + # Add the age for each runner + runners.merge(age, on="Runner") + +In fact, much of what can be done in SQL +`is also possible with pandas `__. + +:obj:`~pandas.DataFrame.groupby` is a powerful method which splits a dataframe and aggregates data +in groups. To see what's possible, let's return to the Titanic dataset. Let's +test the old saying "Women and children first". We start by creating a new +column ``Child`` to indicate whether a passenger was a child or not, based on +the existing ``Age`` column. For this example, let's assume that you are a +child when you are younger than 12 years:: + + titanic["Child"] = titanic["Age"] < 12 + +Now we can test the saying by grouping the data on ``Sex`` and then creating further sub-groups based on ``Child``:: + + titanic.groupby(["Sex", "Child"])["Survived"].mean() + +Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +:obj:`~pandas.DataFrame.std`, :obj:`~pandas.DataFrame.min`, +:obj:`~pandas.DataFrame.max`, :obj:`~pandas.DataFrame.cumsum`, +:obj:`~pandas.DataFrame.median`, :obj:`~pandas.DataFrame.skew`, +:obj:`~pandas.DataFrame.var` etc. + + + +Exercises 2 +----------- + +.. challenge:: Analyze the Titanic passenger list dataset + + In the Titanic passenger list dataset, + investigate the family size of the passengers (i.e. the "SibSp" column). + + - What different family sizes exist in the passenger list? Hint: try the :meth:`~pandas.Series.unique` method + - What are the names of the people in the largest family group? + - (Advanced) Create histograms showing the distribution of family sizes for + passengers split by the fare, i.e. one group of high-fare passengers (where + the fare is above average) and one for low-fare passengers + (Hint: instead of an existing column name, you can give a lambda function + as a parameter to :meth:`~pandas.DataFrame.hist` to compute a value on the fly. For example + ``lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich"``). + + .. solution:: + + - Existing family sizes:: + + titanic["SibSp"].unique() + + - We get 8 from above. There is no ``Name`` column, since we + made ``Name`` the index when we loaded the dataframe with + ``read_csv``, so we use :attr:`pandas.DataFrame.index` to get + the names. So, names of members of largest family(ies):: + + titanic[titanic["SibSp"] == 8].index + + - Histogram of family size based on fare class:: + + titanic.hist("SibSp", + lambda x: "Poor" if titanic["Fare"].loc[x] < titanic["Fare"].mean() else "Rich", + rwidth=0.9) + + + + +Time series superpowers +----------------------- + +An introduction of pandas wouldn't be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv . + +Unfortunately this API does not allow "non-browser requests", so +:obj:`pandas.read_csv` will not work directly on it. Instead, we put a +local copy on Github which we can access (the original data is CC-0, +so we are allowed to do this). (Aside: if you do JupyterLab → +File → Open from URL → paste the URL above, it will open it in +JupyterLab *and* download a copy for your use.) + +We can then load and explore the data:: + + nobel = pd.read_csv("https://github.com/AaltoSciComp/python-for-scicomp/raw/master/resources/data/laureate.csv") + nobel.head() + +This dataset has three columns for time, "born"/"died" and "year". +These are represented as strings and integers, respectively, and +need to be converted to datetime format. :func:`pandas.to_datetime` +makes this easy:: + + # the errors='coerce' argument is needed because the dataset is a bit messy + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + +Pandas knows a lot about dates (using :ref:`/user_guide/basics.rst#dt-accessor`):: + + print(nobel["born"].dt.day) + print(nobel["born"].dt.year) + print(nobel["born"].dt.weekday) + +We can add a column containing the (approximate) lifespan in years rounded +to one decimal:: + + nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1) + +and then plot a :meth:`histogram ` of lifespans:: + + nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9) + +Finally, let's see one more example of an informative plot (:meth:`~pandas.DataFrame.boxplot`) +produced by a single line of code:: + + nobel.boxplot(column="lifespan", by="category") + + + +Exercises 3 +----------- + +.. challenge:: Analyze the Nobel prize dataset + + - What country has received the largest number of Nobel prizes, and how many? + How many countries are represented in the dataset? Hint: use the :obj:`~pandas.Series.describe` method + on the ``bornCountryCode`` column. + - Create a histogram of the age when the laureates received their Nobel prizes. + Hint: follow the above steps we performed for the lifespan. + - List all the Nobel laureates from your country. + + Now more advanced steps: + + - Now define an array of 4 countries of your choice and extract + only laureates from these countries (you need to look at the + data and find how countries are written, and replace ``COUNTRY`` + with those strings):: + + countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4]) + subset = nobel.loc[nobel['bornCountry'].isin(countries)] + + - Use :meth:`~pandas.DataFrame.groupby` to compute how many nobel prizes each country received in + each category. The :meth:`~pandas.core.groupby.GroupBy.size` method tells us how many rows, hence nobel + prizes, are in each group:: + + nobel.groupby(['bornCountry', 'category']).size() + + - (Optional) Create a pivot table to view a spreadsheet like structure, and view it + + - First add a column “number” to the nobel dataframe containing 1’s + (to enable the counting below). We need to make a copy of + ``subset``, because right now it is only a view:: + + subset = subset.copy() + subset.loc[:, 'number'] = 1 + + - Then create the :meth:`~pandas.DataFrame.pivot_table`:: + + table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum) + + - (Optional) Install the **seaborn** visualization library if you don't + already have it, and create a heatmap of your table:: + + import seaborn as sns + sns.heatmap(table,linewidths=.5); + + - Play around with other nice looking plots:: + + sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset); + + :: + + sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5); + + :: + + subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))] + sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm"); + + :: + + sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count"); + + + .. solution:: + + Below is solutions for the basic steps, advanced steps are + inline above. + + We use the :meth:`describe` method: + + :: + + nobel.bornCountryCode.describe() + # count 956 + # unique 81 + # top US + # freq 287 + + We see that the US has received the largest number of Nobel prizes, + and 81 countries are represented. + + To calculate the age at which laureates receive their prize, we need + to ensure that the "year" and "born" columns are in datetime format:: + + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + + Then we add a column with the age at which Nobel prize was received + and plot a histogram:: + + nobel["age_nobel"] = round((nobel["year"] - nobel["born"]).dt.days / 365, 1) + nobel.hist(column="age_nobel", bins=25, figsize=(8,10), rwidth=0.9) + + We can print names of all laureates from a given country, e.g.:: + + nobel[nobel["country"] == "Sweden"].loc[:, "firstname":"surname"] + +Beyond the basics +----------------- + +Larger DataFrame operations might be faster using :func:`~pandas.eval` with string expressions, `see +`__:: + + import pandas as pd + # Make some really big dataframes + nrows, ncols = 100000, 100 + rng = np.random.RandomState(42) + df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols)) + for i in range(4)) + +Adding dataframes the pythonic way yields:: + + %timeit df1 + df2 + df3 + df4 + # 80ms + +And by using :func:`~pandas.eval`:: + + %timeit pd.eval('df1 + df2 + df3 + df4') + # 40ms + + +We can assign function return lists as dataframe columns:: + + def fibo(n): + """Compute Fibonacci numbers. Here we skip the overhead from the + recursive function calls by using a list. """ + if n < 0: + raise NotImplementedError('Not defined for negative values') + elif n < 2: + return n + memo = [0]*(n+1) + memo[0] = 0 + memo[1] = 1 + for i in range(2, n+1): + memo[i] = memo[i-1] + memo[i-2] + return memo + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = fibo(99) # Assigns list to column + + +There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its `API +`__. You should try to get good at +searching the web for an example showing what you can do. And when +there is not, you can always +apply your own functions to the data using :obj:`~pandas.DataFrame.apply`:: + + + from functools import lru_cache + + @lru_cache + def fib(x): + """Compute Fibonacci numbers. The @lru_cache remembers values we + computed before, which speeds up this function a lot.""" + if x < 0: + raise NotImplementedError('Not defined for negative values') + elif x < 2: + return x + else: + return fib(x - 2) + fib(x - 1) + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = df['Generation'].apply(fib) + + +Note that the numpy precision for integers caps at int64 while python ints are unbounded -- +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df['Number of Rabbits'][99] given by both functions above +is in fact . + +Alternatives to Pandas +---------------------- + +**Polars** + +`Polars `__ is a DataFrame library designed to processing data with a fast lighting time. Polars is implemented in Rust Programming language and uses `Apache Arrow `__ as its memory format. + +**Dask** + +`Dask `__ is a Python package for parallel computing in Python and uses parallel data-frames for dealing with very large arrays. + +**Vaex** + +`Vaex `__ is a high performance Python library for lazy Out-of-Core DataFrames, to visualize and explore big tabular datasets. + + +.. keypoints:: + + - pandas dataframes are a good data structure for tabular data + - Dataframes allow both simple and advanced analysis in very compact form diff --git a/_sources/parallel-pi-multiprocessing.ipynb.txt b/_sources/parallel-pi-multiprocessing.ipynb.txt new file mode 100644 index 00000000..970dbada --- /dev/null +++ b/_sources/parallel-pi-multiprocessing.ipynb.txt @@ -0,0 +1,303 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Python multithreading solution\n", + "Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import random" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "def sample(n):\n", + " \"\"\"Make n trials of points in the square. Return (n, number_in_circle)\n", + " \n", + " This is our basic function. By design, it returns everything it\\\n", + " needs to compute the final answer: both n (even though it is an input\n", + " argument) and n_inside_circle. To compute our final answer, all we\n", + " have to do is sum up the n:s and the n_inside_circle:s and do our\n", + " computation\"\"\"\n", + " n_inside_circle = 0\n", + " for i in range(n):\n", + " x = random.random()\n", + " y = random.random()\n", + " if x**2 + y**2 < 1.0:\n", + " n_inside_circle += 1\n", + " return n, n_inside_circle" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it just for timing\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Do the actual calculation (the previous result doesn't get saved)\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is the \"calculate answer\" phase." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.144548" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "pi = 4.0 * (n_inside_circle / n)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in parallel with multiprocessing\n", + "This divides the calculation into 10 tasks and runs `sample` on each of them. Then it re-combines the results." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import multiprocessing.pool\n", + "pool = multiprocessing.pool.Pool()\n", + "# The default pool makes one process per CPU" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it once to time it\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "pool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.140768" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in \"parallel\" with threads\n", + "To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool = multiprocessing.pool.ThreadPool()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%timeit -o\n", + "# Do it once to time it\n", + "threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.142388" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Future ideas\n", + "\n", + "You could make a separate `calculate` function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.\n", + "\n", + "Notice the similarity to [split-apply-combine](https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html) or [map-reduce](https://en.wikipedia.org/wiki/MapReduce) which is a specialization of split-apply-combine." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/_sources/parallel.rst.txt b/_sources/parallel.rst.txt new file mode 100644 index 00000000..2986ef53 --- /dev/null +++ b/_sources/parallel.rst.txt @@ -0,0 +1,513 @@ +Parallel programming +==================== + +.. questions:: + + - When you need more than one processor, what do you do? + - How can we use more than one processor/core in Python? + +.. objectives:: + + - Understand the major strategies of parallelizing code + - Understand mechanics of the ``multiprocessing`` package + - Know when to use more advanced packages or approaches + + + +Modes of parallelism +-------------------- + +You realize you do have more computation to do than you can on one processor? +What do you do? + +1. Profile your code, identify the *actual* slow spots. + +2. Can you improve your code in those areas? Use an existing library? + +3. Are there are any low-effort optimizations that you can make? + +4. Consider using `numba `__ or + `cython `__ to accelerate key functions. + +5. Think about parallelizing. + + +Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers). + +**Parallel computing** is when many different tasks are carried out +simultaneously. There are three main models: + +* **Embarrassingly parallel:** the code does not need to + synchronize/communicate with other instances, and you can run + multiple instances of the code separately, and combine the results + later. If you can do this, great! (array jobs, task queues, + workflow management tools) + +* **Multithreading:** Parallel threads need to communicate and do so via + the same memory (variables, state, etc). (OpenMP, ``threading``) + +* **Multiprocessing, message passing:** Different processes manage + their own memory segments. They share data by communicating (passing + messages) as needed. (``multiprocessing``, MPI). + +.. warning:: + + Parallel programming is not magic, but many things can go wrong and + you can get unexpected results or difficult to debug problems. + Parallel programming is a fascinating world to get involved in, but + make sure you invest enough time to do it well. + + See the video by Raymond Hettinger ("See Also" at bottom + of page) for an entertaining take on this. + + + +Multithreading and the GIL +-------------------------- + +The designers of the Python language made the choice +that **only one thread in a process can run actual Python code** +by using the so-called **global interpreter lock (GIL)**. +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. *But it's not all bad!:* + +* External libraries (NumPy, SciPy, Pandas, etc), written in C or other + languages, can release the lock and run multi-threaded. + +* Most input/output releases the GIL, and input/output is slow. The + ``threading`` library can be used to multithread I/O. + +* Python libraries like ``multiprocessing`` and ``mpi4py`` run *multiple + Python processes* and this circumvents the GIL. + + +Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix: + +.. code-block:: python + + import numpy as np + import time + + A = np.random.random((4000,4000)) + A = A * A.T + time_start = time.time() + np.linalg.inv(A) + time_end = time.time() + print("time spent for inverting A is", round(time_end - time_start,2), 's') + +If we run this in a Jupyter notebook or through a Python script, **it +will automatically use multithreading** through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either ``export OMP_NUM_THREADS=1`` or ``export MKL_NUM_THREADS=1``, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime. + + +.. seealso:: + + * `More on the global interpreter lock + `__ + * `Threading python module + `__. This is + very low level and you shouldn't use it unless you really know what + you are doing. + * We recommend you find a UNIX threading tutorial first before embarking + on using the :py:mod:`threading` module. + + + +multiprocessing +--------------- + +As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +:py:mod:`multiprocessing` module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock. + +To show an example, +the `split-apply-combine `__ +or `map-reduce `__ paradigm is +quite useful for many scientific workflows. Consider you have this:: + + def square(x): + return x*x + +You can apply the function to every element in a list using the +:py:func:`map` function: + +.. code-block:: pycon + + >>> list(map(square, [1, 2, 3, 4, 5, 6])) + [1, 4, 9, 16, 25, 36] + +The :py:class:`multiprocessing.pool.Pool` class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list: + +.. code-block:: pycon + + >>> from multiprocessing import Pool + >>> with Pool() as pool: + ... pool.map(square, [1, 2, 3, 4, 5, 6]) + [1, 4, 9, 16, 25, 36] + +.. warning:: + + Running the above example **interactively** in a Jupyter notebook + or through an Python/IPython terminal may or may not work on your + computer! This is a feature and not a bug, as covered in the + `documentation `__. + + Fortunately, there is a fork of multiprocesssing called + `multiprocess `__ which does + work in interactive environments. All we have to do is install it + by ``pip install multiprocess`` and change the import statement: + ``from multiprocess import Pool``. + + +Exercises, multiprocessing +-------------------------- + +.. challenge:: Parallel-1, multiprocessing + + Here, you find some code which calculates pi by a stochastic + algorithm. You don't really need to worry how the algorithm works, + but it computes random points in a 1x1 square, and computes the + number that fall into a circle. Copy it into a Jupyter notebook + and use the ``%%timeit`` cell magic on the computation part (the + one highlighted line after timeit below): + + .. code-block:: python + :emphasize-lines: 20 + + import random + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x**2 + y**2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + %%timeit + n, n_inside_circle = sample(10**6) + + pi = 4.0 * (n_inside_circle / n) + pi + + Using the :py:class:`multiprocessing.pool.Pool` code from the lesson, run + the ``sample`` function 10 times, each with ``10**5`` samples + only. Combine the results and time the calculation. What is the + difference in time taken? + + NOTE: If you're working in an interactive environment and this + doesn't work with the ``multiprocessing`` module, install and use + the ``multiprocess`` module instead! + + (optional, advanced) Do the same but with + :py:class:`multiprocessing.pool.ThreadPool` instead. This works identically + to ``Pool``, but uses threads instead of different processes. + Compare the time taken. + + .. solution:: + + See the finished notebook here :doc:`parallel-pi-multiprocessing`. + + You notice the version with ``ThreadPool`` is no faster, and + probably takes even longer. This is because this is a + pure-Python function which can not run simultaneously in + multiple threads. + +.. challenge:: (advanced) Parallel-2 Running on a cluster + + How does the pool know how many CPUs to take? What happens if you + run on a computer cluster and request only part of the CPUs on a + node? + + .. solution:: + + Pool by default uses one process for each CPU on the node - it + doesn't know about your cluster's scheduling system. It's + possible that you have permission to use 2 CPUs but it is trying + to use 12. This is generally a bad situation, and will just + slow you down (and make other users on the same node upset)! + + You either need to be able to specify the number of CPUs to use + (and pass it the right number), or make it aware of the cluster + system. For example, on a Slurm cluster you would check the + environment variable ``SLURM_CPUS_PER_TASK``. + + Whatever you do, document what your code is doing under the + hood, so that other users know what is going on (we've learned + this from experience...). + + +MPI +--- + +The message passing interface (MPI) approach to parallelization +is that: + +- Tasks (cores) have a rank and are numbered 0, 1, 2, 3, ... +- Each task (core) manages its own memory +- Tasks communicate and share data by sending messages +- Many higher-level functions exist to distribute information to other tasks + and gather information from other tasks +- All tasks typically run the entire code and we have to be careful to avoid + that all tasks do the same thing + +Introductory MPI lessons where Python is included: + +- https://rantahar.github.io/introduction-to-mpi/ +- https://pdc-support.github.io/introduction-to-mpi/ + +These blog posts are good for gentle MPI/mpi4py introduction: + +- https://www.kth.se/blogs/pdc/2019/08/parallel-programming-in-python-mpi4py-part-1/ +- https://www.kth.se/blogs/pdc/2019/11/parallel-programming-in-python-mpi4py-part-2/ + +Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together. + +Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work: + +.. code-block:: python + :emphasize-lines: 3,23-25,29,39,42 + + import random + import time + from mpi4py import MPI + + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x ** 2 + y ** 2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + + comm = MPI.COMM_WORLD + size = comm.Get_size() + rank = comm.Get_rank() + + n = 10 ** 7 + + if size > 1: + n_task = int(n / size) + else: + n_task = n + + t0 = time.perf_counter() + _, n_inside_circle = sample(n_task) + t = time.perf_counter() - t0 + + print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}") + n_inside_circle = comm.gather(n_inside_circle, root=0) + print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}") + + if rank == 0: + pi_estimate = 4.0 * sum(n_inside_circle) / n + print( + f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds" + ) + + + +Exercises, MPI +-------------- + +.. challenge:: Parallel-3, MPI + + We can do this as **exercise or as demo**. Note that this example requires ``mpi4py`` and a + MPI installation such as for instance `OpenMPI `__. + + - Try to run this example on one core: ``$ python example.py``. + - Then compare the output with a run on multiple cores (in this case 2): ``$ mpiexec -n 2 python example.py``. + - Can you guess what the ``comm.gather`` function does by looking at the print-outs right before and after. + - Why do we have the if-statement ``if rank == 0`` at the end? + - Why did we use ``_, n_inside_circle = sample(n_task)`` and not ``n, n_inside_circle = sample(n_task)``? + + + .. solution:: + + We first run the example normally, and get: + + .. code-block:: console + + $ python example.py + before gather: rank 0, n_inside_circle: 7854305 + after gather: rank 0, n_inside_circle: [7854305] + + number of darts: 10000000, estimate: 3.141722, time spent: 2.5 seconds + + Next we take advantage of the MPI parallelisation and run on 2 cores: + + .. code-block:: console + + $ mpirun -n 2 python mpi_test.py + before gather: rank 0, n_inside_circle: 3926634 + before gather: rank 1, n_inside_circle: 3925910 + after gather: rank 1, n_inside_circle: None + after gather: rank 0, n_inside_circle: [3926634, 3925910] + + number of darts: 10000000, estimate: 3.1410176, time spent: 1.3 seconds + + Note that two MPI processes are now printing output. Also, the parallel + version runs twice as fast! + + The ``comm.gather`` function collects (gathers) values of a + given variable from all MPI ranks onto one `root` rank, which is + conventionally rank 0. + + A conditional ``if rank == 0`` is typically used to print output + (or write data to file, etc) from only one rank. + + An underscore ``_`` is often used as a variable name in cases + where the data is unimportant and will not be reused. + +Coupling to other languages +--------------------------- + +As mentioned further up in "Multithreading and the GIL", Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP "directly". + +However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don't +need parallelism, but need to make an optimized algorithm for a small part of the code. + +Two strategies are common: + +- Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization: + + - C: use the `cffi `__ package (C foreign function interface). :py:mod:`ctypes` is a similar but slightly more primitive module that is in the standard library. + - C++: use `pybind11 `__ + - Fortran: create a C interface using ``iso_c_binding`` and then couple the C layer to Python + using `cffi `__ + - Rust: use `PyO3 `__ + +- Let compiled languages do the shared-memory parallelization part (as in above + point) and let Python do the MPI work and distribute tasks across nodes using + an ``mpi4py`` layer. + +Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course. + +Before you take this route, **profile the application** first to be sure where +the bottleneck is. + +Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason. + + + +Dask and task queues +-------------------- + +There are other strategies that go completely beyond the manual +parallelization methods above. We won't go into much detail. + +Dask +~~~~ + +`Dask `__ is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs. + +Dask is very popular for data analysis and is used by a number of high-level Python libraries: + +- Dask arrays scale NumPy (see also `xarray `__ +- Dask dataframes scale Pandas workflows +- Dask-ML scales Scikit-Learn + +Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block. + +.. discussion:: Example from dask.org + + .. code-block:: + + # Arrays implement the Numpy API + import dask.array as da + x = da.random.random(size=(10000, 10000), + chunks=(1000, 1000)) + x + x.T - x.mean(axis=0) + # It runs using multiple threads on your machine. + # It could also be distributed to multiple machines + + + +Exercises, Dask +--------------- + +.. challenge:: Dask-Examples (optional) + + `Dask examples `__ illustrate the usage of dask and can be run interactively through `mybinder `__. Start an `interactive session on mybinder `__ and test/run a few dask examples. + +.. warning: dask on HPC + + On HPC, it is important to use `dask-mpi `__ that deploys dask using MPI4Py. The setup can be a bit tricky and we recommend the usage of `dask-jobqueue and dask-drmaa `__: these packages need to be installed on the target platform (not through conda) to fully benefit from the native underlying MPI libraries. + +Task queues +~~~~~~~~~~~ + +A **task queue** has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for *embarrassingly parallel* jobs. + +There are different descriptions of `task queues in Python +`__. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant. + + + +See also +-------- + +* `Thinking about Concurrency, Raymond Hettinger + `__. Good introduction to simple and + safe concurrent code. +* `Introduction to Numba and Cython `__. +* `More detailed exposition of parallel computing in Python `__. +* `Introduction to Dask for scalable analytics `__. + +.. keypoints:: + + - Pure Python is not very good for highly parallel code. + - Luckily it interfaces to many things which *are* good, and give + you the full control you need. + - Combining vectorized functions (NumPy, Scipy, pandas, etc.) with + the parallel strategies listed here will get you very far. + - Another popular framework similar to `multiprocessing` is + `joblib `__. diff --git a/_sources/plotting-matplotlib.md.txt b/_sources/plotting-matplotlib.md.txt new file mode 100644 index 00000000..f09b0736 --- /dev/null +++ b/_sources/plotting-matplotlib.md.txt @@ -0,0 +1,434 @@ +# Plotting with Matplotlib + +```{questions} +- What happens if you can't automatically produce plots? +- When to use Matplotlib for data visualization? +- When to prefer other libraries? +``` + +```{objectives} +- Be able to create simple plots with Matplotlib and tweak them +- Know about object-oriented vs pyplot interfaces of Matplotlib +- Be able to adapt gallery examples +- Know how to look for help +- Know that other tools exist +``` + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **Try to minimize manual post-processing**. This could bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Vega-Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization, statistics built in + (we have an [entire lesson about data visualization using Vega-Altair](https://coderefinery.github.io/data-visualization-python/)) + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/gallery/index.html): + Jupyter Notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative. + + +## Why are we starting with Matplotlib? + +- Matplotlib is perhaps the most popular Python plotting library. +- Many libraries build on top of Matplotlib (example: [Seaborn](https://seaborn.pydata.org/examples/index.html)). +- MATLAB users will feel familiar. +- Even if you choose to use another library (see above list), chances are high + that you need to adapt a Matplotlib plot of somebody else. +- Libraries that are built on top of Matplotlib may need knowledge of Matplotlib + for custom adjustments. + +However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code. + +Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. + + +## Getting started with Matplotlib + +We can start in a Jupyter Notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK. + +Let us create our first plot using +{func}`~matplotlib.pyplot.subplots`, +{obj}`~matplotlib.axes.Axes.scatter`, and some other methods on the +{obj}`~matplotlib.axes.Axes` object: + +```python +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("my-first-plot.png") +``` + +```{figure} plotting-matplotlib/first-plot/getting-started.png +:alt: Result of our first plot +:width: 80% + +This is the result of our first plot. +``` + +When running a Matplotlib script on a remote server without a +"display" (e.g. compute cluster), you may need to add the +{obj}`matplotlib.use` call: + +```python +import matplotlib.pyplot as plt +matplotlib.use("Agg") + +# ... rest of the script +``` + +## Exercise: Matplotlib + +````{challenge} Exercise Matplotlib-1: extend the previous example (15 min) +- Extend the previous plot by also plotting this set of values but this time + using a different color (`#56B4E9`): + ```python + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + ``` + +- Then add another color (`#009E73`) which plots the second dataset, scaled + by 2.0. + ```python + # here we multiply all elements of data2_y by 2.0 + data2_y_scaled = [y * 2.0 for y in data2_y] + ``` + +- Try to add a legend to the plot with {meth}`matplotlib.axes.Axes.legend` and searching the web for clues on + how to add labels to each dataset. + You can also consult this great + [quick start guide](https://matplotlib.org/stable/users/explain/quick_start.html). + +- At the end it should look like this one: + ```{figure} plotting-matplotlib/first-plot/exercise.png + :alt: Result of the exercise + ``` + +- Experiment also by using named colors (e.g. "red") instead of the hex-codes. +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 9, 12, 17-18, 23 +--- +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +# this is dataset 2 +data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + +# here we multiply all elements of data2_y by 2.0 +data2_y_scaled = [y * 2.0 for y in data2_y] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00", label="set 1") +ax.scatter(x=data_x, y=data2_y, c="#56B4E9", label="set 2") +ax.scatter(x=data_x, y=data2_y_scaled, c="#009E73", label="set 2 (scaled)") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") +ax.legend() + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("exercise-plot.png") +``` +```` + +```{discussion} Why these colors? +This qualitative color palette is optimized for all color-vision +deficiencies, see and +[Okabe, M., and K. Ito. 2008. "Color Universal Design (CUD): +How to Make Figures and Presentations That Are Friendly to Colorblind People"](http://jfly.iam.u-tokyo.ac.jp/color/). +``` + +--- + +## Matplotlib has two different interfaces + +When plotting with Matplotlib, it is useful to know and understand that +there are **two approaches** even though the reasons of this dual approach is +outside the scope of this lesson. + +- The more modern option is an **object-oriented interface** or **explicit interface** (the + {class}`fig ` and {class}`ax ` objects + can be configured separately and passed around to functions): + ```{code-block} python + --- + emphasize-lines: 8-14 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + ``` + +- The more traditional option mimics MATLAB plotting and uses the + **pyplot interface** or **implicit interface** ({mod}`plt ` carries + the global settings): + ```{code-block} python + --- + emphasize-lines: 8-12 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + plt.scatter(x=data_x, y=data_y, c="#E69F00") + + plt.xlabel("we should label the x axis") + plt.ylabel("we should label the y axis") + plt.title("some title") + ``` + +When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, **we +recommend to learn and use the object oriented interface.** + +```{discussion} Why do we emphasize this? +One day you may want to write functions which wrap +around Matplotlib function calls and then you can send {class}`~matplotlib.figure.Figure` and {class}`~matplotlib.axes.Axes` +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions. + +When using the pyplot interface, settings are modified for the entire +{mod}`matplotlib.pyplot` package. The latter is acceptable for simple scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls. +``` + +--- + +## Styling and customizing plots + +- Before you customize plots "manually" using a graphical program, please + consider how this affects reproducibility. +- **Try to minimize manual post-processing**. This might bite you when you + need to regenerate 50 figures one day before submission deadline or + regenerate a set of figures after the person who created them left the group. +- Matplotlib and also all the other libraries allow to customize almost every aspect of a plot. +- It is useful to study [Matplotlib parts of a figure](https://matplotlib.org/stable/users/explain/quick_start.html#parts-of-a-figure) + so that we know what to search for to customize things. +- Matplotlib cheatsheets: +- You can also select among pre-defined themes/ + [style + sheets](https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html) + with {obj}`~matplotlib.style.use`, for instance: + ```python + plt.style.use('ggplot') + ``` + + +## Exercises: Styling and customization + +Here are 3 exercises where we try to adapt existing scripts to either **tweak +how the plot looks** (exercises 1 and 2) or to **modify the input data** (example 3). + +This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice: +- Select an example that is close to what you have in mind +- Being able to adapt it to your needs +- Being able to search for help +- Being able to understand help request answers (not easy) + +````{challenge} Exercise Customization-1: log scale in Matplotlib (15 min) +In this exercise we will learn how to use log scales. + +- To demonstrate this we first fetch some data to plot: + ```python + import pandas as pd + + url = ( + "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + ) + gapminder_data = pd.read_csv(url).query("year == 2007") + + gapminder_data + ``` +- Try the above snippet in a notebook and it will give you an overview over the data. + +- Then we can plot the data, first using a linear scale: + ```python + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + + ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) + + ax.set_xlabel("GDP per capita (PPP dollars)") + ax.set_ylabel("Life expectancy (years)") + ``` + + This is the result but we realize that a linear scale is not ideal here: + ```{figure} plotting-matplotlib/customizing/gapminder-linear.png + :alt: Gapminder data plotted using a linear scale + ``` + +- Your task is to switch to a log scale and arrive at this result: + ```{figure} plotting-matplotlib/customizing/gapminder-log.png + :alt: Gapminder data plotted using log scale + ``` + +- What does ``alpha=0.5`` do? +```` + +````{solution} +See {meth}`ax.set_xscale() `. + +```{code-block} python +--- +emphasize-lines: 5 +--- +fig, ax = plt.subplots() + +ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP per capita (PPP dollars)") +ax.set_ylabel("Life expectancy (years)") +``` +* {obj}`alpha ` sets transparency + of points. +```` + +````{challenge} Exercise Customization-2: preparing a plot for publication (15 min) +Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches. + +For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small. + +Your task is to make the tickmarks and the axis label font larger, using +[Matplotlib parts of a figure](https://matplotlib.org/stable/users/explain/quick_start.html#parts-of-a-figure) +and web search, and to arrive at this: + +```{figure} plotting-matplotlib/customizing/gapminder-larger-font.png +:alt: Gapminder data plotted with larger font and larger ticks +``` +```` + +````{solution} +See {meth}`ax.tick_params `. + +```{code-block} python +--- +emphasize-lines: 7-8, 10-12 +--- +fig, ax = plt.subplots() + +ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data) + +ax.set_xscale("log") + +ax.set_xlabel("GDP per capita (PPP dollars)", fontsize=15) +ax.set_ylabel("Life expectancy (years)", fontsize=15) + +ax.tick_params(which="major", length=10) +ax.tick_params(which="minor", length=5) +ax.tick_params(labelsize=15) +``` +```` + +--- + +```{discussion} +After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on. +``` + +--- + +## Matplotlib and pandas DataFrames + +In the above exercises we have sent individual columns of the `gapminder_data` DataFrame +into `ax.scatter()` like this: +```python +fig, ax = plt.subplots() + +ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) +``` + +It is possible to do this instead and let Matplotlib "unpack" the columns: +```python +fig, ax = plt.subplots() + +ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data) +``` + +Other input types are possible. See [Types of inputs to plotting +functions](https://matplotlib.org/stable/users/explain/quick_start.html#types-of-inputs-to-plotting-functions). + +--- + +```{keypoints} +- Minimize manual post-processing, script everything. +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Figures for presentation slides and figures for manuscripts have + different requirements. +- Think about color-vision deficiencies when choosing colors. Use + existing solutions for this problem. +``` diff --git a/_sources/plotting-vega-altair.md.txt b/_sources/plotting-vega-altair.md.txt new file mode 100644 index 00000000..f775d36d --- /dev/null +++ b/_sources/plotting-vega-altair.md.txt @@ -0,0 +1,690 @@ +# Plotting with [Vega-Altair](https://altair-viz.github.io/) + +:::{objectives} +- Be able to create simple plots with Vega-Altair and tweak them +- Know how to look for help +- Reading data with Pandas from disk or a web resource +- Know how to tweak example plots from a gallery for your own purpose +- We will build up + [this notebook](https://nbviewer.org/github/AaltoSciComp/python-for-scicomp/blob/master/resources/notebooks/plotting.ipynb) + (spoiler alert!) +::: + +:::{instructor-note} +- 10 min: Introduction +- 10 min: Type-along (creating a first plot) +- 20 min: Exercise (using visual channels) +- 20 min: Exercise (adapting a gallery example and customizing) +- 10 min: Key points, discussion, and Q&A +::: + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **Try to minimize manual post-processing**. This could bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Vega-Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization, statistics built in + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/gallery/index.html): + Jupyter Notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative (e.g. Vega-Altair). + + +## Why are we starting with [Vega-Altair](https://altair-viz.github.io/)? + +- Concise and powerful +- "Simple, friendly and consistent API" allows us to focus on the data + visualization part and get started without too much Python knowledge +- The way it **combines visual channels with data columns** can feel intuitive +- Interfaces very nicely with [Pandas](https://pandas.pydata.org/) ({ref}`earlier episode `) +- Easy to change figures +- Good documentation +- Open source +- Makes it easy to save figures in a number of formats (svg, png, html) +- Easy to save interactive visualizations to be used in websites + + +## Example data: Weather data from two Norwegian cities + +We will experiment with some example weather data obtained from [Norsk +KlimaServiceSenter](https://seklima.met.no/observations/), Meteorologisk +institutt (MET) (CC BY 4.0). The data is in CSV format (comma-separated +values) and contains daily and monthly weather data for two cities in Norway: +Oslo and Tromsø. You can browse the data +[here in the lesson repository](https://github.com/AaltoSciComp/python-for-scicomp/tree/master/resources/data/plotting). + +We will use the Pandas library to read the data into a dataframe. We have learned about Pandas in an {ref}`earlier episode `. + +Pandas can read from and write to a large set of formats +([overview of input/output functions and formats](https://pandas.pydata.org/pandas-docs/stable/reference/io.html)). +We will load a CSV file directly from the web. Instead of using a web URL we +could use a local file name instead. + +Pandas dataframes are a great data structure for **tabular data** and tabular +data turns out to be a great input format for data visualization libraries. +Vega-Altair understands Pandas dataframes and can plot them directly. + + +## Reading data into a dataframe + +We can try this together in a notebook: +Using Pandas we can **merge, join, concatenate, and compare** +dataframes, see . + +Let us try to **concatenate** two dataframes: one for Tromsø weather data (we +will now load monthly values) and one for Oslo: +```{code-block} python +--- +emphasize-lines: 8 +--- +import pandas as pd + +url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/" + +data_tromso = pd.read_csv(url_prefix + "tromso-monthly.csv") +data_oslo = pd.read_csv(url_prefix + "oslo-monthly.csv") + +data_monthly = pd.concat([data_tromso, data_oslo], axis=0) + +# let us print the combined result +data_monthly +``` + +Before plotting the data, there is a problem which we may not see yet: Dates +are not in a standard date format (YYYY-MM-DD). We can fix this: +```python +# replace mm.yyyy to date format +data_monthly["date"] = pd.to_datetime(list(data_monthly["date"]), format="%m.%Y") +``` + +With Pandas it is possible to do a lot more (adjusting missing values, fixing +inconsistencies, changing format). + + +## Plotting the data + +Now let's plot the data. We will start with a plot that is not optimal and +then we will explore and improve a bit as we go: + +```python +import altair as alt + +alt.Chart(data_monthly).mark_bar().encode( + x="date", + y="precipitation", + color="name", +) +``` + +:::{figure} plotting-vega-altair/precipitation-on-top.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +::: + +:::{discussion} Let us pause and explain the code +- `alt` is a short-hand for `altair` which we imported on top of the notebook +- `Chart()` is a function defined inside `altair` which takes the data as argument +- `mark_bar()` is a function that produces bar charts +- `encode()` is a function which encodes data columns to **visual channels** + +Observe how we connect (encode) **visual channels** to data columns: +- x-coordinate with "date" +- y-coordinate with "precipitation" +- color with "name" (name of weather station; city) +::: + +We can improve the plot by giving Vega-Altair a bit more information that the +x-axis is **temporal** (T) and that we would like to see the year and +month (yearmonth): +```{code-block} python +--- +emphasize-lines: 2 +--- +alt.Chart(data_monthly).mark_bar().encode( + x="yearmonth(date):T", + y="precipitation", + color="name", +) +``` + +Apart from T (temporal), there are other +[encoding data types](https://altair-viz.github.io/user_guide/encodings/index.html#encoding-data-types): +- Q (quantitative) +- O (ordinal) +- N (nominal) +- T (temporal) +- G (geojson) + +:::{figure} plotting-vega-altair/precipitation-on-top-yearmonth.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +::: + +Let us improve the plot with another one-line change: +```{code-block} python +--- +emphasize-lines: 5 +--- +alt.Chart(data).mark_bar().encode( + x="yearmonth(date):T", + y="precipitation", + color="name", + column="name", +) +``` + +:::{figure} plotting-vega-altair/precipitation-side.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. +::: + +With another one-line change we can make the bar chart stacked: +```{code-block} python +--- +emphasize-lines: 5 +--- +alt.Chart(data_monthly).mark_bar().encode( + x="yearmonth(date):T", + y="precipitation", + color="name", + xOffset="name", +) +``` +:::{figure} plotting-vega-altair/precipitation-stacked-x.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year +plotted as stacked bar chart. +::: + +This is not publication-quality yet but a really good start! + +Let us try one more example where we can nicely see how Vega-Altair +is able to map visual channels to data columns: +```python +alt.Chart(data_monthly).mark_area(opacity=0.5).encode( + x="yearmonth(date):T", + y="max temperature", + y2="min temperature", + color="name", +) +``` + +:::{figure} plotting-vega-altair/temperature-ranges-combined.svg +:alt: Monthly temperature ranges for two cities in Norway. + +Monthly temperature ranges for two cities in Norway. +::: + +:::{discussion} What other marks and other visual channels exist? +- [Overview of available marks](https://altair-viz.github.io/user_guide/marks/index.html) +- [Overview of available visual channels](https://altair-viz.github.io/user_guide/encodings/channels.html) +- [Gallery of examples](https://altair-viz.github.io/gallery/index.html) +::: + + +## Exercise: Using visual channels to re-arrange plots + +::::{exercise} Plotting-1: Using visual channels to re-arrange plots +1. Try to reproduce the above plots if they are not already in your notebook. + +1. Above we have plotted the monthly precipitation for two cities side by side + using a stacked plot. Try to arrive at the following plot where months are + along the y-axis and the precipitation amount is along the x-axis: + :::{figure} plotting-vega-altair/precipitation-stacked-y.svg + ::: + +1. Ask the Internet or AI how to change the axis title from "precipitation" + to "Precipitation (mm)". + +1. Modify the temperature range plot to show the temperature ranges for the + two cities side by side like this: + :::{figure} plotting-vega-altair/temperature-ranges-side.svg + ::: + +:::{solution} +1. Copy-paste code blocks from above. + +1. Basically we switched x and y: + ```{code-block} python + --- + emphasize-lines: 2,3,5 + --- + alt.Chart(data_monthly).mark_bar().encode( + y="yearmonth(date):T", + x="precipitation", + color="name", + yOffset="name", + ) + ``` + +1. This can be done with the following modification: + ```{code-block} python + --- + emphasize-lines: 3 + --- + alt.Chart(data_monthly).mark_bar().encode( + y="yearmonth(date):T", + x=alt.X("precipitation").title("Precipitation (mm)"), + color="name", + yOffset="name", + ) + ``` + +1. We added one line: + ```{code-block} python + --- + emphasize-lines: 6 + --- + alt.Chart(data_monthly).mark_area(opacity=0.5).encode( + x="yearmonth(date):T", + y="max temperature", + y2="min temperature", + color="name", + column="name", + ) + ``` +::: +:::: + + +## More fun with visual channels + +Now we will try to **plot the daily data and look at snow depths**. We first +read and concatenate two datasets: +```python +url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/" + +data_tromso = pd.read_csv(url_prefix + "tromso-daily.csv") +data_oslo = pd.read_csv(url_prefix + "oslo-daily.csv") + +data_daily = pd.concat([data_tromso, data_oslo], axis=0) +``` + +We adjust the data a bit: +```python +# replace dd.mm.yyyy to date format +data_daily["date"] = pd.to_datetime(list(data_daily["date"]), format="%d.%m.%Y") + +# we are here only interested in the range december to may +data_daily = data_daily[ + (data_daily["date"] > "2022-12-01") & (data_daily["date"] < "2023-05-01") +] +``` + +Now we can plot the snow depths for the months December to May for the two +cities: +```python +alt.Chart(data_daily).mark_bar().encode( + x="date", + y="snow depth", + column="name", +) +``` + +:::{figure} plotting-vega-altair/snow-depth.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. +::: + +What happens if we try to color the plot by the "max temperature" values? +```{code-block} python +--- +emphasize-lines: 4 +--- +alt.Chart(data_daily).mark_bar().encode( + x="date", + y="snow depth", + color="max temperature", + column="name", +) +``` + +The result looks neat: +:::{figure} plotting-vega-altair/snow-depth-color.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. +::: + +We can change the color scheme ([available color schemes](https://vega.github.io/vega/docs/schemes/)): +```{code-block} python +--- +emphasize-lines: 4 +--- +alt.Chart(data_daily).mark_bar().encode( + x="date", + y="snow depth", + color=alt.Color("max temperature").scale(scheme="plasma"), + column="name", +) +``` + +With the following result: +:::{figure} plotting-vega-altair/snow-depth-plasma.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +::: + +Let's try one more change to show that we can experiment with different +plot types by changing `mark_bar()` to something else, in this case `mark_circle()`: +```{code-block} python +--- +emphasize-lines: 1 +--- +alt.Chart(data_daily).mark_circle().encode( + x="date", + y="snow depth", + color=alt.Color("max temperature").scale(scheme="plasma"), + column="name", +) +``` + +:::{figure} plotting-vega-altair/snow-depth-circles.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +::: + + +## Themes + +In [Vega-Altair](https://altair-viz.github.io/) you can change the theme and +select from a long [list of themes](https://github.com/vega/vega-themes). On +top of your notebook try to add: +```python +alt.themes.enable('dark') +``` +Then re-run all cells. Later you can try some other themes such as: +- `fivethirtyeight` +- `latimes` +- `urbaninstitute` + +You can even define your own themes! + + +## Exercise: Adapting a gallery example + +In this exercise we can try to adapt existing scripts to either **tweak how the +plot looks** or to **modify the input data**. This is very close to real life: +there are so many options and possibilities and it is almost impossible to +remember everything so this strategy is useful to practice: +- Select an example that is close to what you have in mind +- Being able to adapt it to your needs +- Being able to search for help + +::::{exercise} Plotting-2: Adapting a gallery example +**This is a great exercise which is very close to real life.** + +- Browse the [Vega-Altair example gallery](https://altair-viz.github.io/gallery/index.html). +- Select one example that is close to your current/recent visualization project + or simply interests you. +- First try to reproduce this example, as-is, in the Jupyter Notebook. +- **If you get the error "ModuleNotFoundError: No module named + 'vega_datasets'", then try one of these examples:** (they do not need the "vega_datasets" module) + - [Slider cutoff](https://altair-viz.github.io/gallery/slider_cutoff.html) + (**below you can find a walk-through for this example**) + - [Multi-Line tooltip](https://altair-viz.github.io/gallery/multiline_tooltip_standard.html) + - [Heatmap](https://altair-viz.github.io/gallery/simple_heatmap.html) + - [Layered histogram](https://altair-viz.github.io/gallery/layered_histogram.html) +- Then try to print out the data that is used in this example just before the call of the plotting function + to learn about its structure. Consider writing the data to file before changing it. +- Then try to modify the data a bit. +- If you have time, try to feed it different, simplified data. + **This will be key for adapting the examples to your projects.** + +:::{solution} Example walk-through for the slider cutoff example +In this walk-through I imagine browsing: + +Then this example caught my eye: + +I then copy-paste the example code into a notebook and try to run it and I get +the same result. + +If you get stuck below, **you can also browse all the steps** in a [notebook +using +nbviewer](https://nbviewer.org/github/AaltoSciComp/python-for-scicomp/blob/master/resources/notebooks/plotting-exercise-2.ipynb). + +Next, there is a lot of code that I don't (need to) understand yet but my eyes are trying to find +`alt.Chart` which tells me that the data must be the "df" in `alt.Chart(df)`: +```{code-block} python +--- +emphasize-lines: 15 +--- +import altair as alt +import pandas as pd +import numpy as np + +rand = np.random.RandomState(42) + +df = pd.DataFrame({ + 'xval': range(100), + 'yval': rand.randn(100).cumsum() +}) + +slider = alt.binding_range(min=0, max=100, step=1) +cutoff = alt.param(bind=slider, value=50) + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff +) +``` + +My next step will be to print out the data `df` just before the call to `alt.Chart`: +```{code-block} python +--- +emphasize-lines: 15 +--- +import altair as alt +import pandas as pd +import numpy as np + +rand = np.random.RandomState(42) + +df = pd.DataFrame({ + 'xval': range(100), + 'yval': rand.randn(100).cumsum() +}) + +slider = alt.binding_range(min=0, max=100, step=1) +cutoff = alt.param(bind=slider, value=50) + +print(df) + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff + ) +``` + +The print reveals that `df` is a dataframe which contains x and y values: +```text + xval yval +0 0 0.496714 +1 1 0.358450 +2 2 1.006138 +3 3 2.529168 +4 4 2.295015 +.. ... ... +95 95 -10.712354 +96 96 -10.416233 +97 97 -10.155178 +98 98 -10.150065 +99 99 -10.384652 + +[100 rows x 2 columns] +``` + +The next thing that often helps me is to save the data to a comma-separated +values (CSV) file: +```python +import pandas as pd + +df.to_csv("data.csv", index=False) +``` + +I then open the file in an editor and see that it contains 100 rows: +```text +xval,yval +0,0.4967141530112327 +1,0.358449851840048 +2,1.0061383899407406 +3,2.5291682463487657 +4,2.2950148716254297 +5,2.060877914676249 +6,3.6400907301836405 +7,4.407525459336549 +8,3.938051073401597 +9,4.4806111169875615 +... +``` + +Saving the data to file often helps me to see the structure of the data and now +I am in a position to replace this with my own data. I create a file called +"mydata.csv" and there I use the maximum temperatures for months 1-10 from the +Tromso monthly data which we used further up: +```text +xval,yval +01,7.7 +02,6.6 +03,4.5 +04,9.8 +05,17.7 +06,25.4 +07,26.7 +08,25.1 +09,19.3 +10,9.8 +``` + +In the notebook I then verify that the reading of the data works: +```python +mydata = pd.read_csv("mydata.csv") + +mydata +``` + +Now I can replace the example with my own data (note how I now can comment out +some code that I don't need any longer): +```{code-block} python +--- +emphasize-lines: 16 +--- +import altair as alt +import pandas as pd +# import numpy as np + +# rand = np.random.RandomState(42) + +# df = pd.DataFrame({ +# 'xval': range(100), +# 'yval': rand.randn(100).cumsum() +# }) + +slider = alt.binding_range(min=0, max=100, step=1) +cutoff = alt.param(bind=slider, value=50) + +# print(df) +df = pd.read_csv("mydata.csv") + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff + ) +``` + +Seems to work! I then make few more adjustments (I want the slider to work on +the y-axis and have a more reasonable default): +```{code-block} python +--- +emphasize-lines: 4,5,13 +--- +import altair as alt +import pandas as pd + +slider = alt.binding_range(min=0, max=30, step=1) +cutoff = alt.param(bind=slider, value=15) + +df = pd.read_csv("mydata.csv") + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.yval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff + ) +``` + +My next steps would then be to change axis titles, display the month names, add +a legend, and refine from here. + +**You can also browse all the steps** in a [notebook using +nbviewer](https://nbviewer.org/github/AaltoSciComp/python-for-scicomp/blob/master/resources/notebooks/plotting-exercise-2.ipynb). +::: +:::: + +--- + +:::{keypoints} +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Minimize manual post-processing and try to script all steps. +- CSV (comma-separated values) files are often a good format to store the data + that we wish to plot. +- Read the data into a Pandas dataframe and then plot it with Vega-Altair + where you connect data columns to + [visual channels](https://altair-viz.github.io/user_guide/encodings/channels.html). +::: diff --git a/_sources/productivity.md.txt b/_sources/productivity.md.txt new file mode 100644 index 00000000..4a660c37 --- /dev/null +++ b/_sources/productivity.md.txt @@ -0,0 +1,188 @@ +# Productivity tools + +:::{objectives} +- Know about tools that can help you **spot code problems** and help you following + a **consistent code style** without you having to do it manually. +- Get an overview of **AI-based tools** and how they can help you + writing code. +::: + +:::{instructor-note} +- Demo/discussion: 20 min +::: + + +## Linters and formatters + +**Linter**: Tool that analyzes source code to detect potential errors, unused +imports, unused variables, code style violations, and to improve readability. +- Popular linters: + - [Autoflake](https://pypi.org/project/autoflake/) + - [Flake8](https://flake8.pycqa.org/) + - [Pyflakes](https://pypi.org/project/pyflakes/) + - [Pycodestyle](https://pycodestyle.pycqa.org/) + - [Pylint](https://pylint.readthedocs.io/) + - [Ruff](https://docs.astral.sh/ruff/) + +**Formatter**: Tool that automatically formats your code to a consistent style, +for instance following [PEP 8](https://peps.python.org/pep-0008/). + +- Popular formatters: + - [Black](https://black.readthedocs.io/) + - [YAPF](https://github.com/google/yapf) + - [Ruff](https://docs.astral.sh/ruff/) + +In this course we will focus on [Ruff](https://docs.astral.sh/ruff/) since it +can do **both checking and formatting** and you don't have to switch between +multiple tools. + +:::{discussion} Linters and formatters can be configured to your liking +These tools typically have good defaults. But if you don't like the defaults, +you can configure what they should ignore or how they should format or not format. +::: + + +## Examples + +This code example (which we possibly recognize from the previous section about +{ref}`profiling`) +has few problems (highlighted): +```{code-block} python +--- +emphasize-lines: 2, 7, 10 +--- +import re +import requests + + +def count_unique_words(file_path: str) -> int: + unique_words = set() + forgotten_variable = 13 + with open(file_path, "r", encoding="utf-8") as file: + for line in file: + words = re.findall(r"\b\w+\b", line.lower())) + for word in words: + unique_words.add(word) + return len(unique_words) +``` + +Please try whether you can locate these problems using Ruff: +```console +$ ruff check +``` + +Next, let us try to auto-format a code example which is badly formatted and also difficult +to read: +:::::{tabs} + ::::{tab} Badly formatted + ```python + import re + def count_unique_words (file_path : str)->int: + unique_words=set() + with open(file_path,"r",encoding="utf-8") as file: + for line in file: + words=re.findall(r"\b\w+\b",line.lower()) + for word in words: + unique_words.add(word) + return len( unique_words ) + ``` + :::: + + ::::{tab} Auto-formatted + ```python + import re + + + def count_unique_words(file_path: str) -> int: + unique_words = set() + with open(file_path, "r", encoding="utf-8") as file: + for line in file: + words = re.findall(r"\b\w+\b", line.lower()) + for word in words: + unique_words.add(word) + return len(unique_words) + ``` + + This was done using: + ```console + $ ruff format + ``` + :::: +::::: + + +## Type checking + +A (static) type checker is a tool that checks whether the types of variables in your +code match the types that you have specified. +- Tools: + - [Mypy](https://mypy.readthedocs.io/) + - [Pyright](https://github.com/microsoft/pyright) (Microsoft) + - [Pyre](https://pyre-check.org/) (Meta) + + +## Integration with editors + +Many/most of the above tools can be integrated with your editor. For instance, +you can configure your editor to automatically format your code when you save +the file. However, this only makes sense when all team members agree to follow +the same style, otherwise saving and possibly committing changes to version +control will show up changes to code written by others which you possibly +didn't intend to make. + + +## Integration with Jupyter notebooks + +It is possible to automatically format your code in Jupyter notebooks! +For this to work you need +the following three dependencies installed: +- `jupyterlab-code-formatter` +- `black` +- `isort` + +More information and a screen-cast of how this works can be found at +. + + +## Integration with version control + +If you use version control and like to have your code checked or formatted +**before you commit the change**, you can use tools like [pre-commit](https://pre-commit.com/). + + +## AI-assisted coding + +We can use AI as an assistant/apprentice: +- Code completion +- Write a test based on an implementation +- Write an implementation based on a test + +Or we can use AI as a mentor: +- Explain a concept +- Improve code +- Show a different (possibly better) way of implementing the same thing + + +:::{figure} productivity/chatgpt.png +:alt: Screenshot of ChatGPT +:width: 100% + +Example for using a chat-based AI tool. +::: + +:::{figure} productivity/code-completion.gif +:alt: Screen-cast of working with GitHub Copilot +:width: 100% + +Example for using AI to complete code in an editor. +::: + +:::{admonition} AI tools open up a box of questions +- Legal +- Ethical +- Privacy +- Lock-in/ monopolies +- Lack of diversity +- Will we still need to learn programming? +- How will it affect learning and teaching programming? +::: diff --git a/_sources/profiling.md.txt b/_sources/profiling.md.txt new file mode 100644 index 00000000..3136d599 --- /dev/null +++ b/_sources/profiling.md.txt @@ -0,0 +1,215 @@ +# Profiling + +:::{objectives} +- Understand when improving code performance is worth the time and effort. +- Knowing how to find performance bottlenecks in Python code. +- Try `scalene` as one of many tools to profile Python code. +::: + +:::{instructor-note} +- Discussion: 20 min +- Exercise: 20 min +::: + + +## Should we even optimize the code? + +Classic quote to keep in mind: "Premature optimization is the root of all evil." [Donald Knuth] + +:::{discussion} +It is important to ask ourselves whether it is worth it. +- Is it worth spending e.g. 2 days to make a program run 20% faster? +- Is it worth optimizing the code so that it spends 90% less memory? + +Depends. What does it depend on? +::: + + +## Measure instead of guessing + +Before doing code surgery to optimize the run time or lower the memory usage, +we should **measure** where the bottlenecks are. This is called **profiling**. + +Analogy: Medical doctors don't start surgery based on guessing. They first measure +(X-ray, MRI, ...) to know precisely where the problem is. + +Not only programming beginners can otherwise guess wrong, but also experienced +programmers can be surprised by the results of profiling. + + +## One of the simplest tools is to insert timers + +Below we will list some tools that can be used to profile Python code. +But even without these tools you can find **time-consuming parts** of your code +by inserting timers: + + + +```{code-block} python +--- +emphasize-lines: 1,8,10 +--- +import time + + +# ... +# code before the function + + +start = time.time() +result = some_function() +print(f"some_function took {time.time() - start} seconds") + + +# code after the function +# ... +``` + + +## Many tools exist + +The list below here is probably not complete, but it gives an overview of the +different tools available for profiling Python code. + +CPU profilers: +- [cProfile and profile](https://docs.python.org/3/library/profile.html) +- [line_profiler](https://kernprof.readthedocs.io/) +- [py-spy](https://github.com/benfred/py-spy) +- [Yappi](https://github.com/sumerc/yappi) +- [pyinstrument](https://pyinstrument.readthedocs.io/) +- [Perfetto](https://perfetto.dev/docs/analysis/trace-processor-python) + +Memory profilers: +- [memory_profiler](https://pypi.org/project/memory-profiler/) (not actively maintained) +- [Pympler](https://pympler.readthedocs.io/) +- [tracemalloc](https://docs.python.org/3/library/tracemalloc.html) +- [guppy/heapy](https://github.com/zhuyifei1999/guppy3/) + +Both CPU and memory: +- [Scalene](https://github.com/plasma-umass/scalene) + +In the exercise below, we will use Scalene to profile a Python program. Scalene +is a sampling profiler that can profile CPU, memory, and GPU usage of Python. + + +## Tracing profilers vs. sampling profilers + +**Tracing profilers** record every function call and event in the program, +logging the exact sequence and duration of events. +- **Pros:** + - Provides detailed information on the program's execution. + - Deterministic: Captures exact call sequences and timings. +- **Cons:** + - Higher overhead, slowing down the program. + - Can generate larger amount of data. + +**Sampling profilers** periodically samples the program's state (where it is +and how much memory is used), providing a statistical view of where time is +spent. +- **Pros:** + - Lower overhead, as it doesn't track every event. + - Scales better with larger programs. +- **Cons:** + - Less precise, potentially missing infrequent or short calls. + - Provides an approximation rather than exact timing. + +:::{discussion} Analogy: Imagine we want to optimize the London Underground (subway) system +We wish to detect bottlenecks in the system to improve the service and for this we have +asked few passengers to help us by tracking their journey. +- **Tracing**: We follow every train and passenger, recording every stop + and delay. When passengers enter and exit the train, we record the exact time + and location. +- **Sampling**: Every 5 minutes the phone notifies the passenger to note + down their current location. We then use this information to estimate + the most crowded stations and trains. +::: + + +## Choosing the right system size + +Sometimes we can configure the system size (for instance the time step in a simulation +or the number of time steps or the matrix dimensions) to make the program finish sooner. + +For profiling, we should choose a system size that is **representative of the real-world** +use case. If we profile a program with a small input size, we might not see the same +bottlenecks as when running the program with a larger input size. + +Often, when we scale up the system size, or scale the number of processors, new bottlenecks +might appear which we didn't see before. This brings us back to: "measure instead of guessing". + + +## Exercises + +::::{exercise} Exercise: Practicing profiling +In this exercise we will use the Scalene profiler to find out where most of the time is spent +and most of the memory is used in a given code example. + +Please try to go through the exercise in the following steps: +1. Make sure `scalene` is installed in your environment (if you have followed + this course from the start and installed the recommended software + environment, then it is). +1. Download Leo Tolstoy's "War and Peace" from the following link (the text is + provided by [Project Gutenberg](https://www.gutenberg.org/)): + + (right-click and "save as" to download the file and **save it as "book.txt"**). +1. **Before** you run the profiler, try to predict in which function the code + will spend most of the time and in which function it will use most of the + memory. +1. Run the `scalene` profiler on the following code example and browse the + generated HTML report to find out where most of the time is spent and where + most of the memory is used: + ```console + $ scalene example.py + ``` + Alternatively you can do this (and then open the generated file in a browser): + ```console + $ scalene example.py --html > profile.html + ``` + You can find an example of the generated HTML report in the solution below. +1. Does the result match your prediction? Can you explain the results? + +:::{literalinclude} profiling/exercise.py +::: + +:::{solution} + ```{figure} profiling/exercise.png + :alt: Result of the profiling run for the above code example. + :width: 100% + + Result of the profiling run for the above code example. You can click on the image to make it larger. + ``` + + Results: + - Most time is spent in the `count_unique_words2` function. + - Most memory is used in the `count_unique_words1` function. + + Explanation: + - The `count_unique_words2` function is the slowest because it **uses a list** + to store unique words and checks if a word is already in the list before + adding it. + Checking whether a list contains an element might require traversing the + whole list, which is an O(n) operation. As the list grows in size, + the lookup time increases with the size of the list. + - The `count_unique_words1` and `count_unique_words3` functions are faster + because they **use a set** to store unique words. + Checking whether a set contains an element is an O(1) operation. + - The `count_unique_words1` function uses the most memory because it **creates + a list of all words** in the text file and then **creates a set** from that + list. + - The `count_unique_words3` function uses less memory because it traverses + the text file line by line instead of reading the whole file into memory. + + What we can learn from this exercise: + - When processing large files, it can be good to read them line by line + or in batches + instead of reading the whole file into memory. + - It is good to get an overview over standard data structures and their + advantages and disadvantages (e.g. adding an element to a list is fast but checking whether + it already contains the element can be slow). + ::: +:::: + + +## Additional resources + +- [Python performance workshop (by ENCCS)](https://enccs.github.io/python-perf/profile/) diff --git a/_sources/python.rst.txt b/_sources/python.rst.txt new file mode 100644 index 00000000..b9f21315 --- /dev/null +++ b/_sources/python.rst.txt @@ -0,0 +1,186 @@ +Introduction to Python +====================== + +.. questions:: + + - What are the basic blocks of Python language? + - How are functions and classes defined in Python? + +.. objectives:: + + - Get a *very* short introduction to Python types and syntax + - Be able to follow the rest of the examples in the course, even if you don't understand everything perfectly. + + We expect everyone to be able to know the following basic material + to follow the course (though it is not *everything* you need to + know about Python). + +If you are not familiar with Python, here is a *very* short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise. + +.. seealso:: + + This page contains an overview of the basics of Python. You can + also refer to `This Python overview from a different lesson + `__ + which is slightly more engaging. + + + +Scalars +------- + +Scalar types, that is, single elements of various types: + +:: + + i = 42 # integer + i = 2**77 # Integers have arbitrary precision + g = 3.14 # floating point number + c = 2 - 3j # Complex number + b = True # boolean + s = "Hello!" # String (Unicode) + q = b'Hello' # bytes (8-bit values) + +Read more: :class:`int`, :class:`float`, :class:`complex`, +:class:`bool`, :class:`str`, :class:`bytes`. + + +Collections +----------- + +Collections are data structures capable of storing multiple values. + +:: + + l = [1, 2, 3] # list + l[1] # lists are indexed by int + l[1] = True # list elements can be any type + d = {"Janne": 123, "Richard": 456} # dictionary + d["Janne"] + s = set(("apple", "cherry", "banana", "apple")) # Set of unique values + s + +Read more: :class:`list`, :class:`tuple`, :class:`dict`, :class:`set`. + + +Control structures +------------------ + +Python has the usual control structures, that is conditional +statements and loops. For example, the :ref:`if` statement: + +:: + + x = 2 + if x == 3: + print('x is 3') + elif x == 2: + print('x is 2') + else: + print('x is something else') + +:ref:`While ` loops loop until some condition is met: + +:: + + x = 0 + while x < 42: + print('x is ', x) + x += 0.2 + +:ref:`For ` loops loop over some collection of values: + +:: + + xs = [1, 2, 3, 4] + for x in xs: + print(x) + + +Often you want to loop over a sequence of integers, in that case the +:class:`range` function is useful: + +:: + + for x in range(9): + print(x) + +Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the :func:`enumerate` +function: + +:: + + xs = [1, 'hello', 'world'] + for ii, x in enumerate(xs): + print(ii, x) + + +Functions and classes +--------------------- + +Python functions are defined by the :ref:`def` keyword. They take a +number of arguments, and return a number of return values. + +:: + + def hello(name): + """Say hello to the person given by the argument""" + print('Hello', name) + return 'Hello ' + name + + hello("Anne") + +Classes are defined by the :ref:`class` keyword: + +:: + + class Hello: + def __init__(self, name): + self._name = name + def say(self): + print('Hello', self._name) + + h = Hello("Richard") + h.say() + + +Python type system +------------------ + +Python is strongly and dynamically typed. + +Strong here means, roughly, that it's not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior). + +:: + + x = 42 + type(x) + x + "hello" + +Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type: + +:: + + x = 42 + x = "hello" + + +*Jargon*: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation. + + +??? (lesson here) + + + +.. keypoints:: + + - Python offers a nice set of basic types as many other programming languages + - Python is strongly typed and dynamically typed diff --git a/_sources/quick-reference.rst.txt b/_sources/quick-reference.rst.txt new file mode 100644 index 00000000..6d3141e5 --- /dev/null +++ b/_sources/quick-reference.rst.txt @@ -0,0 +1,26 @@ +Quick reference +=============== + +* `Pandas cheatsheet + `__ (pandas.pydata.org) + +* `Pandas cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy cheatsheet + `__ + (via `Datacamp + `__) + +* `JupyterLab cheatsheet + `__ + +* `Matplotlib cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy, Pandas, Matplotlib, Scikit-learn all together + `__ diff --git a/_sources/scipy.rst.txt b/_sources/scipy.rst.txt new file mode 100644 index 00000000..0d921a43 --- /dev/null +++ b/_sources/scipy.rst.txt @@ -0,0 +1,183 @@ +SciPy +===== + +.. questions:: + + - When you need more advanced mathematical functions, where do you + look? + +.. objectives:: + + - Understand that SciPy exists and what kinds of things it has. + - Understand the importance of using external libraries and how to + use them. + - Understand the purpose of wrapping existing C/Fortran code. + - Non-objective: know details of everything (or anything) in SciPy. + +.. seealso:: + + * Main article: `SciPy documentation `__ + + + +SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms. + + + +What's in SciPy? +---------------- + +Briefly, it contains functionality for + +- Special functions (Bessel, Gamma, etc.) +- Numerical integration +- Optimization +- Interpolation +- Fast Fourier Transform (FFT) +- Signal processing +- Linear algebra (more complete than in NumPy) +- Sparse matrices +- Statistics +- More I/O routine, e.g. Matrix Market format for sparse matrices, + MATLAB files (.mat), etc. + +Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages. + +Most functions are documented ridiculously well from a scientific +standpoint: you aren't just using some unknown function, but have a +full scientific description and citation to the method and +implementation. + + + +Exercises: use SciPy +-------------------- + +These exercises do not exist because *you* might need *these* +functions someday. They are because *you* will need to *read +documentation and understand documentation of an an external library* +eventually. + +1: Numerical integration +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Define a function of one variable and using + `scipy.integrate.quad `__ + calculate the integral of your function in the + interval ``[0.0, 4.0]``. Then vary the interval and also modify the function and check + whether scipy can integrate it. + + +.. solution:: + + .. code-block:: python + + from scipy import integrate + + def myfunction(x): + # you need to define result + return result + + integral = integrate.quad(myfunction, 0.0, 4.0) + print(integral) + + `quad + `__ + uses the Fortran library QUADPACK, which one can assume is pretty + good. You can also see a whole lot of scientific information about + the function on the docs page - including the scientific names of + the methods used. + + + +2: Sparse matrices +~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Use the SciPy sparse matrix functionality to create a random sparse + matrix with a probability of non-zero elements of 0.05 and size 10000 + x 10000. The use the SciPy sparse linear algebra support to calculate + the matrix-vector product of the sparse matrix you just created and a + random vector. Use the %timeit macro to measure how long it + takes. Does the optional ``format`` argument when you create the + sparse matrix make a difference? + + Then, compare to how long it takes if you'd instead first convert the + sparse matrix to a normal NumPy dense array, and use the NumPy ``dot`` + method to calculate the matrix-vector product. + + Can you figure out a quick rule of thumb when it's worth using a + sparse matrix representation vs. a dense representation? + +.. solution:: + + The basic code to do the test is: + + .. code-block:: + + import numpy + import scipy.sparse + + vector = numpy.random.random(10000) + matrix = scipy.sparse.rand(10000, 10000, density=.05, format='csc') + + # We time this line + matrix.dot(vector) + + From the top of the `spare matrix module documentation + `__, we can + see there are a variety of different available sparse matrix types: + ``bsr``, ``coo``, ``csr``, ``csc``, etc. These each represent a + different way of storing the matrices. + + It seems that ``csr`` and ``csc`` are fairly fast. ``lil`` and + ``dok`` are slow but it says that these are good for creating + matrices with random insertions. + + For example, ``csr`` takes 7ms, ``lil`` 42ms, ``dok`` 1600ms, and + converting to a non-sparse array ``matrix.toarray()`` and + multiplying takes 64ms on one particular computer. + + This code allows us to time the performance at different + densities. It seems that with the ``csr`` format, sparse is better + below densities of around .4 to .5: + + ..code-block:: + + for density in [.01, .05, .1, .2, .3, .4, .5]: + matrix = scipy.sparse.rand(10000, 10000, density=density, format='csr') + time_sparse = timeit.timeit('matrix.dot(vector)', number=10, globals=globals()) + matrix2 = matrix.toarray() + time_full = timeit.timeit('matrix2.dot(vector)', number=10, globals=globals()) + print(f"{density} {time_sparse:.3f} {time_full:.3f}") + + + +See also +-------- + +* `SciPy general introduction `__ +* `SciPy documentation + `__ + + + +.. keypoints:: + + - When you need advance math or scientific functions, let's just + admit it: you do a web search first. + - But when you see something in SciPy come up, you know your + solutions are in good hands. diff --git a/_sources/scripts.rst.txt b/_sources/scripts.rst.txt new file mode 100644 index 00000000..9fc450ee --- /dev/null +++ b/_sources/scripts.rst.txt @@ -0,0 +1,340 @@ +.. _scripts: + +Scripts +======= + +.. questions:: + + - Why are command line programs useful, compared to Jupyter + notebooks and similar? + - How to create a Python script? + - How to generalize a Python script? + +.. objectives:: + + - Learn how to streamline your Python notebooks by creating repeatable Python scripts + - Learn how to import other Python files + - Learn to parse command line arguments in Python + +Why scripts? +------------- + +So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work. + +But after several weeks of hard work with Python, you may end up: + +- either with 10 different notebooks (so that you can run them concurrently) +- or with a very long notebook which is becoming hardly readable! + +Let's imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks? + +In this episode, we will learn how to automate your work using Python scripts so that + +* you do not need to manually configure your notebooks to be able to run with different parameters +* can easily run you work via other tools, such as on computing clusters. + + +From Jupyter notebooks to Python scripts +----------------------------------------- + +.. highlight:: console + + +Save as Python script +--------------------- + +Jupyter notebooks can be parameterized for instance using `papermill `_. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See `CodeRefinery's lesson on Modular code development `__. + +You need to convert the notebook to a Python file. +Check the `JupyterLab documentation `_ for more information. +You can get a command line by (File → New Launcher → Terminal - if you +go through New Launcher, your command line will be in the directory +you are currently browsing), you can convert files in the terminal by running:: + + $ jupyter nbconvert --to script your_notebook_name.ipynb + + + +If nbconvert doesn't work, within JupyterLab, you can export any +Jupyter notebook to a Python +script, but this downloads it to your own computer and then you need +to copy it to a place you are working (maybe upload it back to +JupyterLab?): + +.. figure:: https://jupyterlab.readthedocs.io/en/stable/_images/exporting-menu.png + :width: 80% + :alt: JupyterLab screenshot as described in caption. + + Select File (top menu bar) → Export Notebook as → **Export notebook to Executable Script**. + + + +Exercises 1 +----------- + +.. challenge:: Scripts-1 + + .. highlight:: console + + + 1. Download the :download:`weather_observations.ipynb <../resources/code/scripts/weather_observations.ipynb>` and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from `rp5.kz `_ and was slightly adjusted for this lecture. + + **Hint:** Copy the URL above (right-click) and in JupyterLab, use + File → Open from URL → Paste the URL. It will both download it to + the directory JupyterLab is in and open it for you. + + 2. Open a terminal in Jupyter: File → New Launcher, then click + "Terminal" there. (if you do it this way, it will be in the right + directory. File → New → Terminal might not be.) + + 3. Convert the Jupyter script to a Python script by calling:: + + $ jupyter nbconvert --to script weather_observations.ipynb + + 4. Run the script (note: you may have ``python3`` rather than ``python``):: + + $ python weather_observations.py + + + +Command line arguments with :data:`sys.argv` +-------------------------------------------- + +We now have a Python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +**What we need is to allow the code to do something different based on something outside the code itself**: in this case, to +plot information for different time ranges. This can be achieved by +using Pythons :py:mod:`sys` package, which provides access to arguments given to the Python interpreter at +startup in the :py:data:`sys.argv` list. The first (i.e. ``sys.argv[0]`` entry of this array is the script that is running, +and any further argument (separated by space) is appended to this list, like such: + +.. code-block:: console + + $ python my_script.py A B + $ # sys.argv[1] is 'A' + $ # sys.argv[2] is 'B' + +Lets see how it works: We modify the **weather_observations.py** script such that we allow start +and end times as well as the output file to be passed in as arguments +to the function. Open it (find the ``.py`` file from the JupyterLab +file browser) and make these edits: + +.. code-block:: python + :emphasize-lines: 1,5-6,8,14-15 + + import sys + import pandas as pd + + # define the start and end time for the plot + start_date = pd.to_datetime(sys.argv[1], dayfirst=True) + end_date = pd.to_datetime(sys.argv[2], dayfirst=True) + ... + + # select the data + weather = weather[weather['Local time'].between(start_date,end_date)] + ... + + # save the figure + output_file_name = sys.argv[3] + fig.savefig(output_file_name) + +We can try it out (see the file ``spring_in_tapiola.png`` made in the +file browser): + +.. code-block:: console + + $ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png + + +.. discussion:: + + - Does it work? + + - Why is this better than modifying the script every time I want it to + plot data for a different period? + + - What problems do you expect when using this approach (using :data:`sys.argv`)? + +This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time: + +- `argparse `__: + built-in to Python, this is the one that we will show below. +- `doctopt `__: you write the help text and this generates a parser for you. +- `click `__: another nice + library for command line interfaces - very easy to use. + + +Parsing command line arguments with :mod:`argparse` +--------------------------------------------------- + +:py:mod:`Argparse ` not only gives you descriptive command line arguments, it also automatically +generates a ``--help`` option for you. To use ``argparse`` you first set up a parser +by calling :class:`parser = argparse.ArgumentParser() ` and then you add arguments using +:py:meth:`parser.add_argument(args) `. There are two different types of arguments: + +- Positional arguments +- Optional arguments + +**Positional arguments** are detected by their order, while **optional arguments** need to be +given with their respective flags ( like ``--name`` or ``-n``). +The following example would parse a positional argument ``Name`` of type ``string`` +and an optional argument ``date`` of type ``string`` which defaults to ``01/01/2000``. + +.. code-block:: python + :emphasize-lines: 3, 5-8, 10 + + import argparse + + parser = argparse.ArgumentParser() + # One positional and one optional argument + parser.add_argument('name', type=str, metavar="N", + help="The name of the subject") + parser.add_argument('-d', '--date', type=string, default="01/01/2000", + help="Birth date of the subject") + + args = parser.parse_args() + + print(args.name + " was born on " + args.date) + +If this code was in ``birthday.py`` and we would call ``python birthday.py --help`` it +would show the following message: + +.. code-block:: console + + $ python birthday.py --help + usage: birthday.py [-h] [-d DATE] N + + positional arguments: + N The name of the subject + + optional arguments: + -h, --help show this help message and exit + -d DATE, --date DATE Birth date of the subject + + +Exercises 2 +----------- + +.. challenge:: Scripts-2 + + 1. Take the Python script (``weather_observations.py``) we have written in the preceding exercise and use + :py:mod:`argparse` to specify the input (URL) and output files and allow the start and end dates to be set. + + * Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on. + * Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output. + * Hint: The start and end dates should be optional parameters with the defaults as they are in the current script. + + 2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). + Also try using this data for Cairo: ``https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv`` + + +.. solution:: + + .. literalinclude:: ../resources/code/scripts/weather_observations_argparse.py + :language: python + :emphasize-lines: 2,4-8,10,13,16-17,37 + + + + +.. discussion:: + + **What was the point of doing this?** + + Now you can do this: + + .. code-block:: console + + $ python weather_observations.py --help + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png + $ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png + $ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv temperature_cairo.png + + - We can now process different input files without changing the script. + - We can select multiple time ranges without modifying the script. + - We can easily save these commands to know what we did. + - This way we can also loop over file patterns (using shell loops or similar) or use + the script in a workflow management system and process many files in parallel. + - By changing from :data:`sys.argv` to :mod:`argparse` we made the script more robust against + user input errors and also got a help text (accessible via ``--help``). + + +Load larger option lists using config files +------------------------------------------- + +In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line: + +.. code-block:: console + + + $ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021 + + +This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple ``Parameter = Value`` +format, and parse it yourself, or you can use e.g. the ``JSON`` or ``YAML`` formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won't go into the details of the formats, and will only give +a short example using YAML here. + +The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (`yaml `__) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the :mod:`json` package). + +The Python module :download:`optionsparser.py <../resources/code/scripts/optionsparser.py>` provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values. + +In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation ...), set the labels and titles explicitly etc. + +In the YAML format, names and values are separated by ``:``. Our above example would therefore translate to the following YAML file: + +.. literalinclude:: ../resources/code/scripts/weather_options.yml + :language: yaml + +Exercises 3 (optional) +---------------------- + +.. challenge:: Scripts-3 + + 1. Download the :download:`optionsparser.py ` + function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). + Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line + (using e.g. :mod:`argparse` or :data:`sys.argv`) still needs to be read from the command line. + + + 2. Run your script with different config files. + + +.. solution:: + + The modified **weather_observations.py** script: + + .. literalinclude:: ../resources/code/scripts/weather_observations_config.py + :language: python + :emphasize-lines: 5,9-12,15-27,30,33,36-37,58 + +What did this config file parser get us? Now, we have separated the +code from the configuration. We could save all the configuration in +version control - separately and have one script that runs them. If +done right, our work could be much more reproducible and +understandable. + + +.. admonition:: Further reading + + - Linking Jupyterlab notebooks to python scripts (making linking ``.py``- and ``.ipynb``-files easier) using `jupytext `_ + - The `wikipedia page about YAML `_ contains a lot of additional information on the YAML syntax. + - `The Coderefinery Lesson about reproducible research `_ can give additional information about good coding practices and workflow automation. + + - `CodeRefinery's lesson on Modular code development `__ diff --git a/_sources/web-apis.ipynb.txt b/_sources/web-apis.ipynb.txt new file mode 100644 index 00000000..f2b376d5 --- /dev/null +++ b/_sources/web-apis.ipynb.txt @@ -0,0 +1,678 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c87bb04a-3f53-45ac-bbc9-fe182c844219", + "metadata": { + "tags": [] + }, + "source": [ + "# Web APIs with Python\n", + "\n", + ":::{questions}\n", + "- Have you ever needed to get some data from somewhere else on the web?\n", + ":::\n", + "\n", + ":::{objectives}\n", + "- Understand a web server and API and why might you need to talk to one.\n", + "- Basics of the [requests](https://requests.readthedocs.io/en/latest/) Python library\n", + "- Some lightweight recommendations on saving data when you get to more serious data download.\n", + ":::\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "2398bb45-e061-4e7a-8931-82906a3892ff", + "metadata": { + "tags": [] + }, + "source": [ + "## Requests\n", + "\n", + "Requests is a Python library that makes **requests** to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.\n", + "\n", + "First, let's take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c69a16ac-a5b3-4ff0-a949-720b5bbd37cd", + "metadata": {}, + "outputs": [], + "source": [ + "# Embed the requests homepage\n", + "from IPython.display import IFrame\n", + "requests_documentation_url = \"https://requests.readthedocs.io/en/latest/\"\n", + "IFrame(requests_documentation_url, '100%', '30%')" + ] + }, + { + "cell_type": "markdown", + "id": "6d6b334b-309e-429b-aad5-0ab76f071c15", + "metadata": {}, + "source": [ + "## Retrieve data from API\n", + "\n", + "An **API (Application Programming Interface)** is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the **request-response** cycle.\n", + "\n", + "We can find a list of some free APIs (available without authentication) at . These APIs can be used for developing and testing our code." + ] + }, + { + "cell_type": "markdown", + "id": "0a21faac-a7d8-448d-a8db-6fb23b9bd64c", + "metadata": { + "tags": [] + }, + "source": [ + "Let's make a request to the Cat Fact API. If we go to , it gives us the definitions:\n", + "* GET `/fact` is the **API endpoint**.\n", + "* **GET** is the type of request we make and\n", + "* `/fact` is the **path**.\n", + "\n", + "You can even test this in your web browser: \n", + "\n", + "Using the Requests library, we do this with {func}`~requests.get`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fa134bb7-1250-46bd-bd80-e3e0d0820523", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "64a7f3be-420b-4e1c-a76d-67d9e6b29f4f", + "metadata": { + "tags": [] + }, + "source": [ + "The {class}`requests.Response` object tells us what the server said. We can access the response content using {attr}`~requests.Response.content`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b3e1ddb3-76a1-4e53-a32b-4005d92626c6", + "metadata": {}, + "outputs": [], + "source": [ + "response_content = response.content\n", + "\n", + "# Display\n", + "display(response_content)" + ] + }, + { + "cell_type": "markdown", + "id": "3886ff1c-0619-4fc5-828a-269257db6e63", + "metadata": { + "tags": [] + }, + "source": [ + "The response content is in the [JSON format](https://en.wikipedia.org/wiki/JSON) and Requests gives us the {meth}`~requests.Response.json` method that decodes it and returns the corresponding data as Python objects. This is equivalent to {func}`json.load`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7651cd8c-9581-4d04-b3bf-c57997a5684a", + "metadata": {}, + "outputs": [], + "source": [ + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json)" + ] + }, + { + "cell_type": "markdown", + "id": "10ca2577-94a4-4689-a01a-2681fe4c5d20", + "metadata": { + "tags": [] + }, + "source": [ + "(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)" + ] + }, + { + "cell_type": "markdown", + "id": "80e02c0b-9b59-44ea-ab26-092b6cdb510b", + "metadata": { + "tags": [] + }, + "source": [ + "## API which requires parameters\n", + "\n", + "Let's then examine another API which accepts [parameters](https://requests.readthedocs.io/en/latest/user/quickstart/#passing-parameters-in-urls) to specify the information request. In particular, we will request a list of Finnish universities from using the `/search` end point and a parameter _country_ with value _Finland_, like this:\n", + "`http://universities.hipolabs.com/search?country=Finland` ." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b98cba34-0f3a-43fb-befe-0e1c48fdb1c3", + "metadata": {}, + "outputs": [], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search?country=Finland'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])" + ] + }, + { + "cell_type": "markdown", + "id": "18ee30d2-e072-41b2-b4d4-8203cb5e86ce", + "metadata": { + "tags": [] + }, + "source": [ + "URLs containing parameters can always be constructed manually using the _&_ character and then listing the parameter (_key_, _value_) pairs as above.\n", + "\n", + "However, _Requests_ allows us to provide the parameters as a dictionary of strings, using the _params_ keyword argument to {func}`~requests.get`. This is easier to read and less error-prone." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1c1ddced-d423-42cd-89ac-3a0c6d751d9d", + "metadata": {}, + "outputs": [], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search'\n", + "\n", + "# Make the parameter dictionary\n", + "parameters = {'country' : 'Finland'}\n", + "\n", + "# Get response\n", + "response = requests.get(url, params=parameters)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])\n" + ] + }, + { + "cell_type": "markdown", + "id": "35c751c9-009c-46f7-af8a-40c4132dcfbd", + "metadata": {}, + "source": [ + "## Exercises 1" + ] + }, + { + "cell_type": "markdown", + "id": "033d8d63-43db-4a3e-a9cd-e142134a0b9b", + "metadata": {}, + "source": [ + "::::{exercise} Exercise WebAPIs-1: Request different activity suggestions from the Bored API\n", + "\n", + "Go to the [documentation page of the Bored API](https://www.boredapi.com/documentation). The Bored API is an open API which can be used to randomly generate activity suggestions.\n", + "\n", + "Let's examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response\n", + "\n", + "```json\n", + "{\n", + " \"activity\": \"Learn Express.js\",\n", + " \"accessibility\": 0.25,\n", + " \"type\": \"education\",\n", + " \"participants\": 1,\n", + " \"price\": 0.1,\n", + " \"link\": \"https://expressjs.com/\",\n", + " \"key\": \"3943506\"\n", + "} \n", + "```\n", + "\n", + "Let's replicate the query and see if we can get another random suggestion.\n", + "::::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1744a2a7-5c9a-48d4-96b4-9d523b2e43bc", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Send the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "77fdd8cd-2c85-474e-bceb-2a737c92521b", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "69ae7da6-6c9c-4f2a-94ea-fc75f437eb80", + "metadata": {}, + "source": [ + "Next, let's try to narrow down the suggestions by adding some parameters\n", + "- type\n", + "- participants\n", + "\n", + "All possible parameter values are presented at the bottom of the bored documentation page. [Relevant parts in the _Requests_ documentation](https://requests.readthedocs.io/en/latest/user/quickstart/#parameters)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "933feded-0d73-4038-b909-6f713cb3782a", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'education',\n", + " 'participants' : 1,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f9dbeea0-31d3-43b0-8d18-94b608e82a77", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(\"Response\")\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "301eb0af-2db2-474b-87e4-8d8815a3a04b", + "metadata": {}, + "source": [ + "Let's narrow the request further with more parameters\n", + "- price range\n", + "- accessibility range\n", + "\n", + "(All possible parameter values are again presented at the bottom of the document page.)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d04823d4-154e-48ec-9576-f537bd20c271", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'social',\n", + " 'participants' : 2,\n", + " 'minprice' : 0,\n", + " 'maxprice' : 1000,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "87978afc-6d0d-46c0-ad0f-e5b851d302e1", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())\n", + "display(\"\")" + ] + }, + { + "cell_type": "markdown", + "id": "0a019d02-cd86-4fdc-874e-b99557955cd1", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "\n", + ":::{exercise} Exercise WebAPIs-2: Examine request and response headers\n", + "\n", + "Request [headers](https://requests.readthedocs.io/en/latest/user/quickstart/#response-headers) are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).\n", + "\n", + "Let's first make a request.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eb583c27-2ce3-420e-a116-b717f8fa0e3e", + "metadata": {}, + "outputs": [], + "source": [ + "# Import modules\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Make the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "271d5abd-6648-4976-899e-25e93d5d8f73", + "metadata": {}, + "source": [ + "We can access the headers of the original request" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "91f78d05-60e7-48ad-8f13-bc4d445e75bc", + "metadata": {}, + "outputs": [], + "source": [ + "display(\"Request headers\")\n", + "display(dict(response.request.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "d6149ec8-c57f-4fab-aaa5-6a61fc7d0291", + "metadata": {}, + "source": [ + "We can also access the headers of the response " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d4ff753a-d3dd-41c9-b533-386d0b30d4c3", + "metadata": {}, + "outputs": [], + "source": [ + "display(\"Response headers\")\n", + "display(dict(response.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "7132bc48-90a0-49ea-a215-a87006aecf1d", + "metadata": {}, + "source": [ + "In many cases, the default headers\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive'}\n", + "```\n", + "\n", + "added automatically by _Requests_ are sufficient. However, similarly to parameters, we can pass [custom headers](https://requests.readthedocs.io/en/latest/user/quickstart/#custom-headers) to the _get_ function as an argument. \n", + "\n", + "This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive',\n", + " 'example-user-id' : 'example-password'}\n", + "```\n", + "\n", + "For examples of APIs using this type of authentication, see\n", + "\n", + "- [Imgur API](https://api.imgur.com/oauth2)\n", + "\n", + "For more on authentication, see also [_Requests_ documentation](https://requests.readthedocs.io/en/latest/user/authentication/). \n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "3d50de82-4f2c-4bc4-8f23-3cb4bdb62127", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "\n", + ":::{exercise} Exercise WebAPIs-3: Scrape links from a webpage (Advanced)\n", + "\n", + "Let's use _Requests_ to get the HTML source code of www.example.com, examine it, and use the [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) library to extract links from it. **Note:** This requires the extra `bs4` Python package to be installed, which was not in our initial requirements. Consider this a demo.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cc3373a9-e54f-4049-b715-481ec9893189", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# Define webpage to scrape\n", + "url = \"http://www.example.com/\"\n", + "\n", + "# Make a request for the URL\n", + "response = requests.get(url)\n", + "\n", + "# Examine the response\n", + "display(response.content)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d59e52c4-95cf-427d-b3d4-8d0a6dc02aa5", + "metadata": {}, + "outputs": [], + "source": [ + "# Looks like HTML :) Let's access it using the text attribute\n", + "html = response.text\n", + "\n", + "print(html)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "327695ae-b376-4d5b-9293-6e89ff272790", + "metadata": {}, + "outputs": [], + "source": [ + "# Import beautiful soup module\n", + "from bs4 import BeautifulSoup\n", + "\n", + "# Create soup\n", + "soup = BeautifulSoup(html, 'html.parser')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0e21c6de-a845-4823-b777-bf2cd44fbfd2", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract page title from the HTML\n", + "print(f\"Found title: {soup.title.text}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a7fa0e7b-b171-4e65-b987-84a101da58df", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract links (hrefs) from the HTML\n", + "for link in soup.find_all('a'):\n", + " print(f\"Found link: {link.get('href')}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6581edcb-c170-4cc7-a442-d8d8c724ca50", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract all text from the HTML\n", + "print(f\"Found text: {soup.get_text()}\") " + ] + }, + { + "cell_type": "markdown", + "id": "7cdff2d8-0c98-45b3-a825-ed1492d10302", + "metadata": {}, + "source": [ + "## After exercises: Saving retrieved data to disk\n", + "\n", + "Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudinal study.\n", + "\n", + "To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don't, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).\n", + "\n", + "For example, let's retrieve three cat facts and save them to a JSONLINES file using the [jsonlines library](https://jsonlines.readthedocs.io/en/latest/)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "80a8dcd1-ba04-45de-840e-aa014c19a75c", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "import jsonlines\n", + "import time\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make three requests in loop and make a list of response JSON objects\n", + "for i in range(3):\n", + "\n", + " # Logging\n", + " print(f\"Make request {i}\")\n", + "\n", + " # Make a request\n", + " response = requests.get(url)\n", + " \n", + " # Decode to JSON\n", + " response_json = response.json()\n", + " \n", + " # Open a jsonlines writer in 'append' mode \n", + " with jsonlines.open('catfacts.jsonl', mode='a') as writer:\n", + "\n", + " # Write\n", + " writer.write(response_json)\n", + " \n", + " # Sleep for one second between requests\n", + " time.sleep(1)\n" + ] + }, + { + "cell_type": "markdown", + "id": "efb4a0ff-6a70-471a-af61-39c0350d4166", + "metadata": {}, + "source": [ + "We can then read the objects from the disk using the same library." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2d424c23-bdf3-47f7-a643-4312a07c955a", + "metadata": {}, + "outputs": [], + "source": [ + "# Open a jsonlines reader\n", + "with jsonlines.open('catfacts.jsonl', mode='r') as reader:\n", + " \n", + " # Read and display\n", + " for obj in reader:\n", + " display(obj)" + ] + }, + { + "cell_type": "markdown", + "id": "2f6b8117-b1ef-43cb-9458-0fe4ac49b67a", + "metadata": {}, + "source": [ + "## Wrap-up\n", + "\n", + "\n", + ":::{keypoints}\n", + "- Requests is a common tool\n", + "- Web APIs may often require some trial and error, but actually getting data is usually not that difficult\n", + "- Storing all the data and processing it well can be a much larger issue.\n", + ":::\n", + "\n" + ] + } + ], + "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.8.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/_sources/work-with-data.rst.txt b/_sources/work-with-data.rst.txt new file mode 100644 index 00000000..cc3d73e5 --- /dev/null +++ b/_sources/work-with-data.rst.txt @@ -0,0 +1,466 @@ +Working with Data +================= + +.. questions:: + + - How do you store your data right now? + - Are you doing data cleaning / preprocessing every time you load the data? + +.. objectives:: + + - Learn benefits/drawbacks of common data formats. + - Learn how you can read and write data in a variety of formats. + + +.. figure:: https://imgs.xkcd.com/comics/norm_normal_file_format.png + + Source: `xkcd #2116 `__ + + +What is a data format? +---------------------- + +Data format can mean two different things + +1. `data structure `__ or how + you're storing the data in memory while you're working on it; +2. `file format `__ or the way you're + storing the data in the disk. + +Let's consider this randomly generated DataFrame with various columns:: + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.info() + +This DataFrame is structured in the *tidy data* format. +In tidy data we have multiple columns of data that are collected in a Pandas +DataFrame, where each column represents a value of a specific type. + +.. image:: img/pandas/tidy_data.png + +Let's consider another example:: + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + np.info(data_array) + + +Here we have a different data structure: we have a two-dimensional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block +instead of individual columns. This also means that the whole array must have one +data type. + + +.. figure:: https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png + + Source: `Elegant Scipy `__ + +Now the question is: **Can the data be saved to the disk without changing the +data format?** + +For this we need a **file format** that can easily store our **data structure**. + +.. admonition:: Data type vs. data structure vs. file format + :class: dropdown + + - **Data type:** Type of a single piece of data (integer, string, + float, ...). + - **Data structure:** How the data is organized in memory (individual + columns, 2D-array, nested dictionaries, ...). + - **File format:** How the data is organized when it is saved to the disk + (columns of strings, block of binary data, ...). + + For example, a black and white image stored as a .png-file (**file format**) + might be stored in memory as an NxM array (**data structure**) of integers + (**data type**) with each entry representing the color value of the pixel. + +What to look for in a file format? +---------------------------------- + +When deciding which file format you should use for your program, you should +remember the following: + +**There is no file format that is good for every use case.** + +and + +**It is very likely, that a good format already exists for your use case.** + +There are, indeed, various standard file formats for various use cases: + +.. figure:: https://imgs.xkcd.com/comics/standards.png + + Source: `xkcd #927 `__. + +Usually, you'll want to consider the following things when choosing a file +format: + +1. Is the file format good for my data structure (is it fast/space + efficient/easy to use)? +2. Is everybody else / leading authorities in my field recommending a certain + format? +3. Do I need a human-readable format or is it enough to work on it using code? +4. Do I want to archive / share the data or do I just want to store it while + I'm working? + +Pandas supports +`many file formats `__ +for tidy data and Numpy supports +`some file formats `__ +for array data. However, there are many other file formats that can be used +through other libraries. + +Table below describes some data formats: + +.. list-table:: + :header-rows: 1 + + * - | Name: + - | Human + | readable: + - | Space + | efficiency: + - | Arbitrary + | data: + - | Tidy + | data: + - | Array + | data: + - | Long term + | storage/sharing: + + * - :ref:`Pickle ` + - ❌ + - 🟨 + - ✅ + - 🟨 + - 🟨 + - ❌ + + * - :ref:`CSV ` + - ✅ + - ❌ + - ❌ + - ✅ + - 🟨 + - ✅ + + * - :ref:`Feather ` + - ❌ + - ✅ + - ❌ + - ✅ + - ❌ + - ❌ + + * - :ref:`Parquet ` + - ❌ + - ✅ + - 🟨 + - ✅ + - 🟨 + - ✅ + + * - :ref:`npy ` + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + - ❌ + + * - :ref:`HDF5 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`NetCDF4 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`JSON ` + - ✅ + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + + * - :ref:`Excel ` + - ❌ + - ❌ + - ❌ + - 🟨 + - ❌ + - 🟨 + + * - :ref:`Graph formats ` + - 🟨 + - 🟨 + - ❌ + - ❌ + - ❌ + - ✅ + +.. important:: + + - ✅ : Good + - 🟨 : Ok / depends on a case + - ❌ : Bad + + +A more in-depth analysis of the file formats mentioned above, can be found +:doc:`here `. + +Pros and cons +------------- + +Let's have a general look at pros and cons of some types of file formats + +Binary File formats +~~~~~~~~~~~~~~~~~~~ + +Good things ++++++++++++ + +- Can represent floating point numbers with full precision. +- Can potentially save lots of space, especially, when storing numbers. +- Data reading and writing is usually much faster than loading from text files, + since the format contains information about the data structure, and thus + memory allocation can be done more efficiently. +- More explicit specification for storing multiple data sets and metadata in + the same file. +- Many binary formats allow for partial loading of the data. + This makes it possible to work with datasets that are larger than your + computer's memory. + +Bad things +++++++++++ + +- Commonly requires the use of a specific library to read and write the data. +- Library specific formats can be version dependent. +- Not human readable. +- Sharing can be more difficult (requires some expertise to be able to + read the data). +- Might require more documentation efforts. + +Textual formats +~~~~~~~~~~~~~~~ + +Good things ++++++++++++ + +- Human readable. +- Easy to check for (structural) errors. +- Supported by many tool out of the box. +- Easily shared. + +Bad things +++++++++++ + +- Can be slow to read and write. +- High potential to increase required disk space substantially (e.g. when + storing floating point numbers as text). +- Prone to losing precision when storing floating point numbers. +- Multi-dimensional data can be hard to represent. +- While the data format might be specified, the data structure might not be + clear when starting to read the data. + +Further considerations +~~~~~~~~~~~~~~~~~~~~~~ + +- The closer your stored data is to the code, the more likely it depends on the + environment you are working in. If you ``pickle``, e.g. a generated model, + you can only be sure that the model will work as intended if you load it in + an environment that has the same versions of all libraries the model depends + on. + + +Exercise +-------- + +.. challenge:: + + You have a model that you have been training for a while. + Lets assume it's a relatively simple neural network (consisting of a + network structure and it's associated weights). + + Let's consider 2 scenarios + + A: You have a different project, that is supposed to take this model, and + do some processing with it to determine it's efficiency after different + times of training. + + B: You want to publish the model and make it available to others. + + What are good options to store the model in each of these scenarios? + +.. solution:: + + A: + + Some export into a binary format that can be easily read. E.g. pickle + or a specific export function from the library you use. + + It also depends on whether you intend to make the intermediary steps + available to others. If you do, you might also want to consider storing + structure and weights separately or use a format specific for the + type of model you are training to keep the data independent of the + library. + + B: + + You might want to consider a more general format that is supported by + many libraries, e.g. ONNX, or a format that is specifically designed + for the type of model you are training. + + You might also want to consider additionally storing the model in a way + that is easily readable by humans, to make it easier for others to + understand the model. + + +Case study: Converting untidy data to tidy data +----------------------------------------------- + +Many data analysis tools (like Pandas) are designed to work with tidy data, +but some data is not in a suitable format. What we have seen often in the +past is people then not using the powerful tools, but write complicated +scripts that extract individual pieces from the data each time they need +to do a calculation. + +As an example, let's see how we can use country data from an example REST API +endpoint (for more information on how to work with web APIs, see +:doc:`this page `). Let's get the data with the following piece +of code: + +.. code-block:: python + + import json + import requests + + url = 'https://api.sampleapis.com/countries/countries' + + response = requests.get(url) + + countries_json = json.loads(response.content) + +Let's try to find the country with the largest population. + +An example of a "questionable" way of solving this problem would be something +like the following piece of code that is written in pure Python: + +.. code-block:: python + + max_population = 0 + top_population_country = '' + + for country in countries_json: + if country.get('population', 0) > max_population: + top_population_country = country['name'] + max_population = country.get('population', 0) + + print(top_population_country) + +This is a very natural way of writing a solution for the problem, but it has +major caveats: + +1. We throw all of the other data out so we cannot answer any + follow up questions. +2. For bigger data, this would be very slow and ineffective. +3. We have to write lots of code to do a simple thing. + +Another typical solution would be something like the following code, +which picks some of the data and creates a Pandas dataframe out of it: + +.. code-block:: python + + import pandas as pd + + countries_list = [] + + for country in countries_json: + countries_list.append([country['name'], country.get('population',0)]) + + countries_df = pd.DataFrame(countries_list, columns=['name', 'population']) + + print(countries_df.nlargest(1, 'population')['name'].values[0]) + +This solution has many of the same problems as the previous one, but now we can +use Pandas to do follow up analysis. + +Better solution would be to use Pandas' +`pandas.DataFrame.from_dict `__ +or `pandas.json_normalize `__ +to read the full data in: + +.. code-block:: python + + countries_df = pd.DataFrame.from_dict(countries_json) + print(countries_df.nlargest(1, 'population')['name'].values[0]) + + countries_df = pd.json_normalize(countries_json) + print(countries_df.nlargest(1, 'population')['name'].values[0]) + +.. admonition:: Key points + + - Convert your data to a format where it is easy to do analysis on it. + - Check the tools you're using if they have an existing feature that can help + you read the data in. + + +Things to remember +------------------ + +1. **There is no file format that is good for every use case.** +2. Usually, your research question determines which libraries you want to use + to solve it. Similarly, the data format you have determines file format you + want to use. +3. However, if you're using a previously existing framework or tools or you + work in a specific field, you should prioritize using the formats that are + used in said framework/tools/field. +4. When you're starting your project, it's a good idea to take your initial + data, clean it, and store the results in a good binary format that works as + a starting point for your future analysis. If you've written the cleaning + procedure as a script, you can always reproduce it. +5. Throughout your work, you should use code to turn important data to + a human-readable format (e.g. plots, averages, + :meth:`pandas.DataFrame.head`), not to keep your full data in a + human-readable format. +6. Once you've finished, you should store the data in a format that can be + easily shared to other people. + + +See also +-------- + +- `Pandas' IO tools `__ +- `Tidy data comparison notebook `__ +- `Array data comparison notebook `__ + + +.. keypoints:: + + - Pandas can read and write a variety of data formats. + - There are many good, standard formats, and you don't need to create your own. + - There are plenty of other libraries dedicated to various formats. diff --git a/_sources/xarray.rst.txt b/_sources/xarray.rst.txt new file mode 100644 index 00000000..a49b9ab6 --- /dev/null +++ b/_sources/xarray.rst.txt @@ -0,0 +1,444 @@ +.. _xarray: + +Xarray +====== + +.. questions:: + + - How shall we deal with real-world datasets that are usually more than just raw numbers? + - What is the advantage of using labelled multidimensional arrays? + - What does Xarray add to Numpy and Pandas to address these questions? + +.. objectives:: + + - Learn how to apply operations over dimensions and select values by label + - Understand Xarray's DataArrays and Datasets + - Learn how to easily plot data in Xarray + - Learn how to turn your own data into an Xarray Dataset + + +.. highlight:: python + + +We have already seen how Pandas simplifies working with tabular NumPy data by adding labels to columns and rows. In this lesson, we take a look at how xarray can be used to add the same functionality to multidimensional data. Let's consider the following example: + +Imagine we have a dataset representing temperature measurements across different heights, latitudes, and longitudes. We can store the temperature data as a 3D NumPy array where each axis corresponds to one of these dimensions: :: + + import numpy as np + # Create a 3D numpy array: height x latitude x longitude + data = np.random.rand(10, 5, 5) # 10 heights, 5 latitudes, 5 longitudes + + +Let's assume now we want to take a look at a specific value in the dataset at a certain height, latitude, and longitude. We could do this by indexing the array with the corresponding indices: :: + + # Get the temperature at height 3, latitude 2, longitude 4 + temperature = data[3, 2, 4] + +OK, we got a value, but how do we know whether this value corresponds to the correct height, latitude and longitude? Are we sure that latitude was the second dimension in the dataset? Was it the second or third index that corresponds to the correct position? In pure NumPy, we are mostly left in the dark and need to manually keep track of these things. + +Unfortunately, Pandas isn't of much help either since it is not designed for data with more than 2 dimensions. Fortunately, `some clever climate scientists `_ have come up with a solution to this problem and created Xarray. + +What is Xarray? +---------------- + +Xarray is a powerful Python library that introduces labelled multidimensional arrays. This means the axes have labels (=dimensions), each row/column has a label (coordinates), and labels can even have units of measurement. This makes it much easier to follow what the data in an array means and select specific portions of data. + +We will first download a dataset similar to the example above to illustrate the advantages of Xarray. We will cover how to transform your own data into an Xarray Dataset later in this lecture. + +.. Note:: + + If you have set up your ``python-for-scicomp`` environment yesterday or earlier, you need to install the packages ``netcdf4`` and ``pythia_datasets`` manually. You can do this by running the following command in your (JupyterLab) terminal: :: + + conda install netcdf4 pythia-datasets -c conda-forge + +Let us open a python shell and download a public dataset: :: + + >>> from pythia_datasets import DATASETS + >>> filepath = DATASETS.fetch('NARR_19930313_0000.nc') + +We can now import xarray and open the dataset. Le'ts take a look at what it contains: :: + + >>> import xarray as xr + >>> ds = xr.open_dataset(filepath) + >>> ds + Size: 15MB + Dimensions: (time1: 1, isobaric1: 29, y: 119, x: 268) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 ... 1e+03 + * y (y) float32 476B -3.117e+03 ... 714.1 + * x (x) float32 1kB -3.324e+03 ... 5.343e+03 + Data variables: + u-component_of_wind_isobaric (time1, isobaric1, y, x) float32 4MB ... + LambertConformal_Projection int32 4B ... + lat (y, x) float64 255kB ... + lon (y, x) float64 255kB ... + Geopotential_height_isobaric (time1, isobaric1, y, x) float32 4MB ... + v-component_of_wind_isobaric (time1, isobaric1, y, x) float32 4MB ... + Temperature_isobaric (time1, isobaric1, y, x) float32 4MB ... + Attributes: + Originating_or_generating_Center: US National Weather Service, Nation... + Originating_or_generating_Subcenter: North American Regional Reanalysis ... + GRIB_table_version: 0,131 + Generating_process_or_model: North American Regional Reanalysis ... + Conventions: CF-1.6 + history: Read using CDM IOSP GribCollection v3 + featureType: GRID + History: Translated to CF-1.0 Conventions by... + geospatial_lat_min: 10.753308882144761 + geospatial_lat_max: 46.8308828962289 + geospatial_lon_min: -153.88242040519995 + geospatial_lon_max: -42.666108129242815 + +That was a lot of information at once, but let's break it down. + + - Close to the top of the output we see the ``Dimensions`` of the dataset: ``time1``, ``isobaric1``, ``y``, and ``x``. + - Below the dimensions, we see the ``Coordinates`` of the dataset. These are for each dimension the labels for each value along that dimension. For example, we have a timestamp of each value along the first dimension (``time1``). + - The ``Data variables`` are the actual data stored in the dataset. We see that the dataset contains a bunch of arrays, most of which are 4-dimensional, where each dimension corresponds to one of the ``Dimensions`` described above. There are also some 2-dimensional arrays that only have some of the ``Dimensions`` described above. + - At the bottom, we see the ``Attributes`` of the dataset. This is a dictionary that stores metadata about the dataset. + + +The following image shows the structure of this particular Xarray Dataset: + + .. image:: img/xarray/xarray_dataset_image.png + + +Accessing and manipulating data in Xarray +----------------------------------------- + +An xarray ``Dataset`` typically consists of multiple ``DataArrays``. Our example dataset has 7 of them (``u-component_of_wind_isobaric``, ``LambertConformal_Projection``, ``lat``, ``lon``, ``Geopotential_height_isobaric``, ``v-component_of_wind_isobaric``, ``Temperature_isobaric``). +We can select a single ``DataArray`` from the dataset using a dictionary-like syntax: :: + + >>> temperature_data = ds['Temperature_isobaric'] + >>> temperature_data + Size: 4MB + [924868 values with dtype=float32] + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + * x (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03 + Attributes: + long_name: Temperature @ Isobaric surface + units: K + description: Temperature + grid_mapping: LambertConformal_Projection + Grib_Variable_Id: VAR_7-15-131-11_L100 + Grib1_Center: 7 + Grib1_Subcenter: 15 + Grib1_TableVersion: 131 + Grib1_Parameter: 11 + Grib1_Level_Type: 100 + Grib1_Level_Desc: Isobaric surface + + + +Xarray uses Numpy(-like) arrays under the hood, we can always access the underlying Numpy array using the ``.values`` attribute: :: + + >>> temperature_numpy = ds['Temperature_isobaric'].values + >>> temperature_numpy + array([[[[201.88957, 202.2177 , 202.49895, ..., 195.10832, 195.23332, + 195.37395], + [201.68645, 202.0302 , 202.3427 , ..., 195.24895, 195.38957, + 195.51457], + [201.5302 , 201.87395, 202.20207, ..., 195.37395, 195.51457, + 195.63957], + ..., + [276.735 , 276.70374, 276.6881 , ..., 289.235 , 289.1725 , + 289.07874], + [276.86 , 276.84436, 276.78186, ..., 289.1881 , 289.11 , + 289.01624], + [277.01624, 276.82874, 276.82874, ..., 289.14124, 289.0475 , + 288.96936]]]], dtype=float32) + + +Xarray allows you to select data using the ``.sel()`` method, which uses the labels of the dimensions to extract data: :: + + >>> ds['Temperature_isobaric'].sel(x='-3292.0078') + Size: 14kB + array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895], + [202.58566, 202.58566, ..., 219.16379, 219.28879], + ..., + [292.1622 , 292.14658, ..., 275.05283, 275.11533], + [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + x float32 4B -3.292e+03 + Attributes: + long_name: Temperature @ Isobaric surface + units: K + description: Temperature + grid_mapping: LambertConformal_Projection + Grib_Variable_Id: VAR_7-15-131-11_L100 + Grib1_Center: 7 + Grib1_Subcenter: 15 + Grib1_TableVersion: 131 + Grib1_Parameter: 11 + Grib1_Level_Type: 100 + Grib1_Level_Desc: Isobaric surface + + +We can still access the same data by index using the ``.isel()`` method: :: + + >>> ds['Temperature_isobaric'].isel(x=1) + Size: 14kB + array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895], + [202.58566, 202.58566, ..., 219.16379, 219.28879], + ..., + [292.1622 , 292.14658, ..., 275.05283, 275.11533], + [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + x float32 4B -3.292e+03 + Attributes: + long_name: Temperature @ Isobaric surface + units: K + description: Temperature + grid_mapping: LambertConformal_Projection + Grib_Variable_Id: VAR_7-15-131-11_L100 + Grib1_Center: 7 + Grib1_Subcenter: 15 + Grib1_TableVersion: 131 + Grib1_Parameter: 11 + Grib1_Level_Type: 100 + Grib1_Level_Desc: Isobaric surface + + +A ``DataArray`` provides a lot of the functionality we expect from Numpy arrays, such as ``sum()``, ``mean()``, ``median()``, ``min()``, and ``max()`` that we can use these methods to aggregate data over one or multiple dimensions: :: + + >>> # Calculate the mean over the 'isobaric1' dimension + >>> ds['Temperature_isobaric'].mean(dim='isobaric1') + Size: 128kB + array([[[259.88446, 259.90222, 259.91678, ..., 262.61667, 262.6285 , + 262.65167], + [259.74866, 259.76752, 259.78638, ..., 262.5757 , 262.58218, + 262.57516], + [259.6156 , 259.63498, 259.65115, ..., 262.52075, 262.51215, + 262.4976 ], + ..., + [249.8796 , 249.83649, 249.79501, ..., 254.43617, 254.49059, + 254.54985], + [249.8505 , 249.80202, 249.75244, ..., 254.37044, 254.42378, + 254.47711], + [249.82195, 249.75998, 249.71204, ..., 254.30956, 254.35805, + 254.41139]]], dtype=float32) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + * x (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03 + + +Let's take a look at a concrete example and compare it to NumPy. We will calculate the max temperature over the 'isobaric1' dimension at a specific value for x: :: + + >>> # Xarray + >>> ds['Temperature_isobaric'].sel(x='-3259.5447').max(dim='isobaric1') + array([[294.11 , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 , + ..., + 276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]], + dtype=float32) + +In comparison, if we were to use plain Numpy, this would be: :: + + >>> # NumPy + >>> np.max(temperature_numpy[:, :, :, 2 ], axis = 1) + array([[294.11 , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 , + ..., + 276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]], + dtype=float32) + + + +As you can see, the Xarray code is much more readable and we didn't need to keep track of the right indices and order of the dimensions. + +Plotting data in Xarray +----------------------- + +Like Pandas, Xarray comes with basic plotting capabilities. We can easily plot data in 1D and 2D using the ``.plot()`` method. Xarray uses a widely used plotting library called matplotlib for this. When calling the ``.plot()`` method, Xarray checks the dimensionality of the data and plots it accordingly. Let's import matplotlib and plot the data: :: + + >>> import matplotlib.pyplot as plt + + >>> ds['Temperature_isobaric'].isel(x=2).plot() + >>> plt.show() + +For a 2D DataArray the plot would resemble this example: + + .. image:: img/xarray/xarray_2d_plot.png + +Note, that we didn't specify the axes labels, Xarray automatically used the coordinates of the DataArray for the plot. This plot might not be one you include directly in a paper, but it is a great way to quickly visualize your data. + +Let's have a look at a dataslice of 1D data: :: + + >>> ds['Temperature_isobaric'].isel(x=2, y=5).plot() + >>> plt.show() + +The resulting plot detects the dimentionality of the data and plots it accordingly: + + .. image:: img/xarray/xarray_1d_plot.png + +If the data has more than two dimensions, Xarray will plot a histogram of the data: :: + + >>> ds['Temperature_isobaric'].plot() + >>> plt.show() + +The resulting plot would look like this: + + .. image:: img/xarray/xarray_hist.png + +We can modify the plots by passing additional arguments to the ``.plot()`` method. Since we haven't discussed the plotting library matplotlib in this course, we will not go into further detail here. You can find more information in the `Xarray documentation `_. + +Exercises 1 +----------- + +.. challenge:: Exercises: Xarray-1 + + Download the ``NARR_19930313_0000.nc`` dataset have a look at all Data variables. Calculate the geopotential height at ``x=5148.3726`` averaged over ``y`` and return the median value. You can use the ``.plot()`` method to check on the way whether you use the correct dimensions and indices. + +.. solution:: Solutions: Xarray-1 + + One way of calculating this is: :: + + >>> from pythia_datasets import DATASETS + >>> import xarray as xr + >>> + >>> filepath = DATASETS.fetch('NARR_19930313_0000.nc') + >>> ds = xr.open_dataset(filepath) + >>> ds['Geopotential_height_isobaric'].sel(x=5148.3726).mean('y').median() + Size: 4B + array(4395.487, dtype=float32) + Coordinates: + x float32 4B 5.148e+03 + + + + +Creating your own Xarray Dataset +-------------------------------- + +Creating your own Xarray Dataset is quite simple. We can create a Dataset from scratch using basic Python data structures. Let's create a simple weather dataset with pressure and humidity data with the following script: :: + + import xarray as xr + import numpy as np + + # Define coordinates using basic Python lists + time = ['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05'] + location = ['Location1', 'Location2', 'Location3'] + + # Define data variables as numpy arrays + pressure_data = np.random.rand(5, 3) * 1000 # Random pressure data in hPa + humidity_data = np.random.rand(5, 3) * 100 # Random humidity data + + # Put everything together to create the Dataset + ds = xr.Dataset( + data_vars = { + "pressure": (["time", "location"], pressure_data), + "humidity": (["time", "location"], humidity_data) + }, + coords={ + "time": time, + "location": location + }, + attrs={ + "description": "Weather data", + "creation_date": "2023-01-01", + "author": "Data Scientist" + } + ) + + +Converting Xarray objects to NumPy, Pandas and NetCDF +------------------------------------------------------ + +Another handy feature of Xarray is the simple conversion between Xarray objects, NumPy arrays, Pandas DataFrames and even NetCDF files. + +To convert an xarray DataArray to a NumPy array, you can use the ``.values`` attribute or the ``.to_numpy()`` method: :: + + # Convert the 'pressure' DataArray to a NumPy array + pressure_numpy = ds['pressure'].values + # or + pressure_numpy = ds['pressure'].to_numpy() + +To convert the entire Dataset or individual DataArrays to pandas DataFrames, use the ``.to_dataframe()`` method: :: + + # Convert the entire Dataset to a DataFrame + df = ds.to_dataframe() + # Convert a single DataArray to DataFrame + pressure_df = ds['pressure'].to_dataframe() + +To save the dataset as a NetCDF file, use the ``.to_netcdf()`` method: :: + + # Save the Dataset as a NetCDF file + ds.to_netcdf('weather_data.nc') + + +Exercises 2 +----------- + +.. challenge:: Exercises: Xarray-2 + + Let's change from climate science to finance for this example. Put the stock prices and trading volumes of three companies over ten days in one dataset. Create an Xarray Dataset that uses time and company as dimensions and contains two DataArrays: ``stock_price`` and ``trading_volume``. You can choose the values for the stock prices and trading volumes yourself. As a last thing, add the currency of the stock prices as an attribute to the Dataset. + +.. solution:: Solutions: Xarray-2 + + We can use a script similar to this one: :: + + import xarray as xr + import numpy as np + + time = [ + "2023-01-01", + "2023-01-02", + "2023-01-03", + "2023-01-04", + "2023-01-05", + "2023-01-06", + "2023-01-07", + "2023-01-08", + "2023-01-09", + "2023-01-10", + ] + companies = ["AAPL", "GOOGL", "MSFT"] + stock_prices = np.random.normal(loc=[100, 1500, 200], scale=[10, 50, 20], size=(10, 3)) + trading_volumes = np.random.randint(1000, 10000, size=(10, 3)) + ds = xr.Dataset( + data_vars = { + "stock_price": (["time", "company"], stock_prices), + "trading_volume": (["time", "company"], trading_volumes), + }, + coords={"time": time, "company": companies}, + attrs={"currency": "USD"}, + ) + print(ds) + + The output should then resemble this: :: + + > python exercise.py + Size: 940B + Dimensions: (time: 10, company: 3) + Coordinates: + * time (time) `_ in the Xarray documentation. +- If you want to accelerate Xarray operations with your GPU, have a look at `CuPy-Xarray `_. +- Xarray can be combined with pint, a Python library that adds support for physical quantities to NumPy arrays. This `blog post `_ provides a good introduction to the topic. +- You can extend Xarray with your own methods using the `register_dataset_accessor() `_ method. This is a powerful feature that allows you to add custom methods to your own Xarray Datasets. diff --git a/_static/_sphinx_javascript_frameworks_compat.js b/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..81415803 --- /dev/null +++ b/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,123 @@ +/* Compatability shim for jQuery and underscores.js. + * + * Copyright Sphinx contributors + * Released under the two clause BSD licence + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/_static/basic.css b/_static/basic.css new file mode 100644 index 00000000..f316efcb --- /dev/null +++ b/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/_static/check-solid.svg b/_static/check-solid.svg new file mode 100644 index 00000000..92fad4b5 --- /dev/null +++ b/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/_static/clipboard.min.js b/_static/clipboard.min.js new file mode 100644 index 00000000..54b3c463 --- /dev/null +++ b/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/_static/copybutton.css b/_static/copybutton.css new file mode 100644 index 00000000..f1916ec7 --- /dev/null +++ b/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/_static/copybutton.js b/_static/copybutton.js new file mode 100644 index 00000000..b3987037 --- /dev/null +++ b/_static/copybutton.js @@ -0,0 +1,248 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copier dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = ``; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = 'div.highlight pre'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} + + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '.linenos, .gp'; + + let text = filterText(target, exclude); + return formatCopyText(text, '', false, true, true, true, '', '') +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) \ No newline at end of file diff --git a/_static/copybutton_funcs.js b/_static/copybutton_funcs.js new file mode 100644 index 00000000..dbe1aaad --- /dev/null +++ b/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/_static/css/badge_only.css b/_static/css/badge_only.css new file mode 100644 index 00000000..88ba55b9 --- /dev/null +++ b/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px} \ No newline at end of file diff --git a/_static/css/fonts/Roboto-Slab-Bold.woff b/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/_static/css/fonts/Roboto-Slab-Bold.woff2 b/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/_static/css/fonts/Roboto-Slab-Regular.woff b/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/_static/css/fonts/Roboto-Slab-Regular.woff2 b/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/_static/css/fonts/fontawesome-webfont.eot b/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/_static/css/fonts/fontawesome-webfont.svg b/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_static/css/fonts/fontawesome-webfont.ttf b/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/_static/css/fonts/fontawesome-webfont.woff b/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/_static/css/fonts/fontawesome-webfont.woff2 b/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/_static/css/fonts/lato-bold-italic.woff b/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/_static/css/fonts/lato-bold-italic.woff differ diff --git a/_static/css/fonts/lato-bold-italic.woff2 b/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/_static/css/fonts/lato-bold.woff b/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/_static/css/fonts/lato-bold.woff differ diff --git a/_static/css/fonts/lato-bold.woff2 b/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/_static/css/fonts/lato-bold.woff2 differ diff --git a/_static/css/fonts/lato-normal-italic.woff b/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/_static/css/fonts/lato-normal-italic.woff differ diff --git a/_static/css/fonts/lato-normal-italic.woff2 b/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/_static/css/fonts/lato-normal.woff b/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/_static/css/fonts/lato-normal.woff differ diff --git a/_static/css/fonts/lato-normal.woff2 b/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/_static/css/fonts/lato-normal.woff2 differ diff --git a/_static/css/theme.css b/_static/css/theme.css new file mode 100644 index 00000000..0f14f106 --- /dev/null +++ b/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search .wy-dropdown>aactive,.wy-side-nav-search .wy-dropdown>afocus,.wy-side-nav-search>a:hover,.wy-side-nav-search>aactive,.wy-side-nav-search>afocus{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon,.wy-side-nav-search>a.icon{display:block}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.switch-menus{position:relative;display:block;margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-side-nav-search>div.switch-menus>div.language-switch,.wy-side-nav-search>div.switch-menus>div.version-switch{display:inline-block;padding:.2em}.wy-side-nav-search>div.switch-menus>div.language-switch select,.wy-side-nav-search>div.switch-menus>div.version-switch select{display:inline-block;margin-right:-2rem;padding-right:2rem;max-width:240px;text-align-last:center;background:none;border:none;border-radius:0;box-shadow:none;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-size:1em;font-weight:400;color:hsla(0,0%,100%,.3);cursor:pointer;appearance:none;-webkit-appearance:none;-moz-appearance:none}.wy-side-nav-search>div.switch-menus>div.language-switch select:active,.wy-side-nav-search>div.switch-menus>div.language-switch select:focus,.wy-side-nav-search>div.switch-menus>div.language-switch select:hover,.wy-side-nav-search>div.switch-menus>div.version-switch select:active,.wy-side-nav-search>div.switch-menus>div.version-switch select:focus,.wy-side-nav-search>div.switch-menus>div.version-switch select:hover{background:hsla(0,0%,100%,.1);color:hsla(0,0%,100%,.5)}.wy-side-nav-search>div.switch-menus>div.language-switch select option,.wy-side-nav-search>div.switch-menus>div.version-switch select option{color:#000}.wy-side-nav-search>div.switch-menus>div.language-switch:has(>select):after,.wy-side-nav-search>div.switch-menus>div.version-switch:has(>select):after{display:inline-block;width:1.5em;height:100%;padding:.1em;content:"\f0d7";font-size:1em;line-height:1.2em;font-family:FontAwesome;text-align:center;pointer-events:none;box-sizing:border-box}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel,.rst-content .menuselection{font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .guilabel,.rst-content .menuselection{border:1px solid #7fbbe3;background:#e7f2fa}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/_static/doctools.js b/_static/doctools.js new file mode 100644 index 00000000..4d67807d --- /dev/null +++ b/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/_static/documentation_options.js b/_static/documentation_options.js new file mode 100644 index 00000000..87fc516a --- /dev/null +++ b/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'dirhtml', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/_static/file.png b/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/_static/file.png differ diff --git a/_static/fonts/Lato/lato-bold.eot b/_static/fonts/Lato/lato-bold.eot new file mode 100644 index 00000000..3361183a Binary files /dev/null and b/_static/fonts/Lato/lato-bold.eot differ diff --git a/_static/fonts/Lato/lato-bold.ttf b/_static/fonts/Lato/lato-bold.ttf new file mode 100644 index 00000000..29f691d5 Binary files /dev/null and b/_static/fonts/Lato/lato-bold.ttf differ diff --git a/_static/fonts/Lato/lato-bold.woff b/_static/fonts/Lato/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/_static/fonts/Lato/lato-bold.woff differ diff --git a/_static/fonts/Lato/lato-bold.woff2 b/_static/fonts/Lato/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/_static/fonts/Lato/lato-bold.woff2 differ diff --git a/_static/fonts/Lato/lato-bolditalic.eot b/_static/fonts/Lato/lato-bolditalic.eot new file mode 100644 index 00000000..3d415493 Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.eot differ diff --git a/_static/fonts/Lato/lato-bolditalic.ttf b/_static/fonts/Lato/lato-bolditalic.ttf new file mode 100644 index 00000000..f402040b Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.ttf differ diff --git a/_static/fonts/Lato/lato-bolditalic.woff b/_static/fonts/Lato/lato-bolditalic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.woff differ diff --git a/_static/fonts/Lato/lato-bolditalic.woff2 b/_static/fonts/Lato/lato-bolditalic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.woff2 differ diff --git a/_static/fonts/Lato/lato-italic.eot b/_static/fonts/Lato/lato-italic.eot new file mode 100644 index 00000000..3f826421 Binary files /dev/null and b/_static/fonts/Lato/lato-italic.eot differ diff --git a/_static/fonts/Lato/lato-italic.ttf b/_static/fonts/Lato/lato-italic.ttf new file mode 100644 index 00000000..b4bfc9b2 Binary files /dev/null and b/_static/fonts/Lato/lato-italic.ttf differ diff --git a/_static/fonts/Lato/lato-italic.woff b/_static/fonts/Lato/lato-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/_static/fonts/Lato/lato-italic.woff differ diff --git a/_static/fonts/Lato/lato-italic.woff2 b/_static/fonts/Lato/lato-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/_static/fonts/Lato/lato-italic.woff2 differ diff --git a/_static/fonts/Lato/lato-regular.eot b/_static/fonts/Lato/lato-regular.eot new file mode 100644 index 00000000..11e3f2a5 Binary files /dev/null and b/_static/fonts/Lato/lato-regular.eot differ diff --git a/_static/fonts/Lato/lato-regular.ttf b/_static/fonts/Lato/lato-regular.ttf new file mode 100644 index 00000000..74decd9e Binary files /dev/null and b/_static/fonts/Lato/lato-regular.ttf differ diff --git a/_static/fonts/Lato/lato-regular.woff b/_static/fonts/Lato/lato-regular.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/_static/fonts/Lato/lato-regular.woff differ diff --git a/_static/fonts/Lato/lato-regular.woff2 b/_static/fonts/Lato/lato-regular.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/_static/fonts/Lato/lato-regular.woff2 differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot new file mode 100644 index 00000000..79dc8efe Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf new file mode 100644 index 00000000..df5d1df2 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot new file mode 100644 index 00000000..2f7ca78a Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf new file mode 100644 index 00000000..eb52a790 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 differ diff --git a/_static/jquery.js b/_static/jquery.js new file mode 100644 index 00000000..c4c6022f --- /dev/null +++ b/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t +
Languages
+ ${config.projects.translations + .map( + (translation) => ` +
+ ${translation.language.code} +
+ `, + ) + .join("\n")} + + `; + return languagesHTML; + } + + function renderVersions(config) { + if (!config.versions.active.length) { + return ""; + } + const versionsHTML = ` +
+
Versions
+ ${config.versions.active + .map( + (version) => ` +
+ ${version.slug} +
+ `, + ) + .join("\n")} +
+ `; + return versionsHTML; + } + + function renderDownloads(config) { + if (!Object.keys(config.versions.current.downloads).length) { + return ""; + } + const downloadsNameDisplay = { + pdf: "PDF", + epub: "Epub", + htmlzip: "HTML", + }; + + const downloadsHTML = ` +
+
Downloads
+ ${Object.entries(config.versions.current.downloads) + .map( + ([name, url]) => ` +
+ ${downloadsNameDisplay[name]} +
+ `, + ) + .join("\n")} +
+ `; + return downloadsHTML; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const flyout = ` +
+ + Read the Docs + v: ${config.versions.current.slug} + + +
+
+ ${renderLanguages(config)} + ${renderVersions(config)} + ${renderDownloads(config)} +
+
On Read the Docs
+
+ Project Home +
+
+ Builds +
+
+ Downloads +
+
+
+
Search
+
+
+ +
+
+
+
+ + Hosted by Read the Docs + +
+
+ `; + + // Inject the generated flyout into the body HTML element. + document.body.insertAdjacentHTML("beforeend", flyout); + + // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout. + document + .querySelector("#flyout-search-form") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + }) +} + +if (themeLanguageSelector || themeVersionSelector) { + function onSelectorSwitch(event) { + const option = event.target.selectedIndex; + const item = event.target.options[option]; + window.location.href = item.dataset.url; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const versionSwitch = document.querySelector( + "div.switch-menus > div.version-switch", + ); + if (themeVersionSelector) { + let versions = config.versions.active; + if (config.versions.current.hidden || config.versions.current.type === "external") { + versions.unshift(config.versions.current); + } + const versionSelect = ` + + `; + + versionSwitch.innerHTML = versionSelect; + versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + + const languageSwitch = document.querySelector( + "div.switch-menus > div.language-switch", + ); + + if (themeLanguageSelector) { + if (config.projects.translations.length) { + // Add the current language to the options on the selector + let languages = config.projects.translations.concat( + config.projects.current, + ); + languages = languages.sort((a, b) => + a.language.name.localeCompare(b.language.name), + ); + + const languageSelect = ` + + `; + + languageSwitch.innerHTML = languageSelect; + languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + else { + languageSwitch.remove(); + } + } + }); +} + +document.addEventListener("readthedocs-addons-data-ready", function (event) { + // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. + document + .querySelector("[role='search'] input") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); +}); \ No newline at end of file diff --git a/_static/language_data.js b/_static/language_data.js new file mode 100644 index 00000000..367b8ed8 --- /dev/null +++ b/_static/language_data.js @@ -0,0 +1,199 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/_static/logo-hexagons-02-compact.svg.ico b/_static/logo-hexagons-02-compact.svg.ico new file mode 100644 index 00000000..bafe8f98 Binary files /dev/null and b/_static/logo-hexagons-02-compact.svg.ico differ diff --git a/_static/minipres.js b/_static/minipres.js new file mode 100644 index 00000000..ad11c871 --- /dev/null +++ b/_static/minipres.js @@ -0,0 +1,223 @@ +// Add goTo method to elements +// http://stackoverflow.com/questions/4801655/how-to-go-to-a-specific-element-on-page +(function($) { + $.fn.goTo = function() { + $('html, body').animate({ + scrollTop: $(this).offset().top //+ 'px' + }, 'fast'); + return this; // for chaining... + } +})(jQuery); + +// NO good way to do this!. Copy a hack from here +// https://stackoverflow.com/questions/901115/how-can-i-get-query-string-values-in-javascript +// https://stackoverflow.com/a/2880929 +var urlParams; +(window.onpopstate = function () { + var match, + pl = /\+/g, // Regex for replacing addition symbol with a space + search = /([^&=]+)=?([^&]*)/g, + decode = function (s) { return decodeURIComponent(s.replace(pl, " ")); }, + query = window.location.search.substring(1); + urlParams = {}; + while (match = search.exec(query)) + urlParams[decode(match[1])] = decode(match[2]); +})(); + +// Select heading levels +var maxHeading = urlParams['h'] +if (maxHeading === undefined) maxHeading = 2 +var headingLevels = []; +for (h=2 ; h (sections.length-1) ) { + // if we would scroll past bottom, or above top, do nothing + return; + } + + console.log('xxxxxx'); + var targetSection = sections[targetPos]; + console.log(targetSection, typeof(targetSection)); + + // Return targetSection top and height + var secProperties = section_top_and_height(targetSection); + var top = secProperties['top']; + var height = secProperties['height'] + var win_height = window.innerHeight; + //console.info(top, height, win_height) + + var scroll_to = 0; + if (height >= win_height || height == 0) { + scroll_to = top; + } else { + scroll_to = top - (win_height-height)/3.; + } + //console.info(top, height, win_height, scroll_to) + + $('html, body').animate({ + scrollTop: scroll_to //+ 'px' + }, 'fast'); + +} + + +function minipres() { + /* Enable the minipres mode: + - call the hide() function + - set up the scrolling listener + */ + document.addEventListener('keydown', function (event) { + switch(event.which) { + case 37: // left + switch_slide(-1); + event.preventDefault(); + return false; + break; + //case 38: // up + case 39: // right + switch_slide(+1); + event.preventDefault(); + return false; + break; + //case 40: // down + default: + return; // exit this handler for other keys + } + }, true) + + hide() + + // Increase space between sections + //$("div .section").css('margin-bottom', '50%'); + $(sectionSelector).css('margin-top', '50%'); + + // Reduce size/color of other sections + if (hiddenSectionSelector.length > 0) { + var hideNodes = $(hiddenSectionSelector); + console.log(typeof hideNodes, hideNodes); + for (node in hideNodes) { + console.log("a", typeof node, node); + node = hideNodes[node]; // what's right way to iterate values? + console.log("b", typeof node, node); + if (node.parentNode && node.parentNode.className == "section") { + node = node.parentNode; + console.log("c", typeof node, node); + //node.css['transform'] = 'scale(.5)'; + //node.css['transform-origin'] = 'top center'; + $(node).css('color', 'lightgrey'); + //$(node).css('font-size', '20%'); + //$(node).css('visibility', 'collapse'); + //ntahousnatouhasno; + } + } + } +} + +function hide() { + /* Hide all non-essential elements on the page + */ + + // This is for sphinx_rst_theme and readthedocs + $(".wy-nav-side").remove(); + $(".wy-nav-content-wrap").css('margin-left', 0); + $('.rst-versions').remove(); // readthedocs version selector + + // Add other formats here. +} + + +var slideshow = minipres; + +if (window.location.search.match(/[?&](minipres|slideshow|pres)([=&]|$)/) ) { + //minipres() + window.addEventListener("load", minipres); +} else if (window.location.search.match(/[?&](plain)([=&]|$)/) ) { + window.addEventListener("load", hide); +} diff --git a/_static/minus.png b/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/_static/minus.png differ diff --git a/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css b/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css new file mode 100644 index 00000000..33566310 --- /dev/null +++ b/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css @@ -0,0 +1,2342 @@ +/* Variables */ +:root { + --mystnb-source-bg-color: #f7f7f7; + --mystnb-stdout-bg-color: #fcfcfc; + --mystnb-stderr-bg-color: #fdd; + --mystnb-traceback-bg-color: #fcfcfc; + --mystnb-source-border-color: #ccc; + --mystnb-source-margin-color: green; + --mystnb-stdout-border-color: #f7f7f7; + --mystnb-stderr-border-color: #f7f7f7; + --mystnb-traceback-border-color: #ffd6d6; + --mystnb-hide-prompt-opacity: 70%; + --mystnb-source-border-radius: .4em; + --mystnb-source-border-width: 1px; +} + +/* Whole cell */ +div.container.cell { + padding-left: 0; + margin-bottom: 1em; +} + +/* Removing all background formatting so we can control at the div level */ +.cell_input div.highlight, +.cell_output pre, +.cell_input pre, +.cell_output .output { + border: none; + box-shadow: none; +} + +.cell_output .output pre, +.cell_input pre { + margin: 0px; +} + +/* Input cells */ +div.cell div.cell_input, +div.cell details.above-input>summary { + padding-left: 0em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + background-color: var(--mystnb-source-bg-color); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; + border-radius: var(--mystnb-source-border-radius); +} + +div.cell_input>div, +div.cell_output div.output>div.highlight { + margin: 0em !important; + border: none !important; +} + +/* All cell outputs */ +.cell_output { + padding-left: 1em; + padding-right: 0em; + margin-top: 1em; +} + +/* Text outputs from cells */ +.cell_output .output.text_plain, +.cell_output .output.traceback, +.cell_output .output.stream, +.cell_output .output.stderr { + margin-top: 1em; + margin-bottom: 0em; + box-shadow: none; +} + +.cell_output .output.text_plain, +.cell_output .output.stream { + background: var(--mystnb-stdout-bg-color); + border: 1px solid var(--mystnb-stdout-border-color); +} + +.cell_output .output.stderr { + background: var(--mystnb-stderr-bg-color); + border: 1px solid var(--mystnb-stderr-border-color); +} + +.cell_output .output.traceback { + background: var(--mystnb-traceback-bg-color); + border: 1px solid var(--mystnb-traceback-border-color); +} + +/* Collapsible cell content */ +div.cell details.above-input div.cell_input { + border-top-left-radius: 0; + border-top-right-radius: 0; + border-top: var(--mystnb-source-border-width) var(--mystnb-source-border-color) dashed; +} + +div.cell div.cell_input.above-output-prompt { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; +} + +div.cell details.above-input>summary { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; + border-bottom: var(--mystnb-source-border-width) var(--mystnb-source-border-color) dashed; + padding-left: 1em; + margin-bottom: 0; +} + +div.cell details.above-output>summary { + background-color: var(--mystnb-source-bg-color); + padding-left: 1em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + border-radius: var(--mystnb-source-border-radius); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; +} + +div.cell details.below-input>summary { + background-color: var(--mystnb-source-bg-color); + padding-left: 1em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + border-top: none; + border-bottom-left-radius: var(--mystnb-source-border-radius); + border-bottom-right-radius: var(--mystnb-source-border-radius); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; +} + +div.cell details.hide>summary>span { + opacity: var(--mystnb-hide-prompt-opacity); +} + +div.cell details.hide[open]>summary>span.collapsed { + display: none; +} + +div.cell details.hide:not([open])>summary>span.expanded { + display: none; +} + +@keyframes collapsed-fade-in { + 0% { + opacity: 0; + } + + 100% { + opacity: 1; + } +} +div.cell details.hide[open]>summary~* { + -moz-animation: collapsed-fade-in 0.3s ease-in-out; + -webkit-animation: collapsed-fade-in 0.3s ease-in-out; + animation: collapsed-fade-in 0.3s ease-in-out; +} + +/* Math align to the left */ +.cell_output .MathJax_Display { + text-align: left !important; +} + +/* Pandas tables. Pulled from the Jupyter / nbsphinx CSS */ +div.cell_output table { + border: none; + border-collapse: collapse; + border-spacing: 0; + color: black; + font-size: 1em; + table-layout: fixed; +} + +div.cell_output thead { + border-bottom: 1px solid black; + vertical-align: bottom; +} + +div.cell_output tr, +div.cell_output th, +div.cell_output td { + text-align: right; + vertical-align: middle; + padding: 0.5em 0.5em; + line-height: normal; + white-space: normal; + max-width: none; + border: none; +} + +div.cell_output th { + font-weight: bold; +} + +div.cell_output tbody tr:nth-child(odd) { + background: #f5f5f5; +} + +div.cell_output tbody tr:hover { + background: rgba(66, 165, 245, 0.2); +} + +/** source code line numbers **/ +span.linenos { + opacity: 0.5; +} + +/* Inline text from `paste` operation */ + +span.pasted-text { + font-weight: bold; +} + +span.pasted-inline img { + max-height: 2em; +} + +tbody span.pasted-inline img { + max-height: none; +} + +/* Font colors for translated ANSI escape sequences +Color values are copied from Jupyter Notebook +https://github.com/jupyter/notebook/blob/52581f8eda9b319eb0390ac77fe5903c38f81e3e/notebook/static/notebook/less/ansicolors.less#L14-L21 +Background colors from +https://nbsphinx.readthedocs.io/en/latest/code-cells.html#ANSI-Colors +*/ +div.highlight .-Color-Bold { + font-weight: bold; +} + +div.highlight .-Color[class*=-Black] { + color: #3E424D +} + +div.highlight .-Color[class*=-Red] { + color: #E75C58 +} + +div.highlight .-Color[class*=-Green] { + color: #00A250 +} + +div.highlight .-Color[class*=-Yellow] { + color: #DDB62B +} + +div.highlight .-Color[class*=-Blue] { + color: #208FFB +} + +div.highlight .-Color[class*=-Magenta] { + color: #D160C4 +} + +div.highlight .-Color[class*=-Cyan] { + color: #60C6C8 +} + +div.highlight .-Color[class*=-White] { + color: #C5C1B4 +} + +div.highlight .-Color[class*=-BGBlack] { + background-color: #3E424D +} + +div.highlight .-Color[class*=-BGRed] { + background-color: #E75C58 +} + +div.highlight .-Color[class*=-BGGreen] { + background-color: #00A250 +} + +div.highlight .-Color[class*=-BGYellow] { + background-color: #DDB62B +} + +div.highlight .-Color[class*=-BGBlue] { + background-color: #208FFB +} + +div.highlight .-Color[class*=-BGMagenta] { + background-color: #D160C4 +} + +div.highlight .-Color[class*=-BGCyan] { + background-color: #60C6C8 +} + +div.highlight .-Color[class*=-BGWhite] { + background-color: #C5C1B4 +} + +/* Font colors for 8-bit ANSI */ + +div.highlight .-Color[class*=-C0] { + color: #000000 +} + +div.highlight .-Color[class*=-BGC0] { + background-color: #000000 +} + +div.highlight .-Color[class*=-C1] { + color: #800000 +} + +div.highlight .-Color[class*=-BGC1] { + background-color: #800000 +} + +div.highlight .-Color[class*=-C2] { + color: #008000 +} + +div.highlight .-Color[class*=-BGC2] { + background-color: #008000 +} + +div.highlight .-Color[class*=-C3] { + color: #808000 +} + +div.highlight .-Color[class*=-BGC3] { + background-color: #808000 +} + +div.highlight .-Color[class*=-C4] { + color: #000080 +} + +div.highlight .-Color[class*=-BGC4] { + background-color: #000080 +} + +div.highlight .-Color[class*=-C5] { + color: #800080 +} + +div.highlight .-Color[class*=-BGC5] { + background-color: #800080 +} + +div.highlight .-Color[class*=-C6] { + color: #008080 +} + +div.highlight .-Color[class*=-BGC6] { + background-color: #008080 +} + +div.highlight .-Color[class*=-C7] { + color: #C0C0C0 +} + +div.highlight .-Color[class*=-BGC7] { + background-color: #C0C0C0 +} + +div.highlight .-Color[class*=-C8] { + color: #808080 +} + +div.highlight .-Color[class*=-BGC8] { + background-color: #808080 +} + +div.highlight .-Color[class*=-C9] { + color: #FF0000 +} + +div.highlight .-Color[class*=-BGC9] { + background-color: #FF0000 +} + +div.highlight .-Color[class*=-C10] { + color: #00FF00 +} + +div.highlight .-Color[class*=-BGC10] { + background-color: #00FF00 +} + +div.highlight .-Color[class*=-C11] { + color: #FFFF00 +} + +div.highlight .-Color[class*=-BGC11] { + background-color: #FFFF00 +} + +div.highlight .-Color[class*=-C12] { + color: #0000FF +} + +div.highlight .-Color[class*=-BGC12] { + background-color: #0000FF +} + +div.highlight .-Color[class*=-C13] { + color: #FF00FF +} + +div.highlight .-Color[class*=-BGC13] { + background-color: #FF00FF +} + +div.highlight .-Color[class*=-C14] { + color: #00FFFF +} + +div.highlight .-Color[class*=-BGC14] { + background-color: #00FFFF +} + +div.highlight .-Color[class*=-C15] { + color: #FFFFFF +} + +div.highlight .-Color[class*=-BGC15] { + background-color: #FFFFFF +} + +div.highlight .-Color[class*=-C16] { + color: #000000 +} + +div.highlight .-Color[class*=-BGC16] { + background-color: #000000 +} + +div.highlight .-Color[class*=-C17] { + color: #00005F +} + +div.highlight .-Color[class*=-BGC17] { + background-color: #00005F +} + +div.highlight .-Color[class*=-C18] { + color: #000087 +} + +div.highlight .-Color[class*=-BGC18] { + background-color: #000087 +} + +div.highlight .-Color[class*=-C19] { + color: #0000AF +} + +div.highlight .-Color[class*=-BGC19] { + background-color: #0000AF +} + +div.highlight .-Color[class*=-C20] { + color: #0000D7 +} + +div.highlight .-Color[class*=-BGC20] { + background-color: #0000D7 +} + +div.highlight .-Color[class*=-C21] { + color: #0000FF +} + +div.highlight .-Color[class*=-BGC21] { + background-color: #0000FF +} + +div.highlight .-Color[class*=-C22] { + color: #005F00 +} + +div.highlight .-Color[class*=-BGC22] { + background-color: #005F00 +} + +div.highlight .-Color[class*=-C23] { + color: #005F5F +} + +div.highlight .-Color[class*=-BGC23] { + background-color: #005F5F +} + +div.highlight .-Color[class*=-C24] { + color: #005F87 +} + +div.highlight .-Color[class*=-BGC24] { + background-color: #005F87 +} + +div.highlight .-Color[class*=-C25] { + color: #005FAF +} + +div.highlight .-Color[class*=-BGC25] { + background-color: #005FAF +} + +div.highlight .-Color[class*=-C26] { + color: #005FD7 +} + +div.highlight .-Color[class*=-BGC26] { + background-color: #005FD7 +} + +div.highlight .-Color[class*=-C27] { + color: #005FFF +} + +div.highlight .-Color[class*=-BGC27] { + background-color: #005FFF +} + +div.highlight .-Color[class*=-C28] { + color: #008700 +} + +div.highlight .-Color[class*=-BGC28] { + background-color: #008700 +} + +div.highlight .-Color[class*=-C29] { + color: #00875F +} + +div.highlight .-Color[class*=-BGC29] { + background-color: #00875F +} + +div.highlight .-Color[class*=-C30] { + color: #008787 +} + +div.highlight .-Color[class*=-BGC30] { + background-color: #008787 +} + +div.highlight .-Color[class*=-C31] { + color: #0087AF +} + +div.highlight .-Color[class*=-BGC31] { + background-color: #0087AF +} + +div.highlight .-Color[class*=-C32] { + color: #0087D7 +} + +div.highlight .-Color[class*=-BGC32] { + background-color: #0087D7 +} + +div.highlight .-Color[class*=-C33] { + color: #0087FF +} + +div.highlight .-Color[class*=-BGC33] { + background-color: #0087FF +} + +div.highlight .-Color[class*=-C34] { + color: #00AF00 +} + +div.highlight .-Color[class*=-BGC34] { + background-color: #00AF00 +} + +div.highlight .-Color[class*=-C35] { + color: #00AF5F +} + +div.highlight .-Color[class*=-BGC35] { + background-color: #00AF5F +} + +div.highlight .-Color[class*=-C36] { + color: #00AF87 +} + +div.highlight .-Color[class*=-BGC36] { + background-color: #00AF87 +} + +div.highlight .-Color[class*=-C37] { + color: #00AFAF +} + +div.highlight .-Color[class*=-BGC37] { + background-color: #00AFAF +} + +div.highlight .-Color[class*=-C38] { + color: #00AFD7 +} + +div.highlight .-Color[class*=-BGC38] { + background-color: #00AFD7 +} + +div.highlight .-Color[class*=-C39] { + color: #00AFFF +} + +div.highlight .-Color[class*=-BGC39] { + background-color: #00AFFF +} + +div.highlight .-Color[class*=-C40] { + color: #00D700 +} + +div.highlight .-Color[class*=-BGC40] { + background-color: #00D700 +} + +div.highlight .-Color[class*=-C41] { + color: #00D75F +} + +div.highlight .-Color[class*=-BGC41] { + background-color: #00D75F +} + +div.highlight .-Color[class*=-C42] { + color: #00D787 +} + +div.highlight .-Color[class*=-BGC42] { + background-color: #00D787 +} + +div.highlight .-Color[class*=-C43] { + color: #00D7AF +} + +div.highlight .-Color[class*=-BGC43] { + background-color: #00D7AF +} + +div.highlight .-Color[class*=-C44] { + color: #00D7D7 +} + +div.highlight .-Color[class*=-BGC44] { + background-color: #00D7D7 +} + +div.highlight .-Color[class*=-C45] { + color: #00D7FF +} + +div.highlight .-Color[class*=-BGC45] { + background-color: #00D7FF +} + +div.highlight .-Color[class*=-C46] { + color: #00FF00 +} + +div.highlight .-Color[class*=-BGC46] { + background-color: #00FF00 +} + +div.highlight .-Color[class*=-C47] { + color: #00FF5F +} + +div.highlight .-Color[class*=-BGC47] { + background-color: #00FF5F +} + +div.highlight .-Color[class*=-C48] { + color: #00FF87 +} + +div.highlight .-Color[class*=-BGC48] { + background-color: #00FF87 +} + +div.highlight .-Color[class*=-C49] { + color: #00FFAF +} + +div.highlight .-Color[class*=-BGC49] { + background-color: #00FFAF +} + +div.highlight .-Color[class*=-C50] { + color: #00FFD7 +} + +div.highlight .-Color[class*=-BGC50] { + background-color: #00FFD7 +} + +div.highlight .-Color[class*=-C51] { + color: #00FFFF +} + +div.highlight .-Color[class*=-BGC51] { + background-color: #00FFFF +} + +div.highlight .-Color[class*=-C52] { + color: #5F0000 +} + +div.highlight .-Color[class*=-BGC52] { + background-color: #5F0000 +} + +div.highlight .-Color[class*=-C53] { + color: #5F005F +} + +div.highlight .-Color[class*=-BGC53] { + background-color: #5F005F +} + +div.highlight .-Color[class*=-C54] { + color: #5F0087 +} + +div.highlight .-Color[class*=-BGC54] { + background-color: #5F0087 +} + +div.highlight .-Color[class*=-C55] { + color: #5F00AF +} + +div.highlight .-Color[class*=-BGC55] { + background-color: #5F00AF +} + +div.highlight .-Color[class*=-C56] { + color: #5F00D7 +} + +div.highlight .-Color[class*=-BGC56] { + background-color: #5F00D7 +} + +div.highlight .-Color[class*=-C57] { + color: #5F00FF +} + +div.highlight .-Color[class*=-BGC57] { + background-color: #5F00FF +} + +div.highlight .-Color[class*=-C58] { + color: #5F5F00 +} + +div.highlight .-Color[class*=-BGC58] { + background-color: #5F5F00 +} + +div.highlight .-Color[class*=-C59] { + color: #5F5F5F +} + +div.highlight .-Color[class*=-BGC59] { + background-color: #5F5F5F +} + +div.highlight .-Color[class*=-C60] { + color: #5F5F87 +} + +div.highlight .-Color[class*=-BGC60] { + background-color: #5F5F87 +} + +div.highlight .-Color[class*=-C61] { + color: #5F5FAF +} + +div.highlight .-Color[class*=-BGC61] { + background-color: #5F5FAF +} + +div.highlight .-Color[class*=-C62] { + color: #5F5FD7 +} + +div.highlight .-Color[class*=-BGC62] { + background-color: #5F5FD7 +} + +div.highlight .-Color[class*=-C63] { + color: #5F5FFF +} + +div.highlight .-Color[class*=-BGC63] { + background-color: #5F5FFF +} + +div.highlight .-Color[class*=-C64] { + color: #5F8700 +} + +div.highlight .-Color[class*=-BGC64] { + background-color: #5F8700 +} + +div.highlight .-Color[class*=-C65] { + color: #5F875F +} + +div.highlight .-Color[class*=-BGC65] { + background-color: #5F875F +} + +div.highlight .-Color[class*=-C66] { + color: #5F8787 +} + +div.highlight .-Color[class*=-BGC66] { + background-color: #5F8787 +} + +div.highlight .-Color[class*=-C67] { + color: #5F87AF +} + +div.highlight .-Color[class*=-BGC67] { + background-color: #5F87AF +} + +div.highlight .-Color[class*=-C68] { + color: #5F87D7 +} + +div.highlight .-Color[class*=-BGC68] { + background-color: #5F87D7 +} + +div.highlight .-Color[class*=-C69] { + color: #5F87FF +} + +div.highlight .-Color[class*=-BGC69] { + background-color: #5F87FF +} + +div.highlight .-Color[class*=-C70] { + color: #5FAF00 +} + +div.highlight .-Color[class*=-BGC70] { + background-color: #5FAF00 +} + +div.highlight .-Color[class*=-C71] { + color: #5FAF5F +} + +div.highlight .-Color[class*=-BGC71] { + background-color: #5FAF5F +} + +div.highlight .-Color[class*=-C72] { + color: #5FAF87 +} + +div.highlight .-Color[class*=-BGC72] { + background-color: #5FAF87 +} + +div.highlight .-Color[class*=-C73] { + color: #5FAFAF +} + +div.highlight .-Color[class*=-BGC73] { + background-color: #5FAFAF +} + +div.highlight .-Color[class*=-C74] { + color: #5FAFD7 +} + +div.highlight .-Color[class*=-BGC74] { + background-color: #5FAFD7 +} + +div.highlight .-Color[class*=-C75] { + color: #5FAFFF +} + +div.highlight .-Color[class*=-BGC75] { + background-color: #5FAFFF +} + +div.highlight .-Color[class*=-C76] { + color: #5FD700 +} + +div.highlight .-Color[class*=-BGC76] { + background-color: #5FD700 +} + +div.highlight .-Color[class*=-C77] { + color: #5FD75F +} + +div.highlight .-Color[class*=-BGC77] { + background-color: #5FD75F +} + +div.highlight .-Color[class*=-C78] { + color: #5FD787 +} + +div.highlight .-Color[class*=-BGC78] { + background-color: #5FD787 +} + +div.highlight .-Color[class*=-C79] { + color: #5FD7AF +} + +div.highlight .-Color[class*=-BGC79] { + background-color: #5FD7AF +} + +div.highlight .-Color[class*=-C80] { + color: #5FD7D7 +} + +div.highlight .-Color[class*=-BGC80] { + background-color: #5FD7D7 +} + +div.highlight .-Color[class*=-C81] { + color: #5FD7FF +} + +div.highlight .-Color[class*=-BGC81] { + background-color: #5FD7FF +} + +div.highlight .-Color[class*=-C82] { + color: #5FFF00 +} + +div.highlight .-Color[class*=-BGC82] { + background-color: #5FFF00 +} + +div.highlight .-Color[class*=-C83] { + color: #5FFF5F +} + +div.highlight .-Color[class*=-BGC83] { + background-color: #5FFF5F +} + +div.highlight .-Color[class*=-C84] { + color: #5FFF87 +} + +div.highlight .-Color[class*=-BGC84] { + background-color: #5FFF87 +} + +div.highlight .-Color[class*=-C85] { + color: #5FFFAF +} + +div.highlight .-Color[class*=-BGC85] { + background-color: #5FFFAF +} + +div.highlight .-Color[class*=-C86] { + color: #5FFFD7 +} + +div.highlight .-Color[class*=-BGC86] { + background-color: #5FFFD7 +} + +div.highlight .-Color[class*=-C87] { + color: #5FFFFF +} + +div.highlight .-Color[class*=-BGC87] { + background-color: #5FFFFF +} + +div.highlight .-Color[class*=-C88] { + color: #870000 +} + +div.highlight .-Color[class*=-BGC88] { + background-color: #870000 +} + +div.highlight .-Color[class*=-C89] { + color: #87005F +} + +div.highlight .-Color[class*=-BGC89] { + background-color: #87005F +} + +div.highlight .-Color[class*=-C90] { + color: #870087 +} + +div.highlight .-Color[class*=-BGC90] { + background-color: #870087 +} + +div.highlight .-Color[class*=-C91] { + color: #8700AF +} + +div.highlight .-Color[class*=-BGC91] { + background-color: #8700AF +} + +div.highlight .-Color[class*=-C92] { + color: #8700D7 +} + +div.highlight .-Color[class*=-BGC92] { + background-color: #8700D7 +} + +div.highlight .-Color[class*=-C93] { + color: #8700FF +} + +div.highlight .-Color[class*=-BGC93] { + background-color: #8700FF +} + +div.highlight .-Color[class*=-C94] { + color: #875F00 +} + +div.highlight .-Color[class*=-BGC94] { + background-color: #875F00 +} + +div.highlight .-Color[class*=-C95] { + color: #875F5F +} + +div.highlight .-Color[class*=-BGC95] { + background-color: #875F5F +} + +div.highlight .-Color[class*=-C96] { + color: #875F87 +} + +div.highlight .-Color[class*=-BGC96] { + background-color: #875F87 +} + +div.highlight .-Color[class*=-C97] { + color: #875FAF +} + +div.highlight .-Color[class*=-BGC97] { + background-color: #875FAF +} + +div.highlight .-Color[class*=-C98] { + color: #875FD7 +} + +div.highlight .-Color[class*=-BGC98] { + background-color: #875FD7 +} + +div.highlight .-Color[class*=-C99] { + color: #875FFF +} + +div.highlight .-Color[class*=-BGC99] { + background-color: #875FFF +} + +div.highlight .-Color[class*=-C100] { + color: #878700 +} + +div.highlight .-Color[class*=-BGC100] { + background-color: #878700 +} + +div.highlight .-Color[class*=-C101] { + color: #87875F +} + +div.highlight .-Color[class*=-BGC101] { + background-color: #87875F +} + +div.highlight .-Color[class*=-C102] { + color: #878787 +} + +div.highlight .-Color[class*=-BGC102] { + background-color: #878787 +} + +div.highlight .-Color[class*=-C103] { + color: #8787AF +} + +div.highlight .-Color[class*=-BGC103] { + background-color: #8787AF +} + +div.highlight .-Color[class*=-C104] { + color: #8787D7 +} + +div.highlight .-Color[class*=-BGC104] { + background-color: #8787D7 +} + +div.highlight .-Color[class*=-C105] { + color: #8787FF +} + +div.highlight .-Color[class*=-BGC105] { + background-color: #8787FF +} + +div.highlight .-Color[class*=-C106] { + color: #87AF00 +} + +div.highlight .-Color[class*=-BGC106] { + background-color: #87AF00 +} + +div.highlight .-Color[class*=-C107] { + color: #87AF5F +} + +div.highlight .-Color[class*=-BGC107] { + background-color: #87AF5F +} + +div.highlight .-Color[class*=-C108] { + color: #87AF87 +} + +div.highlight .-Color[class*=-BGC108] { + background-color: #87AF87 +} + +div.highlight .-Color[class*=-C109] { + color: #87AFAF +} + +div.highlight .-Color[class*=-BGC109] { + background-color: #87AFAF +} + +div.highlight .-Color[class*=-C110] { + color: #87AFD7 +} + +div.highlight .-Color[class*=-BGC110] { + background-color: #87AFD7 +} + +div.highlight .-Color[class*=-C111] { + color: #87AFFF +} + +div.highlight .-Color[class*=-BGC111] { + background-color: #87AFFF +} + +div.highlight .-Color[class*=-C112] { + color: #87D700 +} + +div.highlight .-Color[class*=-BGC112] { + background-color: #87D700 +} + +div.highlight .-Color[class*=-C113] { + color: #87D75F +} + +div.highlight .-Color[class*=-BGC113] { + background-color: #87D75F +} + +div.highlight .-Color[class*=-C114] { + color: #87D787 +} + +div.highlight .-Color[class*=-BGC114] { + background-color: #87D787 +} + +div.highlight .-Color[class*=-C115] { + color: #87D7AF +} + +div.highlight .-Color[class*=-BGC115] { + background-color: #87D7AF +} + +div.highlight .-Color[class*=-C116] { + color: #87D7D7 +} + +div.highlight .-Color[class*=-BGC116] { + background-color: #87D7D7 +} + +div.highlight .-Color[class*=-C117] { + color: #87D7FF +} + +div.highlight .-Color[class*=-BGC117] { + background-color: #87D7FF +} + +div.highlight .-Color[class*=-C118] { + color: #87FF00 +} + +div.highlight .-Color[class*=-BGC118] { + background-color: #87FF00 +} + +div.highlight .-Color[class*=-C119] { + color: #87FF5F +} + +div.highlight .-Color[class*=-BGC119] { + background-color: #87FF5F +} + +div.highlight .-Color[class*=-C120] { + color: #87FF87 +} + +div.highlight .-Color[class*=-BGC120] { + background-color: #87FF87 +} + +div.highlight .-Color[class*=-C121] { + color: #87FFAF +} + +div.highlight .-Color[class*=-BGC121] { + background-color: #87FFAF +} + +div.highlight .-Color[class*=-C122] { + color: #87FFD7 +} + +div.highlight .-Color[class*=-BGC122] { + background-color: #87FFD7 +} + +div.highlight .-Color[class*=-C123] { + color: #87FFFF +} + +div.highlight .-Color[class*=-BGC123] { + background-color: #87FFFF +} + +div.highlight .-Color[class*=-C124] { + color: #AF0000 +} + +div.highlight .-Color[class*=-BGC124] { + background-color: #AF0000 +} + +div.highlight .-Color[class*=-C125] { + color: #AF005F +} + +div.highlight .-Color[class*=-BGC125] { + background-color: #AF005F +} + +div.highlight .-Color[class*=-C126] { + color: #AF0087 +} + +div.highlight .-Color[class*=-BGC126] { + background-color: #AF0087 +} + +div.highlight .-Color[class*=-C127] { + color: #AF00AF +} + +div.highlight .-Color[class*=-BGC127] { + background-color: #AF00AF +} + +div.highlight .-Color[class*=-C128] { + color: #AF00D7 +} + +div.highlight .-Color[class*=-BGC128] { + background-color: #AF00D7 +} + +div.highlight .-Color[class*=-C129] { + color: #AF00FF +} + +div.highlight .-Color[class*=-BGC129] { + background-color: #AF00FF +} + +div.highlight .-Color[class*=-C130] { + color: #AF5F00 +} + +div.highlight .-Color[class*=-BGC130] { + background-color: #AF5F00 +} + +div.highlight .-Color[class*=-C131] { + color: #AF5F5F +} + +div.highlight .-Color[class*=-BGC131] { + background-color: #AF5F5F +} + +div.highlight .-Color[class*=-C132] { + color: #AF5F87 +} + +div.highlight .-Color[class*=-BGC132] { + background-color: #AF5F87 +} + +div.highlight .-Color[class*=-C133] { + color: #AF5FAF +} + +div.highlight .-Color[class*=-BGC133] { + background-color: #AF5FAF +} + +div.highlight .-Color[class*=-C134] { + color: #AF5FD7 +} + +div.highlight .-Color[class*=-BGC134] { + background-color: #AF5FD7 +} + +div.highlight .-Color[class*=-C135] { + color: #AF5FFF +} + +div.highlight .-Color[class*=-BGC135] { + background-color: #AF5FFF +} + +div.highlight .-Color[class*=-C136] { + color: #AF8700 +} + +div.highlight .-Color[class*=-BGC136] { + background-color: #AF8700 +} + +div.highlight .-Color[class*=-C137] { + color: #AF875F +} + +div.highlight .-Color[class*=-BGC137] { + background-color: #AF875F +} + +div.highlight .-Color[class*=-C138] { + color: #AF8787 +} + +div.highlight .-Color[class*=-BGC138] { + background-color: #AF8787 +} + +div.highlight .-Color[class*=-C139] { + color: #AF87AF +} + +div.highlight .-Color[class*=-BGC139] { + background-color: #AF87AF +} + +div.highlight .-Color[class*=-C140] { + color: #AF87D7 +} + +div.highlight .-Color[class*=-BGC140] { + background-color: #AF87D7 +} + +div.highlight .-Color[class*=-C141] { + color: #AF87FF +} + +div.highlight .-Color[class*=-BGC141] { + background-color: #AF87FF +} + +div.highlight .-Color[class*=-C142] { + color: #AFAF00 +} + +div.highlight .-Color[class*=-BGC142] { + background-color: #AFAF00 +} + +div.highlight .-Color[class*=-C143] { + color: #AFAF5F +} + +div.highlight .-Color[class*=-BGC143] { + background-color: #AFAF5F +} + +div.highlight .-Color[class*=-C144] { + color: #AFAF87 +} + +div.highlight .-Color[class*=-BGC144] { + background-color: #AFAF87 +} + +div.highlight .-Color[class*=-C145] { + color: #AFAFAF +} + +div.highlight .-Color[class*=-BGC145] { + background-color: #AFAFAF +} + +div.highlight .-Color[class*=-C146] { + color: #AFAFD7 +} + +div.highlight .-Color[class*=-BGC146] { + background-color: #AFAFD7 +} + +div.highlight .-Color[class*=-C147] { + color: #AFAFFF +} + +div.highlight .-Color[class*=-BGC147] { + background-color: #AFAFFF +} + +div.highlight .-Color[class*=-C148] { + color: #AFD700 +} + +div.highlight .-Color[class*=-BGC148] { + background-color: #AFD700 +} + +div.highlight .-Color[class*=-C149] { + color: #AFD75F +} + +div.highlight .-Color[class*=-BGC149] { + background-color: #AFD75F +} + +div.highlight .-Color[class*=-C150] { + color: #AFD787 +} + +div.highlight .-Color[class*=-BGC150] { + background-color: #AFD787 +} + +div.highlight .-Color[class*=-C151] { + color: #AFD7AF +} + +div.highlight .-Color[class*=-BGC151] { + background-color: #AFD7AF +} + +div.highlight .-Color[class*=-C152] { + color: #AFD7D7 +} + +div.highlight .-Color[class*=-BGC152] { + background-color: #AFD7D7 +} + +div.highlight .-Color[class*=-C153] { + color: #AFD7FF +} + +div.highlight .-Color[class*=-BGC153] { + background-color: #AFD7FF +} + +div.highlight .-Color[class*=-C154] { + color: #AFFF00 +} + +div.highlight .-Color[class*=-BGC154] { + background-color: #AFFF00 +} + +div.highlight .-Color[class*=-C155] { + color: #AFFF5F +} + +div.highlight .-Color[class*=-BGC155] { + background-color: #AFFF5F +} + +div.highlight .-Color[class*=-C156] { + color: #AFFF87 +} + +div.highlight .-Color[class*=-BGC156] { + background-color: #AFFF87 +} + +div.highlight .-Color[class*=-C157] { + color: #AFFFAF +} + +div.highlight .-Color[class*=-BGC157] { + background-color: #AFFFAF +} + +div.highlight .-Color[class*=-C158] { + color: #AFFFD7 +} + +div.highlight .-Color[class*=-BGC158] { + background-color: #AFFFD7 +} + +div.highlight .-Color[class*=-C159] { + color: #AFFFFF +} + +div.highlight .-Color[class*=-BGC159] { + background-color: #AFFFFF +} + +div.highlight .-Color[class*=-C160] { + color: #D70000 +} + +div.highlight .-Color[class*=-BGC160] { + background-color: #D70000 +} + +div.highlight .-Color[class*=-C161] { + color: #D7005F +} + +div.highlight .-Color[class*=-BGC161] { + background-color: #D7005F +} + +div.highlight .-Color[class*=-C162] { + color: #D70087 +} + +div.highlight .-Color[class*=-BGC162] { + background-color: #D70087 +} + +div.highlight .-Color[class*=-C163] { + color: #D700AF +} + +div.highlight .-Color[class*=-BGC163] { + background-color: #D700AF +} + +div.highlight .-Color[class*=-C164] { + color: #D700D7 +} + +div.highlight .-Color[class*=-BGC164] { + background-color: #D700D7 +} + +div.highlight .-Color[class*=-C165] { + color: #D700FF +} + +div.highlight .-Color[class*=-BGC165] { + background-color: #D700FF +} + +div.highlight .-Color[class*=-C166] { + color: #D75F00 +} + +div.highlight .-Color[class*=-BGC166] { + background-color: #D75F00 +} + +div.highlight .-Color[class*=-C167] { + color: #D75F5F +} + +div.highlight .-Color[class*=-BGC167] { + background-color: #D75F5F +} + +div.highlight .-Color[class*=-C168] { + color: #D75F87 +} + +div.highlight .-Color[class*=-BGC168] { + background-color: #D75F87 +} + +div.highlight .-Color[class*=-C169] { + color: #D75FAF +} + +div.highlight .-Color[class*=-BGC169] { + background-color: #D75FAF +} + +div.highlight .-Color[class*=-C170] { + color: #D75FD7 +} + +div.highlight .-Color[class*=-BGC170] { + background-color: #D75FD7 +} + +div.highlight .-Color[class*=-C171] { + color: #D75FFF +} + +div.highlight .-Color[class*=-BGC171] { + background-color: #D75FFF +} + +div.highlight .-Color[class*=-C172] { + color: #D78700 +} + +div.highlight .-Color[class*=-BGC172] { + background-color: #D78700 +} + +div.highlight .-Color[class*=-C173] { + color: #D7875F +} + +div.highlight .-Color[class*=-BGC173] { + background-color: #D7875F +} + +div.highlight .-Color[class*=-C174] { + color: #D78787 +} + +div.highlight .-Color[class*=-BGC174] { + background-color: #D78787 +} + +div.highlight .-Color[class*=-C175] { + color: #D787AF +} + +div.highlight .-Color[class*=-BGC175] { + background-color: #D787AF +} + +div.highlight .-Color[class*=-C176] { + color: #D787D7 +} + +div.highlight .-Color[class*=-BGC176] { + background-color: #D787D7 +} + +div.highlight .-Color[class*=-C177] { + color: #D787FF +} + +div.highlight .-Color[class*=-BGC177] { + background-color: #D787FF +} + +div.highlight .-Color[class*=-C178] { + color: #D7AF00 +} + +div.highlight .-Color[class*=-BGC178] { + background-color: #D7AF00 +} + +div.highlight .-Color[class*=-C179] { + color: #D7AF5F +} + +div.highlight .-Color[class*=-BGC179] { + background-color: #D7AF5F +} + +div.highlight .-Color[class*=-C180] { + color: #D7AF87 +} + +div.highlight .-Color[class*=-BGC180] { + background-color: #D7AF87 +} + +div.highlight .-Color[class*=-C181] { + color: #D7AFAF +} + +div.highlight .-Color[class*=-BGC181] { + background-color: #D7AFAF +} + +div.highlight .-Color[class*=-C182] { + color: #D7AFD7 +} + +div.highlight .-Color[class*=-BGC182] { + background-color: #D7AFD7 +} + +div.highlight .-Color[class*=-C183] { + color: #D7AFFF +} + +div.highlight .-Color[class*=-BGC183] { + background-color: #D7AFFF +} + +div.highlight .-Color[class*=-C184] { + color: #D7D700 +} + +div.highlight .-Color[class*=-BGC184] { + background-color: #D7D700 +} + +div.highlight .-Color[class*=-C185] { + color: #D7D75F +} + +div.highlight .-Color[class*=-BGC185] { + background-color: #D7D75F +} + +div.highlight .-Color[class*=-C186] { + color: #D7D787 +} + +div.highlight .-Color[class*=-BGC186] { + background-color: #D7D787 +} + +div.highlight .-Color[class*=-C187] { + color: #D7D7AF +} + +div.highlight .-Color[class*=-BGC187] { + background-color: #D7D7AF +} + +div.highlight .-Color[class*=-C188] { + color: #D7D7D7 +} + +div.highlight .-Color[class*=-BGC188] { + background-color: #D7D7D7 +} + +div.highlight .-Color[class*=-C189] { + color: #D7D7FF +} + +div.highlight .-Color[class*=-BGC189] { + background-color: #D7D7FF +} + +div.highlight .-Color[class*=-C190] { + color: #D7FF00 +} + +div.highlight .-Color[class*=-BGC190] { + background-color: #D7FF00 +} + +div.highlight .-Color[class*=-C191] { + color: #D7FF5F +} + +div.highlight .-Color[class*=-BGC191] { + background-color: #D7FF5F +} + +div.highlight .-Color[class*=-C192] { + color: #D7FF87 +} + +div.highlight .-Color[class*=-BGC192] { + background-color: #D7FF87 +} + +div.highlight .-Color[class*=-C193] { + color: #D7FFAF +} + +div.highlight .-Color[class*=-BGC193] { + background-color: #D7FFAF +} + +div.highlight .-Color[class*=-C194] { + color: #D7FFD7 +} + +div.highlight .-Color[class*=-BGC194] { + background-color: #D7FFD7 +} + +div.highlight .-Color[class*=-C195] { + color: #D7FFFF +} + +div.highlight .-Color[class*=-BGC195] { + background-color: #D7FFFF +} + +div.highlight .-Color[class*=-C196] { + color: #FF0000 +} + +div.highlight .-Color[class*=-BGC196] { + background-color: #FF0000 +} + +div.highlight .-Color[class*=-C197] { + color: #FF005F +} + +div.highlight .-Color[class*=-BGC197] { + background-color: #FF005F +} + +div.highlight .-Color[class*=-C198] { + color: #FF0087 +} + +div.highlight .-Color[class*=-BGC198] { + background-color: #FF0087 +} + +div.highlight .-Color[class*=-C199] { + color: #FF00AF +} + +div.highlight .-Color[class*=-BGC199] { + background-color: #FF00AF +} + +div.highlight .-Color[class*=-C200] { + color: #FF00D7 +} + +div.highlight .-Color[class*=-BGC200] { + background-color: #FF00D7 +} + +div.highlight .-Color[class*=-C201] { + color: #FF00FF +} + +div.highlight .-Color[class*=-BGC201] { + background-color: #FF00FF +} + +div.highlight .-Color[class*=-C202] { + color: #FF5F00 +} + +div.highlight .-Color[class*=-BGC202] { + background-color: #FF5F00 +} + +div.highlight .-Color[class*=-C203] { + color: #FF5F5F +} + +div.highlight .-Color[class*=-BGC203] { + background-color: #FF5F5F +} + +div.highlight .-Color[class*=-C204] { + color: #FF5F87 +} + +div.highlight .-Color[class*=-BGC204] { + background-color: #FF5F87 +} + +div.highlight .-Color[class*=-C205] { + color: #FF5FAF +} + +div.highlight .-Color[class*=-BGC205] { + background-color: #FF5FAF +} + +div.highlight .-Color[class*=-C206] { + color: #FF5FD7 +} + +div.highlight .-Color[class*=-BGC206] { + background-color: #FF5FD7 +} + +div.highlight .-Color[class*=-C207] { + color: #FF5FFF +} + +div.highlight .-Color[class*=-BGC207] { + background-color: #FF5FFF +} + +div.highlight .-Color[class*=-C208] { + color: #FF8700 +} + +div.highlight .-Color[class*=-BGC208] { + background-color: #FF8700 +} + +div.highlight .-Color[class*=-C209] { + color: #FF875F +} + +div.highlight .-Color[class*=-BGC209] { + background-color: #FF875F +} + +div.highlight .-Color[class*=-C210] { + color: #FF8787 +} + +div.highlight .-Color[class*=-BGC210] { + background-color: #FF8787 +} + +div.highlight .-Color[class*=-C211] { + color: #FF87AF +} + +div.highlight .-Color[class*=-BGC211] { + background-color: #FF87AF +} + +div.highlight .-Color[class*=-C212] { + color: #FF87D7 +} + +div.highlight .-Color[class*=-BGC212] { + background-color: #FF87D7 +} + +div.highlight .-Color[class*=-C213] { + color: #FF87FF +} + +div.highlight .-Color[class*=-BGC213] { + background-color: #FF87FF +} + +div.highlight .-Color[class*=-C214] { + color: #FFAF00 +} + +div.highlight .-Color[class*=-BGC214] { + background-color: #FFAF00 +} + +div.highlight .-Color[class*=-C215] { + color: #FFAF5F +} + +div.highlight .-Color[class*=-BGC215] { + background-color: #FFAF5F +} + +div.highlight .-Color[class*=-C216] { + color: #FFAF87 +} + +div.highlight .-Color[class*=-BGC216] { + background-color: #FFAF87 +} + +div.highlight .-Color[class*=-C217] { + color: #FFAFAF +} + +div.highlight .-Color[class*=-BGC217] { + background-color: #FFAFAF +} + +div.highlight .-Color[class*=-C218] { + color: #FFAFD7 +} + +div.highlight .-Color[class*=-BGC218] { + background-color: #FFAFD7 +} + +div.highlight .-Color[class*=-C219] { + color: #FFAFFF +} + +div.highlight .-Color[class*=-BGC219] { + background-color: #FFAFFF +} + +div.highlight .-Color[class*=-C220] { + color: #FFD700 +} + +div.highlight .-Color[class*=-BGC220] { + background-color: #FFD700 +} + +div.highlight .-Color[class*=-C221] { + color: #FFD75F +} + +div.highlight .-Color[class*=-BGC221] { + background-color: #FFD75F +} + +div.highlight .-Color[class*=-C222] { + color: #FFD787 +} + +div.highlight .-Color[class*=-BGC222] { + background-color: #FFD787 +} + +div.highlight .-Color[class*=-C223] { + color: #FFD7AF +} + +div.highlight .-Color[class*=-BGC223] { + background-color: #FFD7AF +} + +div.highlight .-Color[class*=-C224] { + color: #FFD7D7 +} + +div.highlight .-Color[class*=-BGC224] { + background-color: #FFD7D7 +} + +div.highlight .-Color[class*=-C225] { + color: #FFD7FF +} + +div.highlight .-Color[class*=-BGC225] { + background-color: #FFD7FF +} + +div.highlight .-Color[class*=-C226] { + color: #FFFF00 +} + +div.highlight .-Color[class*=-BGC226] { + background-color: #FFFF00 +} + +div.highlight .-Color[class*=-C227] { + color: #FFFF5F +} + +div.highlight .-Color[class*=-BGC227] { + background-color: #FFFF5F +} + +div.highlight .-Color[class*=-C228] { + color: #FFFF87 +} + +div.highlight .-Color[class*=-BGC228] { + background-color: #FFFF87 +} + +div.highlight .-Color[class*=-C229] { + color: #FFFFAF +} + +div.highlight .-Color[class*=-BGC229] { + background-color: #FFFFAF +} + +div.highlight .-Color[class*=-C230] { + color: #FFFFD7 +} + +div.highlight .-Color[class*=-BGC230] { + background-color: #FFFFD7 +} + +div.highlight .-Color[class*=-C231] { + color: #FFFFFF +} + +div.highlight .-Color[class*=-BGC231] { + background-color: #FFFFFF +} + +div.highlight .-Color[class*=-C232] { + color: #080808 +} + +div.highlight .-Color[class*=-BGC232] { + background-color: #080808 +} + +div.highlight .-Color[class*=-C233] { + color: #121212 +} + +div.highlight .-Color[class*=-BGC233] { + background-color: #121212 +} + +div.highlight .-Color[class*=-C234] { + color: #1C1C1C +} + +div.highlight .-Color[class*=-BGC234] { + background-color: #1C1C1C +} + +div.highlight .-Color[class*=-C235] { + color: #262626 +} + +div.highlight .-Color[class*=-BGC235] { + background-color: #262626 +} + +div.highlight .-Color[class*=-C236] { + color: #303030 +} + +div.highlight .-Color[class*=-BGC236] { + background-color: #303030 +} + +div.highlight .-Color[class*=-C237] { + color: #3A3A3A +} + +div.highlight .-Color[class*=-BGC237] { + background-color: #3A3A3A +} + +div.highlight .-Color[class*=-C238] { + color: #444444 +} + +div.highlight .-Color[class*=-BGC238] { + background-color: #444444 +} + +div.highlight .-Color[class*=-C239] { + color: #4E4E4E +} + +div.highlight .-Color[class*=-BGC239] { + background-color: #4E4E4E +} + +div.highlight .-Color[class*=-C240] { + color: #585858 +} + +div.highlight .-Color[class*=-BGC240] { + background-color: #585858 +} + +div.highlight .-Color[class*=-C241] { + color: #626262 +} + +div.highlight .-Color[class*=-BGC241] { + background-color: #626262 +} + +div.highlight .-Color[class*=-C242] { + color: #6C6C6C +} + +div.highlight .-Color[class*=-BGC242] { + background-color: #6C6C6C +} + +div.highlight .-Color[class*=-C243] { + color: #767676 +} + +div.highlight .-Color[class*=-BGC243] { + background-color: #767676 +} + +div.highlight .-Color[class*=-C244] { + color: #808080 +} + +div.highlight .-Color[class*=-BGC244] { + background-color: #808080 +} + +div.highlight .-Color[class*=-C245] { + color: #8A8A8A +} + +div.highlight .-Color[class*=-BGC245] { + background-color: #8A8A8A +} + +div.highlight .-Color[class*=-C246] { + color: #949494 +} + +div.highlight .-Color[class*=-BGC246] { + background-color: #949494 +} + +div.highlight .-Color[class*=-C247] { + color: #9E9E9E +} + +div.highlight .-Color[class*=-BGC247] { + background-color: #9E9E9E +} + +div.highlight .-Color[class*=-C248] { + color: #A8A8A8 +} + +div.highlight .-Color[class*=-BGC248] { + background-color: #A8A8A8 +} + +div.highlight .-Color[class*=-C249] { + color: #B2B2B2 +} + +div.highlight .-Color[class*=-BGC249] { + background-color: #B2B2B2 +} + +div.highlight .-Color[class*=-C250] { + color: #BCBCBC +} + +div.highlight .-Color[class*=-BGC250] { + background-color: #BCBCBC +} + +div.highlight .-Color[class*=-C251] { + color: #C6C6C6 +} + +div.highlight .-Color[class*=-BGC251] { + background-color: #C6C6C6 +} + +div.highlight .-Color[class*=-C252] { + color: #D0D0D0 +} + +div.highlight .-Color[class*=-BGC252] { + background-color: #D0D0D0 +} + +div.highlight .-Color[class*=-C253] { + color: #DADADA +} + +div.highlight .-Color[class*=-BGC253] { + background-color: #DADADA +} + +div.highlight .-Color[class*=-C254] { + color: #E4E4E4 +} + +div.highlight .-Color[class*=-BGC254] { + background-color: #E4E4E4 +} + +div.highlight .-Color[class*=-C255] { + color: #EEEEEE +} + +div.highlight .-Color[class*=-BGC255] { + background-color: #EEEEEE +} diff --git a/_static/play-solid.svg b/_static/play-solid.svg new file mode 100644 index 00000000..bcd81f7a --- /dev/null +++ b/_static/play-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/_static/plus.png b/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/_static/plus.png differ diff --git a/_static/pygments.css b/_static/pygments.css new file mode 100644 index 00000000..84ab3030 --- /dev/null +++ b/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #008000; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #9C6500 } /* Comment.Preproc */ +.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #E40000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #008400 } /* Generic.Inserted */ +.highlight .go { color: #717171 } /* Generic.Output */ +.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #008000 } /* Keyword.Pseudo */ +.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #B00040 } /* Keyword.Type */ +.highlight .m { color: #666666 } /* Literal.Number */ +.highlight .s { color: #BA2121 } /* Literal.String */ +.highlight .na { color: #687822 } /* Name.Attribute */ +.highlight .nb { color: #008000 } /* Name.Builtin */ +.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.highlight .no { color: #880000 } /* Name.Constant */ +.highlight .nd { color: #AA22FF } /* Name.Decorator */ +.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #0000FF } /* Name.Function */ +.highlight .nl { color: #767600 } /* Name.Label */ +.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #19177C } /* Name.Variable */ +.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #666666 } /* Literal.Number.Bin */ +.highlight .mf { color: #666666 } /* Literal.Number.Float */ +.highlight .mh { color: #666666 } /* Literal.Number.Hex */ +.highlight .mi { color: #666666 } /* Literal.Number.Integer */ +.highlight .mo { color: #666666 } /* Literal.Number.Oct */ +.highlight .sa { color: #BA2121 } /* Literal.String.Affix */ +.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */ +.highlight .sc { color: #BA2121 } /* Literal.String.Char */ +.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #BA2121 } /* Literal.String.Double */ +.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */ +.highlight .sx { color: #008000 } /* Literal.String.Other */ +.highlight .sr { color: #A45A77 } /* Literal.String.Regex */ +.highlight .s1 { color: #BA2121 } /* Literal.String.Single */ +.highlight .ss { color: #19177C } /* Literal.String.Symbol */ +.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #0000FF } /* Name.Function.Magic */ +.highlight .vc { color: #19177C } /* Name.Variable.Class */ +.highlight .vg { color: #19177C } /* Name.Variable.Global */ +.highlight .vi { color: #19177C } /* Name.Variable.Instance */ +.highlight .vm { color: #19177C } /* Name.Variable.Magic */ +.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/_static/searchtools.js b/_static/searchtools.js new file mode 100644 index 00000000..b08d58c9 --- /dev/null +++ b/_static/searchtools.js @@ -0,0 +1,620 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + "Search finished, found ${resultCount} page(s) matching the search query." + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/_static/sphinx-thebe.css b/_static/sphinx-thebe.css new file mode 100644 index 00000000..1da27930 --- /dev/null +++ b/_static/sphinx-thebe.css @@ -0,0 +1,129 @@ +/* Thebelab Buttons */ +.thebelab-button { + z-index: 999; + display: inline-block; + padding: 0.35em 1.2em; + margin: 0px 1px; + border-radius: 0.12em; + box-sizing: border-box; + text-decoration: none; + font-family: "Roboto", sans-serif; + font-weight: 300; + text-align: center; + transition: all 0.2s; + background-color: #dddddd; + border: 0.05em solid white; + color: #000000; +} + +.thebelab-button:hover { + border: 0.05em solid black; + background-color: #fcfcfc; +} + +.thebe-launch-button { + height: 2.2em; + font-size: 0.8em; + border: 1px black solid; +} + +/* Thebelab Cell */ +.thebelab-cell pre { + background: none; +} + +.thebelab-cell .thebelab-input { + padding-left: 1em; + margin-bottom: 0.5em; + margin-top: 0.5em; +} + +.thebelab-cell .jp-OutputArea { + margin-top: 0.5em; + margin-left: 1em; +} + +button.thebelab-button.thebelab-run-button { + margin-left: 1.5em; + margin-bottom: 0.5em; +} + +/* Loading button */ +button.thebe-launch-button div.spinner { + float: left; + margin-right: 1em; +} + +/* Remove the spinner when thebelab is ready */ +.thebe-launch-button.thebe-status-ready .spinner { + display: none; +} + +.thebe-launch-button span.status { + font-family: monospace; + font-weight: bold; +} + +.thebe-launch-button.thebe-status-ready span.status { + color: green; +} + +.spinner { + height: 2em; + text-align: center; + font-size: 0.7em; +} + +.spinner > div { + background-color: #f37726; + height: 100%; + width: 6px; + display: inline-block; + + -webkit-animation: sk-stretchdelay 1.2s infinite ease-in-out; + animation: sk-stretchdelay 1.2s infinite ease-in-out; +} + +.spinner .rect2 { + -webkit-animation-delay: -1.1s; + animation-delay: -1.1s; +} + +.spinner .rect3 { + -webkit-animation-delay: -1s; + animation-delay: -1s; +} + +.spinner .rect4 { + -webkit-animation-delay: -0.9s; + animation-delay: -0.9s; +} + +.spinner .rect5 { + -webkit-animation-delay: -0.8s; + animation-delay: -0.8s; +} + +@-webkit-keyframes sk-stretchdelay { + 0%, + 40%, + 100% { + -webkit-transform: scaleY(0.4); + } + 20% { + -webkit-transform: scaleY(1); + } +} + +@keyframes sk-stretchdelay { + 0%, + 40%, + 100% { + transform: scaleY(0.4); + -webkit-transform: scaleY(0.4); + } + 20% { + transform: scaleY(1); + -webkit-transform: scaleY(1); + } +} diff --git a/_static/sphinx-thebe.js b/_static/sphinx-thebe.js new file mode 100644 index 00000000..d92b1d3b --- /dev/null +++ b/_static/sphinx-thebe.js @@ -0,0 +1,127 @@ +/** + * Add attributes to Thebe blocks to initialize thebe properly + */ +var configureThebe = () => { + // Load thebe config in case we want to update it as some point + console.log("[sphinx-thebe]: Loading thebe config..."); + thebe_config = document.querySelector("script[type=\"text/x-thebe-config\"]"); + + // If we already detect a Thebe cell, don't re-run + if (document.querySelectorAll("div.thebe-cell").length > 0) { + return; + } + + // Update thebe buttons with loading message + document.querySelectorAll(".thebe-launch-button").forEach((button) => { + button.innerHTML = ` + + `; + }); + + // Set thebe event hooks + var thebeStatus; + thebelab.on("status", function (evt, data) { + console.log("Status changed:", data.status, data.message); + + const button = document.querySelector(".thebe-launch-button "); + button.classList.replace( + `thebe-status-${thebeStatus}`, + `thebe-status-${data.status}` + ) + button.querySelector(".loading-text") + .innerHTML = ( + `Launching from mybinder.org: + ${data.status}` + ); + + // Now update our thebe status + thebeStatus = data.status; + + // Find any cells with an initialization tag and ask thebe to run them when ready + if (data.status === "ready") { + var thebeInitCells = document.querySelectorAll( + ".thebe-init, .tag_thebe-init" + ); + thebeInitCells.forEach((cell) => { + console.log("Initializing Thebe with cell: " + cell.id); + cell.querySelector(".thebelab-run-button").click(); + }); + } + }); +}; + +/** + * Update the page DOM to use Thebe elements + */ +var modifyDOMForThebe = () => { + // Find all code cells, replace with Thebe interactive code cells + const codeCells = document.querySelectorAll(thebe_selector); + codeCells.forEach((codeCell, index) => { + const codeCellId = (index) => `codecell${index}`; + codeCell.id = codeCellId(index); + codeCellText = codeCell.querySelector(thebe_selector_input); + codeCellOutput = codeCell.querySelector(thebe_selector_output); + + // Clean up the language to make it work w/ CodeMirror and add it to the cell + dataLanguage = detectLanguage(kernelName); + + // Re-arrange the cell and add metadata + if (codeCellText) { + codeCellText.setAttribute("data-language", dataLanguage); + codeCellText.setAttribute("data-executable", "true"); + + // If we had an output, insert it just after the `pre` cell + if (codeCellOutput) { + codeCellOutput.setAttribute("data-output", ""); + codeCellText.insertAdjacentElement('afterend', codeCellOutput); + } + } + + // Remove sphinx-copybutton blocks, which are common in Sphinx + codeCell.querySelectorAll("button.copybtn").forEach((el) => { + el.remove(); + }); + }); +}; + +var initThebe = () => { + // Load thebe dynamically if it's not already loaded + if (typeof thebelab === "undefined") { + console.log("[sphinx-thebe]: Loading thebe from CDN..."); + document.querySelector(".thebe-launch-button ").innerText = "Loading thebe from CDN..."; + + const script = document.createElement("script"); + script.src = `${THEBE_JS_URL}`; + document.head.appendChild(script); + + // Runs once the script has finished loading + script.addEventListener("load", () => { + console.log("[sphinx-thebe]: Finished loading thebe from CDN..."); + configureThebe(); + modifyDOMForThebe(); + thebelab.bootstrap(); + }); + } else { + console.log( + "[sphinx-thebe]: thebe already loaded, not loading from CDN..." + ); + configureThebe(); + modifyDOMForThebe(); + thebelab.bootstrap(); + } +}; + +// Helper function to munge the language name +var detectLanguage = (language) => { + if (language.indexOf("python") > -1) { + language = "python"; + } else if (language === "ir") { + language = "r"; + } + return language; +}; diff --git a/_static/sphinx_highlight.js b/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/_static/sphinx_lesson.css b/_static/sphinx_lesson.css new file mode 100644 index 00000000..68cb32da --- /dev/null +++ b/_static/sphinx_lesson.css @@ -0,0 +1,103 @@ +/* sphinx_lesson.css + * https://webaim.org/resources/contrastchecker/?fcolor=00000&bcolor=FCE762 + * */ +:root { + --sphinx-lesson-selection-bg-color: #fce762; + --sphinx-lesson-selection-fg-color: #000000; +} + +/* https://webaim.org/resources/contrastchecker/?fcolor=FFFFFF&bcolor=745315 + * when dark theme is selected the some themes use this attirbute + */ +html[data-theme='dark'], body[data-theme='dark'] { + --sphinx-lesson-selection-bg-color: #745315; + --sphinx-lesson-selection-fg-color: #ffffff; +} + +/* when browser/system theme is dark and no theme is selected */ +@media (prefers-color-scheme: dark) { + html[data-theme='auto'], body[data-theme='auto'] { + --sphinx-lesson-selection-bg-color: #745315; + --sphinx-lesson-selection-fg-color: #ffffff; + } +} + +body.wy-body-for-nav img.with-border { + border: 2px solid; +} + +.rst-content .admonition-no-content { + padding-bottom: 0px; +} + +.rst-content .demo > .admonition-title::before { + content: "\01F440"; /* Eyes */ } +.rst-content .type-along > .admonition-title::before { + content: "\02328\0FE0F"; /* Keyboard */ } +.rst-content .exercise > .admonition-title::before { + content: "\0270D\0FE0F"; /* Hand */ } +.rst-content .solution > .admonition-title::before { + content: "\02714\0FE0E"; /* Check mark */ } +.rst-content .homework > .admonition-title::before { + content: "\01F4DD"; /* Memo */ } +.rst-content .discussion > .admonition-title::before { + content: "\01F4AC"; /* Speech balloon */ } +.rst-content .questions > .admonition-title::before { + content: "\02753\0FE0E"; /* Question mark */ } +.rst-content .prerequisites > .admonition-title::before { + content: "\02699"; /* Gear */ } +.rst-content .seealso > .admonition-title::before { + content: "\027A1\0FE0E"; /* Question mark */ } + + +/* instructor-note */ +.rst-content .instructor-note { + background: #e7e7e7; +} +.rst-content .instructor-note > .admonition-title { + background: #6a6a6a; +} +.rst-content .instructor-note > .admonition-title::before { + content: ""; +} + + +/* sphinx_toggle_button, make the font white */ +.rst-content .toggle.admonition button.toggle-button { + color: white; +} + +/* sphinx-togglebutton, remove underflow when toggled to hidden mode */ +.rst-content .admonition.toggle-hidden { + padding-bottom: 0px; +} + +/* selection / highlight colour uses a yellow background and a black text */ +/*** Works on common browsers ***/ +::selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/*** Mozilla based browsers ***/ +::-moz-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/***For Other Browsers ***/ +::-o-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +::-ms-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/*** For Webkit ***/ +::-webkit-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} diff --git a/_static/sphinx_rtd_theme_ext_color_contrast.css b/_static/sphinx_rtd_theme_ext_color_contrast.css new file mode 100644 index 00000000..e68feb82 --- /dev/null +++ b/_static/sphinx_rtd_theme_ext_color_contrast.css @@ -0,0 +1,47 @@ +/* The following are for web accessibility of sphinx_rtd_theme: they + * solve some of the most frequent contrast issues. Remove when this + * solved: + * https://github.com/readthedocs/sphinx_rtd_theme/issues/971 + */ +/* background: #fcfcfc, note boxes #E7F2FA */ +a { color: #2573A7; } /* original #2980B9, #1F5C84; */ +body { color: #242424; } /* original #404040, #383838 */ +.wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a { + color: #ffffff; +} /* original #fcfcfc */ +footer { color: #737373; } /* original gray=#808080*/ +footer span.commit code, footer span.commit .rst-content tt, .rst-content footer span.commit tt { + color: #737373; +} /* original gray=#808080*/ +.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal { + color: #AB2314; +} +/* Sidebar background */ +.wy-side-nav-search { background-color: #277CB4;} + +/* Same, but for pygments */ +.highlight .ch { color: #3E7A89; } /* #! line */ +.highlight .c1 { color: #3E7A89; } /* also comments */ +.highlight .nv { color: #AD3ECC; } /* variable */ +.highlight .gp { color: #B45608; } /* prompt character, $*/ +.highlight .si { color: #3975B1; } /* ${} variable text */ +.highlight .nc { color: #0C78A7; } + +/* Sphinx admonitions */ +/* warning */ +.wy-alert.wy-alert-warning .wy-alert-title, .rst-content .wy-alert-warning.note .wy-alert-title, .rst-content .attention .wy-alert-title, .rst-content .caution .wy-alert-title, .rst-content .wy-alert-warning.danger .wy-alert-title, .rst-content .wy-alert-warning.error .wy-alert-title, .rst-content .wy-alert-warning.hint .wy-alert-title, .rst-content .wy-alert-warning.important .wy-alert-title, .rst-content .wy-alert-warning.tip .wy-alert-title, .rst-content .warning .wy-alert-title, .rst-content .wy-alert-warning.seealso .wy-alert-title, .rst-content .admonition-todo .wy-alert-title, .rst-content .wy-alert-warning.admonition .wy-alert-title, .wy-alert.wy-alert-warning .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-warning .admonition-title, .rst-content .wy-alert-warning.note .admonition-title, .rst-content .attention .admonition-title, .rst-content .caution .admonition-title, .rst-content .wy-alert-warning.danger .admonition-title, .rst-content .wy-alert-warning.error .admonition-title, .rst-content .wy-alert-warning.hint .admonition-title, .rst-content .wy-alert-warning.important .admonition-title, .rst-content .wy-alert-warning.tip .admonition-title, .rst-content .warning .admonition-title, .rst-content .wy-alert-warning.seealso .admonition-title, .rst-content .admonition-todo .admonition-title, .rst-content .wy-alert-warning.admonition .admonition-title { + background: #B15E16; } +/* important */ +.wy-alert.wy-alert-success .wy-alert-title, .rst-content .wy-alert-success.note .wy-alert-title, .rst-content .wy-alert-success.attention .wy-alert-title, .rst-content .wy-alert-success.caution .wy-alert-title, .rst-content .wy-alert-success.danger .wy-alert-title, .rst-content .wy-alert-success.error .wy-alert-title, .rst-content .hint .wy-alert-title, .rst-content .important .wy-alert-title, .rst-content .tip .wy-alert-title, .rst-content .wy-alert-success.warning .wy-alert-title, .rst-content .wy-alert-success.seealso .wy-alert-title, .rst-content .wy-alert-success.admonition-todo .wy-alert-title, .rst-content .wy-alert-success.admonition .wy-alert-title, .wy-alert.wy-alert-success .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-success .admonition-title, .rst-content .wy-alert-success.note .admonition-title, .rst-content .wy-alert-success.attention .admonition-title, .rst-content .wy-alert-success.caution .admonition-title, .rst-content .wy-alert-success.danger .admonition-title, .rst-content .wy-alert-success.error .admonition-title, .rst-content .hint .admonition-title, .rst-content .important .admonition-title, .rst-content .tip .admonition-title, .rst-content .wy-alert-success.warning .admonition-title, .rst-content .wy-alert-success.seealso .admonition-title, .rst-content .wy-alert-success.admonition-todo .admonition-title, .rst-content .wy-alert-success.admonition .admonition-title { + background: #12826C; } +/* seealso, note, etc */ +.wy-alert.wy-alert-info .wy-alert-title, .rst-content .note .wy-alert-title, .rst-content .wy-alert-info.attention .wy-alert-title, .rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error .wy-alert-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content .wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .seealso .wy-alert-title, .rst-content .wy-alert-info.admonition-todo .wy-alert-title, .rst-content .wy-alert-info.admonition .wy-alert-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-info .admonition-title, .rst-content .note .admonition-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.caution .admonition-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content .wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.tip .admonition-title, .rst-content .wy-alert-info.warning .admonition-title, .rst-content .seealso .admonition-title, .rst-content .wy-alert-info.admonition-todo .admonition-title, .rst-content .wy-alert-info.admonition .admonition-title { + background: #277CB4; } +/* error, danger */ +.rst-content .danger .admonition-title, .rst-content .danger .wy-alert-title, .rst-content .error .admonition-title, .rst-content .error .wy-alert-title, .rst-content .wy-alert-danger.admonition-todo .admonition-title, .rst-content .wy-alert-danger.admonition-todo .wy-alert-title, .rst-content .wy-alert-danger.admonition .admonition-title, .rst-content .wy-alert-danger.admonition .wy-alert-title, .rst-content .wy-alert-danger.attention .admonition-title, .rst-content .wy-alert-danger.attention .wy-alert-title, .rst-content .wy-alert-danger.caution .admonition-title, .rst-content .wy-alert-danger.caution .wy-alert-title, .rst-content .wy-alert-danger.hint .admonition-title, .rst-content .wy-alert-danger.hint .wy-alert-title, .rst-content .wy-alert-danger.important .admonition-title, .rst-content .wy-alert-danger.important .wy-alert-title, .rst-content .wy-alert-danger.note .admonition-title, .rst-content .wy-alert-danger.note .wy-alert-title, .rst-content .wy-alert-danger.seealso .admonition-title, .rst-content .wy-alert-danger.seealso .wy-alert-title, .rst-content .wy-alert-danger.tip .admonition-title, .rst-content .wy-alert-danger.tip .wy-alert-title, .rst-content .wy-alert-danger.warning .admonition-title, .rst-content .wy-alert-danger.warning .wy-alert-title, .rst-content .wy-alert.wy-alert-danger .admonition-title, .wy-alert.wy-alert-danger .rst-content .admonition-title, .wy-alert.wy-alert-danger .wy-alert-title { + background: #e31704; +} + +/* Generic admonition titles */ +.wy-alert-title, .rst-content .admonition-title { + background: #277CB4; } diff --git a/_static/tabs.css b/_static/tabs.css new file mode 100644 index 00000000..957ba60d --- /dev/null +++ b/_static/tabs.css @@ -0,0 +1,89 @@ +.sphinx-tabs { + margin-bottom: 1rem; +} + +[role="tablist"] { + border-bottom: 1px solid #a0b3bf; +} + +.sphinx-tabs-tab { + position: relative; + font-family: Lato,'Helvetica Neue',Arial,Helvetica,sans-serif; + color: #1D5C87; + line-height: 24px; + margin: 0; + font-size: 16px; + font-weight: 400; + background-color: rgba(255, 255, 255, 0); + border-radius: 5px 5px 0 0; + border: 0; + padding: 1rem 1.5rem; + margin-bottom: 0; +} + +.sphinx-tabs-tab[aria-selected="true"] { + font-weight: 700; + border: 1px solid #a0b3bf; + border-bottom: 1px solid white; + margin: -1px; + background-color: white; +} + +.sphinx-tabs-tab:focus { + z-index: 1; + outline-offset: 1px; +} + +.sphinx-tabs-panel { + position: relative; + padding: 1rem; + border: 1px solid #a0b3bf; + margin: 0px -1px -1px -1px; + border-radius: 0 0 5px 5px; + border-top: 0; + background: white; +} + +.sphinx-tabs-panel.code-tab { + padding: 0.4rem; +} + +.sphinx-tab img { + margin-bottom: 24 px; +} + +/* Dark theme preference styling */ + +@media (prefers-color-scheme: dark) { + body[data-theme="auto"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); + } + + body[data-theme="auto"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); + } + + body[data-theme="auto"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 1px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); + } +} + +/* Explicit dark theme styling */ + +body[data-theme="dark"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); +} + +body[data-theme="dark"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); +} + +body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 2px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); +} diff --git a/_static/tabs.js b/_static/tabs.js new file mode 100644 index 00000000..48dc303c --- /dev/null +++ b/_static/tabs.js @@ -0,0 +1,145 @@ +try { + var session = window.sessionStorage || {}; +} catch (e) { + var session = {}; +} + +window.addEventListener("DOMContentLoaded", () => { + const allTabs = document.querySelectorAll('.sphinx-tabs-tab'); + const tabLists = document.querySelectorAll('[role="tablist"]'); + + allTabs.forEach(tab => { + tab.addEventListener("click", changeTabs); + }); + + tabLists.forEach(tabList => { + tabList.addEventListener("keydown", keyTabs); + }); + + // Restore group tab selection from session + const lastSelected = session.getItem('sphinx-tabs-last-selected'); + if (lastSelected != null) selectNamedTabs(lastSelected); +}); + +/** + * Key focus left and right between sibling elements using arrows + * @param {Node} e the element in focus when key was pressed + */ +function keyTabs(e) { + const tab = e.target; + let nextTab = null; + if (e.keyCode === 39 || e.keyCode === 37) { + tab.setAttribute("tabindex", -1); + // Move right + if (e.keyCode === 39) { + nextTab = tab.nextElementSibling; + if (nextTab === null) { + nextTab = tab.parentNode.firstElementChild; + } + // Move left + } else if (e.keyCode === 37) { + nextTab = tab.previousElementSibling; + if (nextTab === null) { + nextTab = tab.parentNode.lastElementChild; + } + } + } + + if (nextTab !== null) { + nextTab.setAttribute("tabindex", 0); + nextTab.focus(); + } +} + +/** + * Select or deselect clicked tab. If a group tab + * is selected, also select tab in other tabLists. + * @param {Node} e the element that was clicked + */ +function changeTabs(e) { + // Use this instead of the element that was clicked, in case it's a child + const notSelected = this.getAttribute("aria-selected") === "false"; + const positionBefore = this.parentNode.getBoundingClientRect().top; + const notClosable = !this.parentNode.classList.contains("closeable"); + + deselectTabList(this); + + if (notSelected || notClosable) { + selectTab(this); + const name = this.getAttribute("name"); + selectNamedTabs(name, this.id); + + if (this.classList.contains("group-tab")) { + // Persist during session + session.setItem('sphinx-tabs-last-selected', name); + } + } + + const positionAfter = this.parentNode.getBoundingClientRect().top; + const positionDelta = positionAfter - positionBefore; + // Scroll to offset content resizing + window.scrollTo(0, window.scrollY + positionDelta); +} + +/** + * Select tab and show associated panel. + * @param {Node} tab tab to select + */ +function selectTab(tab) { + tab.setAttribute("aria-selected", true); + + // Show the associated panel + document + .getElementById(tab.getAttribute("aria-controls")) + .removeAttribute("hidden"); +} + +/** + * Hide the panels associated with all tabs within the + * tablist containing this tab. + * @param {Node} tab a tab within the tablist to deselect + */ +function deselectTabList(tab) { + const parent = tab.parentNode; + const grandparent = parent.parentNode; + + Array.from(parent.children) + .forEach(t => t.setAttribute("aria-selected", false)); + + Array.from(grandparent.children) + .slice(1) // Skip tablist + .forEach(panel => panel.setAttribute("hidden", true)); +} + +/** + * Select grouped tabs with the same name, but no the tab + * with the given id. + * @param {Node} name name of grouped tab to be selected + * @param {Node} clickedId id of clicked tab + */ +function selectNamedTabs(name, clickedId=null) { + const groupedTabs = document.querySelectorAll(`.sphinx-tabs-tab[name="${name}"]`); + const tabLists = Array.from(groupedTabs).map(tab => tab.parentNode); + + tabLists + .forEach(tabList => { + // Don't want to change the tabList containing the clicked tab + const clickedTab = tabList.querySelector(`[id="${clickedId}"]`); + if (clickedTab === null ) { + // Select first tab with matching name + const tab = tabList.querySelector(`.sphinx-tabs-tab[name="${name}"]`); + deselectTabList(tab); + selectTab(tab); + } + }) +} + +if (typeof exports === 'undefined') { + exports = {}; +} + +exports.keyTabs = keyTabs; +exports.changeTabs = changeTabs; +exports.selectTab = selectTab; +exports.deselectTabList = deselectTabList; +exports.selectNamedTabs = selectNamedTabs; diff --git a/_static/term_role_formatting.css b/_static/term_role_formatting.css new file mode 100644 index 00000000..0b66095c --- /dev/null +++ b/_static/term_role_formatting.css @@ -0,0 +1,4 @@ +/* Make terms bold */ +a.reference span.std-term { + font-weight: bold; +} diff --git a/_static/togglebutton.css b/_static/togglebutton.css new file mode 100644 index 00000000..54a67879 --- /dev/null +++ b/_static/togglebutton.css @@ -0,0 +1,160 @@ +/** + * Admonition-based toggles + */ + +/* Visibility of the target */ +.admonition.toggle .admonition-title ~ * { + transition: opacity .3s, height .3s; +} + +/* Toggle buttons inside admonitions so we see the title */ +.admonition.toggle { + position: relative; +} + +/* Titles should cut off earlier to avoid overlapping w/ button */ +.admonition.toggle .admonition-title { + padding-right: 25%; + cursor: pointer; +} + +/* Hovering will cause a slight shift in color to make it feel interactive */ +.admonition.toggle .admonition-title:hover { + box-shadow: inset 0 0 0px 20px rgb(0 0 0 / 1%); +} + +/* Hovering will cause a slight shift in color to make it feel interactive */ +.admonition.toggle .admonition-title:active { + box-shadow: inset 0 0 0px 20px rgb(0 0 0 / 3%); +} + +/* Remove extra whitespace below the admonition title when hidden */ +.admonition.toggle-hidden { + padding-bottom: 0; +} + +.admonition.toggle-hidden .admonition-title { + margin-bottom: 0; +} + +/* hides all the content of a page until de-toggled */ +.admonition.toggle-hidden .admonition-title ~ * { + height: 0; + margin: 0; + opacity: 0; + visibility: hidden; +} + +/* General button style and position*/ +button.toggle-button { + /** + * Background and shape. By default there's no background + * but users can style as they wish + */ + background: none; + border: none; + outline: none; + + /* Positioning just inside the admonition title */ + position: absolute; + right: 0.5em; + padding: 0px; + border: none; + outline: none; +} + +/* Display the toggle hint on wide screens */ +@media (min-width: 768px) { + button.toggle-button.toggle-button-hidden:before { + content: attr(data-toggle-hint); /* This will be filled in by JS */ + font-size: .8em; + align-self: center; + } +} + +/* Icon behavior */ +.tb-icon { + transition: transform .2s ease-out; + height: 1.5em; + width: 1.5em; + stroke: currentColor; /* So that we inherit the color of other text */ +} + +/* The icon should point right when closed, down when open. */ +/* Open */ +.admonition.toggle button .tb-icon { + transform: rotate(90deg); +} + +/* Closed */ +.admonition.toggle button.toggle-button-hidden .tb-icon { + transform: rotate(0deg); +} + +/* With details toggles, we don't rotate the icon so it points right */ +details.toggle-details .tb-icon { + height: 1.4em; + width: 1.4em; + margin-top: 0.1em; /* To center the button vertically */ +} + + +/** + * Details-based toggles. + * In this case, we wrap elements with `.toggle` in a details block. + */ + +/* Details blocks */ +details.toggle-details { + margin: 1em 0; +} + + +details.toggle-details summary { + display: flex; + align-items: center; + cursor: pointer; + list-style: none; + border-radius: .2em; + border-left: 3px solid #1976d2; + background-color: rgb(204 204 204 / 10%); + padding: 0.2em 0.7em 0.3em 0.5em; /* Less padding on left because the SVG has left margin */ + font-size: 0.9em; +} + +details.toggle-details summary:hover { + background-color: rgb(204 204 204 / 20%); +} + +details.toggle-details summary:active { + background: rgb(204 204 204 / 28%); +} + +.toggle-details__summary-text { + margin-left: 0.2em; +} + +details.toggle-details[open] summary { + margin-bottom: .5em; +} + +details.toggle-details[open] summary .tb-icon { + transform: rotate(90deg); +} + +details.toggle-details[open] summary ~ * { + animation: toggle-fade-in .3s ease-out; +} + +@keyframes toggle-fade-in { + from {opacity: 0%;} + to {opacity: 100%;} +} + +/* Print rules - we hide all toggle button elements at print */ +@media print { + /* Always hide the summary so the button doesn't show up */ + details.toggle-details summary { + display: none; + } +} \ No newline at end of file diff --git a/_static/togglebutton.js b/_static/togglebutton.js new file mode 100644 index 00000000..215a7eef --- /dev/null +++ b/_static/togglebutton.js @@ -0,0 +1,187 @@ +/** + * Add Toggle Buttons to elements + */ + +let toggleChevron = ` + + + +`; + +var initToggleItems = () => { + var itemsToToggle = document.querySelectorAll(togglebuttonSelector); + console.log(`[togglebutton]: Adding toggle buttons to ${itemsToToggle.length} items`) + // Add the button to each admonition and hook up a callback to toggle visibility + itemsToToggle.forEach((item, index) => { + if (item.classList.contains("admonition")) { + // If it's an admonition block, then we'll add a button inside + // Generate unique IDs for this item + var toggleID = `toggle-${index}`; + var buttonID = `button-${toggleID}`; + + item.setAttribute('id', toggleID); + if (!item.classList.contains("toggle")){ + item.classList.add("toggle"); + } + // This is the button that will be added to each item to trigger the toggle + var collapseButton = ` + `; + + title = item.querySelector(".admonition-title") + title.insertAdjacentHTML("beforeend", collapseButton); + thisButton = document.getElementById(buttonID); + + // Add click handlers for the button + admonition title (if admonition) + admonitionTitle = document.querySelector(`#${toggleID} > .admonition-title`) + if (admonitionTitle) { + // If an admonition, then make the whole title block clickable + admonitionTitle.addEventListener('click', toggleClickHandler); + admonitionTitle.dataset.target = toggleID + admonitionTitle.dataset.button = buttonID + } else { + // If not an admonition then we'll listen for the button click + thisButton.addEventListener('click', toggleClickHandler); + } + + // Now hide the item for this toggle button unless explicitly noted to show + if (!item.classList.contains("toggle-shown")) { + toggleHidden(thisButton); + } + } else { + // If not an admonition, wrap the block in a
block + // Define the structure of the details block and insert it as a sibling + var detailsBlock = ` +
+ + ${toggleChevron} + ${toggleHintShow} + +
`; + item.insertAdjacentHTML("beforebegin", detailsBlock); + + // Now move the toggle-able content inside of the details block + details = item.previousElementSibling + details.appendChild(item) + item.classList.add("toggle-details__container") + + // Set up a click trigger to change the text as needed + details.addEventListener('click', (click) => { + let parent = click.target.parentElement; + if (parent.tagName.toLowerCase() == "details") { + summary = parent.querySelector("summary"); + details = parent; + } else { + summary = parent; + details = parent.parentElement; + } + // Update the inner text for the proper hint + if (details.open) { + summary.querySelector("span.toggle-details__summary-text").innerText = toggleHintShow; + } else { + summary.querySelector("span.toggle-details__summary-text").innerText = toggleHintHide; + } + + }); + + // If we have a toggle-shown class, open details block should be open + if (item.classList.contains("toggle-shown")) { + details.click(); + } + } + }) +}; + +// This should simply add / remove the collapsed class and change the button text +var toggleHidden = (button) => { + target = button.dataset['target'] + var itemToToggle = document.getElementById(target); + if (itemToToggle.classList.contains("toggle-hidden")) { + itemToToggle.classList.remove("toggle-hidden"); + button.classList.remove("toggle-button-hidden"); + } else { + itemToToggle.classList.add("toggle-hidden"); + button.classList.add("toggle-button-hidden"); + } +} + +var toggleClickHandler = (click) => { + // Be cause the admonition title is clickable and extends to the whole admonition + // We only look for a click event on this title to trigger the toggle. + + if (click.target.classList.contains("admonition-title")) { + button = click.target.querySelector(".toggle-button"); + } else if (click.target.classList.contains("tb-icon")) { + // We've clicked the icon and need to search up one parent for the button + button = click.target.parentElement; + } else if (click.target.tagName == "polyline") { + // We've clicked the SVG elements inside the button, need to up 2 layers + button = click.target.parentElement.parentElement; + } else if (click.target.classList.contains("toggle-button")) { + // We've clicked the button itself and so don't need to do anything + button = click.target; + } else { + console.log(`[togglebutton]: Couldn't find button for ${click.target}`) + } + target = document.getElementById(button.dataset['button']); + toggleHidden(target); +} + +// If we want to blanket-add toggle classes to certain cells +var addToggleToSelector = () => { + const selector = ""; + if (selector.length > 0) { + document.querySelectorAll(selector).forEach((item) => { + item.classList.add("toggle"); + }) + } +} + +// Helper function to run when the DOM is finished +const sphinxToggleRunWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} +sphinxToggleRunWhenDOMLoaded(addToggleToSelector) +sphinxToggleRunWhenDOMLoaded(initToggleItems) + +/** Toggle details blocks to be open when printing */ +if (toggleOpenOnPrint == "true") { + window.addEventListener("beforeprint", () => { + // Open the details + document.querySelectorAll("details.toggle-details").forEach((el) => { + el.dataset["togglestatus"] = el.open; + el.open = true; + }); + + // Open the admonitions + document.querySelectorAll(".admonition.toggle.toggle-hidden").forEach((el) => { + console.log(el); + el.querySelector("button.toggle-button").click(); + el.dataset["toggle_after_print"] = "true"; + }); + }); + window.addEventListener("afterprint", () => { + // Re-close the details that were closed + document.querySelectorAll("details.toggle-details").forEach((el) => { + el.open = el.dataset["togglestatus"] == "true"; + delete el.dataset["togglestatus"]; + }); + + // Re-close the admonition toggle buttons + document.querySelectorAll(".admonition.toggle").forEach((el) => { + if (el.dataset["toggle_after_print"] == "true") { + el.querySelector("button.toggle-button").click(); + delete el.dataset["toggle_after_print"]; + } + }); + }); +} diff --git a/binder/index.html b/binder/index.html new file mode 100644 index 00000000..ffd8603f --- /dev/null +++ b/binder/index.html @@ -0,0 +1,394 @@ + + + + + + + + + + + + + + + Binder — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Binder

+
+

Questions

+
    +

  • Why sharing code alone may not be sufficient.

    • +

  • How to share a computational environment?

    • +

  • What is Binder?

    • +

  • How to binderize my Python repository?

    • +

  • How to publish my Python repository?

    • +
+
+
+

Objectives

+
    +

  • Learn about reproducible computational environments.

    • +

  • Learn to create and share custom computing environments with Binder.

    • +

  • Learn to get a DOI from Zenodo for a repository.

    • +
+
+
+

Why is it sometimes not enough to share your code?

+../_images/python_unmasked.jpg +
+

Exercise 1

+
+

Binder-1: Discuss better strategies than only code sharing (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+
+
+
+

Sharing a computing environment with Binder

+

Binder allows you to create +custom computing environments that can be shared and used by many remote users. +It uses repo2docker to +create a container image (docker image) of a +project using information contained in included configuration files.

+

Repo2docker is a standalone package that you can install locally on your laptop +but an online Binder service is freely available. +This is what we will be using in the tutorial.

+

The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder.

+https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png +

Credit: Juliette Taka, Logilab and the OpenDreamKit project (2017)

+
+

Binder exercise/demo

+

In an earlier episode (Data visualization with Matplotlib) we have created this notebook:

+
import pandas as pd
+import matplotlib.pyplot as plt
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+data_2007 = data[data["year"] == 2007]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xscale("log")
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
+
+

We will now first share it via GitHub “statically”, +then using Binder.

+
+

Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this. This exercise (and all following) +requires git/GitHub knowledge and accounts, which wasn’t a +prerequisite of this course. Thus, this is a demo (and might even +be too fast for you to type-along). Watch the video if you +are reading this later on:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+
+
+
+

How can I get a DOI from Zenodo?

+

Zenodo is a general purpose open-access +repository built and operated by CERN and OpenAIRE that allows researchers to archive and get a +Digital Object Identifier (DOI) to data that they +share.

+ +
+ +
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb b/branch/master/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb new file mode 100644 index 00000000..3c1ecd2a --- /dev/null +++ b/branch/master/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb @@ -0,0 +1,96 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "url = \"https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv\"\n", + "weather = pd.read_csv(url,comment='#')\n", + "\n", + "# define the start and end time for the plot \n", + "start_date=pd.to_datetime('01/06/2021', dayfirst=True)\n", + "end_date=pd.to_datetime('01/10/2021', dayfirst=True)\n", + "\n", + "# The date format in the file is in a day-first format, which matplotlib does nto understand.\n", + "# so we need to convert it.\n", + "weather['Local time'] = pd.to_datetime(weather['Local time'], dayfirst=True)\n", + "# select the data\n", + "weather = weather[weather['Local time'].between(start_date,end_date)]\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, we have the data loaded, and adapted to our needs. So lets get plotting" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYUAAAEcCAYAAAAoSqjDAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAABtDElEQVR4nO2dd7gcVdnAf+/evSU9pBcggRCE0CHSpSNKERQbKkX9wM+GYPsQsWBFUSwgIgLSwYIoItKbhBJCS0JNgJBCSC83N7lt93x/zJzZs7Nnd2f7bHJ+z3Ofuzs7O/vu7Mx5z1vO+4pSCofD4XA4ABKNFsDhcDgc8cEpBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA4HA5HgFMKDkcDEZHJIqJEJNloWUpBRD4pIvc2Wg5H9XFKwWFFRDYYf2kR2WQ8/2Sj5SsHEVkgIkfV+TOnicgdIrJORDpF5CERObCeMlSKTXEppW5SSr23kXI5aoNTCg4rSqnB+g9YCJxgbLup0fKFqcdMu9TPEJEpwAxgDrAdMAG4HbhXRA6ovoR55RARcfe6IxLuQnGUhIgkROQ8EXldRFaJyF9EZIT/mp5RflpEFonIGhH5XxF5t4jMFpG1InKZcawzRGSGiFzmz6RfEZEjjdeHicjVIrJURJaIyI9EpCX03l+JyCrg+yIyRUQe9OVaKSI3ichwf/8bgG2Bf/nWzjdF5DARWRz6foE1ISLfF5G/iciNIrIeOKOQTBa+DzyhlPq2Umq1UqpTKfVb4AbgZ6F9PyMib/vH/bohz74iMktE1ovIMhG5xHhtfxF53D+vL4jIYcZrD4vIj0VkBrAR+IaIzAp913NF5A7/8XEi8pz/OYtE5PvGro/6/9f65+4A//w/ZhzrQBF52v8dnzatIV+WH/q/V6eI3Csio/zXOvzzu8r/Hk+LyNg859NRD5RS7s/9FfwDFgBH+Y+/AjwJbA20A38AbvFfmwwo4AqgA3gv0A38AxgDTASWA4f6+58B9APnAq3Ax4B1wAj/9dv94w/y3z8T+FzovV8GksAAYAfgaF+u0XiD2a9t38N/fhiwuMB3/T7QB5yEN4EaUEgmy3l7B/i0ZfvhQMo/nj5nt/jH3A1YYcjwBHCq/3gwsL//eCKwCjjWl+1o//lo//WH8Sy8XfzzMwzoBKYacjwNfNw4F7v5x9odWAacFPpdk8Z7zwAe8x+PANYAp/qfdYr/fKQhy+vAjv53fhi4yH/tc8C/gIFAC7APMLTR1/yW/OcsBUep/C/wbaXUYqVUD97A+eGQa+WHSqlupdS9QBee0liulFoC/BfYy9h3Od7A3aeU+jPwKnCcP1s8FjhHKdWllFoO/Ar4uPHet5VSlyql+pVSm5RS85VS9ymlepRSK4BLgEMr/L5PKKX+oZRKA0MjyGQyClhq2b4Ub/AdYWy70D/mHOBPeAMreEppBxEZpZTaoJR60t/+KeAupdRdSqm0Uuo+YJYvn+ZapdSL/vlZB/xTH1dEpgI7AXcAKKUeVkrN8Y81G09JRT13xwHzlFI3+J91C/AKcIKxz5+UUq8ppTYBfwH2NL7fSGAHpVRKKfWMUmp9xM911ACnFBylMgm43Tf11wIv4816TZN/mfF4k+X5YOP5EqWUWZXxLTzf+yQ862Gp8Vl/wJudaxaZgonIWBG51XfrrAduxBuYK8H8jCgymawExlu2jwfSeLNp2+focwDwWbwZ9iu+a+V4Q5aPaDl8WQ4OfV7W+QFuJqNsPgH8Qym1EUBE9hMvCL5CRNbhKf+o526CL7PJW3jWjOYd4/FGMtfADcA9wK2+++znItIa8XMdNcApBUepLALer5Qabvx1+FZAOUwUETGebwu87X9ODzDK+JyhSqldjH3DJX5/4m/bTSk1FG82LQX278JzWwDgxwZGh/Yx3xNFJpP7gY9Ytn8UzwLZaGzbxniszwFKqXlKqVPwFM/PgL+JyCBflhtCv8MgpdRFBb7vfcBoEdkTTzncbLx2M57VsI1SahieC1Cfu2KllN/GU1Im2wJFrwnfQrxQKTUNOBA4Hjit2PsctcMpBUepXAH8WEQmAYjIaBE5sYLjjQHOFpFWEfkIsDOeW2QpcC/wSxEZKl6Ae4qIFHJpDAE2AOtEZCLwjdDry4DtjeevAR1+kLUVuAAvHmGlDJkuBA70A74jRGSIiHwZb9D7v9C+3xGRgSKyC/Bp4M8AIvIpERntu6/W+vum8aygE0TkGBFp8QO2h4nI1gXk7wP+ClyM57q6z3h5CLBaKdUtIvviWRKaFf5nmufO5C5gRxH5hIgkReRjwDTgznyyaETkcBHZzVfI6/HcSeli73PUDqcUHKXyG7wZ5b0i0okXdN6vguM9BUzFc7X8GPiwUmqV/9ppQBvwEp6r5W/Y3TGaC4G98YLV/wb+Hnr9p8AFvrvl676f/QvAVXiz2i5gMYWJLJNSah6eS2cPvAD2UuBk4Bil1IzQ7o8A84EHgF/48RiA9wEvisgGvHP/cT9+sgg4ETgfb9BehKcEi93TNwNHAX9VSvUb278A/MD/Tb+L5/fX32Mj3m8zwz93+4e+5yq8Gf7X8ILd3wSOV0qtLCILwDi8c7gezxX5CJ5LydEgJNud63DUDxE5A/gfpdTBjZbF4XB4OEvB4XA4HAFOKTgcDocjwLmPHA6HwxHgLAWHw+FwBDRVud4wo0aNUpMnT260GA6Hw9FUPPPMMyuVUuE1OUCTK4XJkycza9as4js6HA6HI0BEwivQA5z7yOFwOBwBTik4HA6HI8ApBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA0HU++sYrnFq4pvqPD4SiZpl6n4Ngy+fiVXkfKBRcd12BJHI7ND2cpOBwOhyOg7krB7xA1U0ReEJEXReRCf/t2IvKUiMwXkT+LSFu9ZXM4HI4tnUZYCj3AEUqpPYA9gff5nZx+BvxKKbUDXkerzzZANofD4diiqbtSUB4b/Ket/p8CjsBrywdwHXBSvWVrVv40401+dOdLjRbD4XBsBjQkpuA3Gn8eWI7XPPx1YK3RM3YxMDHPe88SkVkiMmvFihV1kTfuXPivl7jqsTcbLYbD4dgMaIhSUEqllFJ7AlsD+wI7lfDeK5VS05VS00ePtlZ+dWyGvLWqixnzo/SBdzgcldDQlFSl1FoReQg4ABguIknfWtgaWNJI2Rzx4tCLHwZcGqrDUWsakX00WkSG+48HAEcDLwMPAR/2dzsd+Ge9ZXM4HI4tnUa4j8YDD4nIbOBp4D6l1J3A/wFfFZH5wEjg6gbI1nQ0e4/t+cs7uWvO0sj796fSweNX3+nkvpeW1UIsh2OLpe7uI6XUbGAvy/Y38OILjhJIGzohlVa0JKRxwpTBBy6bwcbeFG/85FgSEWTf2JcKHh/z60cB51JyOKqJW9Hc5PQZM+fe/nSBPePJxl5vkF/e2RNp//Wb+nK2Nbu15HDECacUmpyUYSr09KcK7BlPRg1uB2DJ2o2R9u/s7s/Z1tXbfN/b4YgrTik0Of0pUyk0n6XQnvQuwa6e3IF9fXcfk8/7N3+dtSjYtmZjb85+6yzWg8PhKA+nFJqUnv4Ui1ZvpC+dUQTdfc03Y25t8eIImyyyL169CYCrjYV5y9fnupnWbXRKweGoFk4pNCnf/Nts3vPzh+jqybhT+tPN51vXgXGbQhNL3HnZ+u6cbc3oNnM44opTCk3Kw696JT5MH3szBlyTCe8StCkF/XXMr2ULSKeb8Hs7HHHFKYUmRWdv9hrZR/98/m3e8/MHSTeRxaAthU2WYHF/OjdGsmpDrlIw4yq1ZPbitVmBfYdjc8QphSbFNphe+uB8Fq3eRFdvboZOXMnEFHIVgA6cKzIDsS37KFUHS+H5RWv5wGUz+P3D82v+WQ5HI3FKoUlJ+A73jZYZti1oG1dE8geabesubPtZDIqq8846L5Yxe/G62n+Yw9FAnFJoUrSlsNFiFdhcMXFFu2N6LIO9DiCbhoBNCdrcTNVGu+uc98ixudPQKqmO8tGWgk0B2HL+44pekd1niQtYLQXL961loHljb39gJdT6sxyOOOAshSYlYynY3EfNE1PQSsE22NoW4220fLdUDQ2FL938HEf88hHeWuWtuHZKwbG545RCkxIEmi1ulxffXl9vccpGr60opBTMV2yWQqqG7qMHX1kOwDv++gjnPnJs7jil0KRoH7ctpvDdf75YZ2k8+lNpPnj5DB55LXqb1D5/4LeletqsCJtlVEtLQbPBz3pqxrUgDkcpOKXQJOhBM51WKKWs2UeD2loA2G+7EfUXEFi7qY/nFq7l3D8/H/k9fYGlkPua/s6mwrAqhToM1Bv8lePNVprc4SgVpxSagDdXdjHl/Lv49+ylbH/+XXzr73Os6xR0sFZXHi2Xfz6/hLfXbir5fXps7iuhMJ9ummNbcJfJTCp8vHos1gtcWc5QcGzmOKXQBDz+utew/pHXPP/2rU8vsloKenVzJatue/vTfOXW5znwogcjv+eGJxZw5C8fzmQSpdOs29TH/OWdRd+rFZktpqC/R7F1F2bNp9/cP4+P/uGJyLJHpRrn1uFoBlxKahOgZ+0Thg8ItulicbaaQZVkyJRTXO47fgxDp5D2pRQf/v3jzFu+oWhXNK1Iwi6g9d19kZWCaSn86v7XShM+Ir3+eemtRwDD4WggzlJoAvS6g8HtuTq82+KqqUQp2NYLREWXoEilFfOWb4j4ebnuowdeXsbu37+XmW+uBop3lKtHTEHL0Izd7RyOUnBKoQnQVoGtNLZtJfDTC9Yw+bx/s2h1tG5mJpUMems35TbAKUQqrYIAs/nVdPbSCxFLStSjZLhWln3OUnBs5tRdKYjINiLykIi8JCIvishX/O3fF5ElIvK8/3dsvWWLK4KnFfotA5JtgZfuRPb0gtUlf1Y5SiHpB73XWJrdFErhNAdYc7avA8u6WF4xbIFm27mqBC2rsxQcmzuNsBT6ga8ppaYB+wNfFJFp/mu/Ukrt6f/d1QDZYkmikKVQYJAa0tFa8mf1pjKWR9Sc/Da/peZaS6vMQoFZ8/uk04rfPTSft9duotv33ycjKgXbZ9jcapWQiZc4peDYvKm7UlBKLVVKPes/7gReBibWW45mQruPzAFJb7O5jzRDOkrPIzCVjBlUfW1ZJ3OX2N05GaWQaynYFNmm3hSTz/s3f3z0jWDb/OUbuPieV/n8Tc8GlkLC1nqN3I5sKzf0MPm8f3P7c4uDbdVuTdrjYgqOLYSylYKITBGRdv/xYSJytogML/EYk4G9gKf8TV8Skdkico2IbJXnPWeJyCwRmbViRfSVs9Vk+fpuDrroQd5YES2YWim6vLQtX7+QpZCMsNDqV/e9xgX/mBM8Nwc9cw3Ee3/1KMdf+pj1GG0t3mW0xmIp2JSCXgj2mwfmBdu0wuvq6Q8yoPIN7K2J7Mv2jRVdAPz2gUyvg2orBa0ge+vU0MfhaBSVWAq3ASkR2QG4EtgGuDnqm0VksH+Mc5RS64HfA1OAPYGlwC9t71NKXamUmq6Umj569OgKxC+fu+YsZcnaTVz3+IK6fJ6eGdvSIQulkEaJv/7mgXnc+ORC7/j96azso+4ii8Y07a3eZbTOYin09ae54B9z+OusRcE2m7vHVEZakeT7/LBbSdclMvtVR5U9KpmYQvNUoHU4yqESpZBWSvUDHwQuVUp9Axgf5Y0i0oqnEG5SSv0dQCm1TCmVUkqlgT8C+1YgW02p+1zR/0CrpVBg8CulTs+cxevY8YL/8MDLy4JtOrX18fkrC763kKWwvLOHG59cyDf+NjvYZvPLd/lWiWAsWsvTFyJsAS1d563jGGy4y6puKRhrMByOzZlKFq/1icgpwOnACf62opFN8XwhVwMvK6UuMbaPV0ot9Z9+EJhbgWw14bzbZrNyQw8HThkFZNw6tUYPkjZLobtCS0Fzv68MHjMUgFYKr6/sKvjetqRXc8mWfbS6K6MolFLMemsNIwe15eynZ/kihb8vQGtL9lzGXjm18sHbzGoK1im4QLNjM6cSS+HTwAHAj5VSb4rIdsANEd53EHAqcEQo/fTnIjJHRGYDhwPnViBbTbj16UXc//Lyun+uHptMV1FQZ6jAzLUUS2GZ74IZYQzY+u260F6+FNF2P9CsU2FNzIykO154m49c8QR/fWZxzn5ZmUhF5A67j/RAbVpN1VjQ1pfOdWml0ipQON19Kc798/NZTXgcjmanbEtBKfUScLbx/E3gZxHe9xhgG11cCmoe9CBp+t2jTISL7WPOhPVqZDPjR4+rxWbd2ptjcx+tNrYtXuO5eQr1exCk6OclQ4FmrRjNMuKVWgr3vvgOA9vst0dfKk1LooX7XlrG7c8tobc/ze8+uXdFn+dwxIWylYKIvInFva6U2r4iiRw5BNVCDaUQpbFMsRm36QrRfY7NOkP6/fYGOClueWohB+0wKphF21JSzW3aotjQnbufRqS4iyZssejzYxYH7C/i++/pT/Hoays5aucxVjfgWTc8k/e9vak0Ha0tgRxu7YJjc6KSmMJ043EH8BGgMYX8a8zKDT0M9F0oUP9Asx6Us5VCcSmKKQVzMNODqOmf1+/Xu5mH+91Dr/NbP6V05/FD836G6VJqb/XOYaEe0qm0Klq2Itli93r2ZFlShY/xpZuf476XlnHfuYcwdeyQgvuG0aXBtcVSjzIbDke9qMR9tCq06dci8gzw3cpEih/Tf3Q/O4wZHDzXvvo6xZnLVgqFxkWlVJY7Ss+yTReMfrv2z5uHW2MEkAuVlDCP1+4P5ht6srvFtSUTgSy2Jjphoqy/KDZQP+rXVyq0ziMf2pJJOkvBsRlSifvIdKIm8CyHzbYU93xL1U+xhkaqT5CN019aIDXfbHnhqo0ccvFD/PRDuwXb9OBtWgpa+enYgxm4HjesI3hcaAA2B3kdKO8KtRBtN5RCZ3dfsEI6H8VeN2XOR6He0MUUbl+/97qOvxRzVTkczUQlg7i5uKwfWAB8tCJpHFb0GGUunErlGYhaEplAbb6x7YXFawG41FhRrAPNZkzh7bXdjBzUbh0kTXfayg09eWU3lYzuuxA+XnuyhU68z1/f3c+A1hYKUQ1LQctg28/W99pE14fScZj+CPEdh6NZqMR9dHg1BXHkJ20JNJuDWUIyCqAjmQgWginl9XPuS6ms2bVOPzV982t937+pFE67ZiZtLQm++b535chkWi1aodgo1iAHMgHoqO8JZx/ZiBKIB7tFUcyF1duvy2hn/3c4NgdKVgoi8iml1I0i8lXb6+aCtM0V7XGIElO4/6VlbD96ENuPHlx85zykrCmpmYGoLZkIyjq0t7YESiGt4Cd3vcwf//smr//kWOYuWUdnd3/Qp6CjNTO46sVj4fIQval0MKs2h76ofvQoMYL21tKWy0SpnhrVzW+zgrp6ilkK2RVTnaXg2Jwox1IY5P8vLWWjSSllAZiN/7l+FkDRtpSFyCxes1sKrS0ZpdBhzLqVUtz0lFfXqLO7jxN/NwOAHcd6CspUAIUCrrb4RdRqobYBNjw7b08WdhdpWluEvpTKm31kEnWgtimFfJZKW0uC3lQ6owx0f2mnExybESUrBaXUH/z/F1ZfnPhRKOhYbL5aqULRpG2BZsNl0Z5M0KkfG/74tIKO1hY29qaConGQSQmNWh8oE2j2Zscbe1KRq4XaLIWwAgq7j/KRTCToS6VojRBTiNqS1Kbw8hXTa096SsGVvHBszlRSOvvnIjJURFpF5AERWSEin6qmcHHA5i9WEVcqVGvQyCxeMzN5Msc2awGZA2xaqSBo+/SCNcF2nf0TVSmYX+N7d7zIHj+4t6iLRRNOP4Xc4G5kpeC7jaK4j6JmBNmUfr4eFdrN1RuyFOIWUXj0tRVByq3DUSqV1D56r1/y+ni8zKMdgG9UQ6g40VfAN1AsprCxwCKtUsisLM5sMxWOGUTuyLIUVDCQvfZOZ7B9gx8YjtqdzJxN6yqqs95aY903nC4aRXl0FMk20mjlZ7qP2vK4kiJbCtaubXmUgu/minsXttOumclp18xstBiOJqUSpaBdT8cBf1VKReuy3mTYZpzFxptnF67hhEsfY2YZPZJtFBvgzIHRDB4rRWApmGmj/RZ3VMHPNwbOYQO8Qrjv+OWqwwxqyx7gowSaB7VHUwo6FdV0H+WzMkxrpKunP2/arFUpFHAfAcxdso6P/uEJOv1yHdVyE67p6uWDl89g0eqNZR+jWrI4tlwqUQp3isgrwD7AAyIyGtjsykXaVusWu+3+M2cpc5as4/6XlhXZMxrFFlNlu4+yLQU9C1+1IbdYXeTPNwaaoM6RpSIqwKD20nMXJg4fEGk/rRRajJTUfJlL5jk75tePMv1H91v3syncfG41bQVd+uB8Zr65Oq+1VC53zn6b5xau5YpHXi/7GKa7zikIRzmUrRSUUucBBwLTlVJ9QBdwYrUEiwu2uIAecPL1U9D+/nJKKNgoVtEi231kxhTslkLJn28IEPjR88g0uAylsPVWAyPtp91GZpw5X+aSqRR0dVYbtsVreS2FkJsraiwkKvq7VHLdmDGwKFaawxGmnHUKH7JsM5/+vRKB4obNfVTMl6zr+q8vUA20FEpxH5mD5Nf/+gJ7bjMcqEwp9GcphcLffUBbNFeQyTYj8lsKOg0UMgFms7x3voE5aulsu/soX0wh+7N0sb/wzzN3yTp2mTC05CZM2uqppGuc+X16+9MMai/7UI4tlHLWKZxQ4DXF5qYULIFmrRTy3fI6S2hDgZW+pVBsgMtnKQA8v2gt4JWPKJesaqpFex2UXg9q6pj8S16SLYKe8Lb6biNzQXN49q6JqhTSSrGpN5WlzPLN1MNKYaXvkjPPzwuL1nLi72bwjWPexRcP3yGSDBqt3CuxFMwJRKEkCYcjH+WsU/h0LQSJK7aU1GIB2g1+1lHYv1vqzPGuOUuZNn5oUUvBHNDyNYapBHPQK5ZN1GJRCmYVVBtbbzWA0w6YxOD2JJc/nO1PN4+XSUXNbMtXHK+Q8jJ97W+t2sjO372bn35oN07Zd1sgvyUYdlVp68t0Mep033tefKdkpdAfpB6XP5ib37saLUkdWx6VrFMYKyJXi8h//OfTROSz1RMtHtjcR8WUwqY+b2AwawKVc6N/4aZnOfKSR4qumDVnsFEzeUrBlL2riJ/aphSKFbgTEX5w4q7sM2mrnNfMILq2QrJjCvndR/OXd7J4TW4mjzlWLvD7T//juSXBtnxKIWyF6QZC5v5a35QT2NfXVT4X3RdvepbPXPu09TWlFI+/vtIa/3E4SqGSSNm1wD3ABP/5a8A5FcoTO2yBZj1I5pvB69LKnUZMIWrQL5VWrDL8/6m0Klom23TZ1MZSiD64mJlBehY/MGKcIWFRKOZ3aw0CzYalkGedQldvP0dd8iifuuqprO0rOnuyZtBaXtOPn2/RYTIh2Lxj5vnRx0kkvHLrZ9/yHOs29vH5G58p2stZf24+g/Lfc5by4Cv2HuF/f3YJn/jjU/x11qJgm2v+4yiHSpTCKKXUX4A0gFKqH2jKdIcn31jFvS++Y33NNmvTN2++mKt+vdNwtURdAfy7h+azz4/uZ3lnZgAppRNZtTNiINNpLArJhARrFYZ2eGsaoioFWzwiy1JoybUUbIoEMhlHC1ZlLIXl67t594/v55L7Xgu2aavOrHeklXqYhEiWPJn9M+dHZy61iHDm9bO444W3ueyhefxn7jtcfM+r1uNqtKVQTp+ON32LZ6GxxiFqpViHw6SSEaRLREbip+2LyP5AUy5g+/iVT+btyWsbkINCaPksBV8pmC9HKSENMNuvYDpj/krj8wrf3MkIi7nClBLeKGXlbkKE+792KM9ccBSDfVdWVOulxSKUWdJC+/TN2Ey+wLYtyK9jPOY6AB3/MS25vN9X7DEM07IILAWRYKDW7rNiZU8CpVDkt3n1nU4mn/dvnluYWSehr1PTinIlvR3lUIlS+CpwBzBFRGYA1wNfLvYmEdlGRB4SkZdE5EUR+Yq/fYSI3Cci8/z/uQ7mOvLi29mrVk36Aksh+6bTg4DNlxs1zXDsUC+HcHVX5nOL+YbNgSp6xdHoP30pNZySCWH8sAGMHNweLGQbO7SD1hZhu1GDGDW4Le97bbN+M0ahffrmwJfIM4Laai7ZlLi24FYb7UXzKYWEiFXpmvvrEhlZ38WXsZjFle88L1vfnWVp/neeV9fon8+/HWyzTRziFmhesnZTVv0uRzypZPHas8CheAvYPgfsopSaHeGt/cDXlFLTgP2BL4rINOA84AGl1FTgAf95XTEH7h/86yVmvrmaJ9/ILVWhB4H/zM24nJ54fRWH/+Jh/vbMYuugctecd/j37KVFZdCDtSlLsdRCXXoCorWqhPy+eBtRymHosdkcxLVSGDmojbkXHsODXzuUySMH2d6e81792LYGwxxv830Nm6VgmznrwXZjb4rH5q3kpqfeyjvDFuxKN60yA7DpPgoT1VIIs99PHuB0o5aRPq9mhzibRRun2kw9/SkOuuhBvvm3KEOEo5GUrBRE5FMicip4cQSl1ItKqbnAx0XkE8Xer5Ra6isUlFKdwMvARLzV0Nf5u10HnFSqbJVizhaHdHg33jpLOQc9aJjtMXUM4Hv/nGu9+a945HW+ePOzeT978nn/5pt/eyFwh2Td8EUsBVMpRCWq8oBomVN6DUGWUvBjCW3JBO3JFkQkbwwAsmf9+jjmOoTAUrAojzDW6qyW82ju96mrn+Lbt8/l9RXZ/bi1WAmRnAwkjR6AtTI3dYKuulpMufZaLFC9ANIsqaFjNF1GwUVtBZmutafeXM3k8/4drFVpJFpJu+qt8accS+HLwO2W7X8HvlbKgURkMrAX8BQwVimlp9LvAGPzvOcsEZklIrNWrKjuBWaa6Ho2ZgZ8NWbMoLc/zezFaxnqD8xdvamig/iarl4WrspNlfzLrMVB0Nic6RaLKQw1lEJUN1VrhPLTpRxTD85Ji6VguqoKrW3LyjTyHw9ozbUURGCncUP4yD5bB9lD4e9jc/vp3som5m8+xJc3PIgGqbCJ3IquegzWA3omLpCRRyueYpZC0DfauH50cTyz0KA+9oaefr59+xy+9fc5wUTFVEY6ecKMTzUKnZ5dLD3Z0XjKUQqtSqkN4Y1KqS4g8pRVRAYDtwHn+CW4zWMp8tSdU0pdqZSarpSaPnr06NIkL4KZg6/dz+s32dwQmSYrn73uaT5w2QxWrO/Jed1GT3+Kw37xMIdc/BDg3djmYirdq8HMXOor4hs2LYVCAW1beqeNsGspiqWQGTgzn6HrILUm88cAzKfZC9U8GcxBRPvzBeHucw7h4o/sgdYFYZltloLte5h1jnbbepjlm5k9oSVHKQzyg+g6XqAHdvMa0EHsYpaCfq+pPPT1N6Qj8xvr4yjgpqcWcsvMhUGmkRk20d83X9ylnmilELVMuqNxlKMUBohIjmNYRIYA+aOI2fu24imEm5RSuizGMhEZ778+HrAnZNeQjcZAogdXW2As07A9zX/nebOwFcbagkIzwg3d/YFLav7yTnb93j38ddbi4HXdUc2cwRazFEylMKFAxVHzhiwUUwg3senuS+WUxA7T0pJrKeiso3bjs8LunnxBY30cc7W2lt9scqSVUGvIHWbTo7ZB2ZY5FMZcNBd2H+nFgvqa0GtKTKUQWAoRlUKfRSbzN9HHMX+mzGro3EZM5ZQeqTbacnNKIf6UoxSuBv4mIpP0Bt8NdKv/WkHEs32vBl5WSl1ivHQHcLr/+HTgn2XIVhFdvSmO+dWj/PSul9nUq5VC/tpH5sCzdmMmHlHIfWQOQnf7gWqz74K+uU1/cSkxhfdOG8vNZ+5n3c8c0Ap1LwtbEd19qaIlsW2WgsZ8r3Z9tFrWHNhKWnQkcy0F83wEPRYiBM5tg7Lpv8+3wFDLIpItDxiWQigeYH5WVwXuIz05MZW4HvjN8xUOdJv7mUp0eWc3LzQgxrA+sBTsv9Pxl/6Xb/19Tj1FcuShZKWglPoF3oD9qIisEpFVwCPAnUqpiyMc4iDgVOAIEXne/zsWuAg4WkTmAUf5z+tCixHcfXVZJ3949I3ghrINJDb30JqNfQVfD14zFka9scJLYR01OFPKUgcMN2S5jzLHs3kChg1o5Y4vHcRtnz8QEeHdk0dYP9ucdetB1Aw46zEm7J/v7ktblYItWyiZNVClsz4LMrNb25qDLKVgCVzrWaZpOdmylPJNjIsNynktBWMldXimO7A9ew2CbbbfVcR9lE4rb6W1xcooZCmYlpXNUtD7mROM826bw4m/m1F0dXW10d+pL6X4/I3P8EYomD93yXpumbmw6p+rlGL5+s2uzUtNKasmglLqCuAK32Wks4iivvcx8hcYPbIceSqlrSXBpnQqeyBO6ZlX7kBhm7lnWQoFYgBmsPNtv3uZmeGUsRSys49E8vcwGDagNcttFPYhtycT9PSnGdia+bn1QN3ekilW19ri7ZdMhCyF/pS1plJLQoJBUL/HNlCZA5p+vaM1wYae7MHcZilklcn2Z5lmjEW/biq3ZIu9AF8x900+S6E1kZElvE5BxzyiWAr5Jgu/eWAev3lgHkfsNMZ7r7GfthTM8iH62KYVq92O5jZtNZjXks6smr98A+OGdVjlqQV6sjNnyTrmLFnH0nXd/OOLB9X8c391/zx++8A8Zp5/JGOG1u/7NjMV1URQSnWWohDiih5slq0zS0vk3nga24zTtBQK0WtYClq5rDeUgr65zc/oT6tg8LFp03AZifBMeZAl4KsHUXPA1gO0uR94ysi2KtnMxU9aYgp6gDQHe20ZaEvBnHknsyyFTMaPRiuylNV9lPs9whQtZGgoBfN4ZhmRsMLXCxa1BagHP/P307GqfJaIdiPqqqtZ7iNfJlOe3mDWbV4j/vVqfIbNBaqvI1sgvpboa0HHpvRCtrvn2svLVIvbnvHidfX+vs1M9QvlNCF6EHnbVAqWmZfGNuMzLYVCmIOFPs7aTZn3Bi6E0OfaUvku/+Te3HzmfjklucPPtdLIKlbXkuue0cHa1kTuZWEGmvVbkhb3UYsxeH1gD69W4v7bjzT28/5rRZwvzqEVgK2khelO0zGMbEvBbogWcx9tNAZUU7EkDUtBy3X2EV5Z7PfvOj7r2P2B+ygzsOsByXTj2OTSVo+5RiWz7iHznWyDvf4Mc5tNebQ3WCloK29FZw8X/ecV/vfGZ5j5Zu4C0WpRSXOpLRWnFMj46U0/a28oxdBk2frcC21tREsh21/sPTbdR7a0RMjMqM3BYdywDg6cMqroZ+pgqDmI60F0pVHiuVDQ1owp6NdNBRAsXjPkO3CHUSy46DimjB4cbAvcPS1aKZiWQq4rybR6RgzyktvMstQtkitzvqBz1OwfsCsZEThkR+98H7LjaBZcdBzH7uYphSD5wD+GLYDdm0pbs9nCcq3v7g+26WvEjKPo68U8lr7+rJatsU1ngkUt0FgttAVlfo/X/ZhaLWXpKXAfO+xUVGdZRA4EJpvHUUpdX6FMdUdbBSs6M4N9qf0P8jWyD2PeoNpfbCoUm08a7FkbhVINj542lvteWgZkgqHmgD3csgq6NY/7yPv87HTWnv501vESlkCzjXC8w/xeNpeNub/u5Wz2SNCKyZzZt+aRoZQaTllKIYiXwIl7TmTf7UYwftiArP30jN42+Jgup66eVE6pDNuMfnVXL+OGdQTXiOl6WuNbpWamUWZbrtLpybIU/MWRdbcUvP/m6ekzYlm1xhUHjE4lTXZuAH4BHAy82/+bXiW56oq+ac21BqUW7oo6E7Hlxa+3WArhi7jDElMotCjp0lP2Ch7rhU8tFkvBJIgzWNxHNivDln5arHyGfo8+52aKZ5Yry3DZfO3oHZk8ciCTRw1EhKyOZi15As02/masBymGebzWwFLw/muFABm33hl/eppl67uLXgf2mkzZq6Eh4/bIKAVTAeRaCmv8Aoo2pdDbn2buknVZ+3dWqVVsVGw9QcK9t2uJra2uw04llsJ0YJpSRTrANAH6RjZrH22K2BSnVGyWgrmSWl+84bhFxn2U2VboZjKzZIb6dZzMsV4f58tH7MClD873jmcJ2mpMy0nP7ExFoR8VVQr+jpNGDGT+8g2csMeE4DWbC0gEvnzkVL585FQA3vzpcVnHa7G4vPKV8HjDDwpHISumYMgSxrR0Hnl1RdGGSLc+vZAJwwdw8t5bc8E/5nL+sTsF14St7Wm3xVLQ16mpKPQAa7Nwl63v5vhLH+PEPScEn9HTn+KWmQtpa0lw8j5bF5S5uy+FSPQKvDbSFmVpU4a1wlkK0alEKcwFxgHFS3/GHNssoljbyXIxb4Cevlx/px4XwlkuepDyGrDoNND8SsGMPWhLwZZKa1obgfvIMtM2ByXtXrIVsCvmCtAz+0kjBzH3wmOyAtimpaDdHLZqo1nHs7itquGOyFpbkcj9vpoBIfmLWQq6B3V7MsFtzy4mIRhKIfPeniCmkNvvYaXv5rS6iiwDrHYVPfjycnYcNwTwrgW9WMymFLr7Ulz/xAI+fdB27PSduxkzpJ2Z3z6q4HcrhO286O8dtSthJRSrCuDIUMndMwp4SUTuEZE79F+1BKsn9exla8sOMcnXLcs2A49a02bogKR/7Mz3/Mj0bdhqYCsf2ntisE3PsE33ywF+5pD5+VpBZa0/sGQB2dDvaW0RBrcn8zbMaS/gojLRSsOWuVQJ7Zbva5PEzApLtkjexkthdOB+fXefsfAsHVgj+jrRFqtZ06rTkmmksQ2+2uro7OkPZufF3Ck3PvkWP7nrFa57fAEAyzsry+KxyaVlMbOtaoVrTRqdSiyF71dLiEailKrrBVOs4mi+AHcw2JruI4vv38aIgV7WTn9a0Zb0FnZtN3IQz333vVn7BaucjQH2tAMm8cQbq/jU/pOCpi5B9pGZkmpJU7Wh1zvYBm5TQZgVUQuRsMzi87nV9HePQpYS1ArKIkw4eyrqBEOXZjd9+739KQa1JdnQ0x/4/00XUZio38VMhdXXn7leZvbitey+9fCs92il9dLbWbUqy8bmVtObamWVm8Spt0TcKVspKKUeqaYgjaLWEZFkQrKUTjGlsN5S8hnsM/CWiAE6ncrZn05z91few9+eWczwgbnZR7pm/wNGc/h9Jm3F/B+/P8t60LK0WNxHxdAz8GKzeVuXNRtJi1KwrbOA0nzX9kBz7n7todTVfJbC4PZkVsaPPl+mUuhLKYZ0ePtpZRC1jWshzM/VmW7rjLUx85ZtyFEK2gLqqtIs3mYp6HO1qYaWQkKymyA5ilOynS0ij/n/O0VkvfHXKSLVmVbUkSiXStQBz0Z41losgG0r1Q2Z/HLzaMX87d96/0588fApwYKl/pRi+9GD+eb7dspZ4GZijmsikpPNY7MU9KBcTMlqBTmgrfClZ+uyZsMWU6hGNkurNdCce1xzmyow+ITLhOjZu7lwsS+VDhYaZiyFVM6K9Sh85qDtrNv19fegofhtbsygEmuVKqzaAs16S75FfdVAy+8CzdEppyDewf7/IUqpocbfEKXU0OqLWDu+9pcXuOaxN4vuZxt8ozapCbt4is381uRZGW2zFIoNfp87dArfOGanYDYbdbZkprPaBoVM7MGiFIocWwf8ilkKZu+EQujPNQfnUrrK5cO+ornwe/rTafKNPYNCZUL0AjRzIV5/WgXuNZ2EsLqrl10mlH5bTRo50Lpdz/yz1gsYSmFFZw+ru3qDtQ1hS+1jf3giUlvZMIXcR7WMKejrwqWkRmeLXtF827OL+fFdLxfdz5bKGTU9LzyoFlMK+fLHbX7tqF2sgpLTEZWCuQLZrhDzu4+KWQq9/qhZVCn47iNVRM1oxWTuFy5al49CPSXM/gz6exZTUN+/48WsFq0mOoagWeZX7gxn3miL4qf/eZln3lrD8s4e9pk0ouDn2shnXRTrM/HuH9/P3j+8L9hmWmB9qTRPvbm6YFvZfNgshcB9VKGLLJVW1uNDRpGHu9n99K6X875nS2eLVgpRMWf72l8ddeAJB16jtssMo2eQps86asMSvV9Un7o5gInxNW/7/AF8dPrWwazXzAzSj4sN4npWWmhA9l73XV5FblxbzKEtosK2WXv6dzUbAyWKWArfev9OgFcy5Mk3Vlu/m9k5DeDttZusx+oIqq4qTv7944AX1ymVUtw+hUpjmL/xxgrcPIUshULB9ChMOf8uTv/TzKxtj7y2gvnLO4Prw7SGvnLrc/zh0Td4aWnTebvrglMKETDvLz0zjeqiKDWmkI+t/MCweQNHvfFHDfYCzflcU2GGGgOYaQ3sM2kEP//wHlY/vv6axSZfn9hvWwAOnlq4ZpNeC1FsNmc7BzaFbTtVtpXPet1BtmvM+58vDHPinhOznrdbSpLotGBNPqVgy97acexgy56FiZIFNaDAZCFo5GP2mvbdPMUUug1b8o9e92pOlMpdC6s7IGpOv2YmR13yaKAUzMmFji+4NFU7FSkFEZkkIkf5jwfo/grNQCnZCNnNX7zH0S2F0mIK+dhqYKROp1bG+WUZ8i0SuuXM/bnlzP2D56alYHNR6XHCnKUfsfNYAPYMZbGE2XvbrVhw0XEF24ZCZuApduMGv42xm01h29xVmcV6RjzCUnNJf0a+4HxY8dvO2ZD2bEshX3C1JXS9tCcTQc0nk2IDczGLDTxXVWuLFAw0m6d/nZ+5VE4g35aVlakoa1YOrnygNhWL/snMxWva+nEZSXbKTkkVkTOBs4ARwBRga+AKGtQop1RKceOYN2rQnKaIi0Kvbg3PZMs1lcM+6VIY7Oec7zrRHrA8YIq3QO2WM/fn2YVrrG4hk8BSMAaHY3YZy8l7T7T2XSgH/fsUO89W95FRhkMPPG1+o6Hs/STYvy+l+xbkZhplgtl2GcIpsOYq50FtLXT1pnJ+v748gc/wWD9l9GCrNTS4I5lVliXM8btP4Nm31tKWTHDDk29Z9xnQ1sLG3lSgAMyBM1MlOLNNp0uX0/PZNgDbij/2p9O0lTBXtR13vRGX07JmWdi++PUor9GMVHIHfxHYF3gKQCk1T0TGVEWqOlDKjN28UfVAaHMRZL/HUwrhG6hcSyGRyAxM5VjYD339sGC9Qj4OmDIyUBAFZdGriI3BMCFSNYUAsMof8EYWkVlbBeZNr624jtaWIEffNrPW7qPWZAJ6U1nvtfWOzrdmIjxzNov8DfCVwtBQVdp87p2wApiax3U0flhHQaUwsK2Fn314dy5/eH7efQa0ttCWTAQzddN6eWaht2bFtNRe8X3w5WR3FVrRbFoHff0KSjCKbfeT2dtEK3mb27UeK6mbkUrcRz1KqeDsi0iSaGn/saAUSyFrtWzEQLNWBrmWQvbnRvXPJkS46X/246GvHRZp/zDbjRrEMEu57HLIZGBlZK9ONru3ghoyN/GYoe2Fdg9iLeYAmbHmchfcmbQalkJ4P3P8179/vgly2DXVYVoKvpU2ONTjOl/zl7Di2WG0XSlsvVV+95tIxtIpdH0NH9hGm9G6tLMns3DytXe8hormYP7IayuA7J7iUbG5j/RvnNV4qsTUUdvAbvYn0fehed9lmhnVfiV1M1LJ1O4RETkfGCAiRwNfAP5VHbFqT7lKIcjRL1JiQgfoclJSQxfi0AHJrEY3+WWAg3Yo3lCnWvzuE3vn9R3r72ZmP0Wtw1SMCz+wCxd+YBdWd/UypD0ZNLHJh461rLHMDos13tGuqWIlLQL3UR7VF85iGmIoAO02GtDm+e/1rHjpOnsz+fB53Da03mCvbYfz3MK1WXGGcPkOMzhcaFY/fdJWvL12U/BeW48F01LQE/rRQ0pXCtaCeJYqqaXWITMzopat7+ampxZykGHtpizBbH1PbupN8ezCNbz2Ticf33fbkj53c6YSpfB/wP8Ac4DPAXcBVxV7k4hcAxwPLFdK7epv+z5wJrDC3+18pdRdFchWlHJ9+0HzF+NeM292TYtlgddA34drMnJQe0SlkDnOC999b9ESzZVy3O75B+NEoBQSOdsqRc9wRw5u51vH7lx0/7F+M/aJwwfwij+7zVRxzexnSz/Vvn9bsb/sQLP3P18Ji3AA2rQK9ORhcHuSViN2kY+wNTIu1Gz+L587gLfXbuK2Z5cE24YPaGV5Z0+gHMw4UCFLYfLIQbQlE7y+sosnXl+Vda3q60s3agKzblLp947t3OlN2YHm0o5tuo++cutzPPnG6qw1GtpqsN3v3f0pPnS5l/brlEKGstxHItICvKyU+qNS6iNKqQ/7j6OMVNcC77Ns/5VSak//r6YKAXKzWgqld5oKwFprx3LjtVj87kM7WukM1TYaOTiaA9Ucd4YNbC0aH6gl+iuZKZ1S1pVUOaOHtHPjZ/fjko/tGWxrswSLbb+RzhIq6j7S2SoFLu+9th0ePB5sBJW1i2TU4PZIGWRh5TpumKcUPrjXRLYdMZDWlgSTRg7K6i6nj6sHQ1tDJBsD2loY2NbCC4vWcsofn8xqAGSbsdvcPVEplOlTiVIw91+02kvzNSdeWhmYloKtkdVm0BamapR1KyulUsCrIlKyelVKPQqsLudzq0m4RHXB3gQUHlysSsESUxg7tD0rMwKi+2erNROvBmZ7Sk0j5Tt46qiseImtNpMtBqTdX+ZrrTZLQYqvmbjpf/YLHps9Inr8wWjEoLZoE4DQaZzop+7+6mN78ug3Dw+2mwp5mB9XGdia23bVphT0MaeOHZyVHNBpuI9sqcA9FVgKhcZ6c3DuT6uSjp/V6tSPL9jiNd3GMbX1YGZbVbqAbnOikvndVsCLIvJAlfopfElEZovINSKSdwmniJwlIrNEZNaKFSvy7VaUsLsnMxjk7mtbvGaLM5jYGs+PCbkCwG4p2GSoVmGyahDMpo0RLA7iTfBn1bbf0mop2NxHRvaRjgfoc18orX1gWzIIercbsZZdJg4DPKUQZQJgXlffPnbnvK1FzWtuvP+9g0G9yPc+Zd9tePrbR7HTuKFZrq7Zi9YWlC2wFCIM2nfOfpul6zIL9Ar1mTCPd+vMRex4wX9YtHpj3v1NTAtEZ32ttPR+0JZCfyoduBlNhbLzd+/mb89Eb9e6OVOJUvgOXmzgB8Avjb9y+D3eWoc98Tq55T2OUupKpdR0pdT00aNHl/lxueZxMogB2FbDGgogketesPYXsCx4sqVX2gYKe6+B3O/QKNosaZtxsGTu+sp7+PfZBwcDZsIyYzZdRQP8mIhNKYgID339MO4555DMqtgiro1tRnjBX9Py+NnJu3H7Fw5k9JB2timQMaRJCJxx4GT23nY4Zx6yfd79zGtkz22GA5kB0rRorM2ZEhIEi03/+1VFikMGMQXjPMxdso4p59+VtUK7pz/Fl25+jk9e9RQAb6zYwO3PLSEfpgvoz08vBGBhRKVg3sf6u9gshaCFaVbnw+z4ztf/+gILSmjZurkSi34KSqkgmiUifwTurNax8xGumqhdItZy1BZLwZw1mj2L9Y1pq6wZTksEu6JobcldaBWHQVdjW+AVB4YPbGP4wLZglmnOToMGQslEMKhZYwpGP+ZRg9sZNbidmW+uAmBFkYQA7dtva0lwxaf2ZurYIQxsS7LXtp7he+AOo7juCftCMk1ChO9/YJei39UMCn90+jYkRFi/qY9f3vda1gy4vUC8C6LXzwK7pXDr0wtJpRX3v7yM0w6YDGTWO7zjZ1j9o4BCgGwl0xVaL1IM01IY6BcTXLY+Vyk889YaNvb2ZykCM3XVJku9+cldL3PUzmPZd7sRDZMBKrAUQv0UukUkVW4/BRExU10+iNf/uaaELYXM7DJ3X3NAfm2ZZ3o++lrGdZW05LvbOoLpomhmUHKQRVHYXEVxUgqZqqul12GqB3qhmOki1JlS5mCjB8Tsjm+5rjGd/rl4TeHZq65w2t6a4H27js+qNgtw1M5j8/Y50ERVtNn9HoTTD5wcNE5KFbEUzN+qlFIPZvbRg68sY+abq4Pr16zuq9t/Fur5bdJncUdFLXdhrmvQSv5t322l70ftBtzQ3Z816NuUQiO58tE3+Ogfnmi0GOUrBbOfAjAAOBm4vNj7ROQW4AngXSKyWEQ+C/xcROaIyGzgcODccuWKSo6lYHE5BDIbj4+z5M3ri89abtl484hB3k07PCsomvt5tm0xGnMzdYlSuTPxOKDrDJm/sV6TYFMKJrZBdN/tRrDdqEGcfeTUgp+rg7b50kBbEsJ3T5hWMCMo6u9sXiP6mm0LlLVdKWhL1aYEo2Aqhc9cO4uP/uEJBvvfucsIUmsF0dqS4OWl65m5wMsrue3zBwb7mPeFTQF05ylBHiYVClJDJtVVTw50gccuo6QHZJTCZw/OKOpGte2MUxnvqtQl8FNR/yEi3wPOK7LvKZbNV1dDjlIIZ1cE9WuKWArH7T4hxwVguo80ZmmE+849hPXd/cxf7lkZ5ie3JBLcetb+tLYkglLJZuaSnsnFyVWjB5q4drPSmUjeIO25EoKS2IYi0IFmZXEzmdsGtSd56OuHRf7cYr9VoYE/qkVoKuGWkFLIt9+wAa1s6OnHnHOcsu+23Pr0IqaOGcy85RsKfqa+ZXqMgXNge65SyJQWEd7/m/8CsMuEoUFAHPT6HO+3sblswv7+fJj3cfYkRYIYw2BDRlMJrvWVghnXy9cjvdbEqWJrJQXxPmQ8TQDTAfsyzRiS6z7SboMMuqCaeZ/aJoHaysi6UY1A89SxXvFYPRjst91IHn51RXC8/bcfGVqan3F16JzrOFkK+nv2p9Nc9om9Ijf7qRfbjBjA147ekeP3mMDhv3gYyFhx5qCg5TbvRz2wFsqWyccn9tuW9Zv6OHLnwiXACg38UX/nrLpTCe2+LGz5jB/WwZK1m7LcR3tsM5w3f3oszy9aywf9hVzFMGfTWsH0GSdxvX8tm5bzhOEDslylxToXdvelue2ZxUwYPqBgPS7T/WXK1ZFsCVyG2n3kKa6MDPOXeUpw6piMm6+nQampcarYWomlcILxuB9YAJxYkTR1JGwmZjp9ZWhtSdCfToVmfsIZB05mx7FDOP/2Od5+Ce07zexnCzTvte1WPPKNwxg+sI2f3f0KkKnAaloZ+jjZSiE+WiFjKaQ5fvcJDZYmFxHhyyFXj3bpmBVM9QzSFpAux4swZfRgLv7IHkX3K/RbRrUIbW4fWyVd05U1YfgAeGtNTuVbEbFWo7WtwIfsgoxdltcfm+/1Nhg7tIO3VnlxmHFDO7JWwBeLQW3qS/Gtv3v314KLjsu7n+kizAqwtyaC76TdSBt7U1nZhZ2+5bCHn70FmT4S9SZO7UIrUQpXKaVmmBtE5CBgeZ79Y0VYMwc3WVZWkbCpL5x6SZAdEiiFZK6lEFQ1DX3upJGDskxtW+G8pJEpk/ncOCqF+MxuiqFlNnsl68BwltshWJNQu+9W6KeM+jPbqvSOG5a7DsZUHvr7FjueVgYD25JFi8bZCtItXuMFes1J0qjB7da+1/nIV5vsrOtnsee2w/nCYTsA2fexmTLc1pIILHitLC99cB5vr812Zuw8fmgQoIcGuo9idC9VEh28NOK2WNKXoxR8/7KxTbd1tFXMNLFlWSQN91EY23oGeyOfzE0cI50QlCYuVtY6TugByszL14Fmc2BJWmIK1cbWuU4TVfnbguQ2pWArCmgbgEzloQOzhZSIRqefmqdr3Sbv+ljZmUnhHTm4LeteiGIp2Lj3pWX8/O5XAVjR2ZP1XUxLoTelgliLVgrPLlzLO+uzlcJuE4dlnSMXUyjDUhCRA4ADgdEi8lXjpaFAvJzLBQgvRLKZ422WjCQJWQ1plfHvtkac2WeX4s4dIJKG+0gTp5RPnWUTpfdCXGi1uI+00jVN98AKquFNGvSjaJGcwSDqz9xhcfcMaU/y4X22ZvvRg4JtprWpz4Etw0afi2RCgoVe244YGLh/8qGDyuYx1/od2sxFZOG6T/naqOpBWXd5y8c9L77D5254hj22HhZsMxVEKp0pDDioQJ+PXSZkN56KGuCuNnGKKZRjKbQBg/EUyhDjbz3w4eqJVlvCsyVbgFEP8rYuXJDxSbclcwd2fQPa3BDFVj4HgeYaVCGtBh/aayJ/Pmt/PrBH/OIJ+bBZc/r8mgOz9nvbcuerhf75beXXo1sKtlXvwi8+skfgWgG7UrBl++j9WlsS/PRDuzF1zGB2mzgsd79QpkWXTSn4gWbdKOmsQ7bnmF3GZr3P9j1NhV2sn/hCX1m97JesgNz4gj7PhZo/TfRXmd/+BS9dtnGWQhPHFPyVzI+IyLVKqcLLM2NMeIamZ+UqK6aQm5FkXss7jRvKzAWrA7+rrRCZbQaQVUvJMjBkAs1mv4ICX6bOJBLCfts3h5Xw0NcP47VlncEgYvq59W9u5q4HzexrmK8uhqWQ77ViRF2J3NqSYOzQdsYO7Qi+u819pL/36QdO5uR9tubkfbbmN/fPy9lvSEcyGOwhE2jW51AplTPLP2aXsXlrOGV9p2QL4L13rXGMhas28ot7X+XnH9492Bbcv8ZX6UupoIx9Kq0CxVPIDTZykJeOuq1foqSWsaRCxMlSqCTQvFFELgZ2AQJnplLqiIqlqgNh95EtxztTW99ITzVUxG9P2YvLHprHmCEdXoqpcT8Hq34tN2Ax36reZs4G47ROoZnYbtQgths1iGtn6Lo+mfM42s9Pnz55q6BImlbEtVzElLEUyl+kWEp5isf+z7slf//w64D9u7UlE8z78futZbd1n2nwYgNZSiFkKWzsTdGbSmf1GNExChPb9Wxe72aNokMufgggyzINlJChFfpTaYZ0tLK6q5d+oz+6aYEAbD9qEG/4NY5GDfHcWnpy1p9SzFm8jjdWbuDEPSfmyFgr4hRTqCTQfBPwCrAdcCFeSurTVZCpLuQLNOdzHw0NFiZl3jNuWAc/Omm3YNGSebO1F7AUTGyzRW3uxq0KaTNjCyCPGdrB/V89lO8en6k11GaxHqqNrcd1+LVi2NxH+WhtSQR/kN8Kam1JhHpQeI/NK3hsqNKvVgr3v7ycB19ZxqlXe0XwdhqX8dWb/alP3X8SZ+Up9GcqOlv2UZeR6bSxTyuj7ECzDiqn0ir4LgNDSuHK06Zz9enTec/UUYGloJti9afTnHDZY3zl1uetMtaKzSX7aKRS6mqgTyn1iFLqM0BTWAmQ20+hcKAZdvcDWp3duSl4elGOufAlU3Kg8OBisxR0ipx5E8QpptCM5Bvsdxgz2FoltZa+Zf1b2mtcRTuGLdBcDD3I9/VHG4AyNa4U0ydtBeQWdTSv0c9cO4tnF64Fsjv3mSmfPzxpV87P01HPXG1uC/iavUi6Lamy/WkVuMF2nTA0WFhnnqs7vnQQO4wZzJE7j+WGz+6XkwnWqBl7nGIKlSgF7fRbKiLHichewIgqyFQX8gWazY5mmZIHcMlH9+QLh01hb6OYnUbfKGa9lkxmSxFLwTIK6EwNcz2DUwqVMdSfQYabHIXRA2dNLYVE9meZj6O6CcML0KJgLjosZf90WgX9wcOTp64ee7bOrhOGcekpe3HpKXtZF8bZpO8wjm1rerPeWPVvWz+RSiveNW4IXzhsCleeNt2a7m02YzLR92GqzjP27r4UP7zzJZaujU8xiEpiCj8SkWHA1/DWJwylDoXsqkV44ZW+UbYa2BY0VQ+CxUoxYlAb33zfTtZjaZN1k3GhthWIKZjYZou6WYt5wzmdUBnar93Z3YdIdkKBSRB8rmlMIXewakl4Pvha/s4f2GMC/3rhbT53qN19E8YssGdbOwOZlFSTc4/akYOnjipZviz3kWVl8XqjlW2+dQzJRCK4T7WCNedl+ZSC/i1qmYps476XlnH1Y2/y4CvxWfNblqXg92ieqpRap5Saq5Q6XCm1j1LqjirLVzPC7qNJI73c7nOOypRHCNJKi1woej/TytCDS7H1BVal4B/HvOHKmRk6Mmi/9vrufp46/0j+/oUDrfsVyuWvFvqXtBW1q6VFOHxgG3/93wODUuDFMFM537frOAA++u5tsvYJW1R/+dwBfOWowtVk82GeD2tMwbgf8rn3zCQnfcuYccIhlqA3eArEU8z1deO8tcoLeK81UnC7+1K8aqTa1puylILfo9lW7bRpCM8IthrYxoKLjuO9u4wLtpk+1UKM8btYnbJvpmV1Ju+7dKWwna+gzCJ5TidUxtZ+PvrR08YyZkgHe/uNb8JM8PsXv3faOOvr1UAslkKm/0bNPrZkhhjxg6ljh7DgouOs7lOzKYytkZSNsO7zFoJm7jOb+2hTb2ZbvomabQ2QmexRaJKWTAidhjVSy1Xtmk1Bm9DMZ512zUyO+fWjDSvjXYn7aIaIXAb8GQh62Cmlnq1YqjrQn0pnuRFsEzRtzhb7cSaPGsTz3z2a4QPbuOAfXn8grRSK5WfbMlB0L+fJIweywM+vz2f2OqIxfGAbs7//3qD+fz5GDW7nhe+9N2tArBXmtWFbxNhobA2gbPKZcYaoSiGMWSYe7JaCWWcp33oCU77vnbALHckWjp421rpvmGRCWLfJ/AwoMqerGJ2cssH4bjPf9PpPbOjuD7wG9aSSK39P//8PjG2KJslA6k8r2oy2l7YJhE77i5IuNnyg/ccrxVIY3J706t0nhPu/eihbDWxlnx/dDxRelemIhi1fXnP2kVN5eel6oPYKWP/iZpJBog7uo1IZbKm6aqO1JcHQjiTru/utlVoL0dbitUdNiGQN9Db3kKko8t2S5gLSsUM7uORje0aWpSUhWW6cvlSalkRtK/fo2IlNx23o6Wfh6o1MHjmIYQPrNymspEfz4dUUpN70pxRtSbMXsmUxjV7IVEa6mDZvi3UkMweGoR2eUhC8VEnwUug2FalU6aicrx69Y90/096UKfr7p40fyivvrK+2WAFRraXWFm8S8/CrKyLPbPXY3e73zG5JSNHKqWZwOZ9rpxL3W7IlkbWSuh7pqYX6NyxZu4mPX/kkR08byx9Pm15zWTSVNNkZC/wEmKCUer+ITAMO8NcuxJ7+dJr2ZAIdzinoPoqY1519/GhKwbQUhg5o5e113VkB5t23Hl7yZzuaA3PhYjmB5ju/fHDVZTLJF5S95KN7MGP+Km57djHgVRMeM7QjJwgdhfbWBJ093vcOrzwOY8YZ8i0KrSQhI5mQrGB2uOpBLegukPo8w+9LoUuR14tK1ilcC9wD6LXnrwHnVChP3ehLqaziXrabMSiOVsbFoW+oSSMKZ3qYs6Mff3BXdho3JKfhu2PzpM0aU4j+/kRCapqVlm+Q/tDeW/OLj2TqEBVzkRZCp7gmpHjpjiz3Ub5AcwXut2RCsj6jPpZCfi/Ayg2eK6ve7c8r+bhRSqm/AGkApVQ/0DR+jlRaZa1ktV1KA3w/fjk56wfvMIrffWJvvvG+dxXcz7QU9pk0grvPOaTojMmxeWDrlxGnmALAf77yHqtFIiLBpClcOTUKuoSLrlTbkhBG5InLaUz3Ub6U1HxKctTgdg7dcXTB47e0SNbM3RZL7Eulg+KKS9dtsjYZCvP22k15XcCFLAXtMdjUm+KR11bw+RufKZoeXw0qUQpdIjISvzSKiOwPrIvyRhG5RkSWi8hcY9sIEblPROb5/+05g1Wgpz/FwtUbs5WC5VrSi8jKqUvSkvCW+ttWc5rEKdvEUV/M668cS6Ee7Dx+KLtaSmhDZmZvKyYZFX1/tCSEc47ekS8enl01YOzQ9uBxdxSlkOcEzrrgKK77zL4FZUkmElmDd18qnTMIX/ivFznk4odY09XLAT99kNOunlnwmAAHXvQgn7nWXhaukKWg3VfdfWm+cutz/GfuO9z69KKin1cplSiFrwJ3AFNEZAZwPfDliO+9FnhfaNt5wANKqanAA/7zmnD9428xf/mGrIU3tmtJ12wpry5JzO5uR2zQFTqzS6jHL/uoGLrOUDmWgo6nmIX9Brcn+cYxO2Vl2n3n+GnBY3PAztdLuRJXSzIhWSupr/rvG2x//l1Z64UeeNlbebzaz1Ka9daagsfUAfEn3lhlfb2QpaDdV5v6Uozz09Qfea32K58ryT56VkQOBd6FNwK+qpQq3C4p895HRWRyaPOJwGH+4+uAh4H/K1e+QuhyuWYdHNuMXaeZltOLuInubUeDMK8r07feLOj1CQPLWJugu6FlmlFlXusI9YvWmANovqydSpRqS0KyUkOve+ItwHMT6TRlnTa7JGLwt5jrOYqlsLG3n1Vd3vd6Z31P3v2rRdl6VUQ6gLOBH+KVzv6iv61cxiqllvqP3wGsK05E5CwRmSUis1asWFHWB43y6+ibBbZsl5IuohYuvRuF4W6xmSMPB/gNisxeANq33ozuxHLuDx030wFjc42CGXAe0JpROKZlb7qPLjguU3W1EqUQLmOvD2UW39Nj/KI1hduUamwrs00KVePVlkJ3X5oVnZ4yeGHRWn5450s1bcpTifvoerwGO5cCl/mPb6iGUMqzuazfWil1pVJqulJq+ujRhQNH+dA11M3sAtvNuO2IQXxor4nc8aWDSv6MEU3U1N5RXw7fybtuzVmpnnU3k/tI3z6DylAK+j06s8/03ZtKJp/C6elPsc2IAZy6/ySmGX2WKzl/4XLk+ljmgjbtDlq4OppSMN1cvf1prnz09azj9fSlGJlnrAhnPW4/yit/c/Vjb3LBP+ZE+vxyqEQp7KqU+qxS6iH/70w8xVAuy0RkPID/v2bOs0kjBzJ55EDOPSqzYMl2KbUlE1zysT3ZYcyQkj+jGWd8jvrQZpRkD7Y1oftIz+4HlLHaXruc9OzfnPgOMCyF9jzNhHr60+w0big/PGnXrDIblcQUwqux9U+xpquPuUvWsXJDT2DF5Ct1PXvxWlZ3mYN+ZmC/7vEF/OSuV7hlZiZY3N2fDvpEhwknuJy8z9bB41tmLsqKdVSTSpTCs37GEQAish8wq4Lj3QGc7j8+HfhnBccqyKD2JA9/4/Csao7mDOM9ZZT91dx9znu45cz9i+/o2GLRHf1Ml0kzWgpa/HLcR+/3q67qYnpmMseAIN4geYPYvf3pYE2CWT+sknUbr4Qqk2pPwsa+FMdf+hgn//7xwO21qsvu2//AZTM48XePBc+1pdCSEF5d5h3fHMx7+lJBscYw4aKdU8cMZsFFx3H5J/cGvFTXWlBJQZ19gMdFZKH/fFvgVRGZg+cB2j3fG0XkFryg8igRWQx8D7gI+IuIfBZ4C/hoBbKVjHkvXl8kda0QZhtCh8NGYCkY27RSaCKdYFgKpSuF90wdzRs/OZY75yzl+ifeygq6a0tBkILprloXmLGASpSqrTcEwKoNngJ4a9VGdh4/1N/Wm7VPXyodWBaLVmcGax1TaEkIC/ysM3Mw7+5PM2FYPkvB3kdeN+Fas7E35z3VoBKlEE4pjYxSKl/Z7SPLPWalmJeSc/04aom+ubPdR7mKIu7okhBbFVl0lo9EQoJuaylLTKE3lS6Y7qoVgK0vRVny5HnvW6sy8QPdh2WloRT+8dwSzvnz88EM3kRbCsmEBGmsnd19nHfbbB6bv5JUWmX1sDbJ1x1yq0He/mu6YuY+Ukq9BawHhgEj9Z9S6i3/tabCKQJHvcj4wDM3va7gum5jbW70WqBTurctUsqlELbSFgPbM9sKWgoF+lKUw5eP2MG6Xc/sE5JJIzbdR7pr2pwluWt3A0tBJMh27OpNcevTi4KaRh154ibhQHN7nSyFSlJSfwjMBn4L/NL/+0WV5Ko7Tic46oWe2ZqzY10VVy9sawZ0n4KtKijrbFMKZonzQgUltTJoNWMKFdzH//Mee5tSHQNIq8xAbVp5Ol1U/zcxMxz1cbpCbqp8VQ/C1ZnbWrz9hg9s5QN7TGCbCpRxISpxH30UmKKUqo26qjNOJzjqxUE7jOKIncZwwXE789CrjwBw0l4TeWzeSv43Yv/kOHDZJ/aiqydVkZVtmyWb/SwKWQr6Y7OqzdYgfctcz2QrjjnXtxCWW5SCTrXt6u0PMqwWrspOZx2eR6nmcx+1J1v47Sl7RZS+dCpRCnOB4dQwdbSe1Nt9NOO8I1yfhC2UjtYWrjnj3VnbBrcnueLUfRokUXm0J1uK1vYqhs1SMJVCoR4LQfaRoRRqcR+b2UK2Omid/sx/+fpMmuqm3hRvrNwQBOPNRKLOkKWQb8YfrqTQXkGNqVKo5FN+CjwnIveIyB36r1qC1Zt654dPHD4gcBk4HFsq4QVjkK0URIRff2xPa4XTINCcqE6gGeChrx/GN47JrmzcZUzeCpWtMN1HX//bCxz328dy1hKY7UpP3ttbd6B7socJ11yrpPBgKVTyKdcBP8NLJf2l8deUuJiCw1F/bOms4TagJ+01kR3H5k6gdFC5Jct9VJk8240axEl7Tcz7eqGKyauMRWtPveH1WTYXsgFMGJ6pBPTDk3Zh9vffm7dbXSqP+6jWVPIpG5VSv/VXMz+i/6omWd1xWsHhqDe2cjC2xXA2N5W27k1LoRruo9YCboNNfamssh75elJrMVaG1jPsMiFThnxgWzIIqn/T0nclHGgeXEbhwXKoRCn8V0R+KiIHiMje+q9qktWZZiov4HBsLtgCwzaXki0grd9ra2taCcki5sZ+fkFDgMPeNca6jw4w64Vvmn0m2dvEfOGwHfjRSbtmbQtbJcU601WLSlSPDn+bNR0UcEQFx2wYbp2Cw9EYfvPxPbN6KNjWGtgtBV3mwlynULk8xTKYRg+2N/4x0VlKYffRiEFtXHDczllF/DThxXP1aAdqo5J+CodXU5BG41SCw9EYTtwzvw9fM3ZYblV+PYiaE7pq1I4q1nPaTCE996gd6e5L0duf5qk3VwfbdbntcGC6JSF510Pk00X7Th7BAVNG2l+sAZUsXhsrIleLyH/859P8ukVNiTMUHI74stc2w3O22QbRaqxTSFrMjW1GZOoTjTIshWkThnLDZ/dj1JD2rP31LL831C+hUIptPoV285n7ce7RO1pfqwWVGFvXAvcAE/znrwHnVChPw2im6pQOx5aGLchqUwDVuI9tA/f2owYH/aJtqeT5ekqEF7sVUlr5RK/32FSyUhAR/euMUkr9BUgDKKX6gaZdjeV0gsMRX2xBVlscsBoDaCIhweCtlVFLQjhyZ6+sh2k1aAbm6SkRXoBms0KCz80je73HpnJiCjOBvYEuERmJX9XL762QWxGqSTBNQoejXjx1/pF0djdPEbx68dDXD8vy7ZureVtbhL6Usq5JqFaZi9YWIZVWnLDHeB59bSVnHzmVaeOHcvzu461Nt/L1lAi7jwrJZ9MXIvVPgilHKWgJv4rXGGeKiMwARgMfrpZg9cYpBUcjGDu0g7FDK2ltvnmy3ajsVb5mRlIykaAvlbLOrKuVWt6aSNBNmonDBzDjvExC5YFTvAZcV58+nQnDMxbDYe8aw+UPv55znLD7KNwHOus1i1ZohFu7HKUwWkS+6j++HbgLT1H0AEfhVU5tGiYOH8CStZtqUkjL4XBUn2SLQF/2rDuZEPrTqqLS2SZ6lXRLHnePdiVp9t1uBOccNZX+lOKyh+YH23tKsBRstY0aMSyVoxRagMHkZnHWpo5rjfn32QfT2W3vuORwOOJHsGjNGDE7WlvY0NNftZl1poFP9OOdc9SOvPpOZ5ZSyLEUCozytjIWjVg/VY5SWKqU+kHVJWkQwwe2MbzMzlEOh6P+BIvWjKBCezLBhp7qrGg2KXUVcbjsRSnZRzal0AhLoZyUVOdncTgcDcO2klkP3tVY0Qyg/JLXlSqF3HUK+QUstGq7npRzChvWR9nhcGy5nHXI9px/7E5B1pGpFNr92kjVGkR1Imm+Vpn5GNyezFrxHE5JLT2m0ARKQSm1uvheDofDUV3OP3ZnzjpkitFcx3QfebPsaiWM6HabtuJ8hRAR9t42U/QuXOai1JhCswSaa4qILAA68RbC9SulpjdWIofDESfEEgTWM/pqj6HlVCbdeqvcxW2aki2FBmiF2CkFn8OVUisbLYTD4YgfemA100X1jD6cAlouetZeqvsIYPyw/Eqh0DoFu6XQBO4jh8PhaCRaKWStePYH73ylrEtluN8StJxuZ/l6JkDhQHObZYl2s2Qf1RoF3Csiz4jIWeEXReQsEZklIrNWrFjRAPEcDkcj0QNl0mIpdPdVx1IY7Vc9Led47568FT87eTerq6hQ97T2iPWdak0clcLBSqm9gfcDXxSRQ8wXlVJXKqWmK6Wmjx6d28zb4XBs3mTcR5kBc/pkb3Y+blh1ytX88qN7cOr+k9hr2+Elv1dE+Ni7t2WcpXxJIXdUXCyF2MUUlFJL/P/LReR2YF/g0cZK5XA44oK2EEz30WcP3o4Dp4yydjQrh/HDBvDDUHvMUrFZCoVm/ub3EfEyoKQBy8JiZSmIyCARGaIfA+8F5jZWKofDESf0bNtMSRWRqimEalEo/dSGqTAG+aW4W5Mu+2gscLt/cpLAzUqpuxsrksPhiBPB6uWY11YoJ0itGdjm1XKyuZRqTayUglLqDWCPRsvhcDjii1YKPVUKKteK7UcP4pV3Ost676D2JHT20NoApRAr95HD4XAUQy/yqtaahFoxeeSg4jvlYahfQ6kSa6NcnFJwOBxNxYBWnX4a7+6/lQzoQwe0Ft+pRsTKfeRwOBzFOO/YnUgpxft3G9doUQpSietnmK8UwgX16oFTCg6Ho6kYM6SD33x8r0aLUZRwg55SivVllEL9XWTOfeRwOBw1IFzSohyl0O+UgsPhcGwehC2FI941JvJ7hzr3kcPhcGxe6MV1yYRw31cPZfyw3LIX+Wik+8gpBYfD4agB5orm7UZFS09tSybo7U+zzVYDAVjV1VsT2Qrh3EcOh8NRA8rJPhriV1GdNNJTCql0/d1HTik4HA5HDdBKoZRhXVd7bU8m+OR+23LVafVvPOncRw6Hw1EDCnVZy8evPrYnzy9ay5ihHfz4g7vVQKriOEvB4XA4akA4+ygKA9uSHDhlVA2kiY5TCg6Hw1EDCrXejDPNKbXD4XDEHO0+Uqr+weJKcErB4XA4akAjeiFUg+aU2uFwOGKOzj5qQFZpRTil4HA4HDVgSEdzJnc6peBwOBw1YFgDeyJUglMKDofDUQMa2SinEpxScDgcjhrQiP7K1SBWUovI+0TkVRGZLyLnNVoeh8PhqISJwwfwuUO3b7QYJRGbSIiItAC/A44GFgNPi8gdSqmXGiuZw+FwlMeM845otAglEydLYV9gvlLqDaVUL3ArcGKDZXI4HI4tijgphYnAIuP5Yn9bFiJylojMEpFZK1asqJtwDofDsSUQJ6UQCaXUlUqp6Uqp6aNHj260OA6Hw7FZESelsATYxni+tb/N4XA4HHUiTkrhaWCqiGwnIm3Ax4E7GiyTw+FwbFHEJvtIKdUvIl8C7gFagGuUUi82WCyHw+HYooiNUgBQSt0F3NVoORwOh2NLRZqt1reJiKwA3irz7aOAlVUUpxLiJIuNOMkXJ1mKERdZ4yJHFOIka5xksVGJfJOUUtZMnaZWCpUgIrOUUvXvim0hTrLYiJN8cZKlGHGRNS5yRCFOssZJFhu1ki9OgWaHw+FwNBinFBwOh8MRsCUrhSsbLYBBnGSxESf54iRLMeIia1zkiEKcZI2TLDZqIt8WG1NwOBwORy5bsqXgcDgcjhBOKTgcDocjwCkFh8PhcAQ4pVAnRORDIrJVo+VoBty5Kh0ROUJEBjVajmbCXWd2NkulICJnisjlIjIlBrJ8SkSeBA4GuhstTxh3rkrH7+nxQxEZEANZPikizwCHA32Nlicf7jqLTqPPVaxqH1WCiAiekvsw8E1gKbCfiCxRStX9h/flOQO4CjhQKfVUvWXIhztXpePLmAT+B/g/vMHkXuC/DZInCZwDfBt4v1LqyUbIUQh3nUUnTudqs7AURKRDeaSAZ4H9gN8DhwA7N0Im5eX6Pg3cAvSISEJETheRhsijceeqdESkzT9nfXjnbGfgD8CnRWRkI2RSSvUD84AbgbdEpE1EThaRCY2QJ4y7zqITt3PV9EpBRL4D3C0iXxaRXZRS85RSq4G/AQK8p15+QxG5UESOMzbNxysFfifwAnAAcI2I/NTfv67n352r0hGR7wE3i8gZIjJCKfWUUmoT3k27NXBUvWQTkfNFZD9j0xN4BSH/gzeYfBC4TkS+7e/fqHPmrrPo8sXmXAUopZr2D/gM8DCeZv0B8A9gsvH6e4HrgCND75MqyzECb3XhGrwLrdV4bWvgAmCK/3wHPNNwgjtX8TxXhjzn4rmIjgRuAH4DjDdePwX4J7B9jeUYD9wGrAXmhV47APgJsLX/fFf/3I5s0Dlz11mTnavwX9NaCr4PbhvgcuX5Bn8OzAV+qvdRSt0LLAB2E5HjROSL/vZqL+PuAv6hlNoKr4XoV43X3gZ+ppR63f/s+cDjwKQqy5AXd65KR0RagL2AC5VSDwA/BDbi+fHx5bsFWA8cKiLvFpFP1kicdcBflVLDgbUiYp6zp30ZF/syzQXuxiurXFfcdRadmJ2rbOqpGWugab8H3Gk8Hw3MBA4zth0ALMe7EM6toSyD/f/vxjNRx1v2GQD8GngIGObOVWzPlS7/cjHwJ/9xwpf3DmAfY9+jgU3AIuCzNZRpiP//YGAV0KblMvZpBS4F/g101OMcxeE6KyBLLK6zOJ2rSPLW40OqcFKPAMaFTzLQDrwEHKK3A2cDPzFO8n+Bq4GBtZDF9uP7n3dV6LXD8GYjv66WLHlk+ASwh3E+GnmusmSJ27kyPm+48dgcZKcC9+ErAf8cXYA/+OO5HZ4E/ljFc2aVJXTO/o7XrtZ87URgVh3PWUse2RpxnbUUeK3h1xkwwJSnkecqkrz1+qAyT+aBwIvA9cAOoROb9B9/EXjKeO2LwNeMk14V32oRWRL+Yy3TaOAVf1A5ANgdGApMrOG5Osq/gJYDZzT4XBWSpeHnypDn/cAjwE3At4ztLf7/Nrz0wD8br/2WjFIYQZ4JQhVlSRiDiD5nY4HVeC6iXYBt8fzkk+twzo7DC9L+BDjIPGcNuM4KydLw6wwvJvA43qD+SWN7st7nqiS56/2BJZzQFuBPwCdC282Z3Hj//4PARXim9T3ANxohC4Y2xwtKpoHngXfX6BwJnvn7F7yA1THA5cAX9MVXr3NVqiz1PlcWefcFngI+ABwK/BXYNbTPaF/W+/HWA0zxz9npDZKlw3h+lX/Ongam1emc7YPn3jgW+DheIPeM0D71uicjydKo68z/vZ4ETsLzLtyBoezrea5Klr2RH17kpG4FXAsMx5uxnYpnrnf4r1+Cp4UnA9sD/4s30/p2g2R5FM93KcDxwJvAN+t0rk40Hn8KeMJ4nsQLYtXrXEWRpWHnypDlXOBi//H2wK14Sk3PMC/Hyywahzcb/zGee+a7DZDld3iZKdPwLIdT8QKQdR088Bbt/dJ/PAAvY+ZZfJcX8Ms6XmdRZGnIdeZ/3q7AH4xt0/Csu9H+87qNXyXL32gBjJN2Np5vVpvmI/0f9VD/5vwL8Ge8RUOD8Mz4rULHaIuDLHgm6rA6nKszQ9tbgIPwZpHb+Nve5V+AtT5XZclS63OVT05gN7yslEuBxf7vey3wHTz3zPWWc9YeB1mA6Rixhzqes32B14AR/vPv4AVov+/fI7+u13VWqix1uCdPB442nk8G5mC4f4Ar8FJMh+BZLTU5VxV/l0YL4J+MM/BMrffhacsL8LT/RXhZAx/19xuCl3mxh/HevEGmBsiSrKYsEeX7FkaePJ6v9Gn8bJXQe2t9rkqRpebnqoCc38Gz+rYCfgWc4O83DS/wt2Mdz1kpsjTynH0bGIOnuO7Eixn9Cc9NeAWGwqzDOStFlpqeM/93+xveOofZ5nfHU+bXGc9H+PfDNrU6V9X4i8s6hSPx8obvBr4GdABfAL6LN/gOAVBKdQI3482eEBFR3tLwuMjSX2VZosjXjuemwZdrNl5dno9puQz5an2uSpGlHucqn5ytwJeVUmvwZpBv+fu9AszA/41FJFGHc1aKLI08Zx3AaUqpL+PdDz9QSn0a6MGb4fb4ctbrnowqS03Pmf+73YtXjuIZvHFC8yXgWBF5t/98A/AcoAz5qn2uKqahSsFYUv4cns8PpdQs4DE8P+544BvAMSJygohcgOeSeMnfV22OspQo35PARBE52N9P8IJVA/yLTlVbvjjJUqacjwOTRGQaXpDvKhEZiDcD3RVvzQFKqfTmKEuZcs4AdhSR9yilFiql7vP3OxZ4Q7+/TtdZ3WXJI5/4D69XSq3Fi0N9SEQm+Z+/HrgQ+I6InI7nddgF6KyHfOVSd6Vg1hYxLvQZQEJEDvGfz8W7GfZRSl2PZxIejJd6d7zyV29uTrJUKN/beEpLX2hjgK4a3aANl6VKci4GdlJKXQK8iucCmAZ8SCm1fHOTpUpyvo0XeEdEDhGRR/Csmys2R1kiyKcnOd3+/6fx6lD92NjnMrz4xj54K6Y/opRaV0sZK6UupbNFZF9gf6XUb80Zj28Sp/GqPb4IfExEZiilFovIGLwfGaXUgyLycDVmS3GSpYryjcMrwaD5ulKqd3OSpQZyjsULfAN8Fi91ce3mJEuN5NS/7QK8dOMXNydZSpRPL0Qzx4LLgL+IyC7ASrx42oMi8kgcXUU2am4piMg5wO3ABSLyfn9bC2TNBDrxgkXtwC9EpBUvgLNCH6dKCiE2stRAvlWGfNVQCLGRpYZyLtMyVkkhxEaWGsq50t9vYZUUQmxkKUM+pZRKi8gAERmsZfH3n4MXFB/qb28KhQDUPvsIb/n9XsDJwCOW1y/EW6yzE57b4Vo83/QfqH4WQ2xkibt8cZKlWeSMkyzNImecZClTvu/hlR3Z3X9+Cl6ywM8xKrM2018tTuIJeFH3/f3nLf5fB3AXcLa/PYGXn30zfglbY3tOCmOzyxJ3+eIkS7PIGSdZmkXOOMlSI/n2B7ar9W9a0+uliidzPPAvPDPvO8DLwDH+a7p2y5F4tc1HWd6f2Bxlibt8cZKlWeSMkyzNImecZKmRfLFbb1D2uajiST0BYwk58Dng9vAPi2f2Xeg/39c86ZujLHGXL06yNIuccZKlWeSMkyzNKF89/yo9kafhlZ9tBwaS3ZXqI2RKwJqF47bBW9C0Dq/eR1VOaJxkibt8cZKlWeSMkyzNImecZGlG+Rr1V3JKqp+GNQ7Pl5YGXgfOBL6ilFoqIq3Ka3A+Hi9DAOVF6AWvyuSf8PKOz1FKzSn18+MqS9zli5MszSJnnGRpFjnjJEszyhcLStSsus78jsCNehteDZK/h/b5F3CU/1gXrRoDHF4NbRYnWeIuX5xkaRY54yRLs8gZJ1maUb64/EWyFPy83B8CLSJyF17ubQq8/FsR+QrwtogcqpR6RETa8PL6XxORHwPHi8jhyludWdEKzTjJEnf54iRLs8gZJ1maRc44ydKM8sWNoovXRORQvEJPW+FVCf0h0AccLt5KP5S3yOT7eDnF4KVvnQE8gFfQ6yil1OpKhY2TLHGXL06yNIuccZKlWeSMkyzNKF8siWByvQc41Xh+OfB5vJP2jL8tgeen+wteW8B98crG7llNsyZOssRdvjjJ0ixyxkmWZpEzTrI0o3xx/ItyUgfiRee1r+2TwE/9x8/jlf0Fr/HHrTX+gWMjS9zli5MszSJnnGRpFjnjJEszyhfHv6LuI6XURqVUj8rU7jiaTB2gTwM7i8idwC14ZppZUraqxEmWuMsXJ1maRc44ydIscsZJlmaUL45ETkn1gzUKr6nMHf7mTuB8vLrvbyqllkBd6pjHRpa4yxcnWQoRJznjJEsh4iRnnGRpRvniRClVUtN4XaJWArv72vU7QFop9Zg+oXUiTrLYiJN8cZKlEHGSM06yFCJOcsZJFhtxly8+lOJrwiv2lMbrRvbZRvq94iRL3OWLkyzNImecZGkWOeMkSzPKF5c/XegpEiKyNXAqcIny+6A2ijjJYiNO8sVJlkLESc44yVKIOMkZJ1lsxF2+uFCSUnA4HA7H5k3dezQ7HA6HI744peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwqOWCIiKRF5XkReFJEXRORrIlLwehWRySLyiSrKcLaIvCwiN0Xc/wwRuaxan18uInKSiEwznv9ARI5qpEyO5qHkzmsOR53YpJTaE0BExuB1yhoKfK/AeyYDn/D3rQZfwCubvLhKxysZEUkqpfpLfNtJwJ3ASwBKqe9WWy7H5ouzFByxR3nNTc4CviQek0XkvyLyrP93oL/rRcB7fAvjXBFpEZGLReRpEZktIp+zHV9Evioic/2/c/xtVwDbA/8RkXND+3eIyJ9EZI6IPCcihxsvbyMiD4vIPBH5nr//IBH5t2/xzBWRj/nb9xGRR0TkGRG5R0TG+9sfFpFfi8gs4Nsi8pa2kvxjLRKRVhE50/9uL4jIbSIy0D8XHwAu9s/DFBG5VkQ+7L//SF/mOSJyjYi0+9sXiMiF/vmcIyI7VfzDOZqTRi+pdn/uz/YHbLBsW4tX0Gwg0OFvmwrM8h8fBtxp7H8WcIH/uB2YBWwXOuY+wBxgEDAYeBHYy39tATDKIsfXgGv8xzsBC8k0ZlkKjAQGAHPxSjKfDPzReP8wvDo8jwOj/W0fM475MHC5sf8/8dtA+vtd5T8eaezzIzJloK8FPmy8di3wYV/GRcCO/vbr8XoN6++q3/8F/Rnub8v7c5aCoxlpBf4oInOAvwLT8uz3XuA0EXkeeApvsJ4a2udg4HalVJdSagPwd7zGLIU4GLgRQCn1CvAWXt9fgPuUUquUUpv8Yx2Mp3SOFpGfich7lFLrgHfhVee8z5fvArwGL5o/hx5/zH/8ceO1XX2LaQ5en4Bdisj9LrxqoK/5z68DDjFe/7v//xk8V5xjC8TFFBxNgYhsj9dXdzleXGEZsAeeC7Q739vwZr/31EVIj3DdGKWUek1E9gaOBX4kIg8AtwMvKqUOyHOcLuPxHcBPRGQEnmXzoL/9WuAkpdQLInIGnqVUCboeUAo3NmyxOEvBEXtEZDRwBXCZUkrhuV+WKq+37qlAi79rJ15PXc09wOdFpNU/zo4iMih0+P8CJ/n++EHAB/1thfgv3swcEdkR2BZ41X/taBEZISID8AK+M0RkArBRKXUjcDGwt7//aBE5wD9Oq4hYZ/q+BfM08Bs895huGDMEWOp/v08abwmfB82rwGQR2cF/firwSJHv6tjCcLMBR1wZ4LtVWoF+4AbgEv+1y4HbROQ04G4ys+rZQEpEXsCbRf8Gzw3yrIgIXsetk8wPUUo9KyLXAjP9TVcppZ4rItvlwO99t00/cIZSqsf7CGYCt+G5gm5USs0SkWPwAr9pvKbxn1dK9frB39+KyDC8e/HXeDENG3/Gc5UdZmz7Dp5bbIX/XyuCW/Hca2fjxRL0d+0WkU8DfxWRJJ6iuaLId3VsYbgqqQ6Hw+EIcO4jh8PhcAQ4peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwoOh8PhCHBKweFwOBwB/w9rIgmvO/MuNQAAAABJRU5ErkJggg==\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "# start the figure.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(weather['Local time'], weather['T'])\n", + "# label the axes\n", + "ax.set_xlabel(\"Date of observation\")\n", + "ax.set_ylabel(\"Temperature in Celsius\")\n", + "ax.set_title(\"Temperature Observations\")\n", + "# adjust the date labels, so that they look nicer\n", + "fig.autofmt_xdate()\n", + "# save the figure\n", + "fig.savefig('weather.png')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/master/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py b/branch/master/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py new file mode 100644 index 00000000..8742b5f6 --- /dev/null +++ b/branch/master/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py @@ -0,0 +1,38 @@ +import yaml + +def get_parameters(config_file, required, defaults): + ''' + Parameters: + Optionfile: FileName of the yaml file containing the options + required: Dict of required argument names and their object types. + defaults: Dict of default parameters mapping to their default values + + Returns: An object with fields named according to required and optional values. + ''' + f = open(config_file) + options = yaml.safe_load(f) + # create a parameters object that allows setting attributes. + parameters = type('Options', (), {})() + # check required arguments + for arg in required: + if not arg in options: + raise Exception("Could not find required Argument " + arg + " aborting...") + else: + if not isinstance(options[arg],required[arg]): + raise Exception("Expected input of type " + str(required[arg]) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + # check the default values. + for arg in defaults: + if arg in options: + if not isinstance(options[arg],type(defaults[arg])): + #Wrong type for the parameter + raise Exception("Expected input of type " + str(type(defaults[arg])) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + else: + print( arg + " not found in option file. Using default: " +str(defaults[arg])) + setattr(parameters,arg,defaults[arg]) + return parameters + + diff --git a/branch/master/_images/01_memory_layout.svg b/branch/master/_images/01_memory_layout.svg new file mode 100644 index 00000000..93da7c68 --- /dev/null +++ b/branch/master/_images/01_memory_layout.svg @@ -0,0 +1,584 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How you see a matrix: + How NumPy sees a matrix: + [0,] + [1,] + [2,] + [3,] + [,0] + [,1] + [,2] + [,3] + [0] + [1] + [2] + [3] + [4] + [5] + [6] + [7] + [8] + [9] + [10] + [11] + [12] + [13] + [14] + [15] + + + + diff --git a/branch/master/_images/01_table_dataframe.svg b/branch/master/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/branch/master/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/branch/master/_images/02_views.svg b/branch/master/_images/02_views.svg new file mode 100644 index 00000000..925354e0 --- /dev/null +++ b/branch/master/_images/02_views.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + array "a" + array "b" + .shape.strides + .shape.strides + + + + + data pointer + data pointer + memory buffer + + diff --git a/branch/master/_images/anaconda-navigator-jupyterlab.png b/branch/master/_images/anaconda-navigator-jupyterlab.png new file mode 100644 index 00000000..4ea0854f Binary files /dev/null and b/branch/master/_images/anaconda-navigator-jupyterlab.png differ diff --git a/branch/master/_images/anaconda-prompt.png b/branch/master/_images/anaconda-prompt.png new file mode 100644 index 00000000..e4fcf79b Binary files /dev/null and b/branch/master/_images/anaconda-prompt.png differ diff --git a/branch/master/_images/binder.jpg b/branch/master/_images/binder.jpg new file mode 100644 index 00000000..d04c467d Binary files /dev/null and b/branch/master/_images/binder.jpg differ diff --git a/branch/master/_images/chatgpt.png b/branch/master/_images/chatgpt.png new file mode 100644 index 00000000..67948010 Binary files /dev/null and b/branch/master/_images/chatgpt.png differ diff --git a/branch/master/_images/code-completion.gif b/branch/master/_images/code-completion.gif new file mode 100644 index 00000000..e0bed42f Binary files /dev/null and b/branch/master/_images/code-completion.gif differ diff --git a/branch/master/_images/exercise.png b/branch/master/_images/exercise.png new file mode 100644 index 00000000..6bfedfb4 Binary files /dev/null and b/branch/master/_images/exercise.png differ diff --git a/branch/master/_images/exercise1.png b/branch/master/_images/exercise1.png new file mode 100644 index 00000000..ddfe4352 Binary files /dev/null and b/branch/master/_images/exercise1.png differ diff --git a/branch/master/_images/gapminder-larger-font.png b/branch/master/_images/gapminder-larger-font.png new file mode 100644 index 00000000..cf7270ef Binary files /dev/null and b/branch/master/_images/gapminder-larger-font.png differ diff --git a/branch/master/_images/gapminder-linear.png b/branch/master/_images/gapminder-linear.png new file mode 100644 index 00000000..78b30e77 Binary files /dev/null and b/branch/master/_images/gapminder-linear.png differ diff --git a/branch/master/_images/gapminder-log.png b/branch/master/_images/gapminder-log.png new file mode 100644 index 00000000..7b6c3208 Binary files /dev/null and b/branch/master/_images/gapminder-log.png differ diff --git a/branch/master/_images/getting-started.png b/branch/master/_images/getting-started.png new file mode 100644 index 00000000..8690a86f Binary files /dev/null and b/branch/master/_images/getting-started.png differ diff --git a/branch/master/_images/jupyterlab-notebook.png b/branch/master/_images/jupyterlab-notebook.png new file mode 100644 index 00000000..900fdfd9 Binary files /dev/null and b/branch/master/_images/jupyterlab-notebook.png differ diff --git a/branch/master/_images/jupyterlab-terminal.png b/branch/master/_images/jupyterlab-terminal.png new file mode 100644 index 00000000..33a6b02a Binary files /dev/null and b/branch/master/_images/jupyterlab-terminal.png differ diff --git a/branch/master/_images/main-ui.png b/branch/master/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/branch/master/_images/main-ui.png differ diff --git a/branch/master/_images/notebook-ui.png b/branch/master/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/branch/master/_images/notebook-ui.png differ diff --git a/branch/master/_images/precipitation-on-top-yearmonth.svg b/branch/master/_images/precipitation-on-top-yearmonth.svg new file mode 100644 index 00000000..40a99519 --- /dev/null +++ b/branch/master/_images/precipitation-on-top-yearmonth.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)050100150200250300350precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/precipitation-on-top.svg b/branch/master/_images/precipitation-on-top.svg new file mode 100644 index 00000000..a977ebc6 --- /dev/null +++ b/branch/master/_images/precipitation-on-top.svg @@ -0,0 +1 @@ +OctoberNovemberDecember2023FebruaryMarchAprilMayJuneJulyAugustSeptemberOctoberdate050100150200250300350precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/precipitation-side.svg b/branch/master/_images/precipitation-side.svg new file mode 100644 index 00000000..095c23bd --- /dev/null +++ b/branch/master/_images/precipitation-side.svg @@ -0,0 +1 @@ +name050100150200250precipitationOslo - BlindernTromso - LangnesOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/precipitation-stacked-x.svg b/branch/master/_images/precipitation-stacked-x.svg new file mode 100644 index 00000000..c0992433 --- /dev/null +++ b/branch/master/_images/precipitation-stacked-x.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)050100150200250precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/precipitation-stacked-y.svg b/branch/master/_images/precipitation-stacked-y.svg new file mode 100644 index 00000000..78092adf --- /dev/null +++ b/branch/master/_images/precipitation-stacked-y.svg @@ -0,0 +1 @@ +050100150200250precipitationOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/python_unmasked.jpg b/branch/master/_images/python_unmasked.jpg new file mode 100644 index 00000000..57e3cc47 Binary files /dev/null and b/branch/master/_images/python_unmasked.jpg differ diff --git a/branch/master/_images/snow-depth-circles.svg b/branch/master/_images/snow-depth-circles.svg new file mode 100644 index 00000000..c54504ed --- /dev/null +++ b/branch/master/_images/snow-depth-circles.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - Langnes2023FebruaryMarchAprildate2023FebruaryMarchAprildate−5051015max temperature \ No newline at end of file diff --git a/branch/master/_images/snow-depth-color.svg b/branch/master/_images/snow-depth-color.svg new file mode 100644 index 00000000..7a821dd4 --- /dev/null +++ b/branch/master/_images/snow-depth-color.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate−5051015max temperature \ No newline at end of file diff --git a/branch/master/_images/snow-depth-plasma.svg b/branch/master/_images/snow-depth-plasma.svg new file mode 100644 index 00000000..d5ec8d5e --- /dev/null +++ b/branch/master/_images/snow-depth-plasma.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate−5051015max temperature \ No newline at end of file diff --git a/branch/master/_images/snow-depth.svg b/branch/master/_images/snow-depth.svg new file mode 100644 index 00000000..75581931 --- /dev/null +++ b/branch/master/_images/snow-depth.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate \ No newline at end of file diff --git a/branch/master/_images/temperature-ranges-combined.svg b/branch/master/_images/temperature-ranges-combined.svg new file mode 100644 index 00000000..abc39623 --- /dev/null +++ b/branch/master/_images/temperature-ranges-combined.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)−20−15−10−505101520253035max temperature, min temperatureOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/temperature-ranges-side.svg b/branch/master/_images/temperature-ranges-side.svg new file mode 100644 index 00000000..aa67e29e --- /dev/null +++ b/branch/master/_images/temperature-ranges-side.svg @@ -0,0 +1 @@ +name−20−15−10−505101520253035max temperature, min temperatureOslo - BlindernTromso - LangnesOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/_images/tidy_data.png b/branch/master/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/branch/master/_images/tidy_data.png differ diff --git a/branch/master/_images/xarray_1d_plot.png b/branch/master/_images/xarray_1d_plot.png new file mode 100644 index 00000000..0e0b6a79 Binary files /dev/null and b/branch/master/_images/xarray_1d_plot.png differ diff --git a/branch/master/_images/xarray_2d_plot.png b/branch/master/_images/xarray_2d_plot.png new file mode 100644 index 00000000..15afca26 Binary files /dev/null and b/branch/master/_images/xarray_2d_plot.png differ diff --git a/branch/master/_images/xarray_dataset_image.png b/branch/master/_images/xarray_dataset_image.png new file mode 100644 index 00000000..e3556dea Binary files /dev/null and b/branch/master/_images/xarray_dataset_image.png differ diff --git a/branch/master/_images/xarray_hist.png b/branch/master/_images/xarray_hist.png new file mode 100644 index 00000000..de6b24b6 Binary files /dev/null and b/branch/master/_images/xarray_hist.png differ diff --git a/branch/master/_sources/binder.rst.txt b/branch/master/_sources/binder.rst.txt new file mode 100644 index 00000000..57b1aa42 --- /dev/null +++ b/branch/master/_sources/binder.rst.txt @@ -0,0 +1,200 @@ +Binder +====== + +.. questions:: + + - Why sharing code alone may not be sufficient. + - How to share a computational environment? + - What is Binder? + - How to binderize my Python repository? + - How to publish my Python repository? + +.. objectives:: + + - Learn about reproducible computational environments. + - Learn to create and share custom computing environments with Binder. + - Learn to get a DOI from Zenodo for a repository. + + +Why is it sometimes not enough to share your code? +-------------------------------------------------- + +.. image:: img/binder/python_unmasked.jpg + + +Exercise 1 +~~~~~~~~~~ + +.. challenge:: Binder-1: Discuss better strategies than only code sharing (10 min) + + Lea is a PhD student in computational biology and after 2 years of intensive + work, she is finally ready to publish her first paper. The code she has used + for analyzing her data is available on GitHub but her supervisor who is an + advocate of open science told her that sharing code is not sufficient. + + **Why is it possibly not enough to share "just" your code? + What problems can you anticipate 2-5 years from now?** + + We form small groups (4-5 persons) and discuss in groups. If the workshop is + online, each group will join a breakout room. + If joining a group is not possible or practical, we use the shared document + to discuss this collaboratively. + + Each group write a summary (bullet points) of the discussion in the workshop + shared document (the link will be provided by your instructors). + + +Sharing a computing environment with Binder +------------------------------------------- + +`Binder `__ allows you to create +custom computing environments that can be shared and used by many remote users. +It uses `repo2docker `__ to +create a container image (`docker `__ image) of a +project using information contained in included configuration files. + +Repo2docker is a standalone package that you can install locally on your laptop +but an `online Binder `__ service is freely available. +This is what we will be using in the tutorial. + +The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder. + +.. image:: https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png + +Credit: `Juliette Taka, Logilab and the OpenDreamKit project (2017) `_ + + +Binder exercise/demo +~~~~~~~~~~~~~~~~~~~~ + +In an earlier episode (Data visualization with Matplotlib) we have created this notebook: + +.. code-block:: python + + import pandas as pd + import matplotlib.pyplot as plt + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + data_2007 = data[data["year"] == 2007] + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xscale("log") + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + +We will now first share it via `GitHub `__ "statically", +then using `Binder `__. + +.. challenge:: Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min) + + Instructor demonstrates this. **This exercise (and all following) + requires git/GitHub knowledge and accounts, which wasn't a + prerequisite of this course. Thus, this is a demo (and might even + be too fast for you to type-along). Watch the video if you + are reading this later on**: + + - Creates a GitHub repository + - Uploads the notebook file + - Then we look at the statically rendered version of the notebook on GitHub + - Create a ``requirements.txt`` file which contains: + + .. code-block:: none + + pandas==1.2.3 + matplotlib==3.4.2 + + - Commit and push also this file to your notebook repository. + - Visit https://mybinder.org and copy paste the code under "Copy the text below ..." into your `README.md`: + + .. image:: img/binder/binder.jpg + + - Check that your notebook repository now has a "launch binder" + badge in your `README.md` file on GitHub. + - Try clicking the button and see how your repository is launched + on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud. + - Enjoy being fully reproducible! + + +How can I get a DOI from Zenodo? +--------------------------------- + +`Zenodo `__ is a general purpose open-access +repository built and operated by `CERN `__ and `OpenAIRE +`__ that allows researchers to archive and get a +`Digital Object Identifier (DOI) `__ to data that they +share. + +.. challenge:: Binder-3: Link a Github repository with Zenodo (optional) + + **Everything you deposit on Zenodo is meant to be kept (long-term archive). + Therefore we recommend to practice with the Zenodo "sandbox" (practice/test area) + instead:** https://sandbox.zenodo.org + + 1. **Link GitHub with Zenodo**: + + - Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing). + - Log in to Zenodo with your GitHub account. Be aware that you may need to + authorize Zenodo application (Zenodo will redirect you back to GitHub for + Authorization). + - Choose the repository webhooks options. + - From the drop-down menu next to your email address at the top of the page, select GitHub. + - You will be presented with a list of all your Github repositories. + + 2. **Archiving a repo**: + + - Select a repository you want to archive on Zenodo. + - Toggle the "on" button next to the repository ou need to archive. + - Click on the Repo that you want to reserve. + - Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release. + + 3. **Trigger Zenodo to Archive your repository** + + - Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI. + - If this is the first release of your code then you should give it a + version number of v1.0.0. Add description for your release then click the + Publish release button. + - Zenodo takes an archive of your GitHub repository each time you create a new Release. + + 4. **To ensure that everything is working**: + + - Go to https://zenodo.org/account/settings/github/ (or the corresponding + sandbox at https://sandbox.zenodo.org/account/settings/github/), or the + Upload page (https://zenodo.org/deposit), you will find your repo is + listed. + - Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo. + - You can edit the archive on Zenodo and/or publish a new version of your software. + - It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata + manually, you can also add a ``.zenodo.json`` or a ``CITATION.cff`` file to your repo and Zenodo will infer the metadata from this file. + - Your code is now published on a Github public repository and archived on Zenodo. + - Update the README file in your repository with the newly created zenodo badge. + + +Create a Binder link for your Zenodo DOI +---------------------------------------- + +Rather than specifying a GitHub repository when launching binder, you can instead use a Zenodo DOI. + +.. challenge:: Binder-4: Link Binder with Zenodo (10 min) + + We will be using an existing Zenodo DOI `10.5281/zenodo.3886864 `_ to start Binder: + + - Go to `https://mybinder.org `__ and fill information using Zenodo DOI (as shown on the animation below): + + .. image:: https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif + + - You can also get a Binder badge and update the README file in the + repository. It is good practice to add both the Zenodo badge and the + corresponding Binder badge. + +.. keypoints:: + + - It is easy to sharing reproducible computational environments + - Binder provides a way for anyone to test and run code - without + you needing to set up a dedicated server for it. + - Zenodo provides permanent archives and a DOI. diff --git a/branch/master/_sources/data-formats.rst.txt b/branch/master/_sources/data-formats.rst.txt new file mode 100644 index 00000000..1c7f3839 --- /dev/null +++ b/branch/master/_sources/data-formats.rst.txt @@ -0,0 +1,549 @@ +In depth analysis of some selected file formats +=============================================== + +Here is a selection of file formats that are commonly used in data science. They are somewhat ordered by their intended use. + +Storing arbitrary Python objects +-------------------------------- + + +.. _pickle: + +Pickle +****** + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** None (:mod:`pickle`-module is included with Python). + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** 🟨 + - **Array data:** 🟨 + - **Long term archival/sharing:** ❌! See warning below. + - **Best use cases:** Saving Python objects for debugging. + +.. warning:: + + Loading pickles that you have not created is + risky as they can contain arbitrary executable code. + + Do not unpickle objects from sources that you do not trust! + +:mod:`Pickle ` is Python's own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:: + + import pickle + + with open('data_array.pickle', 'wb') as f: + pickle.dump(data_array, f) + + with open('data_array.pickle', 'rb') as f: + data_array_pickle = pickle.load(f) + + +Exercise 1 +---------- + +.. challenge:: + + - Create an arbitrary python object (for example, a string or a list). Pickle it. + + Read the pickled object back in and check if it matches the original one. + +.. solution:: + + .. code-block:: python + + import pickle + + my_object=['test', 1, 2, 3] + + with open('string.pickle', 'wb') as f: + pickle.dump(my_object, f) + + + with open('string.pickle', 'rb') as f: + my_pickled_object = pickle.load(f) + + print(my_object, my_pickled_object) + print(my_object == my_pickled_object) + + +Storing tidy data +----------------- + +.. _csv: + +CSV (comma-separated values) +**************************** + +.. admonition:: Key features + + - **Type:** Text format + - **Packages needed:** numpy, pandas + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data. Small data. Data that needs to be human-readable. + +CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you're working with big data. + +Pandas has a very nice interface for writing and reading CSV files with `to_csv `__- and `read_csv `__-functions:: + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + +Numpy has `routines `__ for saving and loading arrays as CSV files as well:: + + np.savetxt('data_array.csv', data_array) + + data_array_csv = np.loadtxt('data_array.csv') + +.. admonition:: Storing data in CSVs can reduce data precision + :class: dropdown + + When working with floating point numbers you should be careful to save the data with enough decimal places so that you won't lose precision. + + For example, double-precision floating point numbers have `~16 decimal places of precision `__, but if you use normal Python to write these numbers, you can easily lose some of that precision. + Let's consider the following example: + + .. code-block:: python + + import numpy as np + test_number = np.sqrt(2) + # Write the number in a file + test_file = open('sqrt2.csv', 'w') + test_file.write('%f' % test_number) + test_file.close() + # Read the number from a file + test_file = open('sqrt2.csv', 'r') + test_number2 = np.float64(test_file.readline()) + test_file.close() + # Calculate the distance between these numbers + print(np.abs(test_number - test_number2)) + + CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. + We can check whether our written data matches the generated data: + + .. code-block:: python + + dataset.compare(dataset_csv) + + np.all(data_array == data_array_csv) + + In our case some rows of ``dataset_csv`` loaded from CSV do not match the original ``dataset`` as the last decimal can sometimes be rounded due to `complex technical reasons `__. + + Storage of these high-precision CSV files is usually very inefficient storage-wise. + + Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems. + + +.. _feather: + + +Feather +******* + +.. admonition:: Requires additional packages + :class: dropdown + + + Using Feather requires `pyarrow-package `__ to be installed. + + You can try installing pyarrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** ❌ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Temporary storage of tidy data. + +`Feather `__ is a file format for storing data frames quickly. +There are libraries for Python, R and Julia. + +We can work with Feather files with :external+pandas:ref:`to_feather- and read_feather-functions `:: + + dataset.to_feather('dataset.feather') + dataset_feather = pd.read_feather('dataset.feather') + +Feather is not a good format for storing array data, so we won't present an example of that here. + + +.. _parquet: + + +Parquet +******* + +.. admonition:: Requires additional packages + :class: dropdown + + Using Parquet requires `pyarrow-package `__ to be installed. + + You can try installing PyArrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** 🟨 + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in tidy data format. Archival of said data. + +`Parquet `__ is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.). + +We can work with Parquet files with :external+pandas:ref:`to_parquet- and read_parquet-functions `:: + + dataset.to_parquet('dataset.parquet') + dataset_parquet = pd.read_parquet('dataset.parquet') + +Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won't do that here. + + +Exercise 2 +---------- + +.. challenge:: + + - Create the example ``dataset``: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + - Save the dataset ``dataset`` as CSV. Load the dataset into a variable ``dataset_csv``. + - Use ``dataset.compare(dataset_csv)`` to check if loaded dataset matches the original one. + +.. solution:: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + + print(dataset.compare(dataset_csv)) + + Dataset might not be completely the same. Sometimes the CSV format cannot + fully represent a floating point value, which will result in rounding errors. + +Storing array data +------------------ + + +.. _npy: + + +npy (numpy array format) +************************ + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** numpy + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Saving numpy arrays temporarily. + +If you want to temporarily store numpy arrays, you can use the :func:`numpy.save`- and :func:`numpy.load`-functions:: + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + +There also exists :func:`numpy.savez`-function for storing multiple datasets in a single file:: + + np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array) + data_arrays = np.load('data_arrays.npz') + data_arrays['data_array0'] + +For big arrays it's good idea to check other binary formats such as HDF5 or NetCDF4. + +``np.save``- and ``np.savez``-functions work with +`sparse matrices `__, +but one can also use dedicated +`scipy.sparse.save_npz `__- and +`scipy.sparse.load_npz `__-functions. +Storing sparse matrices using these functions can give huge storage savings. + + +.. _hdf5: + + +HDF5 (Hierarchical Data Format version 5) +***************************************** + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** numpy, pandas, PyTables, h5py + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. + +HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences. + +Pandas allows you to store tables as HDF5 with `PyTables `_, which uses HDF5 to write the files. +You can create a HDF5 file with :external+pandas:ref:`to_hdf- and read_parquet-functions `:: + + dataset.to_hdf('dataset.h5', key='dataset', mode='w') + dataset_hdf5 = pd.read_hdf('dataset.h5') + +For writing data that is not a table, you can use the excellent `h5py-package `__:: + + import h5py + + # Writing: + + # Open HDF5 file + h5_file = h5py.File('data_array.h5', 'w') + # Write dataset + h5_file.create_dataset('data_array', data=data_array) + # Close file and write data to disk. Important! + h5_file.close() + + # Reading: + + # Open HDF5 file again + h5_file = h5py.File('data_array.h5', 'r') + # Read the full dataset + data_array_h5 = h5_file['data_array'][()] + # Close file + h5_file.close() + + +.. _netcdf4: + + +NetCDF4 (Network Common Data Form version 4) +******************************************** + +.. admonition:: Requires additional packages + :class: dropdown + + Using NetCDF4 requires `netCDF4 `__- or `h5netcdf `__-package to be installed. + h5netcdf is often mentioned as being faster to the official netCDF4-package, so we'll be using it in the example. + + A great NetCDF4 interface is provided by a `xarray-package `__. + + You can try installing these packages with + + .. code-block:: bash + + !pip install h5netcdf xarray + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** pandas, netCDF4/h5netcdf, xarray + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets. + +NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs. + +NetCDF4 is a common format for storing large data from big simulations in physical sciences. + +Using interface provided by ``xarray``:: + + # Write tidy data as NetCDF4 + dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf') + # Read tidy data from NetCDF4 + import xarray as xr + dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf') + dataset_netcdf4 = dataset_xarray.to_pandas() + dataset_xarray.close() + +Working with array data is easy as well:: + + # Write array data as NetCDF4 + xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf') + # Read array data from NetCDF4 + data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf') + data_array_netcdf4 = data_array_xarray.to_numpy() + data_array_xarray.close() + +The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (``x``, ``y``, ``z``) or timestamps (``t``) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis. + +Exercise 3 +---------- + +.. challenge:: + + - Create an example numpy array: + + .. code-block:: python + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + - Store the array as a npy. + - Read the dataframe back in and compare it to the original one. Does the data match? + +.. solution:: + + .. code-block:: python + + import numpy as np + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + np.all(data_array == data_array_npy) + + +Other file formats +------------------ + + +.. _json: + +JSON (JavaScript Object Notation) +********************************* + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** None (:mod:`json`-module is included with Python). + - **Space efficiency:** ❌ + - **Arbitrary data:** 🟨 + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Saving nested/relational data, storing web requests. + +JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.). + +You rarely want to keep your data in this format, unless you're working with +nested data with multiple layers or lots of interconnections. + +Similarly to other popular files, Pandas can write and read json files with :meth:`~pandas.DataFrame.to_json`- and :func:`~pandas.read_json`-functions:: + + dataset.to_json('dataset.json') + dataset_json = pd.read_json('dataset.json') + + +.. _excel: + +Excel +***** + +.. admonition:: Requires additional packages + :class: dropdown + + Using Excel files with Pandas requires `openpyxl `__-package to be installed. + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** `openpyxl `__ + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** 🟨 + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data in many fields. Quick data analysis. + +Excel is very popular in social sciences and economics. +However, it is `not a good format `__ for data science. + +See Pandas' documentation on :external+pandas:ref:`working with Excel files `. + + +.. _graph: + +Graph formats (adjency lists, gt, GraphML etc.) +*********************************************** + +.. admonition:: Key features + + - **Type**: Many different formats + - **Packages needed:** Depends on a format. + - **Space efficiency:** 🟨 + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** 🟨 + - **Best use cases:** Saving graphs or data that can be represented as a graph. + +There are plenty of data formats for storing graphs. +We won't list them here as optimal data format depends heavily on the graph structure. + +One can use functions in libraries such as +`networkx `__, +`graph-tool `__, +`igraph `__ +to read and write graphs. + diff --git a/branch/master/_sources/dependencies.rst.txt b/branch/master/_sources/dependencies.rst.txt new file mode 100644 index 00000000..0081116f --- /dev/null +++ b/branch/master/_sources/dependencies.rst.txt @@ -0,0 +1,767 @@ +.. _dependency_management: + +Dependency management +===================== + +.. questions:: + + - Do you expect your code to work in one year? Five? What if it + uses ``numpy`` or ``tensorflow`` or ``random-github-package`` ? + - How can my collaborators easily install my code with all the necessary dependencies? + - How can I make it easy for my others (and me in future) to reproduce my results? + - How can I work on two (or more) projects with different and conflicting dependencies? + +.. objectives:: + + - Learn how to record dependencies + - Be able to communicate the dependencies as part of a report/thesis/publication + - Learn how to use isolated environments for different projects + - Simplify the use and reuse of scripts and projects + + +How do you track dependencies of your project? +---------------------------------------------- + +* **Dependency**: Reliance on a external component. In this case, a + separately installed software package such as ``numpy``. + + + +Exercise 1 +---------- + +.. challenge:: Dependencies-1: Discuss dependency management (5 min) + + Please discuss and answer via **collaborative document** the + following questions: + + - How do you install Python packages (libraries) that you use in your work? + From PyPI using pip? From other places using pip? Using conda? + - How do you track/record the dependencies? Do you write them into a file or README? Into + ``requirements.txt`` or ``environment.yml``? + - If you track dependencies in a file, why do you do this? + - Have you ever experienced that a project needed a different version of a Python + library than the one on your computer? If yes, how did you solve it? + + +.. _pypi: + +PyPI (The Python Package Index) and conda ecosystem +--------------------------------------------------- + +PyPI (The Python Package Index) and conda are popular packaging/dependency +management tools: + +- When you run ``pip install`` you typically install from `PyPI + `__, but you can also ``pip install`` from a GitHub + repository and similar. + +- When you run ``conda install`` you typically install from `Anaconda Cloud + `__ where there are conda channels maintained + by Anaconda Inc. and by various communities. + + +Why are there two ecosystems? + + +.. admonition:: PyPI + + - **Installation tool:** ``pip`` + - **Summary:** PyPI is traditionally used for Python-only packages or + for Python interfaces to external libraries. There are also packages + that have bundled external libraries (such as numpy). + - **Amount of packages:** Huge number. Old versions are supported for + a long time. + - **How libraries are handled:** If your code depends on external + libraries or tools, these things need to be either included in the + pip-package or provided via some other installation system (like + operating system installer or manual installation). + - **Pros:** + - Easy to use + - Package creation is easy + - **Cons:** + - Installing packages that need external libraries can be complicated + +.. admonition:: Conda + + - **Installation tool:** ``conda`` or ``mamba`` + - **Summary:** Conda aims to be a more general package distribution tool + and it tries to provide not only the Python packages, but also libraries + and tools needed by the Python packages. Most scientific software written + in Python uses external libraries to speed up calculations and installing + these libraries can often become complicated without conda. + - **Amount of packages:** Curated list of packages in defaults-channel, huge + number in community managed channels. Other packages can be installed via pip. + - **How libraries are handled:** Required libraries are installed as separate + conda packages. + - **Pros:** + - Quite easy to use + - Easier to manage packages that need external libraries + - **Cons:** + - Package creation is harder + + +Conda ecosystem explained +------------------------- + +.. warning:: + + Anaconda has recently changed its licensing terms, which affects its + use in a professional setting. This caused uproar among academia + and Anaconda modified their position in + `this article `__. + + Main points of the article are: + + - conda (installation tool) and community channels (e.g. conda-forge) + are free to use. + - Anaconda repository and **Anaconda's channels in the community repository** + are free for universities and companies with fewer than 200 employees. + Non-university research institutions and national laboratories need + licenses. + - Miniconda is free, when it does not download Anaconda's packages. + - Miniforge is not related to Anaconda, so it is free. + + For ease of use on sharing environment files, we recommend using + Miniforge to create the environments and using conda-forge as the main + channel that provides software. + +- Package repositories: + + - `Anaconda Community Repository (anaconda.org) `__ + aka. Anaconda Cloud is a package cloud maintained by Anaconda Inc. + It is a repository that houses mirrors of Anaconda's channels and + community maintained channels. + - `Anaconda Repository (repo.anaconda.com) `__ + houses Anaconda's own proprietary software channels. + +- Major package channels: + + - Anaconda's proprietary channels: ``main``, ``r``, ``msys2`` and ``anaconda``. + These are sometimes called ``defaults``. + - `conda-forge `__ is the largest open source + community channel. It has over 27,000 packages that include open-source + versions of packages in Anaconda's channels. + +- Package distributions and installers: + + - `Anaconda `__ is a distribution of conda packages + made by Anaconda Inc.. When using Anaconda remember to check that your + situation abides with their licensing terms. + - `Miniconda `__ is a minimal installer + maintained by Anaconda Inc. that has conda and uses Anaconda's channels + by default. Check licensing terms when using these packages. + - `Miniforge `__ is an open-source + Miniconda replacement that uses conda-forge as the default channel. + Contains mamba as well. + - `micromamba `__ + is a tiny stand-alone version of the mamba package manager written in C++. + It can be used to create and manage environments without installing + base-environment and Python. It is very useful if you want to automate + environment creation or want a more lightweight tool. + +- Package managers: + + - `conda `__ is a package and environment management system + used by Anaconda. It is an open source project maintained by Anaconda Inc.. + - `mamba `__ is a drop in + replacement for conda. It used be much faster than conda due to better + dependency solver but nowadays conda + `also uses the same solver `__. + It still has some UI improvements. + +Exercise 2 +---------- + +.. challenge:: Dependencies-2: Package language detective (5 min) + + Think about the following sentences: + + 1. Yes, you can install my package with pip from GitHub. + 2. I forgot to specify my channels, so my packages came from the defaults. + 3. I have a Miniforge installation and I use mamba to create my environments. + + What hidden information is given in these sentences? + + .. solution:: + + 1. The package is provided as a pip package. However, it is most likely + not uploaded to PyPI as it needs to be installed from a repository. + 2. In this case the person saying the sentence is most likely using + Anaconda or Miniconda because these tools use the ``defaults``-channel + as the default channel. They probably meant to install software from + conda-forge, but forgot to specify the channel. + 3. Miniforge uses conda-forge as the default channel. So unless some + other channel has been specified, packages installed with these + tools come from conda-forge as well. + +Python environments +------------------- + +An **environment** is a basically a folder that contains a Python +interpreter and other Python packages in a folder structure similar +to the operating system's folder structure. + +These environments can be created by the +`venv-module `__ in base +Python, by a pip package called +`virtualenv `_ +or by conda/mamba. + +Using these environments is highly recommended because they solve the +following problems: + +- Installing environments won't modify system packages. + +- You can install specific versions of packages into them. + +- You can create an environment for each project and you won't encounter any + problems if different projects require different versions of packages. + +- If you make some mistake and install something you did not want or need, you + can remove the environment and create a new one. + +- Others can replicate your environment by reusing the same specification + that you used to create the environment. + + +Creating Python environments +---------------------------- + +.. tabs:: + + .. group-tab:: Creating conda environment from environment.yml + + Record channels and packages you need to a file called + ``environment.yml``: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + - python + - numpy + - matplotlib + - pandas + + The ``name`` describes the name of the environment, + ``channels``-list tells which channels should be search for packages + (channel priority goes from top to bottom) and ``dependencies``-list + contains all packages that are needed. + + Using this file you can now create an environment with: + + .. code-block:: console + + $ conda env create --file environment.yml + + .. admonition:: You can also use mamba + + If you have mamba installed, you can replace conda + with mamba in each command. + + You can then activate the environment with: + + .. code-block:: console + + $ conda activate my-environment + + .. callout:: conda activate versus source activate + + ``conda activate`` will only work if you have run ``conda init`` + in the past. Running ``conda init`` will make loading environments + easier as you will always have a conda environment loaded. + + However, this can also cause problems as programs in the + main environment will be constantly loaded and they might be used + even when they're not supposed to be used. A common example is + not having ``pip`` installed in a conda environment which results + ``pip`` from main environment to be used instead. + + You can then check e.g. installed versions of Python and ``numpy``: + + .. code-block:: console + + $ python -c 'import sys; import numpy; print(f"Python version: {sys.version}\nNumPy version: {numpy.__version__}")' + Python version: 3.13.0 | packaged by conda-forge | (main, Oct 8 2024, 20:04:32) [GCC 13.3.0] + NumPy version: 2.1.2 + + To deactivate the environment, you can run: + + .. code-block:: console + + $ conda deactivate + + .. group-tab:: Creating virtual environment from requirements.txt + + Record packages you need to a file called + ``requirements.txt``: + + .. code-block:: text + + numpy + matplotlib + pandas + + This is simply a text file that lists all of the packages that + you need. It is usually called ``requirements.txt``. + + Now you can create a virtual environment with: + + .. code-block:: console + + $ python -m venv my-environment + + You can then activate the environment by sourcing a file called + ``activate``. + + - **Linux/Mac OSX**: + .. code-block:: console + + $ source my-environment/bin/activate + + - **Windows**: most likely you can find it in the Scripts folder. + + Now the environment should be active. You can then install packages + listed in ``requirements.txt`` with + + .. code-block:: console + + $ python -m pip install -r requirements.txt + + You can then check e.g. installed versions of Python and ``numpy``: + + .. code-block:: console + + $ python -c 'import sys; import numpy; print(f"Python version: {sys.version}\nNumPy version: {numpy.__version__}")' + Python version: 3.10.12 (main, Sep 11 2024, 15:47:36) [GCC 11.4.0] + NumPy version: 2.1.2 + + To deactivate the environment, you can run: + + .. code-block:: console + + $ deactivate + + +.. admonition:: Creating environments without environment.yml/requirements.txt + + It is possible to create environments with manual commands, but this + is highly discouraged for continuous use. + + Firstly, replicating the environment becomes much harder. + + Secondly, running package installation commands manually in an + environment can result in unexpected behaviour such as: + + - Package manager might remove an already installed packages or update them. + - Package manager might not find a package that works with already + installed packages. + + The reason for this behavior is that package managers does not know what + commands you ran in the past. It only knows the state of your environment + and what you're currently telling it to install. + + These kinds of problems can be mitigated by recording dependencies in an + ``environment.yml`` or ``requirements.txt`` and using the relevant + package manager to update / recreate the environment. + + +Exercise 3 +---------- + +.. challenge:: Dependencies-3: Create a Python environment (15 min) + + Use conda or venv to create the environment presented in the + example. + + +Adding more packages to existing environments +--------------------------------------------- + +Quite often when you're creating a new environment you might forget +to add all relevant packages to ``environment.yml`` or +``requirements.txt``. + +In these cases the best practice is to add missing packages to +``environment.yml`` or ``requirements.txt`` and to update the environment. + +.. tabs:: + + .. group-tab:: Adding new packages to a conda environment + + Add new packages that you want to install to + ``dependencies`` in + ``environment.yml``. + + Afterwards, run + + .. code-block:: console + + $ conda env update --file environment.yml + + to update the environment. + + .. group-tab:: Adding new packages to a virtual environment + + Add new packages that you want to install to + ``requirements.txt``. + + Afterwards, activate the environment and re-run + + .. code-block:: console + + $ pip install -r requirements.txt + + to update the environment. + +Sometimes the new packages are incompatible with the ones already +in the environment. Maybe they have different dependencies that are +not satisfied with the current versions, maybe the package you're installing +is incompatible with the ones installed. In these cases the safest approach +is to re-create the environment. This will let the dependency solvers +to start from clean slate and with a full picture of what packages +need to be installed. + + +Pinning package versions +------------------------ + +Sometimes your code will only work with a certain range of dependencies. +Maybe you use a function or a class that was introduced in a later version +or a newer version has modified its API. + +In these situations, you'll want to **pin the package versions**. + +For example, there is usually a delay between doing research and that +research being published. During this time packages used in the research +might update and reviewers or interested researchers might not be able +to replicate your results or run your code if new versions are not +compatible. + +.. tabs:: + + .. group-tab:: environment.yml with pinned versions + + When pinning versions in ``environment.yml`` one can use a + variety of comparison operators: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + # Use python 3.11 + - python=3.11 + # numpy that is bigger or equal than version 1, but less than version 2 + - numpy>=1,<2 + # matplotlib greater than 3.8.2 + - matplotlib>3.8.2 + # pandas that is compatible with 2.1 + - pandas~=2.1 + + .. group-tab:: requirements.txt with pinned versions + + When pinning versions in ``requirements.txt`` one can use a + variety of comparison operators: + + .. code-block:: text + + # numpy that is bigger or equal than version 1, but less than version 2 + numpy>=1,<2 + # matplotlib greater than 3.8.2 + matplotlib>3.8.2 + # pandas that is compatible with 2.1 + pandas~=2.1 + +For more information on all possible specifications, see +`this page `__ +from Python's packaging guide. + +See also: https://coderefinery.github.io/reproducible-research/dependencies/ + +.. admonition:: To pin or not to pin? That is the question. + + Pinning versions means that you pin the environment to + **that instance in time** when these specific versions of the + dependencies were being used. + + This can be good for single-use applications, like replicating a research + paper, but it is usually bad for the long-term maintainability of the software. + + Pinning to major versions or to compatible versions is usually the best + practice as that allows your software to co-exist with other packages even + when they are updated. + + Remember that at some point in time you **will** face a situation where + newer versions of the dependencies are no longer compatible with your + software. At this point you'll have to update your software to use the newer + versions or to lock it into a place in time. + + +Exporting package versions from an existing environment +------------------------------------------------------- + +Sometimes you want to create a file that contains the exact versions +of packages in the environment. This is often called *exporting* or +*freezing* and environment. + +Doing this will create a file that does describe the installed +packages, but it won't tell which packages are **the most important +ones** and which ones are just dependencies for those packages. + +Using manually created ``environment.yml`` or ``requirements.txt`` +are in most cases better than automatically created ones because they +shows which packages are the important packages needed by the software. + +.. tabs:: + + .. group-tab:: Exporting environment.yml from a conda environment + + Once you have activated the environment, you can run + + .. code-block:: console + + $ conda env export > environment.yml + + If package build versions are not relevant for the use case, + one can also run + + .. code-block:: console + + $ conda env export --no-builds > environment.yml + + which leaves out the package build versions. + + Alternatively one can also run + + .. code-block:: console + + $ conda env export --from-history > environment.yml + + which creates the ``environment.yml``-file based on + what packages were asked to be installed. + + .. admonition:: conda-lock + + For even more reproducibility, you should try out + `conda-lock `__. + It turns your ``environment.yml`` into a ``conda.lock`` + that has all information needed to **exactly** create + the same environment. You can use ``conda.lock``-files + in same way as ``environment.yml`` when you create + an environment: + + .. code-block:: console + + $ conda env create --file conda.lock + + .. group-tab:: Exporting requirements.txt from a virtual environment + + Once you have activated the environment, you can run + + .. code-block:: console + + $ pip freeze > requirements.txt + + + +Exercise 4 +---------- + +.. challenge:: Dependencies-4: Export an environment (15 min) + + Export the environment you previously created. + + +Additional tips and tricks +-------------------------- + +.. tabs:: + + .. group-tab:: Creating a conda environment from requirements.txt + + conda supports installing an environment from ``requirements.txt``. + + .. code-block:: console + + $ conda env create --name my-environment --channel conda-forge --file requirements.txt + + To create an ``environment.yml`` from this environment that mimics + the ``requirements.txt``, activate it and run + + .. code-block:: console + + $ conda env export --from-history > environment.yml + + .. group-tab:: Adding pip packages into conda environments + + conda supports installing pip packages in an ``environment.yml``. + + Usually this is done to add those packages that are missing + from conda channels. + + To do this you'll want to install ``pip`` into the environment + and then add pip-installed packages to a list called ``pip``. + + See this example ``environment.yml``: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + - python + - pip + - pip: + - numpy + - matplotlib + - pandas + + One can even add a full ``requirements.txt`` to the environment: + + .. code-block:: yaml + + name: my-environment + channels: + - conda-forge + dependencies: + - python + - pip + - pip: + - "-r requirements.txt" + + Do note that in both methods the pip-packages come from PyPI + and not from conda channels. The installation of these packages + is done after conda environment is created and this can also + remove or update conda packages installed previously. + + .. group-tab:: Installing pip packages from GitHub + + Packages available in GitHub or other repositorios + can be given as a URL in ``requirements.txt``. + + For example, to install a development version of the + `black code formatter `__, one can + write the following ``requirement.txt``. + + .. code-block:: text + + git+https://github.com/psf/black + + or + + .. code-block:: text + + https://github.com/psf/black/archive/master.zip + + First one would use git to clone the repository, second would + download the zip archive of the repository. + + +How to communicate the dependencies as part of a report/thesis/publication +-------------------------------------------------------------------------- + +Each notebook or script or project which depends on libraries should come with +either a ``requirements.txt`` or a ``environment.yml``, unless you are creating +and distributing this project as Python package (see next section). + +- Attach a ``requirements.txt`` or a ``environment.yml`` to your thesis. +- Even better: put ``requirements.txt`` or a ``environment.yml`` in your Git repository along your code. +- Even better: also binderize your analysis pipeline (more about that in a later session). + + +.. _version_pinning: + +Version pinning for package creators +------------------------------------ + +We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in ``pyproject.toml`` (or ``setup.py``) +(PyPI) or ``meta.yaml`` (conda). + +These dependencies will then be used by either other libraries (who in turn +write their own ``setup.py`` or ``pyproject.toml`` or ``meta.yaml``) or by +people directly (filling out ``requirements.txt`` or a ``environment.yml``). + +Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from ``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy==1.19.2', + 'matplotlib==3.3.2' + 'pandas==1.1.2' + 'scipy==1.5.2' + ] + # ... + +or you can define a range or keep them undefined like here (example taken from +``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy', + 'matplotlib' + 'pandas' + 'scipy' + ] + # ... + +Should we pin the versions here or not? + +- Pinning versions here would be good for reproducibility. + +- However pinning versions may make it difficult for this library to be used in a project alongside other + libraries with conflicting version dependencies. + +- Therefore **as library creator make the version requirements as wide as possible**. + + - Set minimum version when you know of a reason: ``>=2.1`` + + - Sometimes set maximum version to next major version (``<4``) (when + you currently use ``3.x.y``) when you expect issues with next + major version. + +- As the "end consumer" of libraries, define your dependencies as narrowly as possible. + + +See also +-------- + +Other tools for dependency management: + +- `Poetry `__: dependency management and packaging +- `Pipenv `__: dependency management, alternative to Poetry +- `pyenv `__: if you need different Python versions for different projects +- `micropipenv `__: lightweight tool to "rule them all" +- `mamba `__: a drop in replacement for + conda that does installations faster. +- `miniforge `__: Miniconda alternative with + conda-forge as the default channel and optionally mamba as the default installer. +- `micromamba `__: + tiny version of Mamba as a static C++ executable. Does not need base environment or + Python for installing an environment. +- `pixi `__: a package management tool which builds upon the foundation of the conda ecosystem. + +Other resources: + +- https://scicomp.aalto.fi/scicomp/packaging-software/ + + +.. keypoints:: + + - If somebody asks you what dependencies your code has, you should be able to answer this question **with a file**. + - Install dependencies by first recording them in ``requirements.txt`` or + ``environment.yml`` and install using these files, then you have a trace. + - Use isolated environments and avoid installing packages system-wide. diff --git a/branch/master/_sources/exercises.md.txt b/branch/master/_sources/exercises.md.txt new file mode 100644 index 00000000..61028b90 --- /dev/null +++ b/branch/master/_sources/exercises.md.txt @@ -0,0 +1,12 @@ +# List of exercises + +## Full list + +This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests. + +```{exerciselist} +``` diff --git a/branch/master/_sources/guide.rst.txt b/branch/master/_sources/guide.rst.txt new file mode 100644 index 00000000..3dc6f602 --- /dev/null +++ b/branch/master/_sources/guide.rst.txt @@ -0,0 +1,125 @@ +Instructor's guide +================== + +Learner personas +---------------- + +A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don't know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren't sure if they +are going in the right direction. + +A2 can use numpy and pandas, but have learned little bits here and +there and hasn't had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages) + +B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves. + + +Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren't familiar. + +Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter + + + +About each section +------------------ + +In general, "Python for Scientific Computing could be a multi-year +course. We can't even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path. + +* **Python intro:** We can't really replace a Python tutorial, but + here we try to outline some of the main points. We don't go over + this in the course. + +* **Jupyter:** Jupyter is somewhat useful, but the main reason we go + over it is that it provides a convenient user interface for the + other programming lessons (it's easier to spend a bit of time with + Jupyter than expect people to be able to use some + editor/IDE/shell/etc). So, we do start from the beginning, so that + people can do the other lessons, but also try to teach some advanced + tips and tricks. + +* **Numpy:** The basic of much of the rest of scipy, so we need to + cover it. We try to get the main principles out, but if someone + already knows it this can be a bit boring. We try to make sure + everyone comes out with an appreciation for vectorization and + broadcasting. + +* **Pandas:** A lot of similar goals to the Numpy section, especially + the concepts behind Dataframes that one needs to know in order to + read other documentation. + +* **Visualization:** Matplotlib is getting a bit old, but is still the + backbone of other plotting packages. We try to get forth the ideas + of the matplotlib API that can be seen in other packages and the + importance of scripted plots. + +* **Data formats:** Input/output/storage is a common task, and can + easily either be a bottleneck or a huge mess. This lessons tries to + show some best practices with data formats and, as usual, get the + idea to not "do it yourself". Pandas is used as a common framework, + but we should point out there are plenty of other options. + +* **Scripts:** The most important lesson here is to break out of + Jupyter/run buttons of editors. If you can't make actual programs + with an actual interface, you can't scale up. + + * This is the first lesson to introduce the command line. We + recommend being as simple as possible: at least demonstrate the + JupyterLab terminal and discuss the bigger picture behind what it + means and why. + + * This is also the first lesson to use non-Jupyter code editor. We + recommend again being simple: use the JupyterLab code editor to + start off, and carefully explain what is going on. + +* **Scipy:** We don't cover much here (this is super short), but the + point is scipy exists and the concept of wrapping existing C/fortran + libraries and so on. + +* **Library ecosystem:** This was an overview of the types of packages + available in the "scipy ecosystem", which is a large and ill-defined + thing. But there is another point: choosing what to use. Do you + trust a half-done thing published on someone's personal webpage? If + it's on Github? How do you make your code more reusable? When + coming from academic courses, you get a "build it yourself" idea, + which isn't sustainable in research. + +* **Parallel programming:** + +* **Dependencies:** The main point here is environments, another thing + you often don't learn in courses. + + * There is a lot of material here. Consider what you will demo, + what will be done as exercises, and what is advanced/optional. + However, it is the fourth-day lesson that is most interactive, so + it is OK if it take a while to go through everything. + + * If someone else installs Anaconda for a user (e.g. admin-managed + laptop), the conda environment creations (with ``--name``, + possibly with ``--prefix`` too?) may not work. Be prepared for + this and mention it. You don't need to solve the problem but + acknowledge that the lesson becomes a demo. The virtualenv part + should hopefully work for them. + +* **Binder:** Binder exists and can help make code + reproducible/reusable by others. + +* **Packaging:** How to make your code reusable by others. By the + time we get here, people are tired and the topics get involved. We + more explicitly say "you might want to watch and take this as a + demo". + diff --git a/branch/master/_sources/index.rst.txt b/branch/master/_sources/index.rst.txt new file mode 100644 index 00000000..ac71a0a0 --- /dev/null +++ b/branch/master/_sources/index.rst.txt @@ -0,0 +1,238 @@ +=============================== +Python for Scientific Computing +=============================== + +.. admonition:: Attending the course 5-7 November, 2024? + + `See the course page here + `__ + and watch at https://twitch.tv/coderefinery. + Whether you are or aren't, the course material is below. Videos + will appear in `this playlist `__ (Last year's videos: `playlist `__). + + +Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, Matplotlib for visualization, and so on. In +addition, it talks about *how* python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write. + +This course (like any course) can't teach you Python... it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to. + +.. _prerequisites: + +.. prereq:: + + - Knowing basic Python syntax. We assume that you can do some + Python programming, but not much more that that. We don't cover + standard Python programming. `Here a short course on basic Python + syntax, with further references `__. + - Watch or read the `command line crash course + `__, if you aren't + familiar. + - You should be able to use a text editor to edit files some. + - The :doc:`software installation ` described below + (basically, anaconda). + + These are not prerequisites: + + - Any external libraries, e.g. numpy + - Knowing how to make scripts or use Jupyter + + +.. admonition:: Videos and archived Q&A + + Videos and material from past instances: + + * 2021: `this YouTube playlist + `__. + * 2022: `here + `__, + Q&A: `days 1-2 + `__, `days 3-4 + `__ + + * 2023: `Videos + `__ + + * 2024 (Please contact us if you would like to help to process the videos): `Videos `__ + + +.. csv-table:: + :widths: auto + :delim: ; + + (prereq) ; :doc:`python` + 30 min ; :doc:`jupyter` + 60 min ; :doc:`numpy` or :doc:`numpy-advanced` + 60 min ; :doc:`pandas` + 30 min ; :doc:`xarray` + 60 min ; :doc:`plotting-matplotlib` + 60 min ; :doc:`plotting-vega-altair` + 30 min ; :doc:`work-with-data` + 60 min ; :doc:`scripts` + 40 min ; :doc:`profiling` + 20 min ; :doc:`productivity` + 30 min ; :doc:`web-apis` + 15 min ; :doc:`scipy` + 30 min ; :doc:`libraries` + 45 min ; :doc:`parallel` + 45 min ; :doc:`dependencies` + 30 min ; :doc:`binder` + 60 min ; :doc:`packaging` + + +.. toctree:: + :maxdepth: 1 + :caption: The lesson + :hidden: + + python + jupyter + numpy + numpy-advanced + pandas + xarray + plotting-matplotlib + plotting-vega-altair + work-with-data + scripts + profiling + productivity + scipy + libraries + dependencies + binder + parallel + packaging + web-apis + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + installation + quick-reference + exercises + guide + data-formats + + +.. _learner-personas: + +Who is the course for? +====================== + +The course is targeted towards these learner personas: + +* A is a early career PhD researcher who has been using Python a bit, + but is not sure what they know or don't know. They want to be able + to do their research more efficiently and make sure that they are + using the right tools. A may know that numpy exists, etc. and could + theoretically read some about it themselves, but aren't sure if they + are going in the right direction. + +* A2 can use numpy and pandas, but have learned little bits here and + there and hasn't had a comprehensive introduction. They want to + ensure they are using best practices. (Baseline of high-level + packages) + +* B is a mid-to-late undergraduate student who has used Python in some + classes. They have possibly learned the syntax and enough to use it + in courses, but in a course-like manner where they are expected to + create everything themselves: they want to know how to reuse tools + that already exist. + + +Motivation +========== + +Why Python +---------- + +Python has become popular, largely due to good reasons. It's very easy +to get started, there's lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities. + + +Why not Python for Scientific Computing +--------------------------------------- + +While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools. + +- Implementing performance-critical kernels. Python is a **very** + slow language, which often doesn't matter if you can offload the + heavy lifting to fast compiled code, e.g. by using Numpy array + operations. But if what you're trying to do isn't *vectorizable* + then you're out of luck. An alternative to Python, albeit much less + mature and with a smaller ecosystem, but which provides very fast + generated code, is *Julia*. + +- Creating libraries that can be called from other languages. In this + case you'll often want to create a library with a C interface, which + can then be called from most languages. Suitable languages for this + sort of task, depending on what you are doing, could be Rust, C, + C++, or Fortran. + +- You really like static typing, or functional programming + approaches. *Haskell* might be what you're looking for. + + +Python 2 vs Python 3 +-------------------- + +Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard. + +At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2. + + + +Credits +======= + +This course was originally designed by Janne Blomqvist. + +In 2020 it was completely redesigned by a team of the following: + +* Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, ... +* Editor: +* Testers and advisors: Enrico Glerean + +We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html + + +See also +======== + +* `High Performance Data Analytics in Python + `__ is a logical follow-up to + this lesson that goes more in-depth to tools of high-performance + and large-scale Python. diff --git a/branch/master/_sources/installation.rst.txt b/branch/master/_sources/installation.rst.txt new file mode 100644 index 00000000..9232223b --- /dev/null +++ b/branch/master/_sources/installation.rst.txt @@ -0,0 +1,444 @@ +Software installation +===================== + +This course is interactive and demonstrates many different tools. +Thus, even beyond Python, extra software (Python libraries) needs to +be installed. This page contains the instructions. + +**Once the course starts, we don't have time to stop for installing +software.** + +Please make sure before the course that you have all the required +software installed or some other way access to it. For example, the +workshop could be done with a remote Jupyter server, as long as you +can use the terminal from the Jupyter (you need to be able to access +the command line for some lessons). + +.. admonition:: Do you need help? + :class: important + + Participants from a partner institution are invited to install help + sessions. (Hint: ask your institution to become a partner if it + isn't already!) + + Otherwise, if you need installation help, show this page to someone + around you and they can probably help. These are relatively + standard tools. + + Don't be afraid to ask for help. Installing scientific software is + *harder than it should be* and it helps to have someone guide you + through it. + +.. highlight:: console + + + +Python +------ + +We expect you to have a working Python installation with some common +libraries. **We currently recommend Miniforge, which includes the base and +packages through a different, freely usable channel.** You can +explore the options in the tabs below. + +.. admonition:: Python, conda, anaconda, miniforge, etc? + :class: dropdown + + Unfortunately there's a lot of jargon. We'll go over this in the + course but here is a crash course: + + * **Python** is a programming language very commonly used in + science, it's the topic of this course. + * **Conda** is a package manager: it allows distributing and + installing packages, and is designed for complex scientific + code. + * **Mamba** is a re-implementation of Conda to be much faster with + resolving dependencies and installing things. + * An **Environment** is a self-contained collections of packages + which can be installed separately from others. They are used so + each project can install what it needs without affecting others. + * **Anaconda** is a commercial distribution of Python+Conda+many + packages that all work together. It used to be freely usable for + research, but since ~2023-2024 it's more limited. Thus, we don't + recommend it (even though it has a nice graphical user interface). + * **conda-forge** is another channel of distributing packages that + is maintained by the community, and thus can be used by anyone. + (Anaconda's parent company also hosts conda-forge packages) + * **miniforge** is a distribution of conda pre-configured for + conda-forge. It operates via the command line. + * **miniconda** is a distribution of conda pre-configured to use + the Anaconda channels. + +.. tabs:: + + .. group-tab:: Miniforge + + This is our recommended method - it can be used for any purpose + and makes a strong base for the future. + + Follow the `instructions on the miniforge web page + `__. This installs + the base, and from here other packages can be installed. + + .. + You can read how to install miniconda from the `CodeRefinery + installation instructions + `__. + + Miniforge uses the command line - this gives you the most power + but can feel unfamiliar. See the `command line crash course + `__ for an intro. + + .. group-tab:: Anaconda + + Anaconda is easier to get started with, but may be more limiting + in the future. The Anaconda Navigator provides a graphical + interface to most of what you would need. + + The `Anaconda Python distribution + `__ conveniently packages + everything, but its license has does not allow large organizations to + use it for free (and has actually been enforced against + universities). + + Note the license of Anaconda - there were recently issues with + it being used by large universities for free, and this is not + yet fully resolved. + + .. group-tab:: Other options + + There are many ways to install Python. Other methods can work, + as long as you can install the libraries from the + ``environment.yml`` file mentioned in the Miniforge + instructions. + + We don't currently provide a ``requirements.txt`` for installing + the required packages without Conda/Mamba, though. + + + +Starting Python +--------------- + +You need to Python in a way that activates conda/mamba. + +.. tabs:: + + .. group-tab:: Miniforge + + .. tabs:: + + .. group-tab:: Linux / MacOS + + Linux/MacOS: Each time you start a new command line terminal, + you can activate Miniforge by running. This is needed so that + Miniforge is usable wherever you need, but doesn't affect any + other software on your computer (this is not needed if you + choose "Do you wish to update your shell profile to + automatically initialize conda?", but then it will always be + active):: + + $ source ~/miniforge3/bin/activate + + .. group-tab:: Windows + + Windows: Use the "Miniforge Prompt" to start Miniforge. This + will set up everything so that ``conda`` and ``mamba`` are + available. + + .. group-tab:: Anaconda + + The `Anaconda Navigator + `__ provides a convenient + way to access the software. It can be installed from that page. + + + .. group-tab:: Other options + + You are on your own here. + + +Python for SciComp software environment +--------------------------------------- + +Once Python and conda/mamba are installed, you can use it to install +an environment. An **environment** is a self-contained set of extra +libraries - different projects can use different environments to not +interfere with each other. This environment will have all of the +software needed for this particular course. + +.. tabs:: + + .. group-tab:: Miniforge + + This `environment file + `__ + contains all packages needed for the course, and can be + installed with. The following command will install an + environment named ``python-for-scicomp`` (there may be lots of + warning messages: this is OK if it still goes through): + + .. tabs:: + + .. group-tab:: Linux / MacOS + + :: + + $ mamba env create -n python-for-scicomp -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + .. group-tab:: Windows + + :: + + $ mamba env create -n python-for-scicomp -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + Each time you start a new command line, you need to activate + miniforge and this environment: + + .. tabs:: + + .. group-tab:: Linux / MacOS + + :: + + $ source ~/miniforge3/bin/activate + $ conda activate python-for-scicomp + + .. group-tab:: Windows + + :: + + $ # Start the Miniforge Prompt. + $ conda activate python-for-scicomp + + .. group-tab:: Anaconda + + Anaconda includes most of the things needed for the course + automatically, but as of 2024 not everything. You can use the + navigator to create new environments from this `this environment + file + `__. + You'll have to download it and then `import it + `__. + + When running this course's exercise, make sure the + ``python-for-scicomp`` environment is activated before starting + JupyterLab or any code. You need to start termnials or + JupyterLab from the Anaconda Navigator for the + ``python-for-scicomp`` environment to be used. + + .. group-tab:: Other options + + **Minoconda, Anaconda command line, other conda/mamba command + line tools**: see "Miniforge" instructions. + + Virtual environments: we don't currently provide a + ``requirements.txt`` but many package names can probably be + copied from the ``environment.yml`` file. We really recommend + conda/mamba based systems: it's designed for complex scientific + software. + + Any other Python distribution which you can install libraries into + would work, but because there are so many different ways to do this, + we don't support them. You would need the extra libraries mentioned + in the Miniforge instructions. + + Remember you need to activate the environment each time you use it. + + + +JupyterLab +---------- + +We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). + +.. tabs:: + + .. group-tab:: Miniforge + + JupyterLab was instaled in the previous step. To run it, first, + start the Miniforge command line interface. Remember, you may + need to activate Miniforge and the environment first. + + .. tabs:: + + .. group-tab:: Linux / MacOS + + :: + + $ source ~/miniforge3/bin/activate + $ conda activate python-for-scicomp + $ jupyter-lab + + .. group-tab:: Windows + + :: + + $ # Start the Miniforge Prompt. + $ conda activate python-for-scicomp + $ jupyter-lab + + .. group-tab:: Anaconda + + If you install the full Anaconda distribution, this will be + available and can be started either through Anaconda Navigator + or command line. + + Make sure the ``python-for-scicomp`` environment is selected and + you can start JupyterLab. + + + +Verification of Python and JupyterLab +------------------------------------- + +.. admonition:: Watch the video + + See this `verification in video form + `__ - if you can do this, you are + ready to go for day one. Your exact steps may be a bit different. + + Remember that you need to activate the environment first - see the + step above. + +.. tabs:: + + .. group-tab:: Miniforge + + You can start JupyterLab from the command line:: + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + .. group-tab:: Anaconda + + **You should be able to start JupyterLab.** You can do this from the + `Anaconda Navigator `__ (recommended if you have it): + + .. figure:: img/installation/anaconda-navigator-jupyterlab.png + :class: with-border + + Starting JupyterLab from the Anaconda Navigator. + + ... or you can start JupyterLab from the command line:: + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + +**Verify that you can start a Jupyter notebook.** We will learn how to +do this in day 1, but you can try running ``print("Hello, world!")`` +if you want. + +.. figure:: img/installation/jupyterlab-notebook.png + :class: with-border + + Starting a Jupyter Notebook from JupyterLab. + + + +Text editor +----------- + +For one portion of the course, you will need a text editor. **If you +don't know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.** + +.. admonition:: Other editors + :class: toggle + + Because we need to be simple in our teaching, we only teach the + most basic editors. We encourage you to try out more advanced ones + yourself. + + For other editors, see the `CodeRefinery instructions + `__. You don't + exactly need a terminal editor - the graphical ones, such as VSCode or + whatever you use now, will work as well. + + + +Command line +------------ + +**You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed.** If you want to +test in advance: + +* You can start it from JupyterLab (recommended): + + .. figure:: img/installation/jupyterlab-terminal.png + :class: with-border + :scale: 75% + + From the JupyterLab launcher, select "Terminal". + +.. admonition:: Other ways to access the command line + :class: toggle + + * From the Anaconda Navigator: + + .. figure:: img/installation/anaconda-prompt.png + :class: with-border + + From the Anaconda Navigator, you can select "environments" on the + left, then click on one, then the arrow, then "Open terminal". + + * From your operating system's terminal applications, if you activate + Anaconda. + + + +Verification of the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify command line usage, type the following commands (without the +``$``), and you should see the corresponding output that lists the +Python version: + +.. code-block:: console + + $ python3 -V + Python 3.8.3 + + ## Or python... if it's installed as that + $ python -V + Python 3.8.3 + +Any recent version of Python 3 should work for the course (for example +3.8 or higher). + + + +Zoom +---- + +If this is an online workshop, it might use Zoom. You can see +`CodeRefinery instructions for it +`__. + + + +Need help? +---------- + +If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up! + + + +See also +-------- + +* `Research Software Hour on conda + `__ +* `Conda manual `__ (technical) +* `Anaconda individual edition home + `__ +* `Anaconda getting started + `__ diff --git a/branch/master/_sources/jupyter.ipynb.txt b/branch/master/_sources/jupyter.ipynb.txt new file mode 100644 index 00000000..16aa6435 --- /dev/null +++ b/branch/master/_sources/jupyter.ipynb.txt @@ -0,0 +1,471 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter\n", + "\n", + "\n", + "```{questions}\n", + "\n", + " - What is the purpose of a \"Computational narrative\"?\n", + " - What role does Jupyter play in development?\n", + " - When is Jupyter not a good tool?\n", + "```\n", + "\n", + "```{objectives}\n", + "\n", + " This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.\n", + "\n", + " - Be able to use Jupyter to run examples for the rest of the course.\n", + " - Be able to run Jupyter in a directory do your own work.\n", + " - You won't be a Jupyter expert after this, but should be able to do the rest of the course.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is Jupyter?\n", + "\n", + "Jupyter is a web-based interactive computing system. It is most well known for having the *notebook file format* and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a *computational narrative*.\n", + "\n", + "Jupyter is good for data exploration and interactive work.\n", + "\n", + "**We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.**\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting started with Jupyter\n", + "\n", + "* Start JupyterLab: there are different ways, depending on how you installed it. See the [installation instructions](https://aaltoscicomp.github.io/python-for-scicomp/installation/). If JupyterLab isn't working yet, you have some time to try to follow the installation instructions now.\n", + "\n", + "```````{tabs}\n", + "``````{group-tab} Miniforge\n", + "This is the command line method we went though in our installation instructions.\n", + "`````{tabs}\n", + "````{group-tab} Linux / MacOS\n", + "```console\n", + "$ source ~/miniforge3/bin/activate\n", + "$ conda activate python-for-scicomp\n", + "$ jupyter-lab\n", + "```\n", + "````\n", + "````{group-tab} Windows\n", + "Start the Miniforge Prompt applicaiton first, then:\n", + "```console\n", + "$ conda activate python-for-scicomp\n", + "$ jupyter-lab\n", + "```\n", + "````\n", + "``````\n", + "``````{group-tab} Anaconda\n", + "If you install the full Anaconda distribution, start the Anaconda Navigator. Make sure the ``python-for-scicomp`` environment is selected and you can start JupyterLab.\n", + "``````\n", + "``````{group-tab} Other\n", + "If you have installed Python and the workshop's requiremnts some other way, you hopefully know how to activate that Python and the Python for SciComp software environment and start JupyterLab.\n", + "\n", + "If not, see the [installation instructions](https://aaltoscicomp.github.io/python-for-scicomp/installation/).\n", + "``````\n", + "```````\n", + "\n", + "\n", + "For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here, we see a tour of the JupyterLab interface:\n", + "\n", + "![Main UI tour](img/jupyter/main-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 1\n", + "```{challenge} Exercises: Jupyter-1\n", + "\n", + " If you aren't set up with JupyterLab yet or these things don't work, use this time to see the [installation instructions](https://aaltoscicomp.github.io/python-for-scicomp/installation/) and ask us any questions you may have.\n", + "\n", + " 1. Start Jupyter in the directory you want to use for this course.\n", + " - If you are using Miniforge from the command line, you can navigate with `cd` to a directory of your choice.\n", + " - If you are starting from the Anaconda Navigator, change to the directory you want to use.\n", + "\n", + " 2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.\n", + "\n", + " 4. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.\n", + "\n", + " 5. (optional, advanced) Look at the notebook file in a text\n", + " editor. How does it work?\n", + "\n", + "If everything works for you, this will end very quickly. You can begin reading the next sections independently.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Running code in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A notebook is divided into **cells**. Each cell has some **input**, and when it is executed an **output** appears right below it.\n", + "\n", + "There are different types of cells: primarily **code** cells and **markdown** cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/). For example the previous sentence is:\n", + "\n", + "```none\n", + "Markdown is a lightweight way of giving *style* to `text` - you \n", + "can check out [this reference](https://commonmark.org/help/).\n", + "```\n", + "\n", + "![notebook UI](img/jupyter/notebook-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When using keyboard shortcuts, you can switch between edit mode and command mode with `Enter` and `Esc`. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:\n", + "* `Ctrl-Enter`: Run cell\n", + "* `Shift-Enter`: Run cell and select cell below\n", + "* `Alt-Enter`: Run cell and insert new cell below\n", + "* `a` / `b`: insert new cell above/below\n", + "* `m` / `y`: markdown cell / code cell\n", + "* `x`: cut cell\n", + "* `c`: copy cell\n", + "* `v`: paste cell\n", + "* `d, d`: delete cell" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, let's look at some code samples:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0\n", + "1\n", + "2\n" + ] + } + ], + "source": [ + "for i in range(3):\n", + " print(i)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "10\n" + ] + } + ], + "source": [ + "print(sum(range(5)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By convention, if the last thing in a cell is an object, that object gets printed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "45" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sum(range(5))\n", + "sum(range(10))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to raw cells, there are **magics**, which exist outside of Python. They are a property of the runtime itself (in Python's case, they come from **IPython**. For example, the following cell magic [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) will use the {py:mod}`timeit` module to time a cell by running it multiple times):" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "54.1 ms ± 993 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "for x in range(1000000):\n", + " x**2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Another example is [%%bash](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-bash) which will turn the cell into a shell script (This will only work on operating systems with the Bash shell installed - MacOS and Linux at least):" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1\n", + "2\n", + "3\n" + ] + } + ], + "source": [ + "%%bash\n", + "for x in $(seq 3) ; do\n", + " echo $x\n", + "done" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "* A **cell magic** starts with `%%`, goes on the first line of a cell, and applies to the whole cell\n", + "* A **line magic** starts with `%`, goes on any line, and applies to that line." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "```{challenge} Exercises: Jupyter-2\n", + "\n", + " 1. Run some trivial code, such as ``print(1)``.\n", + "\n", + " 2. Run some slightly less trivial code, like print out the first\n", + " ten [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number).\n", + "\n", + " 3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the [reference](https://commonmark.org/help/) to add a heading, bullet list, and some (bold, italic, or inline code)\n", + "\n", + " 4. Use the [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) magic function to time your Fibonacci\n", + " function.\n", + "\n", + " 5. Again using ``%%timeit``, figure out the fastest way to sum the\n", + " numbers 0 to 1000000.\n", + " \n", + " 6. Once you are done, close your notebooks and other tabs you don't need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.\n", + "```\n", + "\n", + "`````{solution} Solutions: Jupyter-2\n", + "\n", + "1. --\n", + "\n", + "2. Simple fibonacci code\n", + "\n", + " ```python\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " print(a)\n", + " a, b = b, a+b\n", + " ```\n", + "\n", + "3. Markdown description\n", + "\n", + " ```md\n", + " # Fibonacci\n", + " * Start with two variables `a` and `b`\n", + " * Repeat 10 times\n", + " * Print old `a`, then increment both\n", + " * Makes use of the Python *tuple assignment*: `a, b = new_a, new_b`\n", + " ```\n", + "\n", + "4. In this case, the print() statements get out of hand, so we comment that out. In general, writing output usually takes a lot of time reletive to the computation, so we don't want to time that (unless output is the main point of the code, then we do have to time it!\n", + "\n", + " ```ipython\n", + " %%timeit\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " #print(a)\n", + " a, b = b, a+b\n", + " ```\n", + " ```none\n", + " 395 ns ± 10.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n", + " ```\n", + "\n", + "5. --\n", + "\n", + "6. --\n", + "\n", + "`````" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why Jupyter?\n", + "\n", + "- Being able to **edit, check, re-edit** quickly is great for **prototyping and testing new ideas**\n", + " - Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.\n", + "- You can make a **complete story** - in one place. No more having code, figures, and description in different places.\n", + " - Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.\n", + "- Notebook as an interactive publication itself - for example the discovery of gravitational waves data is [released as a notebook](https://www.gw-openscience.org/tutorials/).\n", + "- Jupyter Notebooks display on Github - low-barrier way to share your analysis.\n", + "- Teaching - great for getting difficult software distribution out of the way." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why not Jupyter?\n", + "\n", + "Jupyter is great for many things, but there are some problems if not used well:\n", + "\n", + "- They **don't promote modularity**, and once you get started in a\n", + " notebook it can be hard to migrate to modules.\n", + "- They are **difficult to test**. There are things to run notebooks as\n", + " unit tests like [nbval](https://nbval.readthedocs.io/), but it's not\n", + " perfect.\n", + "- Notebooks can be **version controlled**\n", + " ([nbdime](https://nbdime.readthedocs.io/) helps with that), but\n", + " there are **still limitations**.\n", + "- You can **change code after you run it** and run code out of order.\n", + " This can make debugging hard and results irreproducible if you\n", + " aren't careful.\n", + "- Notebooks **aren't named by default** and tend to **acquire a bunch of\n", + " unrelated stuff**. Be careful with organization!\n", + "- Once lots of code is in notebooks, it can be **hard to change to\n", + " proper programs that can be scripted**.\n", + "\n", + "You can read more about these downsides .\n", + "\n", + "**But these downsides aren't specific to Jupyter!** They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "```{challenge} Exercises: Jupyter-3\n", + "\n", + " (optional) Discuss the following in groups:\n", + "\n", + " 1. Have any of you used Jupyter in a way that became impossible to\n", + " maintain: too many files, code all spread out, not able to find\n", + " your code and run it in the right order. How did you solve that?\n", + "\n", + " 2. On the other hand, what are your successes with Jupyter?\n", + " \n", + " 3. How can you prevent these problems by better development strategies?\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## See also\n", + "\n", + "- The [CodeRefinery Jupyter lesson](https://coderefinery.github.io/jupyter/) has much more, and the source of some of the content above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{keypoints}\n", + "\n", + " - Jupyter is powerful and can be used for interactive work\n", + " - ... but not the end solution when you need to scale up.\n", + "```" + ] + } + ], + "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.12.7" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/master/_sources/libraries.rst.txt b/branch/master/_sources/libraries.rst.txt new file mode 100644 index 00000000..72473aa8 --- /dev/null +++ b/branch/master/_sources/libraries.rst.txt @@ -0,0 +1,353 @@ +Library ecosystem +================= + +.. questions:: + + - What happens when you need some method beyond what we discuss in this course, what is available? + - How do you decide what to build on for your work? + +.. objectives:: + + - Know of some other available packages, but don't necessarily know + how to use them. + - Be able to evaluate what you should reuse and what you should + develop yourself. + +You can't do everything yourself. In fact, once we heard a quote such +as this: + + When you are a student, you are expected to do everything + yourself, and that is how you are evaluated. When you become a + researcher, you *have* to be able to reuse what others have done. + We don't have much practice in doing this. + -- A student + +In this lesson, we'll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types: + +- Well-maintained libraries that are used by many others. +- A wide variety of public code that might work but isn't necessarily + well-maintained (for example, code from articles). + +We'll start with the first then go to the second. + + + +Glossary +-------- + +Library + A collection of code used by a program. + +Package + A library that has been made easily installable and reusable. + Often published on public repositories such as the `Python Package + Index `__ + +Dependency + A requirement of another program, not included in that program. + + + +The Python/SciPy ecosystem +-------------------------- + +This section is nothing more than a tour of what exists in Python. +You aren't expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work. + +The "core" packages `could be considered +`__. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy): + +* Python +* Numpy - arrays, everything builds on this +* Scipy - scientific functions (not necessarily a lot builds on this) +* matplotlib - plotting, many other plotting tools build on this +* pandas - data structures +* IPython / Jupyter: interactive work + + + +Core numerics libraries +~~~~~~~~~~~~~~~~~~~~~~~ + +* `numpy `__ - arrays and array math. +* `scipy `__ - software + for math, science, and engineering. + + + +Plotting +~~~~~~~~ + +* `matplotlib `__ - base plotting package, + somewhat low level but almost everything builds on it. +* `seaborn `__ - higher level plotting + interface; statistical graphics. +* `mayavi `__ - 3D plotting +* `PIL `__ - image manipulation. The + original PIL is no longer maintained, the new "Pillow" is a drop-in + replacement. + + + +Data analysis and other important core packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `pandas `__ - columnar + data analysis +* `statsmodels `__ - just what it says +* `SymPy `__ - symbolic math +* `networkx `__ - graph and network analysis +* `h5py `__ and `PyTables `__ - interfaces to + the `HDF5 `__ on-disk file format +* `dateutil `__ and `pytz + `__ - date arithmetic and handling, + timezone database and conversion + + + +Interactive computing and human interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Interactive computing + + * `IPython `__ - nicer interactive interpreter + * `Jupyter `__ (notebook, lab, hub, ...) - + web-based interface to IPython and other languages + +* Testing + + * `pytest `__ - automated testing interface + +* Documentation + + * `Sphinx `__ - documentation generator + (also used for this lesson...) + +* Development environments + + * `Spyder `__ - interactive Python + development environment. + +* `Binder `__ - load any git repository in + Jupyter automatically, good for reproducible research + + + +Speeding up code and parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `PyMPI `__ - Message + Passing Interface (MPI) in Python for parallelizing jobs. +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `numba `__ - just in time compiling of + functions for speed-up +* `PyPy `__ - Python written in Python so that + it can internally optimize more. +* `Dask `__ - distributed array data structure for + distributed computation +* `Joblib `__ - easy embarrassingly + parallel computing +* `IPyParallel `__ - easy + parallel task engine +* `numexpr `__ - Fast evaluation of + array expressions by automatically compiling the arithmetic. + + + +Machine learning +~~~~~~~~~~~~~~~~ + +If you need some machine learning, you probably already know what you +need and this list is short and irrelevant. + +- `tensorflow `__ +- `pytorch `__ +- `nltk `__ - natural language processing +- `scikit-learn `__ - simple tools for + predictive data analysis + + + +Connecting Python to other languages +------------------------------------ + +As we discussed with Scipy, very many of the above packages aren't +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things: + +* **Extending Python** by writing your own modules in C. + + * It's actually common to first have (or write) an analysis package + in C or C++, then make the Python interface. Then it can be + supported by other languages, too. + + * Or one starts an analysis package in Python, and slowly moves bits + of it to C over time as there is need. + +* **Embedding Python**, where you have another primary application + that uses Python under the hood as an internal scripting language. + +These features aren't exactly unique to Python, but Python does +support them very well. Read more: `Extending and embedding Python +`__. + + + +Tools for interfacing with other languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These days, one rarely directly extends the Python interpreter, but uses + +* `cffi `__ and `ctypes + `__ - interface to C + and compatible libraries +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `f2py `__ - interface to Fortran + code +* `swig `__ - connect to a variety of programming languages. +* ``Boost.python`` - Another Python/C++ interface +* TODO: Julia modules for Python? + + + +Evaluating Python packages for reuse +------------------------------------ + +Above, we talked about well-maintained mainstream packages. **Do you +trust random code you find online (for example included in a paper)?** + +Especially consider scientific results, which *have* to be correct. +Still, you also *can't* build everything yourself, so you have to +carefully evaluate the situation. + +Below are some things to consider: + +* Are there releases? Have they been going on for a while? + +* Are releases installable without copy-paste? + +* Are dependencies handled well? + +* Does the code randomly change, so that it no longer works with your + code. Is this relevant? + +* Is there good documentation, that not just tells how to use it but + how it works? + +* Is there automated testing? What's your evaluation of the risk of + undetectable scientific errors? + +* Is there a community, or is it one person? Is it backed by some + organization? Does it have a permanent home? + +* Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) + where a community *could* form? + +* Do others post issues and make contributions? Are these issues + dealt with in a timely manner? Can you search past bug reports? + +* Is the software citeable? + + + +Is your work reuseable? +----------------------- + +Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a `CodeRefinery workshop `__ will make +sure you have the tools to produce high-quality, reusable code. + + + +What's next? +------------ + +* The `CodeRefinery workshop `__ mentioned + above will prepare you for others to reuse your code and for you to + contribute to other code. +* The upcoming :doc:`dependencies` lesson will teach you how to + record and manage dependencies so that anyone can seamlessly reuse + your code. + + + +Exercises +--------- + +.. exercise:: Libraries 1.1: Libraries in your work + + What libraries do you use in your work? What have you made, which + you could have reused from some other source. What have you used + from some other source that you wished you had re-created? + + Discuss in your groups or HackMD. + +.. solution:: Libraries 1.1 + + ... is there anything to say here? + + +.. exercise:: Libraries 1.2: Evaluating packages + + Below are some links to some packages, both public and made by the + authors of this lesson. Evaluate them, considering "would I use + this in my project?" + + a) https://github.com/networkx/networkx/ + b) some code on webpage in a paper's footnote + c) https://github.com/rkdarst/pcd + d) https://github.com/dftlibs/numgrid + e) https://github.com/rkdarst/dynbench + f) https://vpython.org/ + +.. solution:: Libraries 1.2 + + a) networkx: This seems to be a relatively large, active project + using best practices. Probably usable. + b) I would probably use it if I had to, but would prefer not to. + c) This (written by one of the authors of this lesson) has no + documenting, no community, no best practices, and is very old. + Probably not a good idea to try to use it + d) This project uses best practices, but doesn't seem to have a big + community. It's probably fine to use, but who knows if it will + be maintained 10 years from now. It does have automated tests + via Github Actions (``.github/workflows`` and the green checks), + so the authors have put some work into making it correct. + e) This (also written by one of the authors) looks like it was made + for a paper of some sort. It has some minimal documentation, + but still is missing many best practices and is clearly not + maintained anymore (look at the ancient pull request). Probably + not a good idea to use unless you have to. + f) This project has a pretty website, and some information. But + seems to not be using best practices of an open repository, and + custom locations which could disappear at any time. + + You notice that several of the older projects here were written by + one of the authors of this lesson. It goes to show that everyone + starts somewhere and improves over time - don't feel bad if your + work isn't perfect, as long as you keep trying to get better! + + + +See also +-------- + +* `Topical Software in the SciPy ecosystem + `__ - relatively + detailed (but not comprehensive) list of projects + + +.. keypoints:: + + - Almost everything you need can already be found, except your + incremental work. + - When do you build on that other work, and when do you create + things yourself? diff --git a/branch/master/_sources/numpy-advanced.rst.txt b/branch/master/_sources/numpy-advanced.rst.txt new file mode 100644 index 00000000..8df6552c --- /dev/null +++ b/branch/master/_sources/numpy-advanced.rst.txt @@ -0,0 +1,407 @@ +Advanced NumPy +============== + +.. questions:: + + - How can NumPy be so fast? + - Why are some things fast and some things slow? + - How can I control whether NumPy makes a copy or operates in-place? + +.. objectives:: + + - Understand why NumPy has so many specialized functions for specific operations + - Understand the underlying machinery of the Numpy :class:`~numpy.ndarray` object + - Understand when and why NumPy makes a copy of the data rather than a view + + This is intended as a follow-up to the :doc:`basic NumPy lesson `. The intended + audience for this advanced lesson is those who have used NumPy before and + now want to learn how to get the most out of this amazing package. + + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +`Guide to NumPy `_ by +Travis E. Oliphant, its initial creator. + + + +NumPy can be really fast +------------------------ + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast. + +.. highlight:: c + +How fast can NumPy be? Let's race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:: + + #include + #include + #define N_ELEMENTS 100000000 + int main(int argc, char** argv) { + double* a = (double*) malloc(sizeof(double) * N_ELEMENTS); + int i; + for(i=0; i` before continuing with this + advanced lesson. If you are taking a live course - don't + worry, watch and learn and explore some during the exercises! + +.. solution:: Solutions: Numpy-Advanced-1 + + The script can be implemented like this:: + + import numpy as np + print(np.random.rand(100_000_000).sum()) + + +.. highlight:: python + +The libraries behind the curtain: MKL and BLAS +---------------------------------------------- + +NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel's `Math Kernel Library (MKL) `_, +which are in turn derived from a Fortran library called +`Basic Linear Algebra Subprograms (BLAS) `_. +BLAS for Fortran was `published in 1979 `_ +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +`specialized CPU instructions for manipulating arrays `_. +In other words, they are *fast*. + +One of the functions inside the BLAS library is a +`function `_ +to compute the "norm" of a vector, which is the same as computing its length, using the +`Pythagorean theorem `_: +:math:`\sqrt(a[0]^2 + a[1]^2 + \ldots)`. + +Let's race the BLAS function versus a naive "manual" version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:: + + import numpy as np + rng = np.random.default_rng(seed=0) + a = rng.random(100_000_000) + +We now implement the Pythagorean theorem using basic NumPy functionality and +use ``%%timeit`` to record how long it takes to execute:: + + %%timeit + l = np.sqrt(np.sum(a ** 2)) + print(l) + +And here is the version using the specialized BLAS function :func:`~numpy.linalg.norm`:: + + %%timeit + l = np.linalg.norm(a) + print(l) + + +NumPy tries to avoid copying data +---------------------------------- + +Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy's +:class:`numpy.ndarray` datastructure works behind the scenes. + + +An example: matrix transpose +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let's see how long NumPy's +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +:func:`~numpy.random.rand` matrix:: + + import numpy as np + a = np.random.rand(10_000, 20_000) + print(f'Matrix `a` takes up {a.nbytes / 10**6} MB') + +Let's time the :meth:`~numpy.ndarray.transpose` method:: + + %%timeit + b = a.transpose() + +It takes mere nanoseconds to transpose 1600 MB of data! How? + + +The ndarray exposed +~~~~~~~~~~~~~~~~~~~ +The first thing you need to know about :class:`numpy.ndarray` is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector. + +.. image:: img/numpy-advanced/01_memory_layout.svg + +NumPy is faking the second dimension behind the scenes! When we request the +element at say, ``[2, 3]``, NumPy converts this to the correct index in the +long 1D array ``[11]``. + + * Converting ``[2, 3]`` → ``[11]`` is called "raveling" + * The reverse, converting ``[11]`` → ``[2, 3]`` is called "unraveling" + +The implications of this are many, so take let's take some time to understand +it properly by writing our own ``ravel()`` function. + +Exercise 2 +---------- + +.. challenge:: Exercises: Numpy-Advanced-2 + + Write a function called ``ravel()`` that takes the row and column of an + element in a 2D matrix and produces the appropriate index in an 1D array, + where all the rows are concatenated. See the image above to remind yourself + how each row of the 2D matrix ends up in the 1D array. + + The function takes these inputs: + + - ``row`` The row of the requested element in the matrix as integer index. + - ``col`` The column of the requested element in the matrix as integer index. + - ``n_rows`` The total number of rows of the matrix. + - ``n_cols`` The total number of columns of the matrix. + + Here are some examples of input and desired output: + + - ``ravel(2, 3, n_rows=4, n_cols=4)`` → ``11`` + - ``ravel(2, 3, n_rows=4, n_cols=8)`` → ``19`` + - ``ravel(0, 0, n_rows=1, n_cols=1)`` → ``0`` + - ``ravel(3, 3, n_rows=4, n_cols=4)`` → ``15`` + - ``ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000)`` → ``69_318_923`` + +.. solution:: Solutions: Numpy-Advanced-2 + + The function can be implemented like this:: + + def ravel(row, col, n_rows, n_cols): + return row * n_cols + col + +Strides +------- + +As seen in the exercise, to get to the next row, we have to skip over +``n_cols`` indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of "strides":: + + np.zeros((4, 8)).strides # (64, 8) + np.zeros((4, 5, 6, 7, 8)).strides # (13440, 2688, 448, 64, 8) + +The :attr:`~numpy.ndarray.strides` attribute contains for each dimension, the number of *bytes* (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes. + +So now we know the mystery behind the speed of :meth:`~numpy.ndarray.transpose`. NumPy can avoid +copying any data by just modifying the :attr:`~numpy.ndarray.strides` of the array:: + + import numpy as np + + a = np.random.rand(10_000, 20_000) + b = a.transpose() + + print(a.strides) # (160000, 8) + print(b.strides) # (8, 160000) + +Another example: reshaping +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modifying the shape of an array through :func:`numpy.reshape` is also +accomplished without any copying of data by modifying the :attr:`~numpy.ndarray.strides`:: + + a = np.random.rand(20_000, 10_000) + print(f'{a.strides=}') # (80000, 8) + b = a.reshape(40_000, 5_000) + print(f'{b.strides=}') # (40000, 8) + c = a.reshape(20_000, 5_000, 2) + print(f'{c.strides=}') # (80000, 16, 8) + + +Exercises 3 +----------- + +.. challenge:: Exercises: Numpy-Advanced-3 + + A little known feature of NumPy is the ``numpy.stride_tricks`` module + that allows you to modify the :attr:`~numpy.ndarray.strides` attribute directly. Playing + around with this is very educational. + + 1. Create your own ``transpose()`` function that will transpose a 2D matrix + by reversing its :attr:`~numpy.ndarray.shape` and :attr:`~numpy.ndarray.strides` attributes using + :func:`numpy.lib.stride_tricks.as_strided`. + + 2. Create a (5 ✕ 100 000 000 000) array containing on the first row all + 1's, the second row all 2's, and so on. Start with an 1D array + ``a = np.array([1., 2., 3., 4., 5.])`` + and modify its ``shape`` and ``strides`` attributes using + :func:`numpy.lib.stride_tricks.as_strided` to obtain the desired 2D + matrix:: + + array([[1., 1., 1., ..., 1., 1., 1.], + [2., 2., 2., ..., 2., 2., 2.], + [3., 3., 3., ..., 3., 3., 3.], + [4., 4., 4., ..., 4., 4., 4.], + [5., 5., 5., ..., 5., 5., 5.]]) + + +.. solution:: Solutions: Numpy-Advanced-3 + + 1. The ``transpose()`` function can be implemented like this:: + + from numpy.lib.stride_tricks import as_strided + def transpose(a): + return as_strided(a, shape=a.shape[::-1], strides=a.strides[::-1]) + + # Testing the function on a small matrix + a = np.array([[1, 2, 3], + [4, 5, 6]]) + print('Before transpose:') + print(a) + print('After transpose:') + print(transpose(a)) + + 2. By setting one of the ``.strides`` to `0`, we can repeat a value + infinitely many times without using any additional memory:: + + from numpy.lib.stride_tricks import as_strided + a = np.array([1., 2., 3., 4., 5.]) + as_strided(a, shape=(5, 100_000_000_000), strides=(8, 0)) + + +A fast thing + a fast thing = a fast thing? +------------------------------------------- + +If :func:`numpy.transpose` is fast, and :func:`numpy.reshape` is fast, then +doing them both must be fast too, right?:: + + # Create a large array + a = np.random.rand(10_000, 20_000) + +Measuring the time it takes to first transpose and then reshape:: + + %%timeit -n 1 -r 1 + a.T.reshape(40_000, 5_000) + +In this case, the data actually had to be copied and it's super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the :attr:`~numpy.ndarray.strides`:: + + a = np.array([[1, 2, 3], [4, 5, 6]]) + + print('Original array:') + print(a) + + print('\nTransposed:') + print(a.T) + + print('\nTransposed and then reshaped:') + print(a.T.reshape(2, 3)) + + +Copy versus view +---------------- + +Whenever NumPy constructs a new array by modifying the :attr:`~numpy.ndarray.strides` instead of +copying data, we way it created a "view". This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +:class:`numpy.ndarray` object will have a reference to the original array in +its :attr:`~numpy.ndarray.base` attribute:: + + a = np.zeros((5, 5)) + print(a.base) # None + b = a[:2, :2] + print(b.base.shape) # (5, 5) + +.. warning:: + When you create a large array and select only a portion of it, the large + array will stay in memory if a view was created! + +The new array ``b`` object has a pointer to the same memory buffer as the array +it has been derived from:: + + print(a.__array_interface__['data']) + print(b.__array_interface__['data']) + +Views are created by virtue of modifying the value of the :attr:`~numpy.ndarray.shape` attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:: + + b = a[1:3, 1:3] # This view does not start at the beginning + offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0] + print('Offset:', offset, 'bytes') # Offset: 48 bytes + +.. image:: img/numpy-advanced/02_views.svg + +Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:: + + b[0, 0] = 1. + print(a) # Original matrix was modified + +Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:: + + c = a[[0, 2]] # Select rows 0 and 2 + print(c.base) # None. So not a view. + + +See also +-------- + +* `Guide to Numpy `__ +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + * `Advanced NumPy: Master stride tricks with 25 illustrated exercises `__ + + + +.. keypoints:: + + - The best way to make your code more efficient is to learn more about the + NumPy API and use specialized functions whenever possible. + - NumPy will avoid copying data whenever it can. Whether it can depends on + what kind of layout the data is currently in. diff --git a/branch/master/_sources/numpy.rst.txt b/branch/master/_sources/numpy.rst.txt new file mode 100644 index 00000000..05daa11e --- /dev/null +++ b/branch/master/_sources/numpy.rst.txt @@ -0,0 +1,519 @@ +.. _numpy: + +NumPy +===== + +.. questions:: + + - Why use NumPy instead of pure python? + - How to use basic NumPy? + - What is vectorization? + +.. objectives:: + + - Understand the Numpy array object + - Be able to use basic NumPy functionality + - Understand enough of NumPy to seach for answers to the rest of your questions ;) + + We expect most people to be able to do all the basic exercises + here. It is probably quite easy for many people; we have advanced + exercises at the end in that case. + + + +So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible. + +.. highlight:: python + +What is an array? +----------------- + +For example, consider ``[1, 2.5, 'asdf', False, [1.5, True]]`` - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately. + +NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it. + +An array is a 'grid' of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has: + +* :ref:`dtype ` - data type. Arrays always contain one type +* :term:`shape` - shape of the data, for example ``3×2`` or ``3×2×500`` or even + ``500`` (one dimensional) or ``[]`` (zero dimensional). +* :attr:`data ` - raw data storage in memory. This can be passed to C or + Fortran code for efficient calculations. + + +To test the performance of pure Python vs NumPy we can write in our jupyter notebook: + +Create one list and one 'empty' list, to store the result in :: + + a = list(range(10000)) + b = [ 0 ] * 10000 + +In a new cell starting with ``%%timeit``, loop through the list ``a`` and fill the second list ``b`` with ``a`` squared :: + + %%timeit + for i in range(len(a)): + b[i] = a[i]**2 + +That looks and feels quite fast. But let's take a look at how NumPy performs for the same task. + +So for the NumPy example, create one array and one 'empty' array to store the result in :: + + import numpy as np + a = np.arange(10000) + b = np.zeros(10000) + +In a new cell starting with ``%%timeit``, fill ``b`` with ``a`` squared :: + + %%timeit + b = a ** 2 + +We see that compared to working with numpy arrays, working with traditional python lists is actually slow. + + +Creating arrays +--------------- + +There are different ways of creating arrays (:func:`numpy.array`, :attr:`numpy.ndarray.shape`, :attr:`numpy.ndarray.size`):: + + a = np.array([1,2,3]) # 1-dimensional array (rank 1) + b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2) + + b.shape # the shape (rows,columns) + b.size # number of elements + +In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (:func:`numpy.zeros`, :func:`numpy.ones`, :func:`numpy.full`, :func:`numpy.eye`, :func:`numpy.arange`, :func:`numpy.linspace`):: + + np.zeros((2, 3)) # 2x3 array with all elements 0 + np.ones((1,2)) # 1x2 array with all elements 1 + np.full((2,2),7) # 2x2 array with all elements 7 + np.eye(2) # 2x2 identity matrix + + np.arange(10) # Evenly spaced values in an interval + np.linspace(0,9,10) # same as above, see exercise + + c = np.ones((3,3)) + d = np.ones((3, 2), 'bool') # 3x2 boolean array + +Arrays can also be stored and read from a (.npy) file (:func:`numpy.save`, :func:`numpy.load`):: + + np.save('x.npy', a) # save the array a to a .npy file + x = np.load('x.npy') # load an array from a .npy file and store it in variable x + +In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (:attr:`numpy.ndarray.dtype`, :meth:`numpy.ndarray.astype`):: + + d.dtype # datatype of the array + d.astype('int') # change datatype from boolean to integer + +In the last example, ``.astype('int')``, it will make a **copy** of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed. + + + +Exercises 1 +----------- + +.. challenge:: Exercises: Numpy-1 + + 1. **Datatypes** Try out :func:`np.arange(10) ` and :func:`np.linspace(0,9,10) `, what is the difference? Can you adjust one to do the same as the other? + + 2. **Datatypes** Create a 3x2 array of random float numbers (check :func:`numpy.random.random`) between 0 and 1. Now change the arrays datatype to int (:meth:`array.astype `). How does the array look like? + + 3. **Reshape** Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check :meth:`array.reshape `) in any way possible. What is not possible? + + 4. **NumPyI/O** Save above array to .npy file (:func:`numpy.save`) and read it in again. + +.. solution:: Solutions: Numpy-1 + + 1. **Datatypes** + + - ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**, + - while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**. + + Both ``np.linspace`` and ``np.arange`` take dtype as an argument and can be adjusted to match each other in that way. + + 2. **Datatypes** eg ``a = np.random.random((3,2))``. ``a.astype('int')`` results in an all zero array, not as maybe expected the rounded int (all numbers [0, 1) are cast to 0). + + 3. **Reshape** eg ``b = np.random.randint(0,10,(3,2))``. + + ``b.reshape((6,1))`` and ``b.reshape((2,3))`` possible. + + It is not possible to reshape to shapes using more or less elements than ``b.size = 6``, so for example ``b.reshape((12,1))`` gives an error. + + 4. **NumPyI/O** ``np.save('x.npy', b)`` and ``x = np.load('x.npy')`` + + + +Array maths and vectorization +----------------------------- + +Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do. + +By default, basic arithmetic (``+``, ``-``, ``*``, ``/``) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is "vectorized" +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop. + +Note that unlike Matlab, where ``*`` means matrix multiplication, NumPy uses +``*`` to perform element-by-element multiplication and uses the ``@`` symbol to +perform matrix multiplication:: + + a = np.array([[1,2],[3,4]]) + b = np.array([[5,6],[7,8]]) + + # Addition + c = a + b + d = np.add(a,b) + + # Matrix multiplication + e = a @ b + f = np.dot(a, b) + +Other common mathematical operations include: ``-`` (:data:`numpy.subtract`), ``*`` (:data:`numpy.multiply`), ``/`` (:data:`numpy.divide`), ``.T`` (:func:`numpy.transpose`), :data:`numpy.sqrt`, :func:`numpy.sum`, :func:`numpy.mean`, ... + + + +Exercises 2 +----------- + +.. challenge:: Exercises: Numpy-2 + + - **Matrix multiplication** What is the difference between :data:`numpy.multiply` and :func:`numpy.dot` ? Try it. + - **Axis** What is the difference between :func:`np.sum(axis=1) ` vs + :func:`np.sum(axis=0) ` on a two-dimensional array? What if you leave out the axis parameter? + + +.. solution:: Solutions: Numpy-2 + + - **Matrix multiplication** ``np.multiply`` does elementwise multiplication on two arrays, while ``np.dot`` enables matrix multiplication. + - **Axis** ``axis=1`` does the operation (here: ``np.sum``) over each row, while axis=0 does it over each column. If axis is left out, the sum of the full array is given. + + + +Indexing and Slicing +-------------------- + +.. seealso:: + + :ref:`Numpy basic indexing docs ` + +NumPy has many ways to extract values out of arrays: + +- You can select a single element +- You can select rows or columns +- You can select ranges where a condition is true. + +Clever and efficient use of these operations is a key to NumPy's +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C. + +:: + + a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15 + a[0] # first row + a[:,0] # first column + a[1:3,1:3] # middle 2x2 array + + a[(0, 1), (1, 1)] # second element of first and second row as array + +Boolean indexing on above created array:: + + idx = (a > 0) # creates boolean matrix of same size as a + a[idx] # array with matching values of above criterion + + a[a > 0] # same as above in one line + + + +Exercises 3 +----------- + +.. challenge:: Exercise: Numpy-3 + + :: + + a = np.eye(4) + b = a[:,0] + b[0] = 5 + + - **View vs copy** Try out above code. How does ``a`` look like before ``b`` has changed and after? How could it be avoided? + +.. solution:: Solution: Numpy-3 + + - **View vs copy** The change in ``b`` has also changed the array ``a``! + This is because ``b`` is merely a view of a part of array ``a``. Both + variables point to the same memory. Hence, if one is changed, the other + one also changes. If you need to keep the original array as is, use + ``np.copy(a)``. + + +Types of operations +------------------- + +There are different types of standard operations in NumPy: + +**ufuncs**, ":ref:`universal functions `": These are element-by-element +functions with standardized arguments: + +- One, two, or three input arguments +- For example, ``a + b`` is similar to :data:`np.add(a, b) ` but the ufunc + has more control. +- ``out=`` output argument, store output in this array (rather than + make a new array) - saves copying data! +- See the `full reference + `__ + +- They also do **broadcasting** (:ref:`ref `). Can you add a 1-dimensional array of shape `(3)` + to an 2-dimensional array of shape `(3, 2)`? With broadcasting you + can! + + :: + + a = np.array([[1, 2, 3], + [4, 5, 6]]) + b = np.array([10, 10, 10]) + a + b # array([[11, 12, 13], + # [14, 15, 16]]) + + Broadcasting is smart and consistent about what it does, which I'm + not clever enough to explain quickly here: `the manual page on + broadcasting + `__. + The basic idea is that it expands dimensions of the smaller array so + that they are compatible in shape. + +**Array methods** do something to one array: + +- Some of these are the same as ufuncs:: + + x = np.arange(12) + x.shape = (3, 4) + x # array([[ 0, 1, 2, 3], + # [ 4, 5, 6, 7], + # [ 8, 9, 10, 11]]) + x.max() # 11 + x.max(axis=0) # array([ 8, 9, 10, 11]) + x.max(axis=1) # array([ 3, 7, 11]) + +**Other functions**: there are countless other functions covering +linear algebra, scientific functions, etc. + + + +Exercises 4 +----------- + +.. challenge:: Exercises: Numpy-4 + + - **In-place addition**: Create an array, add it to itself using a + ufunc. + + - **In-place addition** (advanced): Create an array of + ``dtype='float'``, and an array of ``dtype='int'``. Try to use the + int array is the output argument of the first two arrays. + + - **Output arguments and timing** Repeat the initial ``b = a ** + 2`` example using the output arguments and time it. Can you make + it even faster using the output argument? + +.. solution:: Solution: Numpy-4 + + - **in-place addition**:: + + x = np.array([1, 2, 3]) + id(x) # get the memory-ID of x + np.add(x, x, x) # Third argument is output array + np.add(x, x, x) + print(x) + id(x) # get the memory-ID of x + # - notice it is the same + + You note that ``np.add()`` has a third argument that is the + output array (same as ``out=``), *and* the function returns that + same array. + + + - **Output arguments and timing** In this case, on my computer, it was + actually slower (this is due to it being such a small array!):: + + a = np.arange(10000) + b = np.zeros(10000) + + :: + + %%timeit + numpy.square(a, out=b) + + This is a good example of why you always need to time things + before deciding what is best. + + +Linear algebra and other advanced math +-------------------------------------- + +In general, you use :class:`arrays ` (n-dimensions), not :class:`matrixes ` +(specialized 2-dimensional) in NumPy. + +Internally, NumPy doesn't invent its own math routines: it relies on +`BLAS +`__ +and `LAPACK `__ to do this kind +of math - the same as many other languages. + +- `Linear algebra in numpy + `__ + +- `Many, many other array functions + `__ + +- `Scipy `__ has even + more functions + +- Many other libraries use NumPy arrays as the standard data + structure: they take data in this format, and return it similarly. + Thus, all the other packages you may want to use are compatible + +- If you need to write your own fast code in C, NumPy arrays can be + used to pass data. This is known as `extending Python + `__. + + + + +Additional exercises +-------------------- + +.. challenge:: Numpy-5 + + If you have extra time, try these out. These are advanced and + optional, and will not be done in most courses. + + 1. Reverse a vector. Given a vector, reverse it such that the last + element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]`` + + 2. Create a 2D array with zeros on the borders and 1 inside. + + 3. Create a random array with elements [0, 1), then add 10 to all + elements in the range [0.2, 0.7). + + 4. What is :func:`np.round(0.5) `? What is ``np.round(1.5)``? Why? + + 5. In addition to ``np.round``, explore :data:`numpy.ceil`, :data:`numpy.floor`, + :data:`numpy.trunc`. In particular, take note of how they behave with + negative numbers. + + 6. Recall the identity :math:`\sin^2(x) + \cos^2(x) = 1`. Create a + random 4x4 array with values in the range [0, 10). Now test the + equality with :data:`numpy.equal`. What result do you get with + :func:`numpy.allclose` instead of ``np.equal``? + + 7. Create a 1D array with 10 random elements. Sort it. + + 8. What's the difference between :meth:`np_array.sort() ` and + :func:`np.sort(np_array) `? + + 9. For the random array in question 8, instead of sorting it, perform + an indirect sort. That is, return the list of indices which would + index the array in sorted order. + + 10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next + combine them into a single 8x4 array with the content of the zeros + array on top and the ones on the bottom. Finally, do the same, + but create a 4x8 array with the zeros on the left and the ones on + the right. + + 11. NumPy functionality Create two 2D arrays and do matrix multiplication + first manually (for loop), then using the np.dot function. Use %%timeit + to compare execution times. What is happening? + + +.. solution:: Solution Numpy-5 + + 1. One solution is:: + + a = np.array([1, 2, 3]) + a[::-1] + + 2. One solution is:: + + b = np.ones((10,10)) + b[:,[0, -1]]=0 + b[[0, -1],:]=0 + + 3. A possible solution is:: + + x = np.random.rand(100) + y = x + 10*(x >= 0.2)*(x < 0.7) + + 4. For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. + + 5. Let's test those functions with few negative and positive values:: + + a = np.array([-3.3, -2.5, -1.5, -0.75, -0.5, 0.5, 0.75, 1.5, 2.5, 3]) + np.round(a) # [-3. -2. -2. -1. -0. 0. 1. 2. 2. 3.] + np.ceil(a) # [-3. -2. -1. -0. -0. 1. 1. 2. 3. 3.] + np.floor(a) # [-4. -3. -2. -1. -1. 0. 0. 1. 2. 3.] + np.trunc(a) # [-3. -2. -1. -0. -0. 0. 0. 1. 2. 3.] + + + 6. One solution is:: + + x = 10*np.random.rand(4,4) + oo = np.ones((4,4)) + s2c2 = np.square(np.sin(x))+np.square(np.cos(x)) + np.equal(oo,s2c2) + np.allclose(oo,s2c2) + + 7. Sorting the array itself, without copying it:: + + x = np.random.rand(10) + x.sort() + + 8. NumPy.sort() returns a sorted copy of an array. + + 9. ``np.argsort(x)`` + + 10. One solution is:: + + z = np.zeros((4,4)) + o = np.ones((4,4)) + np.concatenate((z,o)) + np.concatenate((z,o),axis=1) + + 11. Using numpy without numpy functionality (np.dot) in this case, is still slow. + + + +See also +-------- + +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + +* `2020 Nature paper on NumPy's role and basic concepts `__ + + + +.. keypoints:: + + - NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally. + - Be aware of some NumPy specific peculiarities diff --git a/branch/master/_sources/packaging.rst.txt b/branch/master/_sources/packaging.rst.txt new file mode 100644 index 00000000..7b795f1f --- /dev/null +++ b/branch/master/_sources/packaging.rst.txt @@ -0,0 +1,324 @@ +Packaging +========= + +.. questions:: + + - How to organize Python projects larger than one script? + - What is a good file and folder structure for Python projects? + - How can you make your Python functions most usable by your collaborators? + - How to prepare your code to make a Python package? + - How to publish your Python package? + +.. objectives:: + + - Learn to identify the components of a Python package + - Learn to create a Python package + - Learn to publish a Python package + + +Organizing Python projects +-------------------------- + +Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file. + +In the :ref:`scripts` episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further. + +**Recommendations**: + +- Collect related functions into modules (files). +- Collect related modules into packages (we will show how). +- Add a ``LICENSE`` file to your code + (see `Software Licensing and Open source explained with cakes `__). +- Write a ``README.md`` file describing what the code does and how to use it. +- It is also recommended to `document your package `__. +- When the project grows, you might need `automated testing `__. + +To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: ``scipy``. + +These are the 3 files: + +.. literalinclude:: packaging-example-project/calculator/adding.py + :caption: adding.py + +.. literalinclude:: packaging-example-project/calculator/subtracting.py + :caption: subtracting.py + +.. literalinclude:: packaging-example-project/calculator/integrating.py + :caption: integrating.py + +We will add a fourth file: + +.. literalinclude:: packaging-example-project/calculator/__init__.py + :caption: __init__.py + +This ``__init__.py`` file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using *relative imports* +(with the dot). + +This is how we will arrange the files in the project folder/repository: + +.. code-block:: none + :emphasize-lines: 3-6 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + └── README.md + +Now we are ready to test the package. For this we need to be in the "root" +folder, what we have called the *project-folder*. We also need to have +``scipy`` available in our environment: + +.. literalinclude:: packaging-example-project/test.py + +The package is not yet pip-installable, though. We will make this possible in +the next section. + + +Testing a local pip install +--------------------------- + +To make our example package pip-installable we need to add one more file: + +.. code-block:: none + :emphasize-lines: 9 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + ├── README.md + └── pyproject.toml + +This is how ``pyproject.toml`` looks: + +.. literalinclude:: packaging-example-project/pyproject.toml + :caption: pyproject.toml + :emphasize-lines: 13-15 + +Note how our package requires ``scipy`` and we decided to not pin the version +here (see :ref:`version_pinning`). + +Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see :ref:`pypi`) + + + +Exercises 1 +----------- + +.. challenge:: Packaging-1 + + To test a local pip install: + + - Create a new folder outside of our example project + - Create a new virtual environment (:ref:`dependency_management`) + - Install the example package from the project folder + into the new environment: ``$ pip install /path/to/project-folder/`` + - Test the local installation: + + .. literalinclude:: packaging-example-project/test.py + + +Sharing packages via PyPI +------------------------- + +Once we are able to pip-install the example package locally, we are ready for +upload. + +We exercise by uploading to `test-PyPI `__, not the +real `PyPI `__, so that if we mess things up, nothing bad +happens. + +We need two more things: + +- We will do this using `Twine `__ so you need + to pip install that, too. +- You need an account on `test-PyPI `__. + +.. highlight:: console + +Let's try it out. First we create the distribution package:: + + $ python3 -m build + +We need twine:: + + $ pip install twine + +And use twine to upload the distribution files to test-PyPI:: + + $ twine upload -r testpypi dist/* + + Uploading distributions to https://test.pypi.org/legacy/ + Enter your username: + Enter your password: + +Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt "myname"):: + + $ pip install -i https://test.pypi.org/simple/ calculator-myname + + +Tools that simplify sharing via PyPI +------------------------------------ + +The solution that we have used to create the example package (using +``setuptools`` and ``twine``) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using ``pyproject.toml`` as more general +alternative to the previous ``setup.py``. + +There are at least two tools which try to make the packaging and PyPI interaction easier: + +- `Poetry `__ +- `Flit `__ + + +Building a conda package and share it +------------------------------------- + +.. demo:: + + Most people will watch and observe this, due to speed which we will + move. + +.. callout:: Prerequisites + + To create a conda package, `conda-build` package is required. You may install it with **Anaconda Navigator** or from the command line:: + + $ conda install conda-build + + +The simplest way for creating a conda package for your python script is to +first publish it in `PyPI `__ following the steps explained +above. + + +Building a python package with conda skeleton pypi +*************************************************** + +Once build, the conda package can be installed locally. For this example, we +will use `runtest `__. `runtest +`__ is a numerically tolerant end-to-end test +library for research software. + +1. Create pypi skeleton:: + + $ conda skeleton pypi runtest + + The command above will create a new folder called `runtest` containing a file `meta.yaml`, the conda recipe for `runtest`. + +2. Edit `meta.yaml` and update requirements: + + .. code-block:: yaml + + requirements: + host: + - pip + - python + - flit + run: + - python + - flit + + In the requirements above, we specified what is required for the `host `__ and for `running `__ the package. + + .. callout:: Remark + + For pure python recipes, this is all you need for building a python package with conda. + If your package needs to be built (for instance compilation), you would need additional files e.g. `build.sh` (to build on Linux/Mac-OSX) and `bld.bat` (to build on Windows systems). You can also add test scripts for testing your package. See `documentation `__ + + +3. Build your package with conda + + Your package is now ready to be build with conda:: + + $ conda-build runtest + + + .. callout:: Conda package location + + Look at the messages produced while building. The location of the local conda package is given (search for `anaconda upload`): + + .. code-block:: none + + ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2 + + The prefix `~/anaconda3/` may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder `win-64` differs too (for instance `linux-64` on Linux machines). + + The conda package we have created is specific to your platform (here `win-64`). It can be converted to other platforms using `conda convert `__. + +4. Check within new environment + + It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments. + + :: + + $ conda create -n local-runtest --use-local runtest + + We can then check `runtest` has been successfully installed in `local-runtest` conda environment. Open a new Terminal with `local-runtest` environment (either from the command line:: + + $ conda activate local-runtest + + or via **Anaconda Navigator** (Open Terminal), import runtest and + check its version: + + .. code-block:: python + + import runtest + print(runtest.__version__) + + +.. callout:: Building a conda package from scratch + + It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the `conda-build documentation `__ for more information. + +To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a `conda channel `__ (see below). + + + +Publishing a python package +*************************** + +- Upload your package to *Anaconda.org*: see instructions `here + `__. + Please note that you will have to create an account on Anaconda. + +- Upload your package to `conda-forge `__: + conda-forge is a conda channel: it contains community-led collection of + recipes, build infrastructure and distributions for the conda package + manager. Anyone can public conda packages to conda-forge if certain + `guidelines `__ are respected. + +- Upload your package to `bioconda `_: bioconda is + a very popular channel for the conda package manager specializing in + bioinformatics software. As for conda-forge, you need to follow their + `guidelines `__ when + building conda recipes. + +You can also `create your own conda channel +`__ +for publishing your packages. + + +.. keypoints:: + + - It is worth it to organize your code for publishing, even if only + you are using it. + - PyPI is a place for Python packages + - conda is similar but is not limited to Python diff --git a/branch/master/_sources/pandas.rst.txt b/branch/master/_sources/pandas.rst.txt new file mode 100644 index 00000000..0fa04fd2 --- /dev/null +++ b/branch/master/_sources/pandas.rst.txt @@ -0,0 +1,623 @@ +.. _pandas: + +Pandas +====== + +.. questions:: + + - How do I learn a new Python package? + - How can I use pandas dataframes in my research? + +.. objectives:: + + - Learn simple and some more advanced usage of pandas dataframes + - Get a feeling for when pandas is useful and know where to find more information + - Understand enough of pandas to be able to read its documentation. + +.. default-domain:: py + + +Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including: + +- A `Getting started guide `__ + (including tutorials and a 10 minute flash intro) +- A `"10 minutes to Pandas" `__ + tutorial +- Thorough `Documentation `__ containing a user guide, + API reference and contribution guide +- A `cheatsheet `__ +- A `cookbook `__ + +A quick Pandas preview +---------------------- + +.. thebe-button:: + +Let's get a flavor of what we can do with pandas (you won't be able to follow everything yet). We will be working with an example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:: + + import pandas as pd + +We can download the data from `this GitHub repository `__ +by visiting the page and saving it to disk, or by directly reading into +a :class:`~pandas.DataFrame`:: + + url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv" + titanic = pd.read_csv(url, index_col='Name') + +We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:: + + # print the first 5 lines of the dataframe + titanic.head() + +:: + + # print summary statistics for each column + titanic.describe() + +Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38\% of passengers survived, etc. + +Let's say we're interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn't survive, and plot corresponding histograms of +the age distribution (:meth:`pandas.DataFrame.groupby`, :meth:`pandas.DataFrame.hist`):: + + print(titanic.groupby("Survived")["Age"].mean()) + +:: + + titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10), + layout=(2,1), zorder=2, sharex=True, rwidth=0.9); + + +Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let's get back to basics. + +.. callout:: Getting help + + Series and DataFrames have a lot functionality, but + how can we find out what methods are available and how they work? One way is to visit + the `API reference `__ + and reading through the list. + Another way is to use the autocompletion feature in Jupyter and type e.g. + ``titanic["Age"].`` in a notebook and then hit ``TAB`` twice - this should open + up a list menu of available methods and attributes. + + Jupyter also offers quick access to help pages (docstrings) which can be + more efficient than searching the internet. Two ways exist: + + - Write a function name followed by question mark and execute the cell, e.g. + write ``titanic.hist?`` and hit ``SHIFT + ENTER``. + - Write the function name and hit ``SHIFT + TAB``. + - Right click and select "Show contextual help". This tab will + update with help for anything you click. + + +What's in a dataframe? +---------------------- + +As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +:class:`pandas.DataFrame` +is composed of rows and columns: + +.. image:: img/pandas/01_table_dataframe.svg + +Each column of a dataframe is a :class:`pandas.Series` object +- a dataframe is thus a collection of series:: + + # print some information about the columns + titanic.info() + +Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type ``int64`` or of type ``object``. + +Let's inspect one column of the Titanic passenger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):: + + titanic["Age"] + titanic.Age # same as above + +:: + + type(titanic["Age"]) # a pandas Series object + +The columns have names. Here's how to get them (:attr:`~pandas.DataFrame.columns`):: + + titanic.columns + +However, the rows also have names! This is what Pandas calls the :obj:`~pandas.DataFrame.index`:: + + titanic.index + +We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and +values. We can refer to columns and rows either by their name +(:attr:`~pandas.DataFrame.loc`, :attr:`~pandas.DataFrame.at`) or by +their index (:attr:`~pandas.DataFrame.iloc`, +:attr:`~pandas.DataFrame.iat`):: + + titanic.loc['Lam, Mr. Ali',"Age"] # select single value by row and column + titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"] # slice the dataframe by row and column *names* + titanic.iloc[0:2,3:6] # same slice as above by row and column *numbers* + + titanic.at['Lam, Mr. Ali',"Age"] = 42 # set single value by row and column *name* (fast) + titanic.at['Lam, Mr. Ali',"Age"] # select single value by row and column *name* (fast) + titanic.iat[0,5] # select same value by row and column *number* (fast) + + titanic["is_passenger"] = True # set a whole column + +Dataframes also support boolean indexing, just like we saw for ``numpy`` +arrays:: + + titanic[titanic["Age"] > 70] + # ".str" creates a string object from a column + titanic[titanic.index.str.contains("Margaret")] + +What if your dataset has missing data? Pandas uses the value :py:data:`numpy.nan` +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:: + + titanic.isna() # returns boolean mask of NaN values + titanic.dropna() # drop missing values + titanic.dropna(how="any") # or how="all" + titanic.dropna(subset=["Cabin"]) # only drop NaNs from one column + titanic.fillna(0) # replace NaNs with zero + titanic.fillna(method='ffill') # forward-fill NaNs + + + +Exercises 1 +----------- + +.. challenge:: Exploring dataframes + + - Have a look at the available methods and attributes using the + `API reference `__ + or the autocomplete feature in Jupyter. + - Try out a few methods using the Titanic dataset and have a look at + the docstrings (help pages) of methods that pique your interest + - Compute the mean age of the first 10 passengers by slicing and the :py:meth:`pandas.DataFrame.mean` method + - (Advanced) Using boolean indexing, compute the survival rate + (mean of "Survived" values) among passengers over and under the average age. + + .. solution:: + + - Mean age of the first 10 passengers:: + + titanic.iloc[:10,:]["Age"].mean() + + or:: + + titanic.loc[:"Nasser, Mrs. Nicholas (Adele Achem)","Age"].mean() + + or:: + + titanic.iloc[:10,4].mean() + + - Survival rate among passengers over and under average age:: + + titanic[titanic["Age"] > titanic["Age"].mean()]["Survived"].mean() + + and:: + + titanic[titanic["Age"] < titanic["Age"].mean()]["Survived"].mean() + + +Tidy data +--------- + +The above analysis was rather straightforward thanks to the fact +that the dataset is *tidy*. + +.. image:: img/pandas/tidy_data.png + +In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data. + +What would untidy data look like? Here's an example from +some run time statistics from a 1500 m running event:: + + runners = pd.DataFrame([ + {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240}, + {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300}, + {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360}, + ]) + +What makes this data untidy is that the column names `400, 800, 1200, 1500` +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row. + +To make untidy data tidy, a common operation is to "melt" it, +which is to convert it from wide form to a long form:: + + runners = pd.melt(runners, id_vars="Runner", + value_vars=[400, 800, 1200, 1500], + var_name="distance", + value_name="time" + ) + +In this form it's easier to **filter**, **group**, **join** +and **aggregate** the data, and it's also easier to model relationships +between variables. + +The opposite of melting is to *pivot* data, which can be useful to +view data in different ways as we'll see below. + +For a detailed exposition of data tidying, have a look at +`this article `__. + + + +Working with dataframes +----------------------- + +We saw above how we can read in data into a dataframe using the :func:`~pandas.read_csv` function. +Pandas also understands multiple other formats, for example using :obj:`~pandas.read_excel`, +:obj:`~pandas.read_hdf`, :obj:`~pandas.read_json`, etc. (and corresponding methods to write to file: +:obj:`~pandas.DataFrame.to_csv`, :obj:`~pandas.DataFrame.to_excel`, :obj:`~pandas.DataFrame.to_hdf`, :obj:`~pandas.DataFrame.to_json`, etc.) + +But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +:class:`~pandas.DataFrame` docs):: + + import numpy as np + dates = pd.date_range('20130101', periods=6) + df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD')) + df + +or a dictionary (see same docs):: + + df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'], + 'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'], + 'C': np.array([3] * 8, dtype='int32'), + 'D': np.random.randn(8), + 'E': np.random.randn(8)}) + df + +There are many ways to operate on dataframes. Let's look at a +few examples in order to get a feeling of what's possible +and what the use cases can be. + +We can easily split and :func:`concatenate ` dataframes:: + + sub1, sub2, sub3 = df[:2], df[2:4], df[4:] + pd.concat([sub1, sub2, sub3]) + +When pulling data from multiple dataframes, a powerful :obj:`pandas.DataFrame.merge` method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:: + + age = pd.DataFrame([ + {"Runner": "Runner 4", "Age": 18}, + {"Runner": "Runner 2", "Age": 21}, + {"Runner": "Runner 1", "Age": 23}, + {"Runner": "Runner 3", "Age": 19}, + ]) + +We now want to use this table to annotate the original ``runners`` table from +before with their age. Note that the ``runners`` and ``age`` dataframes have a +different ordering to it, and ``age`` has an entry for ``Dave`` which is not +present in the ``runners`` table. We can let Pandas deal with all of it using +the :obj:`~pandas.DataFrame.merge` method:: + + # Add the age for each runner + runners.merge(age, on="Runner") + +In fact, much of what can be done in SQL +`is also possible with pandas `__. + +:obj:`~pandas.DataFrame.groupby` is a powerful method which splits a dataframe and aggregates data +in groups. To see what's possible, let's return to the Titanic dataset. Let's +test the old saying "Women and children first". We start by creating a new +column ``Child`` to indicate whether a passenger was a child or not, based on +the existing ``Age`` column. For this example, let's assume that you are a +child when you are younger than 12 years:: + + titanic["Child"] = titanic["Age"] < 12 + +Now we can test the saying by grouping the data on ``Sex`` and then creating further sub-groups based on ``Child``:: + + titanic.groupby(["Sex", "Child"])["Survived"].mean() + +Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +:obj:`~pandas.DataFrame.std`, :obj:`~pandas.DataFrame.min`, +:obj:`~pandas.DataFrame.max`, :obj:`~pandas.DataFrame.cumsum`, +:obj:`~pandas.DataFrame.median`, :obj:`~pandas.DataFrame.skew`, +:obj:`~pandas.DataFrame.var` etc. + + + +Exercises 2 +----------- + +.. challenge:: Analyze the Titanic passenger list dataset + + In the Titanic passenger list dataset, + investigate the family size of the passengers (i.e. the "SibSp" column). + + - What different family sizes exist in the passenger list? Hint: try the :meth:`~pandas.Series.unique` method + - What are the names of the people in the largest family group? + - (Advanced) Create histograms showing the distribution of family sizes for + passengers split by the fare, i.e. one group of high-fare passengers (where + the fare is above average) and one for low-fare passengers + (Hint: instead of an existing column name, you can give a lambda function + as a parameter to :meth:`~pandas.DataFrame.hist` to compute a value on the fly. For example + ``lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich"``). + + .. solution:: + + - Existing family sizes:: + + titanic["SibSp"].unique() + + - We get 8 from above. There is no ``Name`` column, since we + made ``Name`` the index when we loaded the dataframe with + ``read_csv``, so we use :attr:`pandas.DataFrame.index` to get + the names. So, names of members of largest family(ies):: + + titanic[titanic["SibSp"] == 8].index + + - Histogram of family size based on fare class:: + + titanic.hist("SibSp", + lambda x: "Poor" if titanic["Fare"].loc[x] < titanic["Fare"].mean() else "Rich", + rwidth=0.9) + + + + +Time series superpowers +----------------------- + +An introduction of pandas wouldn't be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv . + +Unfortunately this API does not allow "non-browser requests", so +:obj:`pandas.read_csv` will not work directly on it. Instead, we put a +local copy on Github which we can access (the original data is CC-0, +so we are allowed to do this). (Aside: if you do JupyterLab → +File → Open from URL → paste the URL above, it will open it in +JupyterLab *and* download a copy for your use.) + +We can then load and explore the data:: + + nobel = pd.read_csv("https://github.com/AaltoSciComp/python-for-scicomp/raw/master/resources/data/laureate.csv") + nobel.head() + +This dataset has three columns for time, "born"/"died" and "year". +These are represented as strings and integers, respectively, and +need to be converted to datetime format. :func:`pandas.to_datetime` +makes this easy:: + + # the errors='coerce' argument is needed because the dataset is a bit messy + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + +Pandas knows a lot about dates (using :ref:`/user_guide/basics.rst#dt-accessor`):: + + print(nobel["born"].dt.day) + print(nobel["born"].dt.year) + print(nobel["born"].dt.weekday) + +We can add a column containing the (approximate) lifespan in years rounded +to one decimal:: + + nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1) + +and then plot a :meth:`histogram ` of lifespans:: + + nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9) + +Finally, let's see one more example of an informative plot (:meth:`~pandas.DataFrame.boxplot`) +produced by a single line of code:: + + nobel.boxplot(column="lifespan", by="category") + + + +Exercises 3 +----------- + +.. challenge:: Analyze the Nobel prize dataset + + - What country has received the largest number of Nobel prizes, and how many? + How many countries are represented in the dataset? Hint: use the :obj:`~pandas.Series.describe` method + on the ``bornCountryCode`` column. + - Create a histogram of the age when the laureates received their Nobel prizes. + Hint: follow the above steps we performed for the lifespan. + - List all the Nobel laureates from your country. + + Now more advanced steps: + + - Now define an array of 4 countries of your choice and extract + only laureates from these countries (you need to look at the + data and find how countries are written, and replace ``COUNTRY`` + with those strings):: + + countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4]) + subset = nobel.loc[nobel['bornCountry'].isin(countries)] + + - Use :meth:`~pandas.DataFrame.groupby` to compute how many nobel prizes each country received in + each category. The :meth:`~pandas.core.groupby.GroupBy.size` method tells us how many rows, hence nobel + prizes, are in each group:: + + nobel.groupby(['bornCountry', 'category']).size() + + - (Optional) Create a pivot table to view a spreadsheet like structure, and view it + + - First add a column “number” to the nobel dataframe containing 1’s + (to enable the counting below). We need to make a copy of + ``subset``, because right now it is only a view:: + + subset = subset.copy() + subset.loc[:, 'number'] = 1 + + - Then create the :meth:`~pandas.DataFrame.pivot_table`:: + + table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum) + + - (Optional) Install the **seaborn** visualization library if you don't + already have it, and create a heatmap of your table:: + + import seaborn as sns + sns.heatmap(table,linewidths=.5); + + - Play around with other nice looking plots:: + + sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset); + + :: + + sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5); + + :: + + subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))] + sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm"); + + :: + + sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count"); + + + .. solution:: + + Below is solutions for the basic steps, advanced steps are + inline above. + + We use the :meth:`describe` method: + + :: + + nobel.bornCountryCode.describe() + # count 956 + # unique 81 + # top US + # freq 287 + + We see that the US has received the largest number of Nobel prizes, + and 81 countries are represented. + + To calculate the age at which laureates receive their prize, we need + to ensure that the "year" and "born" columns are in datetime format:: + + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + + Then we add a column with the age at which Nobel prize was received + and plot a histogram:: + + nobel["age_nobel"] = round((nobel["year"] - nobel["born"]).dt.days / 365, 1) + nobel.hist(column="age_nobel", bins=25, figsize=(8,10), rwidth=0.9) + + We can print names of all laureates from a given country, e.g.:: + + nobel[nobel["country"] == "Sweden"].loc[:, "firstname":"surname"] + +Beyond the basics +----------------- + +Larger DataFrame operations might be faster using :func:`~pandas.eval` with string expressions, `see +`__:: + + import pandas as pd + # Make some really big dataframes + nrows, ncols = 100000, 100 + rng = np.random.RandomState(42) + df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols)) + for i in range(4)) + +Adding dataframes the pythonic way yields:: + + %timeit df1 + df2 + df3 + df4 + # 80ms + +And by using :func:`~pandas.eval`:: + + %timeit pd.eval('df1 + df2 + df3 + df4') + # 40ms + + +We can assign function return lists as dataframe columns:: + + def fibo(n): + """Compute Fibonacci numbers. Here we skip the overhead from the + recursive function calls by using a list. """ + if n < 0: + raise NotImplementedError('Not defined for negative values') + elif n < 2: + return n + memo = [0]*(n+1) + memo[0] = 0 + memo[1] = 1 + for i in range(2, n+1): + memo[i] = memo[i-1] + memo[i-2] + return memo + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = fibo(99) # Assigns list to column + + +There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its `API +`__. You should try to get good at +searching the web for an example showing what you can do. And when +there is not, you can always +apply your own functions to the data using :obj:`~pandas.DataFrame.apply`:: + + + from functools import lru_cache + + @lru_cache + def fib(x): + """Compute Fibonacci numbers. The @lru_cache remembers values we + computed before, which speeds up this function a lot.""" + if x < 0: + raise NotImplementedError('Not defined for negative values') + elif x < 2: + return x + else: + return fib(x - 2) + fib(x - 1) + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = df['Generation'].apply(fib) + + +Note that the numpy precision for integers caps at int64 while python ints are unbounded -- +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df['Number of Rabbits'][99] given by both functions above +is in fact . + +Alternatives to Pandas +---------------------- + +**Polars** + +`Polars `__ is a DataFrame library designed to processing data with a fast lighting time. Polars is implemented in Rust Programming language and uses `Apache Arrow `__ as its memory format. + +**Dask** + +`Dask `__ is a Python package for parallel computing in Python and uses parallel data-frames for dealing with very large arrays. + +**Vaex** + +`Vaex `__ is a high performance Python library for lazy Out-of-Core DataFrames, to visualize and explore big tabular datasets. + + +.. keypoints:: + + - pandas dataframes are a good data structure for tabular data + - Dataframes allow both simple and advanced analysis in very compact form diff --git a/branch/master/_sources/parallel-pi-multiprocessing.ipynb.txt b/branch/master/_sources/parallel-pi-multiprocessing.ipynb.txt new file mode 100644 index 00000000..970dbada --- /dev/null +++ b/branch/master/_sources/parallel-pi-multiprocessing.ipynb.txt @@ -0,0 +1,303 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Python multithreading solution\n", + "Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import random" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "def sample(n):\n", + " \"\"\"Make n trials of points in the square. Return (n, number_in_circle)\n", + " \n", + " This is our basic function. By design, it returns everything it\\\n", + " needs to compute the final answer: both n (even though it is an input\n", + " argument) and n_inside_circle. To compute our final answer, all we\n", + " have to do is sum up the n:s and the n_inside_circle:s and do our\n", + " computation\"\"\"\n", + " n_inside_circle = 0\n", + " for i in range(n):\n", + " x = random.random()\n", + " y = random.random()\n", + " if x**2 + y**2 < 1.0:\n", + " n_inside_circle += 1\n", + " return n, n_inside_circle" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it just for timing\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Do the actual calculation (the previous result doesn't get saved)\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is the \"calculate answer\" phase." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.144548" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "pi = 4.0 * (n_inside_circle / n)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in parallel with multiprocessing\n", + "This divides the calculation into 10 tasks and runs `sample` on each of them. Then it re-combines the results." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import multiprocessing.pool\n", + "pool = multiprocessing.pool.Pool()\n", + "# The default pool makes one process per CPU" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it once to time it\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "pool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.140768" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in \"parallel\" with threads\n", + "To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool = multiprocessing.pool.ThreadPool()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%timeit -o\n", + "# Do it once to time it\n", + "threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.142388" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Future ideas\n", + "\n", + "You could make a separate `calculate` function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.\n", + "\n", + "Notice the similarity to [split-apply-combine](https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html) or [map-reduce](https://en.wikipedia.org/wiki/MapReduce) which is a specialization of split-apply-combine." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/master/_sources/parallel.rst.txt b/branch/master/_sources/parallel.rst.txt new file mode 100644 index 00000000..2986ef53 --- /dev/null +++ b/branch/master/_sources/parallel.rst.txt @@ -0,0 +1,513 @@ +Parallel programming +==================== + +.. questions:: + + - When you need more than one processor, what do you do? + - How can we use more than one processor/core in Python? + +.. objectives:: + + - Understand the major strategies of parallelizing code + - Understand mechanics of the ``multiprocessing`` package + - Know when to use more advanced packages or approaches + + + +Modes of parallelism +-------------------- + +You realize you do have more computation to do than you can on one processor? +What do you do? + +1. Profile your code, identify the *actual* slow spots. + +2. Can you improve your code in those areas? Use an existing library? + +3. Are there are any low-effort optimizations that you can make? + +4. Consider using `numba `__ or + `cython `__ to accelerate key functions. + +5. Think about parallelizing. + + +Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers). + +**Parallel computing** is when many different tasks are carried out +simultaneously. There are three main models: + +* **Embarrassingly parallel:** the code does not need to + synchronize/communicate with other instances, and you can run + multiple instances of the code separately, and combine the results + later. If you can do this, great! (array jobs, task queues, + workflow management tools) + +* **Multithreading:** Parallel threads need to communicate and do so via + the same memory (variables, state, etc). (OpenMP, ``threading``) + +* **Multiprocessing, message passing:** Different processes manage + their own memory segments. They share data by communicating (passing + messages) as needed. (``multiprocessing``, MPI). + +.. warning:: + + Parallel programming is not magic, but many things can go wrong and + you can get unexpected results or difficult to debug problems. + Parallel programming is a fascinating world to get involved in, but + make sure you invest enough time to do it well. + + See the video by Raymond Hettinger ("See Also" at bottom + of page) for an entertaining take on this. + + + +Multithreading and the GIL +-------------------------- + +The designers of the Python language made the choice +that **only one thread in a process can run actual Python code** +by using the so-called **global interpreter lock (GIL)**. +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. *But it's not all bad!:* + +* External libraries (NumPy, SciPy, Pandas, etc), written in C or other + languages, can release the lock and run multi-threaded. + +* Most input/output releases the GIL, and input/output is slow. The + ``threading`` library can be used to multithread I/O. + +* Python libraries like ``multiprocessing`` and ``mpi4py`` run *multiple + Python processes* and this circumvents the GIL. + + +Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix: + +.. code-block:: python + + import numpy as np + import time + + A = np.random.random((4000,4000)) + A = A * A.T + time_start = time.time() + np.linalg.inv(A) + time_end = time.time() + print("time spent for inverting A is", round(time_end - time_start,2), 's') + +If we run this in a Jupyter notebook or through a Python script, **it +will automatically use multithreading** through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either ``export OMP_NUM_THREADS=1`` or ``export MKL_NUM_THREADS=1``, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime. + + +.. seealso:: + + * `More on the global interpreter lock + `__ + * `Threading python module + `__. This is + very low level and you shouldn't use it unless you really know what + you are doing. + * We recommend you find a UNIX threading tutorial first before embarking + on using the :py:mod:`threading` module. + + + +multiprocessing +--------------- + +As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +:py:mod:`multiprocessing` module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock. + +To show an example, +the `split-apply-combine `__ +or `map-reduce `__ paradigm is +quite useful for many scientific workflows. Consider you have this:: + + def square(x): + return x*x + +You can apply the function to every element in a list using the +:py:func:`map` function: + +.. code-block:: pycon + + >>> list(map(square, [1, 2, 3, 4, 5, 6])) + [1, 4, 9, 16, 25, 36] + +The :py:class:`multiprocessing.pool.Pool` class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list: + +.. code-block:: pycon + + >>> from multiprocessing import Pool + >>> with Pool() as pool: + ... pool.map(square, [1, 2, 3, 4, 5, 6]) + [1, 4, 9, 16, 25, 36] + +.. warning:: + + Running the above example **interactively** in a Jupyter notebook + or through an Python/IPython terminal may or may not work on your + computer! This is a feature and not a bug, as covered in the + `documentation `__. + + Fortunately, there is a fork of multiprocesssing called + `multiprocess `__ which does + work in interactive environments. All we have to do is install it + by ``pip install multiprocess`` and change the import statement: + ``from multiprocess import Pool``. + + +Exercises, multiprocessing +-------------------------- + +.. challenge:: Parallel-1, multiprocessing + + Here, you find some code which calculates pi by a stochastic + algorithm. You don't really need to worry how the algorithm works, + but it computes random points in a 1x1 square, and computes the + number that fall into a circle. Copy it into a Jupyter notebook + and use the ``%%timeit`` cell magic on the computation part (the + one highlighted line after timeit below): + + .. code-block:: python + :emphasize-lines: 20 + + import random + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x**2 + y**2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + %%timeit + n, n_inside_circle = sample(10**6) + + pi = 4.0 * (n_inside_circle / n) + pi + + Using the :py:class:`multiprocessing.pool.Pool` code from the lesson, run + the ``sample`` function 10 times, each with ``10**5`` samples + only. Combine the results and time the calculation. What is the + difference in time taken? + + NOTE: If you're working in an interactive environment and this + doesn't work with the ``multiprocessing`` module, install and use + the ``multiprocess`` module instead! + + (optional, advanced) Do the same but with + :py:class:`multiprocessing.pool.ThreadPool` instead. This works identically + to ``Pool``, but uses threads instead of different processes. + Compare the time taken. + + .. solution:: + + See the finished notebook here :doc:`parallel-pi-multiprocessing`. + + You notice the version with ``ThreadPool`` is no faster, and + probably takes even longer. This is because this is a + pure-Python function which can not run simultaneously in + multiple threads. + +.. challenge:: (advanced) Parallel-2 Running on a cluster + + How does the pool know how many CPUs to take? What happens if you + run on a computer cluster and request only part of the CPUs on a + node? + + .. solution:: + + Pool by default uses one process for each CPU on the node - it + doesn't know about your cluster's scheduling system. It's + possible that you have permission to use 2 CPUs but it is trying + to use 12. This is generally a bad situation, and will just + slow you down (and make other users on the same node upset)! + + You either need to be able to specify the number of CPUs to use + (and pass it the right number), or make it aware of the cluster + system. For example, on a Slurm cluster you would check the + environment variable ``SLURM_CPUS_PER_TASK``. + + Whatever you do, document what your code is doing under the + hood, so that other users know what is going on (we've learned + this from experience...). + + +MPI +--- + +The message passing interface (MPI) approach to parallelization +is that: + +- Tasks (cores) have a rank and are numbered 0, 1, 2, 3, ... +- Each task (core) manages its own memory +- Tasks communicate and share data by sending messages +- Many higher-level functions exist to distribute information to other tasks + and gather information from other tasks +- All tasks typically run the entire code and we have to be careful to avoid + that all tasks do the same thing + +Introductory MPI lessons where Python is included: + +- https://rantahar.github.io/introduction-to-mpi/ +- https://pdc-support.github.io/introduction-to-mpi/ + +These blog posts are good for gentle MPI/mpi4py introduction: + +- https://www.kth.se/blogs/pdc/2019/08/parallel-programming-in-python-mpi4py-part-1/ +- https://www.kth.se/blogs/pdc/2019/11/parallel-programming-in-python-mpi4py-part-2/ + +Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together. + +Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work: + +.. code-block:: python + :emphasize-lines: 3,23-25,29,39,42 + + import random + import time + from mpi4py import MPI + + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x ** 2 + y ** 2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + + comm = MPI.COMM_WORLD + size = comm.Get_size() + rank = comm.Get_rank() + + n = 10 ** 7 + + if size > 1: + n_task = int(n / size) + else: + n_task = n + + t0 = time.perf_counter() + _, n_inside_circle = sample(n_task) + t = time.perf_counter() - t0 + + print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}") + n_inside_circle = comm.gather(n_inside_circle, root=0) + print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}") + + if rank == 0: + pi_estimate = 4.0 * sum(n_inside_circle) / n + print( + f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds" + ) + + + +Exercises, MPI +-------------- + +.. challenge:: Parallel-3, MPI + + We can do this as **exercise or as demo**. Note that this example requires ``mpi4py`` and a + MPI installation such as for instance `OpenMPI `__. + + - Try to run this example on one core: ``$ python example.py``. + - Then compare the output with a run on multiple cores (in this case 2): ``$ mpiexec -n 2 python example.py``. + - Can you guess what the ``comm.gather`` function does by looking at the print-outs right before and after. + - Why do we have the if-statement ``if rank == 0`` at the end? + - Why did we use ``_, n_inside_circle = sample(n_task)`` and not ``n, n_inside_circle = sample(n_task)``? + + + .. solution:: + + We first run the example normally, and get: + + .. code-block:: console + + $ python example.py + before gather: rank 0, n_inside_circle: 7854305 + after gather: rank 0, n_inside_circle: [7854305] + + number of darts: 10000000, estimate: 3.141722, time spent: 2.5 seconds + + Next we take advantage of the MPI parallelisation and run on 2 cores: + + .. code-block:: console + + $ mpirun -n 2 python mpi_test.py + before gather: rank 0, n_inside_circle: 3926634 + before gather: rank 1, n_inside_circle: 3925910 + after gather: rank 1, n_inside_circle: None + after gather: rank 0, n_inside_circle: [3926634, 3925910] + + number of darts: 10000000, estimate: 3.1410176, time spent: 1.3 seconds + + Note that two MPI processes are now printing output. Also, the parallel + version runs twice as fast! + + The ``comm.gather`` function collects (gathers) values of a + given variable from all MPI ranks onto one `root` rank, which is + conventionally rank 0. + + A conditional ``if rank == 0`` is typically used to print output + (or write data to file, etc) from only one rank. + + An underscore ``_`` is often used as a variable name in cases + where the data is unimportant and will not be reused. + +Coupling to other languages +--------------------------- + +As mentioned further up in "Multithreading and the GIL", Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP "directly". + +However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don't +need parallelism, but need to make an optimized algorithm for a small part of the code. + +Two strategies are common: + +- Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization: + + - C: use the `cffi `__ package (C foreign function interface). :py:mod:`ctypes` is a similar but slightly more primitive module that is in the standard library. + - C++: use `pybind11 `__ + - Fortran: create a C interface using ``iso_c_binding`` and then couple the C layer to Python + using `cffi `__ + - Rust: use `PyO3 `__ + +- Let compiled languages do the shared-memory parallelization part (as in above + point) and let Python do the MPI work and distribute tasks across nodes using + an ``mpi4py`` layer. + +Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course. + +Before you take this route, **profile the application** first to be sure where +the bottleneck is. + +Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason. + + + +Dask and task queues +-------------------- + +There are other strategies that go completely beyond the manual +parallelization methods above. We won't go into much detail. + +Dask +~~~~ + +`Dask `__ is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs. + +Dask is very popular for data analysis and is used by a number of high-level Python libraries: + +- Dask arrays scale NumPy (see also `xarray `__ +- Dask dataframes scale Pandas workflows +- Dask-ML scales Scikit-Learn + +Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block. + +.. discussion:: Example from dask.org + + .. code-block:: + + # Arrays implement the Numpy API + import dask.array as da + x = da.random.random(size=(10000, 10000), + chunks=(1000, 1000)) + x + x.T - x.mean(axis=0) + # It runs using multiple threads on your machine. + # It could also be distributed to multiple machines + + + +Exercises, Dask +--------------- + +.. challenge:: Dask-Examples (optional) + + `Dask examples `__ illustrate the usage of dask and can be run interactively through `mybinder `__. Start an `interactive session on mybinder `__ and test/run a few dask examples. + +.. warning: dask on HPC + + On HPC, it is important to use `dask-mpi `__ that deploys dask using MPI4Py. The setup can be a bit tricky and we recommend the usage of `dask-jobqueue and dask-drmaa `__: these packages need to be installed on the target platform (not through conda) to fully benefit from the native underlying MPI libraries. + +Task queues +~~~~~~~~~~~ + +A **task queue** has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for *embarrassingly parallel* jobs. + +There are different descriptions of `task queues in Python +`__. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant. + + + +See also +-------- + +* `Thinking about Concurrency, Raymond Hettinger + `__. Good introduction to simple and + safe concurrent code. +* `Introduction to Numba and Cython `__. +* `More detailed exposition of parallel computing in Python `__. +* `Introduction to Dask for scalable analytics `__. + +.. keypoints:: + + - Pure Python is not very good for highly parallel code. + - Luckily it interfaces to many things which *are* good, and give + you the full control you need. + - Combining vectorized functions (NumPy, Scipy, pandas, etc.) with + the parallel strategies listed here will get you very far. + - Another popular framework similar to `multiprocessing` is + `joblib `__. diff --git a/branch/master/_sources/plotting-matplotlib.md.txt b/branch/master/_sources/plotting-matplotlib.md.txt new file mode 100644 index 00000000..f09b0736 --- /dev/null +++ b/branch/master/_sources/plotting-matplotlib.md.txt @@ -0,0 +1,434 @@ +# Plotting with Matplotlib + +```{questions} +- What happens if you can't automatically produce plots? +- When to use Matplotlib for data visualization? +- When to prefer other libraries? +``` + +```{objectives} +- Be able to create simple plots with Matplotlib and tweak them +- Know about object-oriented vs pyplot interfaces of Matplotlib +- Be able to adapt gallery examples +- Know how to look for help +- Know that other tools exist +``` + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **Try to minimize manual post-processing**. This could bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Vega-Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization, statistics built in + (we have an [entire lesson about data visualization using Vega-Altair](https://coderefinery.github.io/data-visualization-python/)) + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/gallery/index.html): + Jupyter Notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative. + + +## Why are we starting with Matplotlib? + +- Matplotlib is perhaps the most popular Python plotting library. +- Many libraries build on top of Matplotlib (example: [Seaborn](https://seaborn.pydata.org/examples/index.html)). +- MATLAB users will feel familiar. +- Even if you choose to use another library (see above list), chances are high + that you need to adapt a Matplotlib plot of somebody else. +- Libraries that are built on top of Matplotlib may need knowledge of Matplotlib + for custom adjustments. + +However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code. + +Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. + + +## Getting started with Matplotlib + +We can start in a Jupyter Notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK. + +Let us create our first plot using +{func}`~matplotlib.pyplot.subplots`, +{obj}`~matplotlib.axes.Axes.scatter`, and some other methods on the +{obj}`~matplotlib.axes.Axes` object: + +```python +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("my-first-plot.png") +``` + +```{figure} plotting-matplotlib/first-plot/getting-started.png +:alt: Result of our first plot +:width: 80% + +This is the result of our first plot. +``` + +When running a Matplotlib script on a remote server without a +"display" (e.g. compute cluster), you may need to add the +{obj}`matplotlib.use` call: + +```python +import matplotlib.pyplot as plt +matplotlib.use("Agg") + +# ... rest of the script +``` + +## Exercise: Matplotlib + +````{challenge} Exercise Matplotlib-1: extend the previous example (15 min) +- Extend the previous plot by also plotting this set of values but this time + using a different color (`#56B4E9`): + ```python + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + ``` + +- Then add another color (`#009E73`) which plots the second dataset, scaled + by 2.0. + ```python + # here we multiply all elements of data2_y by 2.0 + data2_y_scaled = [y * 2.0 for y in data2_y] + ``` + +- Try to add a legend to the plot with {meth}`matplotlib.axes.Axes.legend` and searching the web for clues on + how to add labels to each dataset. + You can also consult this great + [quick start guide](https://matplotlib.org/stable/users/explain/quick_start.html). + +- At the end it should look like this one: + ```{figure} plotting-matplotlib/first-plot/exercise.png + :alt: Result of the exercise + ``` + +- Experiment also by using named colors (e.g. "red") instead of the hex-codes. +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 9, 12, 17-18, 23 +--- +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +# this is dataset 2 +data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + +# here we multiply all elements of data2_y by 2.0 +data2_y_scaled = [y * 2.0 for y in data2_y] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00", label="set 1") +ax.scatter(x=data_x, y=data2_y, c="#56B4E9", label="set 2") +ax.scatter(x=data_x, y=data2_y_scaled, c="#009E73", label="set 2 (scaled)") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") +ax.legend() + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("exercise-plot.png") +``` +```` + +```{discussion} Why these colors? +This qualitative color palette is optimized for all color-vision +deficiencies, see and +[Okabe, M., and K. Ito. 2008. "Color Universal Design (CUD): +How to Make Figures and Presentations That Are Friendly to Colorblind People"](http://jfly.iam.u-tokyo.ac.jp/color/). +``` + +--- + +## Matplotlib has two different interfaces + +When plotting with Matplotlib, it is useful to know and understand that +there are **two approaches** even though the reasons of this dual approach is +outside the scope of this lesson. + +- The more modern option is an **object-oriented interface** or **explicit interface** (the + {class}`fig ` and {class}`ax ` objects + can be configured separately and passed around to functions): + ```{code-block} python + --- + emphasize-lines: 8-14 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + ``` + +- The more traditional option mimics MATLAB plotting and uses the + **pyplot interface** or **implicit interface** ({mod}`plt ` carries + the global settings): + ```{code-block} python + --- + emphasize-lines: 8-12 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + plt.scatter(x=data_x, y=data_y, c="#E69F00") + + plt.xlabel("we should label the x axis") + plt.ylabel("we should label the y axis") + plt.title("some title") + ``` + +When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, **we +recommend to learn and use the object oriented interface.** + +```{discussion} Why do we emphasize this? +One day you may want to write functions which wrap +around Matplotlib function calls and then you can send {class}`~matplotlib.figure.Figure` and {class}`~matplotlib.axes.Axes` +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions. + +When using the pyplot interface, settings are modified for the entire +{mod}`matplotlib.pyplot` package. The latter is acceptable for simple scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls. +``` + +--- + +## Styling and customizing plots + +- Before you customize plots "manually" using a graphical program, please + consider how this affects reproducibility. +- **Try to minimize manual post-processing**. This might bite you when you + need to regenerate 50 figures one day before submission deadline or + regenerate a set of figures after the person who created them left the group. +- Matplotlib and also all the other libraries allow to customize almost every aspect of a plot. +- It is useful to study [Matplotlib parts of a figure](https://matplotlib.org/stable/users/explain/quick_start.html#parts-of-a-figure) + so that we know what to search for to customize things. +- Matplotlib cheatsheets: +- You can also select among pre-defined themes/ + [style + sheets](https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html) + with {obj}`~matplotlib.style.use`, for instance: + ```python + plt.style.use('ggplot') + ``` + + +## Exercises: Styling and customization + +Here are 3 exercises where we try to adapt existing scripts to either **tweak +how the plot looks** (exercises 1 and 2) or to **modify the input data** (example 3). + +This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice: +- Select an example that is close to what you have in mind +- Being able to adapt it to your needs +- Being able to search for help +- Being able to understand help request answers (not easy) + +````{challenge} Exercise Customization-1: log scale in Matplotlib (15 min) +In this exercise we will learn how to use log scales. + +- To demonstrate this we first fetch some data to plot: + ```python + import pandas as pd + + url = ( + "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + ) + gapminder_data = pd.read_csv(url).query("year == 2007") + + gapminder_data + ``` +- Try the above snippet in a notebook and it will give you an overview over the data. + +- Then we can plot the data, first using a linear scale: + ```python + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + + ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) + + ax.set_xlabel("GDP per capita (PPP dollars)") + ax.set_ylabel("Life expectancy (years)") + ``` + + This is the result but we realize that a linear scale is not ideal here: + ```{figure} plotting-matplotlib/customizing/gapminder-linear.png + :alt: Gapminder data plotted using a linear scale + ``` + +- Your task is to switch to a log scale and arrive at this result: + ```{figure} plotting-matplotlib/customizing/gapminder-log.png + :alt: Gapminder data plotted using log scale + ``` + +- What does ``alpha=0.5`` do? +```` + +````{solution} +See {meth}`ax.set_xscale() `. + +```{code-block} python +--- +emphasize-lines: 5 +--- +fig, ax = plt.subplots() + +ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP per capita (PPP dollars)") +ax.set_ylabel("Life expectancy (years)") +``` +* {obj}`alpha ` sets transparency + of points. +```` + +````{challenge} Exercise Customization-2: preparing a plot for publication (15 min) +Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches. + +For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small. + +Your task is to make the tickmarks and the axis label font larger, using +[Matplotlib parts of a figure](https://matplotlib.org/stable/users/explain/quick_start.html#parts-of-a-figure) +and web search, and to arrive at this: + +```{figure} plotting-matplotlib/customizing/gapminder-larger-font.png +:alt: Gapminder data plotted with larger font and larger ticks +``` +```` + +````{solution} +See {meth}`ax.tick_params `. + +```{code-block} python +--- +emphasize-lines: 7-8, 10-12 +--- +fig, ax = plt.subplots() + +ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data) + +ax.set_xscale("log") + +ax.set_xlabel("GDP per capita (PPP dollars)", fontsize=15) +ax.set_ylabel("Life expectancy (years)", fontsize=15) + +ax.tick_params(which="major", length=10) +ax.tick_params(which="minor", length=5) +ax.tick_params(labelsize=15) +``` +```` + +--- + +```{discussion} +After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on. +``` + +--- + +## Matplotlib and pandas DataFrames + +In the above exercises we have sent individual columns of the `gapminder_data` DataFrame +into `ax.scatter()` like this: +```python +fig, ax = plt.subplots() + +ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) +``` + +It is possible to do this instead and let Matplotlib "unpack" the columns: +```python +fig, ax = plt.subplots() + +ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data) +``` + +Other input types are possible. See [Types of inputs to plotting +functions](https://matplotlib.org/stable/users/explain/quick_start.html#types-of-inputs-to-plotting-functions). + +--- + +```{keypoints} +- Minimize manual post-processing, script everything. +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Figures for presentation slides and figures for manuscripts have + different requirements. +- Think about color-vision deficiencies when choosing colors. Use + existing solutions for this problem. +``` diff --git a/branch/master/_sources/plotting-vega-altair.md.txt b/branch/master/_sources/plotting-vega-altair.md.txt new file mode 100644 index 00000000..f775d36d --- /dev/null +++ b/branch/master/_sources/plotting-vega-altair.md.txt @@ -0,0 +1,690 @@ +# Plotting with [Vega-Altair](https://altair-viz.github.io/) + +:::{objectives} +- Be able to create simple plots with Vega-Altair and tweak them +- Know how to look for help +- Reading data with Pandas from disk or a web resource +- Know how to tweak example plots from a gallery for your own purpose +- We will build up + [this notebook](https://nbviewer.org/github/AaltoSciComp/python-for-scicomp/blob/master/resources/notebooks/plotting.ipynb) + (spoiler alert!) +::: + +:::{instructor-note} +- 10 min: Introduction +- 10 min: Type-along (creating a first plot) +- 20 min: Exercise (using visual channels) +- 20 min: Exercise (adapting a gallery example and customizing) +- 10 min: Key points, discussion, and Q&A +::: + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **Try to minimize manual post-processing**. This could bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Vega-Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization, statistics built in + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/gallery/index.html): + Jupyter Notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative (e.g. Vega-Altair). + + +## Why are we starting with [Vega-Altair](https://altair-viz.github.io/)? + +- Concise and powerful +- "Simple, friendly and consistent API" allows us to focus on the data + visualization part and get started without too much Python knowledge +- The way it **combines visual channels with data columns** can feel intuitive +- Interfaces very nicely with [Pandas](https://pandas.pydata.org/) ({ref}`earlier episode `) +- Easy to change figures +- Good documentation +- Open source +- Makes it easy to save figures in a number of formats (svg, png, html) +- Easy to save interactive visualizations to be used in websites + + +## Example data: Weather data from two Norwegian cities + +We will experiment with some example weather data obtained from [Norsk +KlimaServiceSenter](https://seklima.met.no/observations/), Meteorologisk +institutt (MET) (CC BY 4.0). The data is in CSV format (comma-separated +values) and contains daily and monthly weather data for two cities in Norway: +Oslo and Tromsø. You can browse the data +[here in the lesson repository](https://github.com/AaltoSciComp/python-for-scicomp/tree/master/resources/data/plotting). + +We will use the Pandas library to read the data into a dataframe. We have learned about Pandas in an {ref}`earlier episode `. + +Pandas can read from and write to a large set of formats +([overview of input/output functions and formats](https://pandas.pydata.org/pandas-docs/stable/reference/io.html)). +We will load a CSV file directly from the web. Instead of using a web URL we +could use a local file name instead. + +Pandas dataframes are a great data structure for **tabular data** and tabular +data turns out to be a great input format for data visualization libraries. +Vega-Altair understands Pandas dataframes and can plot them directly. + + +## Reading data into a dataframe + +We can try this together in a notebook: +Using Pandas we can **merge, join, concatenate, and compare** +dataframes, see . + +Let us try to **concatenate** two dataframes: one for Tromsø weather data (we +will now load monthly values) and one for Oslo: +```{code-block} python +--- +emphasize-lines: 8 +--- +import pandas as pd + +url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/" + +data_tromso = pd.read_csv(url_prefix + "tromso-monthly.csv") +data_oslo = pd.read_csv(url_prefix + "oslo-monthly.csv") + +data_monthly = pd.concat([data_tromso, data_oslo], axis=0) + +# let us print the combined result +data_monthly +``` + +Before plotting the data, there is a problem which we may not see yet: Dates +are not in a standard date format (YYYY-MM-DD). We can fix this: +```python +# replace mm.yyyy to date format +data_monthly["date"] = pd.to_datetime(list(data_monthly["date"]), format="%m.%Y") +``` + +With Pandas it is possible to do a lot more (adjusting missing values, fixing +inconsistencies, changing format). + + +## Plotting the data + +Now let's plot the data. We will start with a plot that is not optimal and +then we will explore and improve a bit as we go: + +```python +import altair as alt + +alt.Chart(data_monthly).mark_bar().encode( + x="date", + y="precipitation", + color="name", +) +``` + +:::{figure} plotting-vega-altair/precipitation-on-top.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +::: + +:::{discussion} Let us pause and explain the code +- `alt` is a short-hand for `altair` which we imported on top of the notebook +- `Chart()` is a function defined inside `altair` which takes the data as argument +- `mark_bar()` is a function that produces bar charts +- `encode()` is a function which encodes data columns to **visual channels** + +Observe how we connect (encode) **visual channels** to data columns: +- x-coordinate with "date" +- y-coordinate with "precipitation" +- color with "name" (name of weather station; city) +::: + +We can improve the plot by giving Vega-Altair a bit more information that the +x-axis is **temporal** (T) and that we would like to see the year and +month (yearmonth): +```{code-block} python +--- +emphasize-lines: 2 +--- +alt.Chart(data_monthly).mark_bar().encode( + x="yearmonth(date):T", + y="precipitation", + color="name", +) +``` + +Apart from T (temporal), there are other +[encoding data types](https://altair-viz.github.io/user_guide/encodings/index.html#encoding-data-types): +- Q (quantitative) +- O (ordinal) +- N (nominal) +- T (temporal) +- G (geojson) + +:::{figure} plotting-vega-altair/precipitation-on-top-yearmonth.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +::: + +Let us improve the plot with another one-line change: +```{code-block} python +--- +emphasize-lines: 5 +--- +alt.Chart(data).mark_bar().encode( + x="yearmonth(date):T", + y="precipitation", + color="name", + column="name", +) +``` + +:::{figure} plotting-vega-altair/precipitation-side.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. +::: + +With another one-line change we can make the bar chart stacked: +```{code-block} python +--- +emphasize-lines: 5 +--- +alt.Chart(data_monthly).mark_bar().encode( + x="yearmonth(date):T", + y="precipitation", + color="name", + xOffset="name", +) +``` +:::{figure} plotting-vega-altair/precipitation-stacked-x.svg +:alt: Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. + +Monthly precipitation for the cities Oslo and Tromsø over the course of a year +plotted as stacked bar chart. +::: + +This is not publication-quality yet but a really good start! + +Let us try one more example where we can nicely see how Vega-Altair +is able to map visual channels to data columns: +```python +alt.Chart(data_monthly).mark_area(opacity=0.5).encode( + x="yearmonth(date):T", + y="max temperature", + y2="min temperature", + color="name", +) +``` + +:::{figure} plotting-vega-altair/temperature-ranges-combined.svg +:alt: Monthly temperature ranges for two cities in Norway. + +Monthly temperature ranges for two cities in Norway. +::: + +:::{discussion} What other marks and other visual channels exist? +- [Overview of available marks](https://altair-viz.github.io/user_guide/marks/index.html) +- [Overview of available visual channels](https://altair-viz.github.io/user_guide/encodings/channels.html) +- [Gallery of examples](https://altair-viz.github.io/gallery/index.html) +::: + + +## Exercise: Using visual channels to re-arrange plots + +::::{exercise} Plotting-1: Using visual channels to re-arrange plots +1. Try to reproduce the above plots if they are not already in your notebook. + +1. Above we have plotted the monthly precipitation for two cities side by side + using a stacked plot. Try to arrive at the following plot where months are + along the y-axis and the precipitation amount is along the x-axis: + :::{figure} plotting-vega-altair/precipitation-stacked-y.svg + ::: + +1. Ask the Internet or AI how to change the axis title from "precipitation" + to "Precipitation (mm)". + +1. Modify the temperature range plot to show the temperature ranges for the + two cities side by side like this: + :::{figure} plotting-vega-altair/temperature-ranges-side.svg + ::: + +:::{solution} +1. Copy-paste code blocks from above. + +1. Basically we switched x and y: + ```{code-block} python + --- + emphasize-lines: 2,3,5 + --- + alt.Chart(data_monthly).mark_bar().encode( + y="yearmonth(date):T", + x="precipitation", + color="name", + yOffset="name", + ) + ``` + +1. This can be done with the following modification: + ```{code-block} python + --- + emphasize-lines: 3 + --- + alt.Chart(data_monthly).mark_bar().encode( + y="yearmonth(date):T", + x=alt.X("precipitation").title("Precipitation (mm)"), + color="name", + yOffset="name", + ) + ``` + +1. We added one line: + ```{code-block} python + --- + emphasize-lines: 6 + --- + alt.Chart(data_monthly).mark_area(opacity=0.5).encode( + x="yearmonth(date):T", + y="max temperature", + y2="min temperature", + color="name", + column="name", + ) + ``` +::: +:::: + + +## More fun with visual channels + +Now we will try to **plot the daily data and look at snow depths**. We first +read and concatenate two datasets: +```python +url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/" + +data_tromso = pd.read_csv(url_prefix + "tromso-daily.csv") +data_oslo = pd.read_csv(url_prefix + "oslo-daily.csv") + +data_daily = pd.concat([data_tromso, data_oslo], axis=0) +``` + +We adjust the data a bit: +```python +# replace dd.mm.yyyy to date format +data_daily["date"] = pd.to_datetime(list(data_daily["date"]), format="%d.%m.%Y") + +# we are here only interested in the range december to may +data_daily = data_daily[ + (data_daily["date"] > "2022-12-01") & (data_daily["date"] < "2023-05-01") +] +``` + +Now we can plot the snow depths for the months December to May for the two +cities: +```python +alt.Chart(data_daily).mark_bar().encode( + x="date", + y="snow depth", + column="name", +) +``` + +:::{figure} plotting-vega-altair/snow-depth.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. +::: + +What happens if we try to color the plot by the "max temperature" values? +```{code-block} python +--- +emphasize-lines: 4 +--- +alt.Chart(data_daily).mark_bar().encode( + x="date", + y="snow depth", + color="max temperature", + column="name", +) +``` + +The result looks neat: +:::{figure} plotting-vega-altair/snow-depth-color.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. +::: + +We can change the color scheme ([available color schemes](https://vega.github.io/vega/docs/schemes/)): +```{code-block} python +--- +emphasize-lines: 4 +--- +alt.Chart(data_daily).mark_bar().encode( + x="date", + y="snow depth", + color=alt.Color("max temperature").scale(scheme="plasma"), + column="name", +) +``` + +With the following result: +:::{figure} plotting-vega-altair/snow-depth-plasma.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +::: + +Let's try one more change to show that we can experiment with different +plot types by changing `mark_bar()` to something else, in this case `mark_circle()`: +```{code-block} python +--- +emphasize-lines: 1 +--- +alt.Chart(data_daily).mark_circle().encode( + x="date", + y="snow depth", + color=alt.Color("max temperature").scale(scheme="plasma"), + column="name", +) +``` + +:::{figure} plotting-vega-altair/snow-depth-circles.svg +:alt: Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. + +Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +::: + + +## Themes + +In [Vega-Altair](https://altair-viz.github.io/) you can change the theme and +select from a long [list of themes](https://github.com/vega/vega-themes). On +top of your notebook try to add: +```python +alt.themes.enable('dark') +``` +Then re-run all cells. Later you can try some other themes such as: +- `fivethirtyeight` +- `latimes` +- `urbaninstitute` + +You can even define your own themes! + + +## Exercise: Adapting a gallery example + +In this exercise we can try to adapt existing scripts to either **tweak how the +plot looks** or to **modify the input data**. This is very close to real life: +there are so many options and possibilities and it is almost impossible to +remember everything so this strategy is useful to practice: +- Select an example that is close to what you have in mind +- Being able to adapt it to your needs +- Being able to search for help + +::::{exercise} Plotting-2: Adapting a gallery example +**This is a great exercise which is very close to real life.** + +- Browse the [Vega-Altair example gallery](https://altair-viz.github.io/gallery/index.html). +- Select one example that is close to your current/recent visualization project + or simply interests you. +- First try to reproduce this example, as-is, in the Jupyter Notebook. +- **If you get the error "ModuleNotFoundError: No module named + 'vega_datasets'", then try one of these examples:** (they do not need the "vega_datasets" module) + - [Slider cutoff](https://altair-viz.github.io/gallery/slider_cutoff.html) + (**below you can find a walk-through for this example**) + - [Multi-Line tooltip](https://altair-viz.github.io/gallery/multiline_tooltip_standard.html) + - [Heatmap](https://altair-viz.github.io/gallery/simple_heatmap.html) + - [Layered histogram](https://altair-viz.github.io/gallery/layered_histogram.html) +- Then try to print out the data that is used in this example just before the call of the plotting function + to learn about its structure. Consider writing the data to file before changing it. +- Then try to modify the data a bit. +- If you have time, try to feed it different, simplified data. + **This will be key for adapting the examples to your projects.** + +:::{solution} Example walk-through for the slider cutoff example +In this walk-through I imagine browsing: + +Then this example caught my eye: + +I then copy-paste the example code into a notebook and try to run it and I get +the same result. + +If you get stuck below, **you can also browse all the steps** in a [notebook +using +nbviewer](https://nbviewer.org/github/AaltoSciComp/python-for-scicomp/blob/master/resources/notebooks/plotting-exercise-2.ipynb). + +Next, there is a lot of code that I don't (need to) understand yet but my eyes are trying to find +`alt.Chart` which tells me that the data must be the "df" in `alt.Chart(df)`: +```{code-block} python +--- +emphasize-lines: 15 +--- +import altair as alt +import pandas as pd +import numpy as np + +rand = np.random.RandomState(42) + +df = pd.DataFrame({ + 'xval': range(100), + 'yval': rand.randn(100).cumsum() +}) + +slider = alt.binding_range(min=0, max=100, step=1) +cutoff = alt.param(bind=slider, value=50) + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff +) +``` + +My next step will be to print out the data `df` just before the call to `alt.Chart`: +```{code-block} python +--- +emphasize-lines: 15 +--- +import altair as alt +import pandas as pd +import numpy as np + +rand = np.random.RandomState(42) + +df = pd.DataFrame({ + 'xval': range(100), + 'yval': rand.randn(100).cumsum() +}) + +slider = alt.binding_range(min=0, max=100, step=1) +cutoff = alt.param(bind=slider, value=50) + +print(df) + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff + ) +``` + +The print reveals that `df` is a dataframe which contains x and y values: +```text + xval yval +0 0 0.496714 +1 1 0.358450 +2 2 1.006138 +3 3 2.529168 +4 4 2.295015 +.. ... ... +95 95 -10.712354 +96 96 -10.416233 +97 97 -10.155178 +98 98 -10.150065 +99 99 -10.384652 + +[100 rows x 2 columns] +``` + +The next thing that often helps me is to save the data to a comma-separated +values (CSV) file: +```python +import pandas as pd + +df.to_csv("data.csv", index=False) +``` + +I then open the file in an editor and see that it contains 100 rows: +```text +xval,yval +0,0.4967141530112327 +1,0.358449851840048 +2,1.0061383899407406 +3,2.5291682463487657 +4,2.2950148716254297 +5,2.060877914676249 +6,3.6400907301836405 +7,4.407525459336549 +8,3.938051073401597 +9,4.4806111169875615 +... +``` + +Saving the data to file often helps me to see the structure of the data and now +I am in a position to replace this with my own data. I create a file called +"mydata.csv" and there I use the maximum temperatures for months 1-10 from the +Tromso monthly data which we used further up: +```text +xval,yval +01,7.7 +02,6.6 +03,4.5 +04,9.8 +05,17.7 +06,25.4 +07,26.7 +08,25.1 +09,19.3 +10,9.8 +``` + +In the notebook I then verify that the reading of the data works: +```python +mydata = pd.read_csv("mydata.csv") + +mydata +``` + +Now I can replace the example with my own data (note how I now can comment out +some code that I don't need any longer): +```{code-block} python +--- +emphasize-lines: 16 +--- +import altair as alt +import pandas as pd +# import numpy as np + +# rand = np.random.RandomState(42) + +# df = pd.DataFrame({ +# 'xval': range(100), +# 'yval': rand.randn(100).cumsum() +# }) + +slider = alt.binding_range(min=0, max=100, step=1) +cutoff = alt.param(bind=slider, value=50) + +# print(df) +df = pd.read_csv("mydata.csv") + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff + ) +``` + +Seems to work! I then make few more adjustments (I want the slider to work on +the y-axis and have a more reasonable default): +```{code-block} python +--- +emphasize-lines: 4,5,13 +--- +import altair as alt +import pandas as pd + +slider = alt.binding_range(min=0, max=30, step=1) +cutoff = alt.param(bind=slider, value=15) + +df = pd.read_csv("mydata.csv") + +alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.yval < cutoff, + alt.value('red'), alt.value('blue') + ) +).add_params( + cutoff + ) +``` + +My next steps would then be to change axis titles, display the month names, add +a legend, and refine from here. + +**You can also browse all the steps** in a [notebook using +nbviewer](https://nbviewer.org/github/AaltoSciComp/python-for-scicomp/blob/master/resources/notebooks/plotting-exercise-2.ipynb). +::: +:::: + +--- + +:::{keypoints} +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Minimize manual post-processing and try to script all steps. +- CSV (comma-separated values) files are often a good format to store the data + that we wish to plot. +- Read the data into a Pandas dataframe and then plot it with Vega-Altair + where you connect data columns to + [visual channels](https://altair-viz.github.io/user_guide/encodings/channels.html). +::: diff --git a/branch/master/_sources/productivity.md.txt b/branch/master/_sources/productivity.md.txt new file mode 100644 index 00000000..4a660c37 --- /dev/null +++ b/branch/master/_sources/productivity.md.txt @@ -0,0 +1,188 @@ +# Productivity tools + +:::{objectives} +- Know about tools that can help you **spot code problems** and help you following + a **consistent code style** without you having to do it manually. +- Get an overview of **AI-based tools** and how they can help you + writing code. +::: + +:::{instructor-note} +- Demo/discussion: 20 min +::: + + +## Linters and formatters + +**Linter**: Tool that analyzes source code to detect potential errors, unused +imports, unused variables, code style violations, and to improve readability. +- Popular linters: + - [Autoflake](https://pypi.org/project/autoflake/) + - [Flake8](https://flake8.pycqa.org/) + - [Pyflakes](https://pypi.org/project/pyflakes/) + - [Pycodestyle](https://pycodestyle.pycqa.org/) + - [Pylint](https://pylint.readthedocs.io/) + - [Ruff](https://docs.astral.sh/ruff/) + +**Formatter**: Tool that automatically formats your code to a consistent style, +for instance following [PEP 8](https://peps.python.org/pep-0008/). + +- Popular formatters: + - [Black](https://black.readthedocs.io/) + - [YAPF](https://github.com/google/yapf) + - [Ruff](https://docs.astral.sh/ruff/) + +In this course we will focus on [Ruff](https://docs.astral.sh/ruff/) since it +can do **both checking and formatting** and you don't have to switch between +multiple tools. + +:::{discussion} Linters and formatters can be configured to your liking +These tools typically have good defaults. But if you don't like the defaults, +you can configure what they should ignore or how they should format or not format. +::: + + +## Examples + +This code example (which we possibly recognize from the previous section about +{ref}`profiling`) +has few problems (highlighted): +```{code-block} python +--- +emphasize-lines: 2, 7, 10 +--- +import re +import requests + + +def count_unique_words(file_path: str) -> int: + unique_words = set() + forgotten_variable = 13 + with open(file_path, "r", encoding="utf-8") as file: + for line in file: + words = re.findall(r"\b\w+\b", line.lower())) + for word in words: + unique_words.add(word) + return len(unique_words) +``` + +Please try whether you can locate these problems using Ruff: +```console +$ ruff check +``` + +Next, let us try to auto-format a code example which is badly formatted and also difficult +to read: +:::::{tabs} + ::::{tab} Badly formatted + ```python + import re + def count_unique_words (file_path : str)->int: + unique_words=set() + with open(file_path,"r",encoding="utf-8") as file: + for line in file: + words=re.findall(r"\b\w+\b",line.lower()) + for word in words: + unique_words.add(word) + return len( unique_words ) + ``` + :::: + + ::::{tab} Auto-formatted + ```python + import re + + + def count_unique_words(file_path: str) -> int: + unique_words = set() + with open(file_path, "r", encoding="utf-8") as file: + for line in file: + words = re.findall(r"\b\w+\b", line.lower()) + for word in words: + unique_words.add(word) + return len(unique_words) + ``` + + This was done using: + ```console + $ ruff format + ``` + :::: +::::: + + +## Type checking + +A (static) type checker is a tool that checks whether the types of variables in your +code match the types that you have specified. +- Tools: + - [Mypy](https://mypy.readthedocs.io/) + - [Pyright](https://github.com/microsoft/pyright) (Microsoft) + - [Pyre](https://pyre-check.org/) (Meta) + + +## Integration with editors + +Many/most of the above tools can be integrated with your editor. For instance, +you can configure your editor to automatically format your code when you save +the file. However, this only makes sense when all team members agree to follow +the same style, otherwise saving and possibly committing changes to version +control will show up changes to code written by others which you possibly +didn't intend to make. + + +## Integration with Jupyter notebooks + +It is possible to automatically format your code in Jupyter notebooks! +For this to work you need +the following three dependencies installed: +- `jupyterlab-code-formatter` +- `black` +- `isort` + +More information and a screen-cast of how this works can be found at +. + + +## Integration with version control + +If you use version control and like to have your code checked or formatted +**before you commit the change**, you can use tools like [pre-commit](https://pre-commit.com/). + + +## AI-assisted coding + +We can use AI as an assistant/apprentice: +- Code completion +- Write a test based on an implementation +- Write an implementation based on a test + +Or we can use AI as a mentor: +- Explain a concept +- Improve code +- Show a different (possibly better) way of implementing the same thing + + +:::{figure} productivity/chatgpt.png +:alt: Screenshot of ChatGPT +:width: 100% + +Example for using a chat-based AI tool. +::: + +:::{figure} productivity/code-completion.gif +:alt: Screen-cast of working with GitHub Copilot +:width: 100% + +Example for using AI to complete code in an editor. +::: + +:::{admonition} AI tools open up a box of questions +- Legal +- Ethical +- Privacy +- Lock-in/ monopolies +- Lack of diversity +- Will we still need to learn programming? +- How will it affect learning and teaching programming? +::: diff --git a/branch/master/_sources/profiling.md.txt b/branch/master/_sources/profiling.md.txt new file mode 100644 index 00000000..3136d599 --- /dev/null +++ b/branch/master/_sources/profiling.md.txt @@ -0,0 +1,215 @@ +# Profiling + +:::{objectives} +- Understand when improving code performance is worth the time and effort. +- Knowing how to find performance bottlenecks in Python code. +- Try `scalene` as one of many tools to profile Python code. +::: + +:::{instructor-note} +- Discussion: 20 min +- Exercise: 20 min +::: + + +## Should we even optimize the code? + +Classic quote to keep in mind: "Premature optimization is the root of all evil." [Donald Knuth] + +:::{discussion} +It is important to ask ourselves whether it is worth it. +- Is it worth spending e.g. 2 days to make a program run 20% faster? +- Is it worth optimizing the code so that it spends 90% less memory? + +Depends. What does it depend on? +::: + + +## Measure instead of guessing + +Before doing code surgery to optimize the run time or lower the memory usage, +we should **measure** where the bottlenecks are. This is called **profiling**. + +Analogy: Medical doctors don't start surgery based on guessing. They first measure +(X-ray, MRI, ...) to know precisely where the problem is. + +Not only programming beginners can otherwise guess wrong, but also experienced +programmers can be surprised by the results of profiling. + + +## One of the simplest tools is to insert timers + +Below we will list some tools that can be used to profile Python code. +But even without these tools you can find **time-consuming parts** of your code +by inserting timers: + + + +```{code-block} python +--- +emphasize-lines: 1,8,10 +--- +import time + + +# ... +# code before the function + + +start = time.time() +result = some_function() +print(f"some_function took {time.time() - start} seconds") + + +# code after the function +# ... +``` + + +## Many tools exist + +The list below here is probably not complete, but it gives an overview of the +different tools available for profiling Python code. + +CPU profilers: +- [cProfile and profile](https://docs.python.org/3/library/profile.html) +- [line_profiler](https://kernprof.readthedocs.io/) +- [py-spy](https://github.com/benfred/py-spy) +- [Yappi](https://github.com/sumerc/yappi) +- [pyinstrument](https://pyinstrument.readthedocs.io/) +- [Perfetto](https://perfetto.dev/docs/analysis/trace-processor-python) + +Memory profilers: +- [memory_profiler](https://pypi.org/project/memory-profiler/) (not actively maintained) +- [Pympler](https://pympler.readthedocs.io/) +- [tracemalloc](https://docs.python.org/3/library/tracemalloc.html) +- [guppy/heapy](https://github.com/zhuyifei1999/guppy3/) + +Both CPU and memory: +- [Scalene](https://github.com/plasma-umass/scalene) + +In the exercise below, we will use Scalene to profile a Python program. Scalene +is a sampling profiler that can profile CPU, memory, and GPU usage of Python. + + +## Tracing profilers vs. sampling profilers + +**Tracing profilers** record every function call and event in the program, +logging the exact sequence and duration of events. +- **Pros:** + - Provides detailed information on the program's execution. + - Deterministic: Captures exact call sequences and timings. +- **Cons:** + - Higher overhead, slowing down the program. + - Can generate larger amount of data. + +**Sampling profilers** periodically samples the program's state (where it is +and how much memory is used), providing a statistical view of where time is +spent. +- **Pros:** + - Lower overhead, as it doesn't track every event. + - Scales better with larger programs. +- **Cons:** + - Less precise, potentially missing infrequent or short calls. + - Provides an approximation rather than exact timing. + +:::{discussion} Analogy: Imagine we want to optimize the London Underground (subway) system +We wish to detect bottlenecks in the system to improve the service and for this we have +asked few passengers to help us by tracking their journey. +- **Tracing**: We follow every train and passenger, recording every stop + and delay. When passengers enter and exit the train, we record the exact time + and location. +- **Sampling**: Every 5 minutes the phone notifies the passenger to note + down their current location. We then use this information to estimate + the most crowded stations and trains. +::: + + +## Choosing the right system size + +Sometimes we can configure the system size (for instance the time step in a simulation +or the number of time steps or the matrix dimensions) to make the program finish sooner. + +For profiling, we should choose a system size that is **representative of the real-world** +use case. If we profile a program with a small input size, we might not see the same +bottlenecks as when running the program with a larger input size. + +Often, when we scale up the system size, or scale the number of processors, new bottlenecks +might appear which we didn't see before. This brings us back to: "measure instead of guessing". + + +## Exercises + +::::{exercise} Exercise: Practicing profiling +In this exercise we will use the Scalene profiler to find out where most of the time is spent +and most of the memory is used in a given code example. + +Please try to go through the exercise in the following steps: +1. Make sure `scalene` is installed in your environment (if you have followed + this course from the start and installed the recommended software + environment, then it is). +1. Download Leo Tolstoy's "War and Peace" from the following link (the text is + provided by [Project Gutenberg](https://www.gutenberg.org/)): + + (right-click and "save as" to download the file and **save it as "book.txt"**). +1. **Before** you run the profiler, try to predict in which function the code + will spend most of the time and in which function it will use most of the + memory. +1. Run the `scalene` profiler on the following code example and browse the + generated HTML report to find out where most of the time is spent and where + most of the memory is used: + ```console + $ scalene example.py + ``` + Alternatively you can do this (and then open the generated file in a browser): + ```console + $ scalene example.py --html > profile.html + ``` + You can find an example of the generated HTML report in the solution below. +1. Does the result match your prediction? Can you explain the results? + +:::{literalinclude} profiling/exercise.py +::: + +:::{solution} + ```{figure} profiling/exercise.png + :alt: Result of the profiling run for the above code example. + :width: 100% + + Result of the profiling run for the above code example. You can click on the image to make it larger. + ``` + + Results: + - Most time is spent in the `count_unique_words2` function. + - Most memory is used in the `count_unique_words1` function. + + Explanation: + - The `count_unique_words2` function is the slowest because it **uses a list** + to store unique words and checks if a word is already in the list before + adding it. + Checking whether a list contains an element might require traversing the + whole list, which is an O(n) operation. As the list grows in size, + the lookup time increases with the size of the list. + - The `count_unique_words1` and `count_unique_words3` functions are faster + because they **use a set** to store unique words. + Checking whether a set contains an element is an O(1) operation. + - The `count_unique_words1` function uses the most memory because it **creates + a list of all words** in the text file and then **creates a set** from that + list. + - The `count_unique_words3` function uses less memory because it traverses + the text file line by line instead of reading the whole file into memory. + + What we can learn from this exercise: + - When processing large files, it can be good to read them line by line + or in batches + instead of reading the whole file into memory. + - It is good to get an overview over standard data structures and their + advantages and disadvantages (e.g. adding an element to a list is fast but checking whether + it already contains the element can be slow). + ::: +:::: + + +## Additional resources + +- [Python performance workshop (by ENCCS)](https://enccs.github.io/python-perf/profile/) diff --git a/branch/master/_sources/python.rst.txt b/branch/master/_sources/python.rst.txt new file mode 100644 index 00000000..b9f21315 --- /dev/null +++ b/branch/master/_sources/python.rst.txt @@ -0,0 +1,186 @@ +Introduction to Python +====================== + +.. questions:: + + - What are the basic blocks of Python language? + - How are functions and classes defined in Python? + +.. objectives:: + + - Get a *very* short introduction to Python types and syntax + - Be able to follow the rest of the examples in the course, even if you don't understand everything perfectly. + + We expect everyone to be able to know the following basic material + to follow the course (though it is not *everything* you need to + know about Python). + +If you are not familiar with Python, here is a *very* short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise. + +.. seealso:: + + This page contains an overview of the basics of Python. You can + also refer to `This Python overview from a different lesson + `__ + which is slightly more engaging. + + + +Scalars +------- + +Scalar types, that is, single elements of various types: + +:: + + i = 42 # integer + i = 2**77 # Integers have arbitrary precision + g = 3.14 # floating point number + c = 2 - 3j # Complex number + b = True # boolean + s = "Hello!" # String (Unicode) + q = b'Hello' # bytes (8-bit values) + +Read more: :class:`int`, :class:`float`, :class:`complex`, +:class:`bool`, :class:`str`, :class:`bytes`. + + +Collections +----------- + +Collections are data structures capable of storing multiple values. + +:: + + l = [1, 2, 3] # list + l[1] # lists are indexed by int + l[1] = True # list elements can be any type + d = {"Janne": 123, "Richard": 456} # dictionary + d["Janne"] + s = set(("apple", "cherry", "banana", "apple")) # Set of unique values + s + +Read more: :class:`list`, :class:`tuple`, :class:`dict`, :class:`set`. + + +Control structures +------------------ + +Python has the usual control structures, that is conditional +statements and loops. For example, the :ref:`if` statement: + +:: + + x = 2 + if x == 3: + print('x is 3') + elif x == 2: + print('x is 2') + else: + print('x is something else') + +:ref:`While ` loops loop until some condition is met: + +:: + + x = 0 + while x < 42: + print('x is ', x) + x += 0.2 + +:ref:`For ` loops loop over some collection of values: + +:: + + xs = [1, 2, 3, 4] + for x in xs: + print(x) + + +Often you want to loop over a sequence of integers, in that case the +:class:`range` function is useful: + +:: + + for x in range(9): + print(x) + +Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the :func:`enumerate` +function: + +:: + + xs = [1, 'hello', 'world'] + for ii, x in enumerate(xs): + print(ii, x) + + +Functions and classes +--------------------- + +Python functions are defined by the :ref:`def` keyword. They take a +number of arguments, and return a number of return values. + +:: + + def hello(name): + """Say hello to the person given by the argument""" + print('Hello', name) + return 'Hello ' + name + + hello("Anne") + +Classes are defined by the :ref:`class` keyword: + +:: + + class Hello: + def __init__(self, name): + self._name = name + def say(self): + print('Hello', self._name) + + h = Hello("Richard") + h.say() + + +Python type system +------------------ + +Python is strongly and dynamically typed. + +Strong here means, roughly, that it's not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior). + +:: + + x = 42 + type(x) + x + "hello" + +Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type: + +:: + + x = 42 + x = "hello" + + +*Jargon*: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation. + + +??? (lesson here) + + + +.. keypoints:: + + - Python offers a nice set of basic types as many other programming languages + - Python is strongly typed and dynamically typed diff --git a/branch/master/_sources/quick-reference.rst.txt b/branch/master/_sources/quick-reference.rst.txt new file mode 100644 index 00000000..6d3141e5 --- /dev/null +++ b/branch/master/_sources/quick-reference.rst.txt @@ -0,0 +1,26 @@ +Quick reference +=============== + +* `Pandas cheatsheet + `__ (pandas.pydata.org) + +* `Pandas cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy cheatsheet + `__ + (via `Datacamp + `__) + +* `JupyterLab cheatsheet + `__ + +* `Matplotlib cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy, Pandas, Matplotlib, Scikit-learn all together + `__ diff --git a/branch/master/_sources/scipy.rst.txt b/branch/master/_sources/scipy.rst.txt new file mode 100644 index 00000000..0d921a43 --- /dev/null +++ b/branch/master/_sources/scipy.rst.txt @@ -0,0 +1,183 @@ +SciPy +===== + +.. questions:: + + - When you need more advanced mathematical functions, where do you + look? + +.. objectives:: + + - Understand that SciPy exists and what kinds of things it has. + - Understand the importance of using external libraries and how to + use them. + - Understand the purpose of wrapping existing C/Fortran code. + - Non-objective: know details of everything (or anything) in SciPy. + +.. seealso:: + + * Main article: `SciPy documentation `__ + + + +SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms. + + + +What's in SciPy? +---------------- + +Briefly, it contains functionality for + +- Special functions (Bessel, Gamma, etc.) +- Numerical integration +- Optimization +- Interpolation +- Fast Fourier Transform (FFT) +- Signal processing +- Linear algebra (more complete than in NumPy) +- Sparse matrices +- Statistics +- More I/O routine, e.g. Matrix Market format for sparse matrices, + MATLAB files (.mat), etc. + +Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages. + +Most functions are documented ridiculously well from a scientific +standpoint: you aren't just using some unknown function, but have a +full scientific description and citation to the method and +implementation. + + + +Exercises: use SciPy +-------------------- + +These exercises do not exist because *you* might need *these* +functions someday. They are because *you* will need to *read +documentation and understand documentation of an an external library* +eventually. + +1: Numerical integration +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Define a function of one variable and using + `scipy.integrate.quad `__ + calculate the integral of your function in the + interval ``[0.0, 4.0]``. Then vary the interval and also modify the function and check + whether scipy can integrate it. + + +.. solution:: + + .. code-block:: python + + from scipy import integrate + + def myfunction(x): + # you need to define result + return result + + integral = integrate.quad(myfunction, 0.0, 4.0) + print(integral) + + `quad + `__ + uses the Fortran library QUADPACK, which one can assume is pretty + good. You can also see a whole lot of scientific information about + the function on the docs page - including the scientific names of + the methods used. + + + +2: Sparse matrices +~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Use the SciPy sparse matrix functionality to create a random sparse + matrix with a probability of non-zero elements of 0.05 and size 10000 + x 10000. The use the SciPy sparse linear algebra support to calculate + the matrix-vector product of the sparse matrix you just created and a + random vector. Use the %timeit macro to measure how long it + takes. Does the optional ``format`` argument when you create the + sparse matrix make a difference? + + Then, compare to how long it takes if you'd instead first convert the + sparse matrix to a normal NumPy dense array, and use the NumPy ``dot`` + method to calculate the matrix-vector product. + + Can you figure out a quick rule of thumb when it's worth using a + sparse matrix representation vs. a dense representation? + +.. solution:: + + The basic code to do the test is: + + .. code-block:: + + import numpy + import scipy.sparse + + vector = numpy.random.random(10000) + matrix = scipy.sparse.rand(10000, 10000, density=.05, format='csc') + + # We time this line + matrix.dot(vector) + + From the top of the `spare matrix module documentation + `__, we can + see there are a variety of different available sparse matrix types: + ``bsr``, ``coo``, ``csr``, ``csc``, etc. These each represent a + different way of storing the matrices. + + It seems that ``csr`` and ``csc`` are fairly fast. ``lil`` and + ``dok`` are slow but it says that these are good for creating + matrices with random insertions. + + For example, ``csr`` takes 7ms, ``lil`` 42ms, ``dok`` 1600ms, and + converting to a non-sparse array ``matrix.toarray()`` and + multiplying takes 64ms on one particular computer. + + This code allows us to time the performance at different + densities. It seems that with the ``csr`` format, sparse is better + below densities of around .4 to .5: + + ..code-block:: + + for density in [.01, .05, .1, .2, .3, .4, .5]: + matrix = scipy.sparse.rand(10000, 10000, density=density, format='csr') + time_sparse = timeit.timeit('matrix.dot(vector)', number=10, globals=globals()) + matrix2 = matrix.toarray() + time_full = timeit.timeit('matrix2.dot(vector)', number=10, globals=globals()) + print(f"{density} {time_sparse:.3f} {time_full:.3f}") + + + +See also +-------- + +* `SciPy general introduction `__ +* `SciPy documentation + `__ + + + +.. keypoints:: + + - When you need advance math or scientific functions, let's just + admit it: you do a web search first. + - But when you see something in SciPy come up, you know your + solutions are in good hands. diff --git a/branch/master/_sources/scripts.rst.txt b/branch/master/_sources/scripts.rst.txt new file mode 100644 index 00000000..9fc450ee --- /dev/null +++ b/branch/master/_sources/scripts.rst.txt @@ -0,0 +1,340 @@ +.. _scripts: + +Scripts +======= + +.. questions:: + + - Why are command line programs useful, compared to Jupyter + notebooks and similar? + - How to create a Python script? + - How to generalize a Python script? + +.. objectives:: + + - Learn how to streamline your Python notebooks by creating repeatable Python scripts + - Learn how to import other Python files + - Learn to parse command line arguments in Python + +Why scripts? +------------- + +So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work. + +But after several weeks of hard work with Python, you may end up: + +- either with 10 different notebooks (so that you can run them concurrently) +- or with a very long notebook which is becoming hardly readable! + +Let's imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks? + +In this episode, we will learn how to automate your work using Python scripts so that + +* you do not need to manually configure your notebooks to be able to run with different parameters +* can easily run you work via other tools, such as on computing clusters. + + +From Jupyter notebooks to Python scripts +----------------------------------------- + +.. highlight:: console + + +Save as Python script +--------------------- + +Jupyter notebooks can be parameterized for instance using `papermill `_. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See `CodeRefinery's lesson on Modular code development `__. + +You need to convert the notebook to a Python file. +Check the `JupyterLab documentation `_ for more information. +You can get a command line by (File → New Launcher → Terminal - if you +go through New Launcher, your command line will be in the directory +you are currently browsing), you can convert files in the terminal by running:: + + $ jupyter nbconvert --to script your_notebook_name.ipynb + + + +If nbconvert doesn't work, within JupyterLab, you can export any +Jupyter notebook to a Python +script, but this downloads it to your own computer and then you need +to copy it to a place you are working (maybe upload it back to +JupyterLab?): + +.. figure:: https://jupyterlab.readthedocs.io/en/stable/_images/exporting-menu.png + :width: 80% + :alt: JupyterLab screenshot as described in caption. + + Select File (top menu bar) → Export Notebook as → **Export notebook to Executable Script**. + + + +Exercises 1 +----------- + +.. challenge:: Scripts-1 + + .. highlight:: console + + + 1. Download the :download:`weather_observations.ipynb <../resources/code/scripts/weather_observations.ipynb>` and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from `rp5.kz `_ and was slightly adjusted for this lecture. + + **Hint:** Copy the URL above (right-click) and in JupyterLab, use + File → Open from URL → Paste the URL. It will both download it to + the directory JupyterLab is in and open it for you. + + 2. Open a terminal in Jupyter: File → New Launcher, then click + "Terminal" there. (if you do it this way, it will be in the right + directory. File → New → Terminal might not be.) + + 3. Convert the Jupyter script to a Python script by calling:: + + $ jupyter nbconvert --to script weather_observations.ipynb + + 4. Run the script (note: you may have ``python3`` rather than ``python``):: + + $ python weather_observations.py + + + +Command line arguments with :data:`sys.argv` +-------------------------------------------- + +We now have a Python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +**What we need is to allow the code to do something different based on something outside the code itself**: in this case, to +plot information for different time ranges. This can be achieved by +using Pythons :py:mod:`sys` package, which provides access to arguments given to the Python interpreter at +startup in the :py:data:`sys.argv` list. The first (i.e. ``sys.argv[0]`` entry of this array is the script that is running, +and any further argument (separated by space) is appended to this list, like such: + +.. code-block:: console + + $ python my_script.py A B + $ # sys.argv[1] is 'A' + $ # sys.argv[2] is 'B' + +Lets see how it works: We modify the **weather_observations.py** script such that we allow start +and end times as well as the output file to be passed in as arguments +to the function. Open it (find the ``.py`` file from the JupyterLab +file browser) and make these edits: + +.. code-block:: python + :emphasize-lines: 1,5-6,8,14-15 + + import sys + import pandas as pd + + # define the start and end time for the plot + start_date = pd.to_datetime(sys.argv[1], dayfirst=True) + end_date = pd.to_datetime(sys.argv[2], dayfirst=True) + ... + + # select the data + weather = weather[weather['Local time'].between(start_date,end_date)] + ... + + # save the figure + output_file_name = sys.argv[3] + fig.savefig(output_file_name) + +We can try it out (see the file ``spring_in_tapiola.png`` made in the +file browser): + +.. code-block:: console + + $ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png + + +.. discussion:: + + - Does it work? + + - Why is this better than modifying the script every time I want it to + plot data for a different period? + + - What problems do you expect when using this approach (using :data:`sys.argv`)? + +This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time: + +- `argparse `__: + built-in to Python, this is the one that we will show below. +- `doctopt `__: you write the help text and this generates a parser for you. +- `click `__: another nice + library for command line interfaces - very easy to use. + + +Parsing command line arguments with :mod:`argparse` +--------------------------------------------------- + +:py:mod:`Argparse ` not only gives you descriptive command line arguments, it also automatically +generates a ``--help`` option for you. To use ``argparse`` you first set up a parser +by calling :class:`parser = argparse.ArgumentParser() ` and then you add arguments using +:py:meth:`parser.add_argument(args) `. There are two different types of arguments: + +- Positional arguments +- Optional arguments + +**Positional arguments** are detected by their order, while **optional arguments** need to be +given with their respective flags ( like ``--name`` or ``-n``). +The following example would parse a positional argument ``Name`` of type ``string`` +and an optional argument ``date`` of type ``string`` which defaults to ``01/01/2000``. + +.. code-block:: python + :emphasize-lines: 3, 5-8, 10 + + import argparse + + parser = argparse.ArgumentParser() + # One positional and one optional argument + parser.add_argument('name', type=str, metavar="N", + help="The name of the subject") + parser.add_argument('-d', '--date', type=string, default="01/01/2000", + help="Birth date of the subject") + + args = parser.parse_args() + + print(args.name + " was born on " + args.date) + +If this code was in ``birthday.py`` and we would call ``python birthday.py --help`` it +would show the following message: + +.. code-block:: console + + $ python birthday.py --help + usage: birthday.py [-h] [-d DATE] N + + positional arguments: + N The name of the subject + + optional arguments: + -h, --help show this help message and exit + -d DATE, --date DATE Birth date of the subject + + +Exercises 2 +----------- + +.. challenge:: Scripts-2 + + 1. Take the Python script (``weather_observations.py``) we have written in the preceding exercise and use + :py:mod:`argparse` to specify the input (URL) and output files and allow the start and end dates to be set. + + * Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on. + * Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output. + * Hint: The start and end dates should be optional parameters with the defaults as they are in the current script. + + 2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). + Also try using this data for Cairo: ``https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv`` + + +.. solution:: + + .. literalinclude:: ../resources/code/scripts/weather_observations_argparse.py + :language: python + :emphasize-lines: 2,4-8,10,13,16-17,37 + + + + +.. discussion:: + + **What was the point of doing this?** + + Now you can do this: + + .. code-block:: console + + $ python weather_observations.py --help + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png + $ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png + $ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv temperature_cairo.png + + - We can now process different input files without changing the script. + - We can select multiple time ranges without modifying the script. + - We can easily save these commands to know what we did. + - This way we can also loop over file patterns (using shell loops or similar) or use + the script in a workflow management system and process many files in parallel. + - By changing from :data:`sys.argv` to :mod:`argparse` we made the script more robust against + user input errors and also got a help text (accessible via ``--help``). + + +Load larger option lists using config files +------------------------------------------- + +In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line: + +.. code-block:: console + + + $ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021 + + +This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple ``Parameter = Value`` +format, and parse it yourself, or you can use e.g. the ``JSON`` or ``YAML`` formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won't go into the details of the formats, and will only give +a short example using YAML here. + +The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (`yaml `__) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the :mod:`json` package). + +The Python module :download:`optionsparser.py <../resources/code/scripts/optionsparser.py>` provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values. + +In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation ...), set the labels and titles explicitly etc. + +In the YAML format, names and values are separated by ``:``. Our above example would therefore translate to the following YAML file: + +.. literalinclude:: ../resources/code/scripts/weather_options.yml + :language: yaml + +Exercises 3 (optional) +---------------------- + +.. challenge:: Scripts-3 + + 1. Download the :download:`optionsparser.py ` + function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). + Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line + (using e.g. :mod:`argparse` or :data:`sys.argv`) still needs to be read from the command line. + + + 2. Run your script with different config files. + + +.. solution:: + + The modified **weather_observations.py** script: + + .. literalinclude:: ../resources/code/scripts/weather_observations_config.py + :language: python + :emphasize-lines: 5,9-12,15-27,30,33,36-37,58 + +What did this config file parser get us? Now, we have separated the +code from the configuration. We could save all the configuration in +version control - separately and have one script that runs them. If +done right, our work could be much more reproducible and +understandable. + + +.. admonition:: Further reading + + - Linking Jupyterlab notebooks to python scripts (making linking ``.py``- and ``.ipynb``-files easier) using `jupytext `_ + - The `wikipedia page about YAML `_ contains a lot of additional information on the YAML syntax. + - `The Coderefinery Lesson about reproducible research `_ can give additional information about good coding practices and workflow automation. + + - `CodeRefinery's lesson on Modular code development `__ diff --git a/branch/master/_sources/web-apis.ipynb.txt b/branch/master/_sources/web-apis.ipynb.txt new file mode 100644 index 00000000..f2b376d5 --- /dev/null +++ b/branch/master/_sources/web-apis.ipynb.txt @@ -0,0 +1,678 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c87bb04a-3f53-45ac-bbc9-fe182c844219", + "metadata": { + "tags": [] + }, + "source": [ + "# Web APIs with Python\n", + "\n", + ":::{questions}\n", + "- Have you ever needed to get some data from somewhere else on the web?\n", + ":::\n", + "\n", + ":::{objectives}\n", + "- Understand a web server and API and why might you need to talk to one.\n", + "- Basics of the [requests](https://requests.readthedocs.io/en/latest/) Python library\n", + "- Some lightweight recommendations on saving data when you get to more serious data download.\n", + ":::\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "2398bb45-e061-4e7a-8931-82906a3892ff", + "metadata": { + "tags": [] + }, + "source": [ + "## Requests\n", + "\n", + "Requests is a Python library that makes **requests** to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.\n", + "\n", + "First, let's take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c69a16ac-a5b3-4ff0-a949-720b5bbd37cd", + "metadata": {}, + "outputs": [], + "source": [ + "# Embed the requests homepage\n", + "from IPython.display import IFrame\n", + "requests_documentation_url = \"https://requests.readthedocs.io/en/latest/\"\n", + "IFrame(requests_documentation_url, '100%', '30%')" + ] + }, + { + "cell_type": "markdown", + "id": "6d6b334b-309e-429b-aad5-0ab76f071c15", + "metadata": {}, + "source": [ + "## Retrieve data from API\n", + "\n", + "An **API (Application Programming Interface)** is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the **request-response** cycle.\n", + "\n", + "We can find a list of some free APIs (available without authentication) at . These APIs can be used for developing and testing our code." + ] + }, + { + "cell_type": "markdown", + "id": "0a21faac-a7d8-448d-a8db-6fb23b9bd64c", + "metadata": { + "tags": [] + }, + "source": [ + "Let's make a request to the Cat Fact API. If we go to , it gives us the definitions:\n", + "* GET `/fact` is the **API endpoint**.\n", + "* **GET** is the type of request we make and\n", + "* `/fact` is the **path**.\n", + "\n", + "You can even test this in your web browser: \n", + "\n", + "Using the Requests library, we do this with {func}`~requests.get`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fa134bb7-1250-46bd-bd80-e3e0d0820523", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "64a7f3be-420b-4e1c-a76d-67d9e6b29f4f", + "metadata": { + "tags": [] + }, + "source": [ + "The {class}`requests.Response` object tells us what the server said. We can access the response content using {attr}`~requests.Response.content`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b3e1ddb3-76a1-4e53-a32b-4005d92626c6", + "metadata": {}, + "outputs": [], + "source": [ + "response_content = response.content\n", + "\n", + "# Display\n", + "display(response_content)" + ] + }, + { + "cell_type": "markdown", + "id": "3886ff1c-0619-4fc5-828a-269257db6e63", + "metadata": { + "tags": [] + }, + "source": [ + "The response content is in the [JSON format](https://en.wikipedia.org/wiki/JSON) and Requests gives us the {meth}`~requests.Response.json` method that decodes it and returns the corresponding data as Python objects. This is equivalent to {func}`json.load`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7651cd8c-9581-4d04-b3bf-c57997a5684a", + "metadata": {}, + "outputs": [], + "source": [ + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json)" + ] + }, + { + "cell_type": "markdown", + "id": "10ca2577-94a4-4689-a01a-2681fe4c5d20", + "metadata": { + "tags": [] + }, + "source": [ + "(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)" + ] + }, + { + "cell_type": "markdown", + "id": "80e02c0b-9b59-44ea-ab26-092b6cdb510b", + "metadata": { + "tags": [] + }, + "source": [ + "## API which requires parameters\n", + "\n", + "Let's then examine another API which accepts [parameters](https://requests.readthedocs.io/en/latest/user/quickstart/#passing-parameters-in-urls) to specify the information request. In particular, we will request a list of Finnish universities from using the `/search` end point and a parameter _country_ with value _Finland_, like this:\n", + "`http://universities.hipolabs.com/search?country=Finland` ." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b98cba34-0f3a-43fb-befe-0e1c48fdb1c3", + "metadata": {}, + "outputs": [], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search?country=Finland'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])" + ] + }, + { + "cell_type": "markdown", + "id": "18ee30d2-e072-41b2-b4d4-8203cb5e86ce", + "metadata": { + "tags": [] + }, + "source": [ + "URLs containing parameters can always be constructed manually using the _&_ character and then listing the parameter (_key_, _value_) pairs as above.\n", + "\n", + "However, _Requests_ allows us to provide the parameters as a dictionary of strings, using the _params_ keyword argument to {func}`~requests.get`. This is easier to read and less error-prone." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1c1ddced-d423-42cd-89ac-3a0c6d751d9d", + "metadata": {}, + "outputs": [], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search'\n", + "\n", + "# Make the parameter dictionary\n", + "parameters = {'country' : 'Finland'}\n", + "\n", + "# Get response\n", + "response = requests.get(url, params=parameters)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])\n" + ] + }, + { + "cell_type": "markdown", + "id": "35c751c9-009c-46f7-af8a-40c4132dcfbd", + "metadata": {}, + "source": [ + "## Exercises 1" + ] + }, + { + "cell_type": "markdown", + "id": "033d8d63-43db-4a3e-a9cd-e142134a0b9b", + "metadata": {}, + "source": [ + "::::{exercise} Exercise WebAPIs-1: Request different activity suggestions from the Bored API\n", + "\n", + "Go to the [documentation page of the Bored API](https://www.boredapi.com/documentation). The Bored API is an open API which can be used to randomly generate activity suggestions.\n", + "\n", + "Let's examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response\n", + "\n", + "```json\n", + "{\n", + " \"activity\": \"Learn Express.js\",\n", + " \"accessibility\": 0.25,\n", + " \"type\": \"education\",\n", + " \"participants\": 1,\n", + " \"price\": 0.1,\n", + " \"link\": \"https://expressjs.com/\",\n", + " \"key\": \"3943506\"\n", + "} \n", + "```\n", + "\n", + "Let's replicate the query and see if we can get another random suggestion.\n", + "::::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1744a2a7-5c9a-48d4-96b4-9d523b2e43bc", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Send the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "77fdd8cd-2c85-474e-bceb-2a737c92521b", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "69ae7da6-6c9c-4f2a-94ea-fc75f437eb80", + "metadata": {}, + "source": [ + "Next, let's try to narrow down the suggestions by adding some parameters\n", + "- type\n", + "- participants\n", + "\n", + "All possible parameter values are presented at the bottom of the bored documentation page. [Relevant parts in the _Requests_ documentation](https://requests.readthedocs.io/en/latest/user/quickstart/#parameters)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "933feded-0d73-4038-b909-6f713cb3782a", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'education',\n", + " 'participants' : 1,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f9dbeea0-31d3-43b0-8d18-94b608e82a77", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(\"Response\")\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "301eb0af-2db2-474b-87e4-8d8815a3a04b", + "metadata": {}, + "source": [ + "Let's narrow the request further with more parameters\n", + "- price range\n", + "- accessibility range\n", + "\n", + "(All possible parameter values are again presented at the bottom of the document page.)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d04823d4-154e-48ec-9576-f537bd20c271", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'social',\n", + " 'participants' : 2,\n", + " 'minprice' : 0,\n", + " 'maxprice' : 1000,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "87978afc-6d0d-46c0-ad0f-e5b851d302e1", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())\n", + "display(\"\")" + ] + }, + { + "cell_type": "markdown", + "id": "0a019d02-cd86-4fdc-874e-b99557955cd1", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "\n", + ":::{exercise} Exercise WebAPIs-2: Examine request and response headers\n", + "\n", + "Request [headers](https://requests.readthedocs.io/en/latest/user/quickstart/#response-headers) are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).\n", + "\n", + "Let's first make a request.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eb583c27-2ce3-420e-a116-b717f8fa0e3e", + "metadata": {}, + "outputs": [], + "source": [ + "# Import modules\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Make the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "271d5abd-6648-4976-899e-25e93d5d8f73", + "metadata": {}, + "source": [ + "We can access the headers of the original request" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "91f78d05-60e7-48ad-8f13-bc4d445e75bc", + "metadata": {}, + "outputs": [], + "source": [ + "display(\"Request headers\")\n", + "display(dict(response.request.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "d6149ec8-c57f-4fab-aaa5-6a61fc7d0291", + "metadata": {}, + "source": [ + "We can also access the headers of the response " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d4ff753a-d3dd-41c9-b533-386d0b30d4c3", + "metadata": {}, + "outputs": [], + "source": [ + "display(\"Response headers\")\n", + "display(dict(response.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "7132bc48-90a0-49ea-a215-a87006aecf1d", + "metadata": {}, + "source": [ + "In many cases, the default headers\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive'}\n", + "```\n", + "\n", + "added automatically by _Requests_ are sufficient. However, similarly to parameters, we can pass [custom headers](https://requests.readthedocs.io/en/latest/user/quickstart/#custom-headers) to the _get_ function as an argument. \n", + "\n", + "This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive',\n", + " 'example-user-id' : 'example-password'}\n", + "```\n", + "\n", + "For examples of APIs using this type of authentication, see\n", + "\n", + "- [Imgur API](https://api.imgur.com/oauth2)\n", + "\n", + "For more on authentication, see also [_Requests_ documentation](https://requests.readthedocs.io/en/latest/user/authentication/). \n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "3d50de82-4f2c-4bc4-8f23-3cb4bdb62127", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "\n", + ":::{exercise} Exercise WebAPIs-3: Scrape links from a webpage (Advanced)\n", + "\n", + "Let's use _Requests_ to get the HTML source code of www.example.com, examine it, and use the [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) library to extract links from it. **Note:** This requires the extra `bs4` Python package to be installed, which was not in our initial requirements. Consider this a demo.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cc3373a9-e54f-4049-b715-481ec9893189", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# Define webpage to scrape\n", + "url = \"http://www.example.com/\"\n", + "\n", + "# Make a request for the URL\n", + "response = requests.get(url)\n", + "\n", + "# Examine the response\n", + "display(response.content)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d59e52c4-95cf-427d-b3d4-8d0a6dc02aa5", + "metadata": {}, + "outputs": [], + "source": [ + "# Looks like HTML :) Let's access it using the text attribute\n", + "html = response.text\n", + "\n", + "print(html)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "327695ae-b376-4d5b-9293-6e89ff272790", + "metadata": {}, + "outputs": [], + "source": [ + "# Import beautiful soup module\n", + "from bs4 import BeautifulSoup\n", + "\n", + "# Create soup\n", + "soup = BeautifulSoup(html, 'html.parser')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0e21c6de-a845-4823-b777-bf2cd44fbfd2", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract page title from the HTML\n", + "print(f\"Found title: {soup.title.text}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a7fa0e7b-b171-4e65-b987-84a101da58df", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract links (hrefs) from the HTML\n", + "for link in soup.find_all('a'):\n", + " print(f\"Found link: {link.get('href')}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6581edcb-c170-4cc7-a442-d8d8c724ca50", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract all text from the HTML\n", + "print(f\"Found text: {soup.get_text()}\") " + ] + }, + { + "cell_type": "markdown", + "id": "7cdff2d8-0c98-45b3-a825-ed1492d10302", + "metadata": {}, + "source": [ + "## After exercises: Saving retrieved data to disk\n", + "\n", + "Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudinal study.\n", + "\n", + "To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don't, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).\n", + "\n", + "For example, let's retrieve three cat facts and save them to a JSONLINES file using the [jsonlines library](https://jsonlines.readthedocs.io/en/latest/)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "80a8dcd1-ba04-45de-840e-aa014c19a75c", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "import jsonlines\n", + "import time\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make three requests in loop and make a list of response JSON objects\n", + "for i in range(3):\n", + "\n", + " # Logging\n", + " print(f\"Make request {i}\")\n", + "\n", + " # Make a request\n", + " response = requests.get(url)\n", + " \n", + " # Decode to JSON\n", + " response_json = response.json()\n", + " \n", + " # Open a jsonlines writer in 'append' mode \n", + " with jsonlines.open('catfacts.jsonl', mode='a') as writer:\n", + "\n", + " # Write\n", + " writer.write(response_json)\n", + " \n", + " # Sleep for one second between requests\n", + " time.sleep(1)\n" + ] + }, + { + "cell_type": "markdown", + "id": "efb4a0ff-6a70-471a-af61-39c0350d4166", + "metadata": {}, + "source": [ + "We can then read the objects from the disk using the same library." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2d424c23-bdf3-47f7-a643-4312a07c955a", + "metadata": {}, + "outputs": [], + "source": [ + "# Open a jsonlines reader\n", + "with jsonlines.open('catfacts.jsonl', mode='r') as reader:\n", + " \n", + " # Read and display\n", + " for obj in reader:\n", + " display(obj)" + ] + }, + { + "cell_type": "markdown", + "id": "2f6b8117-b1ef-43cb-9458-0fe4ac49b67a", + "metadata": {}, + "source": [ + "## Wrap-up\n", + "\n", + "\n", + ":::{keypoints}\n", + "- Requests is a common tool\n", + "- Web APIs may often require some trial and error, but actually getting data is usually not that difficult\n", + "- Storing all the data and processing it well can be a much larger issue.\n", + ":::\n", + "\n" + ] + } + ], + "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.8.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/branch/master/_sources/work-with-data.rst.txt b/branch/master/_sources/work-with-data.rst.txt new file mode 100644 index 00000000..cc3d73e5 --- /dev/null +++ b/branch/master/_sources/work-with-data.rst.txt @@ -0,0 +1,466 @@ +Working with Data +================= + +.. questions:: + + - How do you store your data right now? + - Are you doing data cleaning / preprocessing every time you load the data? + +.. objectives:: + + - Learn benefits/drawbacks of common data formats. + - Learn how you can read and write data in a variety of formats. + + +.. figure:: https://imgs.xkcd.com/comics/norm_normal_file_format.png + + Source: `xkcd #2116 `__ + + +What is a data format? +---------------------- + +Data format can mean two different things + +1. `data structure `__ or how + you're storing the data in memory while you're working on it; +2. `file format `__ or the way you're + storing the data in the disk. + +Let's consider this randomly generated DataFrame with various columns:: + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.info() + +This DataFrame is structured in the *tidy data* format. +In tidy data we have multiple columns of data that are collected in a Pandas +DataFrame, where each column represents a value of a specific type. + +.. image:: img/pandas/tidy_data.png + +Let's consider another example:: + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + np.info(data_array) + + +Here we have a different data structure: we have a two-dimensional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block +instead of individual columns. This also means that the whole array must have one +data type. + + +.. figure:: https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png + + Source: `Elegant Scipy `__ + +Now the question is: **Can the data be saved to the disk without changing the +data format?** + +For this we need a **file format** that can easily store our **data structure**. + +.. admonition:: Data type vs. data structure vs. file format + :class: dropdown + + - **Data type:** Type of a single piece of data (integer, string, + float, ...). + - **Data structure:** How the data is organized in memory (individual + columns, 2D-array, nested dictionaries, ...). + - **File format:** How the data is organized when it is saved to the disk + (columns of strings, block of binary data, ...). + + For example, a black and white image stored as a .png-file (**file format**) + might be stored in memory as an NxM array (**data structure**) of integers + (**data type**) with each entry representing the color value of the pixel. + +What to look for in a file format? +---------------------------------- + +When deciding which file format you should use for your program, you should +remember the following: + +**There is no file format that is good for every use case.** + +and + +**It is very likely, that a good format already exists for your use case.** + +There are, indeed, various standard file formats for various use cases: + +.. figure:: https://imgs.xkcd.com/comics/standards.png + + Source: `xkcd #927 `__. + +Usually, you'll want to consider the following things when choosing a file +format: + +1. Is the file format good for my data structure (is it fast/space + efficient/easy to use)? +2. Is everybody else / leading authorities in my field recommending a certain + format? +3. Do I need a human-readable format or is it enough to work on it using code? +4. Do I want to archive / share the data or do I just want to store it while + I'm working? + +Pandas supports +`many file formats `__ +for tidy data and Numpy supports +`some file formats `__ +for array data. However, there are many other file formats that can be used +through other libraries. + +Table below describes some data formats: + +.. list-table:: + :header-rows: 1 + + * - | Name: + - | Human + | readable: + - | Space + | efficiency: + - | Arbitrary + | data: + - | Tidy + | data: + - | Array + | data: + - | Long term + | storage/sharing: + + * - :ref:`Pickle ` + - ❌ + - 🟨 + - ✅ + - 🟨 + - 🟨 + - ❌ + + * - :ref:`CSV ` + - ✅ + - ❌ + - ❌ + - ✅ + - 🟨 + - ✅ + + * - :ref:`Feather ` + - ❌ + - ✅ + - ❌ + - ✅ + - ❌ + - ❌ + + * - :ref:`Parquet ` + - ❌ + - ✅ + - 🟨 + - ✅ + - 🟨 + - ✅ + + * - :ref:`npy ` + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + - ❌ + + * - :ref:`HDF5 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`NetCDF4 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`JSON ` + - ✅ + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + + * - :ref:`Excel ` + - ❌ + - ❌ + - ❌ + - 🟨 + - ❌ + - 🟨 + + * - :ref:`Graph formats ` + - 🟨 + - 🟨 + - ❌ + - ❌ + - ❌ + - ✅ + +.. important:: + + - ✅ : Good + - 🟨 : Ok / depends on a case + - ❌ : Bad + + +A more in-depth analysis of the file formats mentioned above, can be found +:doc:`here `. + +Pros and cons +------------- + +Let's have a general look at pros and cons of some types of file formats + +Binary File formats +~~~~~~~~~~~~~~~~~~~ + +Good things ++++++++++++ + +- Can represent floating point numbers with full precision. +- Can potentially save lots of space, especially, when storing numbers. +- Data reading and writing is usually much faster than loading from text files, + since the format contains information about the data structure, and thus + memory allocation can be done more efficiently. +- More explicit specification for storing multiple data sets and metadata in + the same file. +- Many binary formats allow for partial loading of the data. + This makes it possible to work with datasets that are larger than your + computer's memory. + +Bad things +++++++++++ + +- Commonly requires the use of a specific library to read and write the data. +- Library specific formats can be version dependent. +- Not human readable. +- Sharing can be more difficult (requires some expertise to be able to + read the data). +- Might require more documentation efforts. + +Textual formats +~~~~~~~~~~~~~~~ + +Good things ++++++++++++ + +- Human readable. +- Easy to check for (structural) errors. +- Supported by many tool out of the box. +- Easily shared. + +Bad things +++++++++++ + +- Can be slow to read and write. +- High potential to increase required disk space substantially (e.g. when + storing floating point numbers as text). +- Prone to losing precision when storing floating point numbers. +- Multi-dimensional data can be hard to represent. +- While the data format might be specified, the data structure might not be + clear when starting to read the data. + +Further considerations +~~~~~~~~~~~~~~~~~~~~~~ + +- The closer your stored data is to the code, the more likely it depends on the + environment you are working in. If you ``pickle``, e.g. a generated model, + you can only be sure that the model will work as intended if you load it in + an environment that has the same versions of all libraries the model depends + on. + + +Exercise +-------- + +.. challenge:: + + You have a model that you have been training for a while. + Lets assume it's a relatively simple neural network (consisting of a + network structure and it's associated weights). + + Let's consider 2 scenarios + + A: You have a different project, that is supposed to take this model, and + do some processing with it to determine it's efficiency after different + times of training. + + B: You want to publish the model and make it available to others. + + What are good options to store the model in each of these scenarios? + +.. solution:: + + A: + + Some export into a binary format that can be easily read. E.g. pickle + or a specific export function from the library you use. + + It also depends on whether you intend to make the intermediary steps + available to others. If you do, you might also want to consider storing + structure and weights separately or use a format specific for the + type of model you are training to keep the data independent of the + library. + + B: + + You might want to consider a more general format that is supported by + many libraries, e.g. ONNX, or a format that is specifically designed + for the type of model you are training. + + You might also want to consider additionally storing the model in a way + that is easily readable by humans, to make it easier for others to + understand the model. + + +Case study: Converting untidy data to tidy data +----------------------------------------------- + +Many data analysis tools (like Pandas) are designed to work with tidy data, +but some data is not in a suitable format. What we have seen often in the +past is people then not using the powerful tools, but write complicated +scripts that extract individual pieces from the data each time they need +to do a calculation. + +As an example, let's see how we can use country data from an example REST API +endpoint (for more information on how to work with web APIs, see +:doc:`this page `). Let's get the data with the following piece +of code: + +.. code-block:: python + + import json + import requests + + url = 'https://api.sampleapis.com/countries/countries' + + response = requests.get(url) + + countries_json = json.loads(response.content) + +Let's try to find the country with the largest population. + +An example of a "questionable" way of solving this problem would be something +like the following piece of code that is written in pure Python: + +.. code-block:: python + + max_population = 0 + top_population_country = '' + + for country in countries_json: + if country.get('population', 0) > max_population: + top_population_country = country['name'] + max_population = country.get('population', 0) + + print(top_population_country) + +This is a very natural way of writing a solution for the problem, but it has +major caveats: + +1. We throw all of the other data out so we cannot answer any + follow up questions. +2. For bigger data, this would be very slow and ineffective. +3. We have to write lots of code to do a simple thing. + +Another typical solution would be something like the following code, +which picks some of the data and creates a Pandas dataframe out of it: + +.. code-block:: python + + import pandas as pd + + countries_list = [] + + for country in countries_json: + countries_list.append([country['name'], country.get('population',0)]) + + countries_df = pd.DataFrame(countries_list, columns=['name', 'population']) + + print(countries_df.nlargest(1, 'population')['name'].values[0]) + +This solution has many of the same problems as the previous one, but now we can +use Pandas to do follow up analysis. + +Better solution would be to use Pandas' +`pandas.DataFrame.from_dict `__ +or `pandas.json_normalize `__ +to read the full data in: + +.. code-block:: python + + countries_df = pd.DataFrame.from_dict(countries_json) + print(countries_df.nlargest(1, 'population')['name'].values[0]) + + countries_df = pd.json_normalize(countries_json) + print(countries_df.nlargest(1, 'population')['name'].values[0]) + +.. admonition:: Key points + + - Convert your data to a format where it is easy to do analysis on it. + - Check the tools you're using if they have an existing feature that can help + you read the data in. + + +Things to remember +------------------ + +1. **There is no file format that is good for every use case.** +2. Usually, your research question determines which libraries you want to use + to solve it. Similarly, the data format you have determines file format you + want to use. +3. However, if you're using a previously existing framework or tools or you + work in a specific field, you should prioritize using the formats that are + used in said framework/tools/field. +4. When you're starting your project, it's a good idea to take your initial + data, clean it, and store the results in a good binary format that works as + a starting point for your future analysis. If you've written the cleaning + procedure as a script, you can always reproduce it. +5. Throughout your work, you should use code to turn important data to + a human-readable format (e.g. plots, averages, + :meth:`pandas.DataFrame.head`), not to keep your full data in a + human-readable format. +6. Once you've finished, you should store the data in a format that can be + easily shared to other people. + + +See also +-------- + +- `Pandas' IO tools `__ +- `Tidy data comparison notebook `__ +- `Array data comparison notebook `__ + + +.. keypoints:: + + - Pandas can read and write a variety of data formats. + - There are many good, standard formats, and you don't need to create your own. + - There are plenty of other libraries dedicated to various formats. diff --git a/branch/master/_sources/xarray.rst.txt b/branch/master/_sources/xarray.rst.txt new file mode 100644 index 00000000..a49b9ab6 --- /dev/null +++ b/branch/master/_sources/xarray.rst.txt @@ -0,0 +1,444 @@ +.. _xarray: + +Xarray +====== + +.. questions:: + + - How shall we deal with real-world datasets that are usually more than just raw numbers? + - What is the advantage of using labelled multidimensional arrays? + - What does Xarray add to Numpy and Pandas to address these questions? + +.. objectives:: + + - Learn how to apply operations over dimensions and select values by label + - Understand Xarray's DataArrays and Datasets + - Learn how to easily plot data in Xarray + - Learn how to turn your own data into an Xarray Dataset + + +.. highlight:: python + + +We have already seen how Pandas simplifies working with tabular NumPy data by adding labels to columns and rows. In this lesson, we take a look at how xarray can be used to add the same functionality to multidimensional data. Let's consider the following example: + +Imagine we have a dataset representing temperature measurements across different heights, latitudes, and longitudes. We can store the temperature data as a 3D NumPy array where each axis corresponds to one of these dimensions: :: + + import numpy as np + # Create a 3D numpy array: height x latitude x longitude + data = np.random.rand(10, 5, 5) # 10 heights, 5 latitudes, 5 longitudes + + +Let's assume now we want to take a look at a specific value in the dataset at a certain height, latitude, and longitude. We could do this by indexing the array with the corresponding indices: :: + + # Get the temperature at height 3, latitude 2, longitude 4 + temperature = data[3, 2, 4] + +OK, we got a value, but how do we know whether this value corresponds to the correct height, latitude and longitude? Are we sure that latitude was the second dimension in the dataset? Was it the second or third index that corresponds to the correct position? In pure NumPy, we are mostly left in the dark and need to manually keep track of these things. + +Unfortunately, Pandas isn't of much help either since it is not designed for data with more than 2 dimensions. Fortunately, `some clever climate scientists `_ have come up with a solution to this problem and created Xarray. + +What is Xarray? +---------------- + +Xarray is a powerful Python library that introduces labelled multidimensional arrays. This means the axes have labels (=dimensions), each row/column has a label (coordinates), and labels can even have units of measurement. This makes it much easier to follow what the data in an array means and select specific portions of data. + +We will first download a dataset similar to the example above to illustrate the advantages of Xarray. We will cover how to transform your own data into an Xarray Dataset later in this lecture. + +.. Note:: + + If you have set up your ``python-for-scicomp`` environment yesterday or earlier, you need to install the packages ``netcdf4`` and ``pythia_datasets`` manually. You can do this by running the following command in your (JupyterLab) terminal: :: + + conda install netcdf4 pythia-datasets -c conda-forge + +Let us open a python shell and download a public dataset: :: + + >>> from pythia_datasets import DATASETS + >>> filepath = DATASETS.fetch('NARR_19930313_0000.nc') + +We can now import xarray and open the dataset. Le'ts take a look at what it contains: :: + + >>> import xarray as xr + >>> ds = xr.open_dataset(filepath) + >>> ds + Size: 15MB + Dimensions: (time1: 1, isobaric1: 29, y: 119, x: 268) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 ... 1e+03 + * y (y) float32 476B -3.117e+03 ... 714.1 + * x (x) float32 1kB -3.324e+03 ... 5.343e+03 + Data variables: + u-component_of_wind_isobaric (time1, isobaric1, y, x) float32 4MB ... + LambertConformal_Projection int32 4B ... + lat (y, x) float64 255kB ... + lon (y, x) float64 255kB ... + Geopotential_height_isobaric (time1, isobaric1, y, x) float32 4MB ... + v-component_of_wind_isobaric (time1, isobaric1, y, x) float32 4MB ... + Temperature_isobaric (time1, isobaric1, y, x) float32 4MB ... + Attributes: + Originating_or_generating_Center: US National Weather Service, Nation... + Originating_or_generating_Subcenter: North American Regional Reanalysis ... + GRIB_table_version: 0,131 + Generating_process_or_model: North American Regional Reanalysis ... + Conventions: CF-1.6 + history: Read using CDM IOSP GribCollection v3 + featureType: GRID + History: Translated to CF-1.0 Conventions by... + geospatial_lat_min: 10.753308882144761 + geospatial_lat_max: 46.8308828962289 + geospatial_lon_min: -153.88242040519995 + geospatial_lon_max: -42.666108129242815 + +That was a lot of information at once, but let's break it down. + + - Close to the top of the output we see the ``Dimensions`` of the dataset: ``time1``, ``isobaric1``, ``y``, and ``x``. + - Below the dimensions, we see the ``Coordinates`` of the dataset. These are for each dimension the labels for each value along that dimension. For example, we have a timestamp of each value along the first dimension (``time1``). + - The ``Data variables`` are the actual data stored in the dataset. We see that the dataset contains a bunch of arrays, most of which are 4-dimensional, where each dimension corresponds to one of the ``Dimensions`` described above. There are also some 2-dimensional arrays that only have some of the ``Dimensions`` described above. + - At the bottom, we see the ``Attributes`` of the dataset. This is a dictionary that stores metadata about the dataset. + + +The following image shows the structure of this particular Xarray Dataset: + + .. image:: img/xarray/xarray_dataset_image.png + + +Accessing and manipulating data in Xarray +----------------------------------------- + +An xarray ``Dataset`` typically consists of multiple ``DataArrays``. Our example dataset has 7 of them (``u-component_of_wind_isobaric``, ``LambertConformal_Projection``, ``lat``, ``lon``, ``Geopotential_height_isobaric``, ``v-component_of_wind_isobaric``, ``Temperature_isobaric``). +We can select a single ``DataArray`` from the dataset using a dictionary-like syntax: :: + + >>> temperature_data = ds['Temperature_isobaric'] + >>> temperature_data + Size: 4MB + [924868 values with dtype=float32] + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + * x (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03 + Attributes: + long_name: Temperature @ Isobaric surface + units: K + description: Temperature + grid_mapping: LambertConformal_Projection + Grib_Variable_Id: VAR_7-15-131-11_L100 + Grib1_Center: 7 + Grib1_Subcenter: 15 + Grib1_TableVersion: 131 + Grib1_Parameter: 11 + Grib1_Level_Type: 100 + Grib1_Level_Desc: Isobaric surface + + + +Xarray uses Numpy(-like) arrays under the hood, we can always access the underlying Numpy array using the ``.values`` attribute: :: + + >>> temperature_numpy = ds['Temperature_isobaric'].values + >>> temperature_numpy + array([[[[201.88957, 202.2177 , 202.49895, ..., 195.10832, 195.23332, + 195.37395], + [201.68645, 202.0302 , 202.3427 , ..., 195.24895, 195.38957, + 195.51457], + [201.5302 , 201.87395, 202.20207, ..., 195.37395, 195.51457, + 195.63957], + ..., + [276.735 , 276.70374, 276.6881 , ..., 289.235 , 289.1725 , + 289.07874], + [276.86 , 276.84436, 276.78186, ..., 289.1881 , 289.11 , + 289.01624], + [277.01624, 276.82874, 276.82874, ..., 289.14124, 289.0475 , + 288.96936]]]], dtype=float32) + + +Xarray allows you to select data using the ``.sel()`` method, which uses the labels of the dimensions to extract data: :: + + >>> ds['Temperature_isobaric'].sel(x='-3292.0078') + Size: 14kB + array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895], + [202.58566, 202.58566, ..., 219.16379, 219.28879], + ..., + [292.1622 , 292.14658, ..., 275.05283, 275.11533], + [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + x float32 4B -3.292e+03 + Attributes: + long_name: Temperature @ Isobaric surface + units: K + description: Temperature + grid_mapping: LambertConformal_Projection + Grib_Variable_Id: VAR_7-15-131-11_L100 + Grib1_Center: 7 + Grib1_Subcenter: 15 + Grib1_TableVersion: 131 + Grib1_Parameter: 11 + Grib1_Level_Type: 100 + Grib1_Level_Desc: Isobaric surface + + +We can still access the same data by index using the ``.isel()`` method: :: + + >>> ds['Temperature_isobaric'].isel(x=1) + Size: 14kB + array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895], + [202.58566, 202.58566, ..., 219.16379, 219.28879], + ..., + [292.1622 , 292.14658, ..., 275.05283, 275.11533], + [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * isobaric1 (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + x float32 4B -3.292e+03 + Attributes: + long_name: Temperature @ Isobaric surface + units: K + description: Temperature + grid_mapping: LambertConformal_Projection + Grib_Variable_Id: VAR_7-15-131-11_L100 + Grib1_Center: 7 + Grib1_Subcenter: 15 + Grib1_TableVersion: 131 + Grib1_Parameter: 11 + Grib1_Level_Type: 100 + Grib1_Level_Desc: Isobaric surface + + +A ``DataArray`` provides a lot of the functionality we expect from Numpy arrays, such as ``sum()``, ``mean()``, ``median()``, ``min()``, and ``max()`` that we can use these methods to aggregate data over one or multiple dimensions: :: + + >>> # Calculate the mean over the 'isobaric1' dimension + >>> ds['Temperature_isobaric'].mean(dim='isobaric1') + Size: 128kB + array([[[259.88446, 259.90222, 259.91678, ..., 262.61667, 262.6285 , + 262.65167], + [259.74866, 259.76752, 259.78638, ..., 262.5757 , 262.58218, + 262.57516], + [259.6156 , 259.63498, 259.65115, ..., 262.52075, 262.51215, + 262.4976 ], + ..., + [249.8796 , 249.83649, 249.79501, ..., 254.43617, 254.49059, + 254.54985], + [249.8505 , 249.80202, 249.75244, ..., 254.37044, 254.42378, + 254.47711], + [249.82195, 249.75998, 249.71204, ..., 254.30956, 254.35805, + 254.41139]]], dtype=float32) + Coordinates: + * time1 (time1) datetime64[ns] 8B 1993-03-13 + * y (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1 + * x (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03 + + +Let's take a look at a concrete example and compare it to NumPy. We will calculate the max temperature over the 'isobaric1' dimension at a specific value for x: :: + + >>> # Xarray + >>> ds['Temperature_isobaric'].sel(x='-3259.5447').max(dim='isobaric1') + array([[294.11 , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 , + ..., + 276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]], + dtype=float32) + +In comparison, if we were to use plain Numpy, this would be: :: + + >>> # NumPy + >>> np.max(temperature_numpy[:, :, :, 2 ], axis = 1) + array([[294.11 , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 , + ..., + 276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]], + dtype=float32) + + + +As you can see, the Xarray code is much more readable and we didn't need to keep track of the right indices and order of the dimensions. + +Plotting data in Xarray +----------------------- + +Like Pandas, Xarray comes with basic plotting capabilities. We can easily plot data in 1D and 2D using the ``.plot()`` method. Xarray uses a widely used plotting library called matplotlib for this. When calling the ``.plot()`` method, Xarray checks the dimensionality of the data and plots it accordingly. Let's import matplotlib and plot the data: :: + + >>> import matplotlib.pyplot as plt + + >>> ds['Temperature_isobaric'].isel(x=2).plot() + >>> plt.show() + +For a 2D DataArray the plot would resemble this example: + + .. image:: img/xarray/xarray_2d_plot.png + +Note, that we didn't specify the axes labels, Xarray automatically used the coordinates of the DataArray for the plot. This plot might not be one you include directly in a paper, but it is a great way to quickly visualize your data. + +Let's have a look at a dataslice of 1D data: :: + + >>> ds['Temperature_isobaric'].isel(x=2, y=5).plot() + >>> plt.show() + +The resulting plot detects the dimentionality of the data and plots it accordingly: + + .. image:: img/xarray/xarray_1d_plot.png + +If the data has more than two dimensions, Xarray will plot a histogram of the data: :: + + >>> ds['Temperature_isobaric'].plot() + >>> plt.show() + +The resulting plot would look like this: + + .. image:: img/xarray/xarray_hist.png + +We can modify the plots by passing additional arguments to the ``.plot()`` method. Since we haven't discussed the plotting library matplotlib in this course, we will not go into further detail here. You can find more information in the `Xarray documentation `_. + +Exercises 1 +----------- + +.. challenge:: Exercises: Xarray-1 + + Download the ``NARR_19930313_0000.nc`` dataset have a look at all Data variables. Calculate the geopotential height at ``x=5148.3726`` averaged over ``y`` and return the median value. You can use the ``.plot()`` method to check on the way whether you use the correct dimensions and indices. + +.. solution:: Solutions: Xarray-1 + + One way of calculating this is: :: + + >>> from pythia_datasets import DATASETS + >>> import xarray as xr + >>> + >>> filepath = DATASETS.fetch('NARR_19930313_0000.nc') + >>> ds = xr.open_dataset(filepath) + >>> ds['Geopotential_height_isobaric'].sel(x=5148.3726).mean('y').median() + Size: 4B + array(4395.487, dtype=float32) + Coordinates: + x float32 4B 5.148e+03 + + + + +Creating your own Xarray Dataset +-------------------------------- + +Creating your own Xarray Dataset is quite simple. We can create a Dataset from scratch using basic Python data structures. Let's create a simple weather dataset with pressure and humidity data with the following script: :: + + import xarray as xr + import numpy as np + + # Define coordinates using basic Python lists + time = ['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05'] + location = ['Location1', 'Location2', 'Location3'] + + # Define data variables as numpy arrays + pressure_data = np.random.rand(5, 3) * 1000 # Random pressure data in hPa + humidity_data = np.random.rand(5, 3) * 100 # Random humidity data + + # Put everything together to create the Dataset + ds = xr.Dataset( + data_vars = { + "pressure": (["time", "location"], pressure_data), + "humidity": (["time", "location"], humidity_data) + }, + coords={ + "time": time, + "location": location + }, + attrs={ + "description": "Weather data", + "creation_date": "2023-01-01", + "author": "Data Scientist" + } + ) + + +Converting Xarray objects to NumPy, Pandas and NetCDF +------------------------------------------------------ + +Another handy feature of Xarray is the simple conversion between Xarray objects, NumPy arrays, Pandas DataFrames and even NetCDF files. + +To convert an xarray DataArray to a NumPy array, you can use the ``.values`` attribute or the ``.to_numpy()`` method: :: + + # Convert the 'pressure' DataArray to a NumPy array + pressure_numpy = ds['pressure'].values + # or + pressure_numpy = ds['pressure'].to_numpy() + +To convert the entire Dataset or individual DataArrays to pandas DataFrames, use the ``.to_dataframe()`` method: :: + + # Convert the entire Dataset to a DataFrame + df = ds.to_dataframe() + # Convert a single DataArray to DataFrame + pressure_df = ds['pressure'].to_dataframe() + +To save the dataset as a NetCDF file, use the ``.to_netcdf()`` method: :: + + # Save the Dataset as a NetCDF file + ds.to_netcdf('weather_data.nc') + + +Exercises 2 +----------- + +.. challenge:: Exercises: Xarray-2 + + Let's change from climate science to finance for this example. Put the stock prices and trading volumes of three companies over ten days in one dataset. Create an Xarray Dataset that uses time and company as dimensions and contains two DataArrays: ``stock_price`` and ``trading_volume``. You can choose the values for the stock prices and trading volumes yourself. As a last thing, add the currency of the stock prices as an attribute to the Dataset. + +.. solution:: Solutions: Xarray-2 + + We can use a script similar to this one: :: + + import xarray as xr + import numpy as np + + time = [ + "2023-01-01", + "2023-01-02", + "2023-01-03", + "2023-01-04", + "2023-01-05", + "2023-01-06", + "2023-01-07", + "2023-01-08", + "2023-01-09", + "2023-01-10", + ] + companies = ["AAPL", "GOOGL", "MSFT"] + stock_prices = np.random.normal(loc=[100, 1500, 200], scale=[10, 50, 20], size=(10, 3)) + trading_volumes = np.random.randint(1000, 10000, size=(10, 3)) + ds = xr.Dataset( + data_vars = { + "stock_price": (["time", "company"], stock_prices), + "trading_volume": (["time", "company"], trading_volumes), + }, + coords={"time": time, "company": companies}, + attrs={"currency": "USD"}, + ) + print(ds) + + The output should then resemble this: :: + + > python exercise.py + Size: 940B + Dimensions: (time: 10, company: 3) + Coordinates: + * time (time) `_ in the Xarray documentation. +- If you want to accelerate Xarray operations with your GPU, have a look at `CuPy-Xarray `_. +- Xarray can be combined with pint, a Python library that adds support for physical quantities to NumPy arrays. This `blog post `_ provides a good introduction to the topic. +- You can extend Xarray with your own methods using the `register_dataset_accessor() `_ method. This is a powerful feature that allows you to add custom methods to your own Xarray Datasets. diff --git a/branch/master/_static/_sphinx_javascript_frameworks_compat.js b/branch/master/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..81415803 --- /dev/null +++ b/branch/master/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,123 @@ +/* Compatability shim for jQuery and underscores.js. + * + * Copyright Sphinx contributors + * Released under the two clause BSD licence + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/branch/master/_static/basic.css b/branch/master/_static/basic.css new file mode 100644 index 00000000..f316efcb --- /dev/null +++ b/branch/master/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/branch/master/_static/check-solid.svg b/branch/master/_static/check-solid.svg new file mode 100644 index 00000000..92fad4b5 --- /dev/null +++ b/branch/master/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/branch/master/_static/clipboard.min.js b/branch/master/_static/clipboard.min.js new file mode 100644 index 00000000..54b3c463 --- /dev/null +++ b/branch/master/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/branch/master/_static/copybutton.css b/branch/master/_static/copybutton.css new file mode 100644 index 00000000..f1916ec7 --- /dev/null +++ b/branch/master/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/branch/master/_static/copybutton.js b/branch/master/_static/copybutton.js new file mode 100644 index 00000000..b3987037 --- /dev/null +++ b/branch/master/_static/copybutton.js @@ -0,0 +1,248 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copier dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = ``; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = 'div.highlight pre'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} + + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '.linenos, .gp'; + + let text = filterText(target, exclude); + return formatCopyText(text, '', false, true, true, true, '', '') +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) \ No newline at end of file diff --git a/branch/master/_static/copybutton_funcs.js b/branch/master/_static/copybutton_funcs.js new file mode 100644 index 00000000..dbe1aaad --- /dev/null +++ b/branch/master/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/branch/master/_static/css/badge_only.css b/branch/master/_static/css/badge_only.css new file mode 100644 index 00000000..88ba55b9 --- /dev/null +++ b/branch/master/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px} \ No newline at end of file diff --git a/branch/master/_static/css/fonts/Roboto-Slab-Bold.woff b/branch/master/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/master/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/branch/master/_static/css/fonts/Roboto-Slab-Bold.woff2 b/branch/master/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/master/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/branch/master/_static/css/fonts/Roboto-Slab-Regular.woff b/branch/master/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/master/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/branch/master/_static/css/fonts/Roboto-Slab-Regular.woff2 b/branch/master/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/master/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/branch/master/_static/css/fonts/fontawesome-webfont.eot b/branch/master/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/branch/master/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/branch/master/_static/css/fonts/fontawesome-webfont.svg b/branch/master/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/branch/master/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/branch/master/_static/css/fonts/fontawesome-webfont.ttf b/branch/master/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/branch/master/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/branch/master/_static/css/fonts/fontawesome-webfont.woff b/branch/master/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/branch/master/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/branch/master/_static/css/fonts/fontawesome-webfont.woff2 b/branch/master/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/branch/master/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/branch/master/_static/css/fonts/lato-bold-italic.woff b/branch/master/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/master/_static/css/fonts/lato-bold-italic.woff differ diff --git a/branch/master/_static/css/fonts/lato-bold-italic.woff2 b/branch/master/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/master/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/branch/master/_static/css/fonts/lato-bold.woff b/branch/master/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/master/_static/css/fonts/lato-bold.woff differ diff --git a/branch/master/_static/css/fonts/lato-bold.woff2 b/branch/master/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/master/_static/css/fonts/lato-bold.woff2 differ diff --git a/branch/master/_static/css/fonts/lato-normal-italic.woff b/branch/master/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/master/_static/css/fonts/lato-normal-italic.woff differ diff --git a/branch/master/_static/css/fonts/lato-normal-italic.woff2 b/branch/master/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/master/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/branch/master/_static/css/fonts/lato-normal.woff b/branch/master/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/master/_static/css/fonts/lato-normal.woff differ diff --git a/branch/master/_static/css/fonts/lato-normal.woff2 b/branch/master/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/master/_static/css/fonts/lato-normal.woff2 differ diff --git a/branch/master/_static/css/theme.css b/branch/master/_static/css/theme.css new file mode 100644 index 00000000..0f14f106 --- /dev/null +++ b/branch/master/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search .wy-dropdown>aactive,.wy-side-nav-search .wy-dropdown>afocus,.wy-side-nav-search>a:hover,.wy-side-nav-search>aactive,.wy-side-nav-search>afocus{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon,.wy-side-nav-search>a.icon{display:block}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.switch-menus{position:relative;display:block;margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-side-nav-search>div.switch-menus>div.language-switch,.wy-side-nav-search>div.switch-menus>div.version-switch{display:inline-block;padding:.2em}.wy-side-nav-search>div.switch-menus>div.language-switch select,.wy-side-nav-search>div.switch-menus>div.version-switch select{display:inline-block;margin-right:-2rem;padding-right:2rem;max-width:240px;text-align-last:center;background:none;border:none;border-radius:0;box-shadow:none;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-size:1em;font-weight:400;color:hsla(0,0%,100%,.3);cursor:pointer;appearance:none;-webkit-appearance:none;-moz-appearance:none}.wy-side-nav-search>div.switch-menus>div.language-switch select:active,.wy-side-nav-search>div.switch-menus>div.language-switch select:focus,.wy-side-nav-search>div.switch-menus>div.language-switch select:hover,.wy-side-nav-search>div.switch-menus>div.version-switch select:active,.wy-side-nav-search>div.switch-menus>div.version-switch select:focus,.wy-side-nav-search>div.switch-menus>div.version-switch select:hover{background:hsla(0,0%,100%,.1);color:hsla(0,0%,100%,.5)}.wy-side-nav-search>div.switch-menus>div.language-switch select option,.wy-side-nav-search>div.switch-menus>div.version-switch select option{color:#000}.wy-side-nav-search>div.switch-menus>div.language-switch:has(>select):after,.wy-side-nav-search>div.switch-menus>div.version-switch:has(>select):after{display:inline-block;width:1.5em;height:100%;padding:.1em;content:"\f0d7";font-size:1em;line-height:1.2em;font-family:FontAwesome;text-align:center;pointer-events:none;box-sizing:border-box}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel,.rst-content .menuselection{font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .guilabel,.rst-content .menuselection{border:1px solid #7fbbe3;background:#e7f2fa}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/branch/master/_static/doctools.js b/branch/master/_static/doctools.js new file mode 100644 index 00000000..4d67807d --- /dev/null +++ b/branch/master/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/branch/master/_static/documentation_options.js b/branch/master/_static/documentation_options.js new file mode 100644 index 00000000..87fc516a --- /dev/null +++ b/branch/master/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'dirhtml', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/branch/master/_static/file.png b/branch/master/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/branch/master/_static/file.png differ diff --git a/branch/master/_static/fonts/Lato/lato-bold.eot b/branch/master/_static/fonts/Lato/lato-bold.eot new file mode 100644 index 00000000..3361183a Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bold.eot differ diff --git a/branch/master/_static/fonts/Lato/lato-bold.ttf b/branch/master/_static/fonts/Lato/lato-bold.ttf new file mode 100644 index 00000000..29f691d5 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bold.ttf differ diff --git a/branch/master/_static/fonts/Lato/lato-bold.woff b/branch/master/_static/fonts/Lato/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bold.woff differ diff --git a/branch/master/_static/fonts/Lato/lato-bold.woff2 b/branch/master/_static/fonts/Lato/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bold.woff2 differ diff --git a/branch/master/_static/fonts/Lato/lato-bolditalic.eot b/branch/master/_static/fonts/Lato/lato-bolditalic.eot new file mode 100644 index 00000000..3d415493 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bolditalic.eot differ diff --git a/branch/master/_static/fonts/Lato/lato-bolditalic.ttf b/branch/master/_static/fonts/Lato/lato-bolditalic.ttf new file mode 100644 index 00000000..f402040b Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bolditalic.ttf differ diff --git a/branch/master/_static/fonts/Lato/lato-bolditalic.woff b/branch/master/_static/fonts/Lato/lato-bolditalic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bolditalic.woff differ diff --git a/branch/master/_static/fonts/Lato/lato-bolditalic.woff2 b/branch/master/_static/fonts/Lato/lato-bolditalic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-bolditalic.woff2 differ diff --git a/branch/master/_static/fonts/Lato/lato-italic.eot b/branch/master/_static/fonts/Lato/lato-italic.eot new file mode 100644 index 00000000..3f826421 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-italic.eot differ diff --git a/branch/master/_static/fonts/Lato/lato-italic.ttf b/branch/master/_static/fonts/Lato/lato-italic.ttf new file mode 100644 index 00000000..b4bfc9b2 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-italic.ttf differ diff --git a/branch/master/_static/fonts/Lato/lato-italic.woff b/branch/master/_static/fonts/Lato/lato-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-italic.woff differ diff --git a/branch/master/_static/fonts/Lato/lato-italic.woff2 b/branch/master/_static/fonts/Lato/lato-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-italic.woff2 differ diff --git a/branch/master/_static/fonts/Lato/lato-regular.eot b/branch/master/_static/fonts/Lato/lato-regular.eot new file mode 100644 index 00000000..11e3f2a5 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-regular.eot differ diff --git a/branch/master/_static/fonts/Lato/lato-regular.ttf b/branch/master/_static/fonts/Lato/lato-regular.ttf new file mode 100644 index 00000000..74decd9e Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-regular.ttf differ diff --git a/branch/master/_static/fonts/Lato/lato-regular.woff b/branch/master/_static/fonts/Lato/lato-regular.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-regular.woff differ diff --git a/branch/master/_static/fonts/Lato/lato-regular.woff2 b/branch/master/_static/fonts/Lato/lato-regular.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/master/_static/fonts/Lato/lato-regular.woff2 differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot new file mode 100644 index 00000000..79dc8efe Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf new file mode 100644 index 00000000..df5d1df2 Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot new file mode 100644 index 00000000..2f7ca78a Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf new file mode 100644 index 00000000..eb52a790 Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff differ diff --git a/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/master/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 differ diff --git a/branch/master/_static/jquery.js b/branch/master/_static/jquery.js new file mode 100644 index 00000000..c4c6022f --- /dev/null +++ b/branch/master/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0
"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t +
Languages
+ ${config.projects.translations + .map( + (translation) => ` +
+ ${translation.language.code} +
+ `, + ) + .join("\n")} + + `; + return languagesHTML; + } + + function renderVersions(config) { + if (!config.versions.active.length) { + return ""; + } + const versionsHTML = ` +
+
Versions
+ ${config.versions.active + .map( + (version) => ` +
+ ${version.slug} +
+ `, + ) + .join("\n")} +
+ `; + return versionsHTML; + } + + function renderDownloads(config) { + if (!Object.keys(config.versions.current.downloads).length) { + return ""; + } + const downloadsNameDisplay = { + pdf: "PDF", + epub: "Epub", + htmlzip: "HTML", + }; + + const downloadsHTML = ` +
+
Downloads
+ ${Object.entries(config.versions.current.downloads) + .map( + ([name, url]) => ` +
+ ${downloadsNameDisplay[name]} +
+ `, + ) + .join("\n")} +
+ `; + return downloadsHTML; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const flyout = ` +
+ + Read the Docs + v: ${config.versions.current.slug} + + +
+
+ ${renderLanguages(config)} + ${renderVersions(config)} + ${renderDownloads(config)} +
+
On Read the Docs
+
+ Project Home +
+
+ Builds +
+
+ Downloads +
+
+
+
Search
+
+
+ +
+
+
+
+ + Hosted by Read the Docs + +
+
+ `; + + // Inject the generated flyout into the body HTML element. + document.body.insertAdjacentHTML("beforeend", flyout); + + // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout. + document + .querySelector("#flyout-search-form") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + }) +} + +if (themeLanguageSelector || themeVersionSelector) { + function onSelectorSwitch(event) { + const option = event.target.selectedIndex; + const item = event.target.options[option]; + window.location.href = item.dataset.url; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const versionSwitch = document.querySelector( + "div.switch-menus > div.version-switch", + ); + if (themeVersionSelector) { + let versions = config.versions.active; + if (config.versions.current.hidden || config.versions.current.type === "external") { + versions.unshift(config.versions.current); + } + const versionSelect = ` + + `; + + versionSwitch.innerHTML = versionSelect; + versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + + const languageSwitch = document.querySelector( + "div.switch-menus > div.language-switch", + ); + + if (themeLanguageSelector) { + if (config.projects.translations.length) { + // Add the current language to the options on the selector + let languages = config.projects.translations.concat( + config.projects.current, + ); + languages = languages.sort((a, b) => + a.language.name.localeCompare(b.language.name), + ); + + const languageSelect = ` + + `; + + languageSwitch.innerHTML = languageSelect; + languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + else { + languageSwitch.remove(); + } + } + }); +} + +document.addEventListener("readthedocs-addons-data-ready", function (event) { + // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. + document + .querySelector("[role='search'] input") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); +}); \ No newline at end of file diff --git a/branch/master/_static/language_data.js b/branch/master/_static/language_data.js new file mode 100644 index 00000000..367b8ed8 --- /dev/null +++ b/branch/master/_static/language_data.js @@ -0,0 +1,199 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/branch/master/_static/logo-hexagons-02-compact.svg.ico b/branch/master/_static/logo-hexagons-02-compact.svg.ico new file mode 100644 index 00000000..bafe8f98 Binary files /dev/null and b/branch/master/_static/logo-hexagons-02-compact.svg.ico differ diff --git a/branch/master/_static/minipres.js b/branch/master/_static/minipres.js new file mode 100644 index 00000000..ad11c871 --- /dev/null +++ b/branch/master/_static/minipres.js @@ -0,0 +1,223 @@ +// Add goTo method to elements +// http://stackoverflow.com/questions/4801655/how-to-go-to-a-specific-element-on-page +(function($) { + $.fn.goTo = function() { + $('html, body').animate({ + scrollTop: $(this).offset().top //+ 'px' + }, 'fast'); + return this; // for chaining... + } +})(jQuery); + +// NO good way to do this!. Copy a hack from here +// https://stackoverflow.com/questions/901115/how-can-i-get-query-string-values-in-javascript +// https://stackoverflow.com/a/2880929 +var urlParams; +(window.onpopstate = function () { + var match, + pl = /\+/g, // Regex for replacing addition symbol with a space + search = /([^&=]+)=?([^&]*)/g, + decode = function (s) { return decodeURIComponent(s.replace(pl, " ")); }, + query = window.location.search.substring(1); + urlParams = {}; + while (match = search.exec(query)) + urlParams[decode(match[1])] = decode(match[2]); +})(); + +// Select heading levels +var maxHeading = urlParams['h'] +if (maxHeading === undefined) maxHeading = 2 +var headingLevels = []; +for (h=2 ; h (sections.length-1) ) { + // if we would scroll past bottom, or above top, do nothing + return; + } + + console.log('xxxxxx'); + var targetSection = sections[targetPos]; + console.log(targetSection, typeof(targetSection)); + + // Return targetSection top and height + var secProperties = section_top_and_height(targetSection); + var top = secProperties['top']; + var height = secProperties['height'] + var win_height = window.innerHeight; + //console.info(top, height, win_height) + + var scroll_to = 0; + if (height >= win_height || height == 0) { + scroll_to = top; + } else { + scroll_to = top - (win_height-height)/3.; + } + //console.info(top, height, win_height, scroll_to) + + $('html, body').animate({ + scrollTop: scroll_to //+ 'px' + }, 'fast'); + +} + + +function minipres() { + /* Enable the minipres mode: + - call the hide() function + - set up the scrolling listener + */ + document.addEventListener('keydown', function (event) { + switch(event.which) { + case 37: // left + switch_slide(-1); + event.preventDefault(); + return false; + break; + //case 38: // up + case 39: // right + switch_slide(+1); + event.preventDefault(); + return false; + break; + //case 40: // down + default: + return; // exit this handler for other keys + } + }, true) + + hide() + + // Increase space between sections + //$("div .section").css('margin-bottom', '50%'); + $(sectionSelector).css('margin-top', '50%'); + + // Reduce size/color of other sections + if (hiddenSectionSelector.length > 0) { + var hideNodes = $(hiddenSectionSelector); + console.log(typeof hideNodes, hideNodes); + for (node in hideNodes) { + console.log("a", typeof node, node); + node = hideNodes[node]; // what's right way to iterate values? + console.log("b", typeof node, node); + if (node.parentNode && node.parentNode.className == "section") { + node = node.parentNode; + console.log("c", typeof node, node); + //node.css['transform'] = 'scale(.5)'; + //node.css['transform-origin'] = 'top center'; + $(node).css('color', 'lightgrey'); + //$(node).css('font-size', '20%'); + //$(node).css('visibility', 'collapse'); + //ntahousnatouhasno; + } + } + } +} + +function hide() { + /* Hide all non-essential elements on the page + */ + + // This is for sphinx_rst_theme and readthedocs + $(".wy-nav-side").remove(); + $(".wy-nav-content-wrap").css('margin-left', 0); + $('.rst-versions').remove(); // readthedocs version selector + + // Add other formats here. +} + + +var slideshow = minipres; + +if (window.location.search.match(/[?&](minipres|slideshow|pres)([=&]|$)/) ) { + //minipres() + window.addEventListener("load", minipres); +} else if (window.location.search.match(/[?&](plain)([=&]|$)/) ) { + window.addEventListener("load", hide); +} diff --git a/branch/master/_static/minus.png b/branch/master/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/branch/master/_static/minus.png differ diff --git a/branch/master/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css b/branch/master/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css new file mode 100644 index 00000000..33566310 --- /dev/null +++ b/branch/master/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css @@ -0,0 +1,2342 @@ +/* Variables */ +:root { + --mystnb-source-bg-color: #f7f7f7; + --mystnb-stdout-bg-color: #fcfcfc; + --mystnb-stderr-bg-color: #fdd; + --mystnb-traceback-bg-color: #fcfcfc; + --mystnb-source-border-color: #ccc; + --mystnb-source-margin-color: green; + --mystnb-stdout-border-color: #f7f7f7; + --mystnb-stderr-border-color: #f7f7f7; + --mystnb-traceback-border-color: #ffd6d6; + --mystnb-hide-prompt-opacity: 70%; + --mystnb-source-border-radius: .4em; + --mystnb-source-border-width: 1px; +} + +/* Whole cell */ +div.container.cell { + padding-left: 0; + margin-bottom: 1em; +} + +/* Removing all background formatting so we can control at the div level */ +.cell_input div.highlight, +.cell_output pre, +.cell_input pre, +.cell_output .output { + border: none; + box-shadow: none; +} + +.cell_output .output pre, +.cell_input pre { + margin: 0px; +} + +/* Input cells */ +div.cell div.cell_input, +div.cell details.above-input>summary { + padding-left: 0em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + background-color: var(--mystnb-source-bg-color); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; + border-radius: var(--mystnb-source-border-radius); +} + +div.cell_input>div, +div.cell_output div.output>div.highlight { + margin: 0em !important; + border: none !important; +} + +/* All cell outputs */ +.cell_output { + padding-left: 1em; + padding-right: 0em; + margin-top: 1em; +} + +/* Text outputs from cells */ +.cell_output .output.text_plain, +.cell_output .output.traceback, +.cell_output .output.stream, +.cell_output .output.stderr { + margin-top: 1em; + margin-bottom: 0em; + box-shadow: none; +} + +.cell_output .output.text_plain, +.cell_output .output.stream { + background: var(--mystnb-stdout-bg-color); + border: 1px solid var(--mystnb-stdout-border-color); +} + +.cell_output .output.stderr { + background: var(--mystnb-stderr-bg-color); + border: 1px solid var(--mystnb-stderr-border-color); +} + +.cell_output .output.traceback { + background: var(--mystnb-traceback-bg-color); + border: 1px solid var(--mystnb-traceback-border-color); +} + +/* Collapsible cell content */ +div.cell details.above-input div.cell_input { + border-top-left-radius: 0; + border-top-right-radius: 0; + border-top: var(--mystnb-source-border-width) var(--mystnb-source-border-color) dashed; +} + +div.cell div.cell_input.above-output-prompt { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; +} + +div.cell details.above-input>summary { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; + border-bottom: var(--mystnb-source-border-width) var(--mystnb-source-border-color) dashed; + padding-left: 1em; + margin-bottom: 0; +} + +div.cell details.above-output>summary { + background-color: var(--mystnb-source-bg-color); + padding-left: 1em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + border-radius: var(--mystnb-source-border-radius); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; +} + +div.cell details.below-input>summary { + background-color: var(--mystnb-source-bg-color); + padding-left: 1em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + border-top: none; + border-bottom-left-radius: var(--mystnb-source-border-radius); + border-bottom-right-radius: var(--mystnb-source-border-radius); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; +} + +div.cell details.hide>summary>span { + opacity: var(--mystnb-hide-prompt-opacity); +} + +div.cell details.hide[open]>summary>span.collapsed { + display: none; +} + +div.cell details.hide:not([open])>summary>span.expanded { + display: none; +} + +@keyframes collapsed-fade-in { + 0% { + opacity: 0; + } + + 100% { + opacity: 1; + } +} +div.cell details.hide[open]>summary~* { + -moz-animation: collapsed-fade-in 0.3s ease-in-out; + -webkit-animation: collapsed-fade-in 0.3s ease-in-out; + animation: collapsed-fade-in 0.3s ease-in-out; +} + +/* Math align to the left */ +.cell_output .MathJax_Display { + text-align: left !important; +} + +/* Pandas tables. Pulled from the Jupyter / nbsphinx CSS */ +div.cell_output table { + border: none; + border-collapse: collapse; + border-spacing: 0; + color: black; + font-size: 1em; + table-layout: fixed; +} + +div.cell_output thead { + border-bottom: 1px solid black; + vertical-align: bottom; +} + +div.cell_output tr, +div.cell_output th, +div.cell_output td { + text-align: right; + vertical-align: middle; + padding: 0.5em 0.5em; + line-height: normal; + white-space: normal; + max-width: none; + border: none; +} + +div.cell_output th { + font-weight: bold; +} + +div.cell_output tbody tr:nth-child(odd) { + background: #f5f5f5; +} + +div.cell_output tbody tr:hover { + background: rgba(66, 165, 245, 0.2); +} + +/** source code line numbers **/ +span.linenos { + opacity: 0.5; +} + +/* Inline text from `paste` operation */ + +span.pasted-text { + font-weight: bold; +} + +span.pasted-inline img { + max-height: 2em; +} + +tbody span.pasted-inline img { + max-height: none; +} + +/* Font colors for translated ANSI escape sequences +Color values are copied from Jupyter Notebook +https://github.com/jupyter/notebook/blob/52581f8eda9b319eb0390ac77fe5903c38f81e3e/notebook/static/notebook/less/ansicolors.less#L14-L21 +Background colors from +https://nbsphinx.readthedocs.io/en/latest/code-cells.html#ANSI-Colors +*/ +div.highlight .-Color-Bold { + font-weight: bold; +} + +div.highlight .-Color[class*=-Black] { + color: #3E424D +} + +div.highlight .-Color[class*=-Red] { + color: #E75C58 +} + +div.highlight .-Color[class*=-Green] { + color: #00A250 +} + +div.highlight .-Color[class*=-Yellow] { + color: #DDB62B +} + +div.highlight .-Color[class*=-Blue] { + color: #208FFB +} + +div.highlight .-Color[class*=-Magenta] { + color: #D160C4 +} + +div.highlight .-Color[class*=-Cyan] { + color: #60C6C8 +} + +div.highlight .-Color[class*=-White] { + color: #C5C1B4 +} + +div.highlight .-Color[class*=-BGBlack] { + background-color: #3E424D +} + +div.highlight .-Color[class*=-BGRed] { + background-color: #E75C58 +} + +div.highlight .-Color[class*=-BGGreen] { + background-color: #00A250 +} + +div.highlight .-Color[class*=-BGYellow] { + background-color: #DDB62B +} + +div.highlight .-Color[class*=-BGBlue] { + background-color: #208FFB +} + +div.highlight .-Color[class*=-BGMagenta] { + background-color: #D160C4 +} + +div.highlight .-Color[class*=-BGCyan] { + background-color: #60C6C8 +} + +div.highlight .-Color[class*=-BGWhite] { + background-color: #C5C1B4 +} + +/* Font colors for 8-bit ANSI */ + +div.highlight .-Color[class*=-C0] { + color: #000000 +} + +div.highlight .-Color[class*=-BGC0] { + background-color: #000000 +} + +div.highlight .-Color[class*=-C1] { + color: #800000 +} + +div.highlight .-Color[class*=-BGC1] { + background-color: #800000 +} + +div.highlight .-Color[class*=-C2] { + color: #008000 +} + +div.highlight .-Color[class*=-BGC2] { + background-color: #008000 +} + +div.highlight .-Color[class*=-C3] { + color: #808000 +} + +div.highlight .-Color[class*=-BGC3] { + background-color: #808000 +} + +div.highlight .-Color[class*=-C4] { + color: #000080 +} + +div.highlight .-Color[class*=-BGC4] { + background-color: #000080 +} + +div.highlight .-Color[class*=-C5] { + color: #800080 +} + +div.highlight .-Color[class*=-BGC5] { + background-color: #800080 +} + +div.highlight .-Color[class*=-C6] { + color: #008080 +} + +div.highlight .-Color[class*=-BGC6] { + background-color: #008080 +} + +div.highlight .-Color[class*=-C7] { + color: #C0C0C0 +} + +div.highlight .-Color[class*=-BGC7] { + background-color: #C0C0C0 +} + +div.highlight .-Color[class*=-C8] { + color: #808080 +} + +div.highlight .-Color[class*=-BGC8] { + background-color: #808080 +} + +div.highlight .-Color[class*=-C9] { + color: #FF0000 +} + +div.highlight .-Color[class*=-BGC9] { + background-color: #FF0000 +} + +div.highlight .-Color[class*=-C10] { + color: #00FF00 +} + +div.highlight .-Color[class*=-BGC10] { + background-color: #00FF00 +} + +div.highlight .-Color[class*=-C11] { + color: #FFFF00 +} + +div.highlight .-Color[class*=-BGC11] { + background-color: #FFFF00 +} + +div.highlight .-Color[class*=-C12] { + color: #0000FF +} + +div.highlight .-Color[class*=-BGC12] { + background-color: #0000FF +} + +div.highlight .-Color[class*=-C13] { + color: #FF00FF +} + +div.highlight .-Color[class*=-BGC13] { + background-color: #FF00FF +} + +div.highlight .-Color[class*=-C14] { + color: #00FFFF +} + +div.highlight .-Color[class*=-BGC14] { + background-color: #00FFFF +} + +div.highlight .-Color[class*=-C15] { + color: #FFFFFF +} + +div.highlight .-Color[class*=-BGC15] { + background-color: #FFFFFF +} + +div.highlight .-Color[class*=-C16] { + color: #000000 +} + +div.highlight .-Color[class*=-BGC16] { + background-color: #000000 +} + +div.highlight .-Color[class*=-C17] { + color: #00005F +} + +div.highlight .-Color[class*=-BGC17] { + background-color: #00005F +} + +div.highlight .-Color[class*=-C18] { + color: #000087 +} + +div.highlight .-Color[class*=-BGC18] { + background-color: #000087 +} + +div.highlight .-Color[class*=-C19] { + color: #0000AF +} + +div.highlight .-Color[class*=-BGC19] { + background-color: #0000AF +} + +div.highlight .-Color[class*=-C20] { + color: #0000D7 +} + +div.highlight .-Color[class*=-BGC20] { + background-color: #0000D7 +} + +div.highlight .-Color[class*=-C21] { + color: #0000FF +} + +div.highlight .-Color[class*=-BGC21] { + background-color: #0000FF +} + +div.highlight .-Color[class*=-C22] { + color: #005F00 +} + +div.highlight .-Color[class*=-BGC22] { + background-color: #005F00 +} + +div.highlight .-Color[class*=-C23] { + color: #005F5F +} + +div.highlight .-Color[class*=-BGC23] { + background-color: #005F5F +} + +div.highlight .-Color[class*=-C24] { + color: #005F87 +} + +div.highlight .-Color[class*=-BGC24] { + background-color: #005F87 +} + +div.highlight .-Color[class*=-C25] { + color: #005FAF +} + +div.highlight .-Color[class*=-BGC25] { + background-color: #005FAF +} + +div.highlight .-Color[class*=-C26] { + color: #005FD7 +} + +div.highlight .-Color[class*=-BGC26] { + background-color: #005FD7 +} + +div.highlight .-Color[class*=-C27] { + color: #005FFF +} + +div.highlight .-Color[class*=-BGC27] { + background-color: #005FFF +} + +div.highlight .-Color[class*=-C28] { + color: #008700 +} + +div.highlight .-Color[class*=-BGC28] { + background-color: #008700 +} + +div.highlight .-Color[class*=-C29] { + color: #00875F +} + +div.highlight .-Color[class*=-BGC29] { + background-color: #00875F +} + +div.highlight .-Color[class*=-C30] { + color: #008787 +} + +div.highlight .-Color[class*=-BGC30] { + background-color: #008787 +} + +div.highlight .-Color[class*=-C31] { + color: #0087AF +} + +div.highlight .-Color[class*=-BGC31] { + background-color: #0087AF +} + +div.highlight .-Color[class*=-C32] { + color: #0087D7 +} + +div.highlight .-Color[class*=-BGC32] { + background-color: #0087D7 +} + +div.highlight .-Color[class*=-C33] { + color: #0087FF +} + +div.highlight .-Color[class*=-BGC33] { + background-color: #0087FF +} + +div.highlight .-Color[class*=-C34] { + color: #00AF00 +} + +div.highlight .-Color[class*=-BGC34] { + background-color: #00AF00 +} + +div.highlight .-Color[class*=-C35] { + color: #00AF5F +} + +div.highlight .-Color[class*=-BGC35] { + background-color: #00AF5F +} + +div.highlight .-Color[class*=-C36] { + color: #00AF87 +} + +div.highlight .-Color[class*=-BGC36] { + background-color: #00AF87 +} + +div.highlight .-Color[class*=-C37] { + color: #00AFAF +} + +div.highlight .-Color[class*=-BGC37] { + background-color: #00AFAF +} + +div.highlight .-Color[class*=-C38] { + color: #00AFD7 +} + +div.highlight .-Color[class*=-BGC38] { + background-color: #00AFD7 +} + +div.highlight .-Color[class*=-C39] { + color: #00AFFF +} + +div.highlight .-Color[class*=-BGC39] { + background-color: #00AFFF +} + +div.highlight .-Color[class*=-C40] { + color: #00D700 +} + +div.highlight .-Color[class*=-BGC40] { + background-color: #00D700 +} + +div.highlight .-Color[class*=-C41] { + color: #00D75F +} + +div.highlight .-Color[class*=-BGC41] { + background-color: #00D75F +} + +div.highlight .-Color[class*=-C42] { + color: #00D787 +} + +div.highlight .-Color[class*=-BGC42] { + background-color: #00D787 +} + +div.highlight .-Color[class*=-C43] { + color: #00D7AF +} + +div.highlight .-Color[class*=-BGC43] { + background-color: #00D7AF +} + +div.highlight .-Color[class*=-C44] { + color: #00D7D7 +} + +div.highlight .-Color[class*=-BGC44] { + background-color: #00D7D7 +} + +div.highlight .-Color[class*=-C45] { + color: #00D7FF +} + +div.highlight .-Color[class*=-BGC45] { + background-color: #00D7FF +} + +div.highlight .-Color[class*=-C46] { + color: #00FF00 +} + +div.highlight .-Color[class*=-BGC46] { + background-color: #00FF00 +} + +div.highlight .-Color[class*=-C47] { + color: #00FF5F +} + +div.highlight .-Color[class*=-BGC47] { + background-color: #00FF5F +} + +div.highlight .-Color[class*=-C48] { + color: #00FF87 +} + +div.highlight .-Color[class*=-BGC48] { + background-color: #00FF87 +} + +div.highlight .-Color[class*=-C49] { + color: #00FFAF +} + +div.highlight .-Color[class*=-BGC49] { + background-color: #00FFAF +} + +div.highlight .-Color[class*=-C50] { + color: #00FFD7 +} + +div.highlight .-Color[class*=-BGC50] { + background-color: #00FFD7 +} + +div.highlight .-Color[class*=-C51] { + color: #00FFFF +} + +div.highlight .-Color[class*=-BGC51] { + background-color: #00FFFF +} + +div.highlight .-Color[class*=-C52] { + color: #5F0000 +} + +div.highlight .-Color[class*=-BGC52] { + background-color: #5F0000 +} + +div.highlight .-Color[class*=-C53] { + color: #5F005F +} + +div.highlight .-Color[class*=-BGC53] { + background-color: #5F005F +} + +div.highlight .-Color[class*=-C54] { + color: #5F0087 +} + +div.highlight .-Color[class*=-BGC54] { + background-color: #5F0087 +} + +div.highlight .-Color[class*=-C55] { + color: #5F00AF +} + +div.highlight .-Color[class*=-BGC55] { + background-color: #5F00AF +} + +div.highlight .-Color[class*=-C56] { + color: #5F00D7 +} + +div.highlight .-Color[class*=-BGC56] { + background-color: #5F00D7 +} + +div.highlight .-Color[class*=-C57] { + color: #5F00FF +} + +div.highlight .-Color[class*=-BGC57] { + background-color: #5F00FF +} + +div.highlight .-Color[class*=-C58] { + color: #5F5F00 +} + +div.highlight .-Color[class*=-BGC58] { + background-color: #5F5F00 +} + +div.highlight .-Color[class*=-C59] { + color: #5F5F5F +} + +div.highlight .-Color[class*=-BGC59] { + background-color: #5F5F5F +} + +div.highlight .-Color[class*=-C60] { + color: #5F5F87 +} + +div.highlight .-Color[class*=-BGC60] { + background-color: #5F5F87 +} + +div.highlight .-Color[class*=-C61] { + color: #5F5FAF +} + +div.highlight .-Color[class*=-BGC61] { + background-color: #5F5FAF +} + +div.highlight .-Color[class*=-C62] { + color: #5F5FD7 +} + +div.highlight .-Color[class*=-BGC62] { + background-color: #5F5FD7 +} + +div.highlight .-Color[class*=-C63] { + color: #5F5FFF +} + +div.highlight .-Color[class*=-BGC63] { + background-color: #5F5FFF +} + +div.highlight .-Color[class*=-C64] { + color: #5F8700 +} + +div.highlight .-Color[class*=-BGC64] { + background-color: #5F8700 +} + +div.highlight .-Color[class*=-C65] { + color: #5F875F +} + +div.highlight .-Color[class*=-BGC65] { + background-color: #5F875F +} + +div.highlight .-Color[class*=-C66] { + color: #5F8787 +} + +div.highlight .-Color[class*=-BGC66] { + background-color: #5F8787 +} + +div.highlight .-Color[class*=-C67] { + color: #5F87AF +} + +div.highlight .-Color[class*=-BGC67] { + background-color: #5F87AF +} + +div.highlight .-Color[class*=-C68] { + color: #5F87D7 +} + +div.highlight .-Color[class*=-BGC68] { + background-color: #5F87D7 +} + +div.highlight .-Color[class*=-C69] { + color: #5F87FF +} + +div.highlight .-Color[class*=-BGC69] { + background-color: #5F87FF +} + +div.highlight .-Color[class*=-C70] { + color: #5FAF00 +} + +div.highlight .-Color[class*=-BGC70] { + background-color: #5FAF00 +} + +div.highlight .-Color[class*=-C71] { + color: #5FAF5F +} + +div.highlight .-Color[class*=-BGC71] { + background-color: #5FAF5F +} + +div.highlight .-Color[class*=-C72] { + color: #5FAF87 +} + +div.highlight .-Color[class*=-BGC72] { + background-color: #5FAF87 +} + +div.highlight .-Color[class*=-C73] { + color: #5FAFAF +} + +div.highlight .-Color[class*=-BGC73] { + background-color: #5FAFAF +} + +div.highlight .-Color[class*=-C74] { + color: #5FAFD7 +} + +div.highlight .-Color[class*=-BGC74] { + background-color: #5FAFD7 +} + +div.highlight .-Color[class*=-C75] { + color: #5FAFFF +} + +div.highlight .-Color[class*=-BGC75] { + background-color: #5FAFFF +} + +div.highlight .-Color[class*=-C76] { + color: #5FD700 +} + +div.highlight .-Color[class*=-BGC76] { + background-color: #5FD700 +} + +div.highlight .-Color[class*=-C77] { + color: #5FD75F +} + +div.highlight .-Color[class*=-BGC77] { + background-color: #5FD75F +} + +div.highlight .-Color[class*=-C78] { + color: #5FD787 +} + +div.highlight .-Color[class*=-BGC78] { + background-color: #5FD787 +} + +div.highlight .-Color[class*=-C79] { + color: #5FD7AF +} + +div.highlight .-Color[class*=-BGC79] { + background-color: #5FD7AF +} + +div.highlight .-Color[class*=-C80] { + color: #5FD7D7 +} + +div.highlight .-Color[class*=-BGC80] { + background-color: #5FD7D7 +} + +div.highlight .-Color[class*=-C81] { + color: #5FD7FF +} + +div.highlight .-Color[class*=-BGC81] { + background-color: #5FD7FF +} + +div.highlight .-Color[class*=-C82] { + color: #5FFF00 +} + +div.highlight .-Color[class*=-BGC82] { + background-color: #5FFF00 +} + +div.highlight .-Color[class*=-C83] { + color: #5FFF5F +} + +div.highlight .-Color[class*=-BGC83] { + background-color: #5FFF5F +} + +div.highlight .-Color[class*=-C84] { + color: #5FFF87 +} + +div.highlight .-Color[class*=-BGC84] { + background-color: #5FFF87 +} + +div.highlight .-Color[class*=-C85] { + color: #5FFFAF +} + +div.highlight .-Color[class*=-BGC85] { + background-color: #5FFFAF +} + +div.highlight .-Color[class*=-C86] { + color: #5FFFD7 +} + +div.highlight .-Color[class*=-BGC86] { + background-color: #5FFFD7 +} + +div.highlight .-Color[class*=-C87] { + color: #5FFFFF +} + +div.highlight .-Color[class*=-BGC87] { + background-color: #5FFFFF +} + +div.highlight .-Color[class*=-C88] { + color: #870000 +} + +div.highlight .-Color[class*=-BGC88] { + background-color: #870000 +} + +div.highlight .-Color[class*=-C89] { + color: #87005F +} + +div.highlight .-Color[class*=-BGC89] { + background-color: #87005F +} + +div.highlight .-Color[class*=-C90] { + color: #870087 +} + +div.highlight .-Color[class*=-BGC90] { + background-color: #870087 +} + +div.highlight .-Color[class*=-C91] { + color: #8700AF +} + +div.highlight .-Color[class*=-BGC91] { + background-color: #8700AF +} + +div.highlight .-Color[class*=-C92] { + color: #8700D7 +} + +div.highlight .-Color[class*=-BGC92] { + background-color: #8700D7 +} + +div.highlight .-Color[class*=-C93] { + color: #8700FF +} + +div.highlight .-Color[class*=-BGC93] { + background-color: #8700FF +} + +div.highlight .-Color[class*=-C94] { + color: #875F00 +} + +div.highlight .-Color[class*=-BGC94] { + background-color: #875F00 +} + +div.highlight .-Color[class*=-C95] { + color: #875F5F +} + +div.highlight .-Color[class*=-BGC95] { + background-color: #875F5F +} + +div.highlight .-Color[class*=-C96] { + color: #875F87 +} + +div.highlight .-Color[class*=-BGC96] { + background-color: #875F87 +} + +div.highlight .-Color[class*=-C97] { + color: #875FAF +} + +div.highlight .-Color[class*=-BGC97] { + background-color: #875FAF +} + +div.highlight .-Color[class*=-C98] { + color: #875FD7 +} + +div.highlight .-Color[class*=-BGC98] { + background-color: #875FD7 +} + +div.highlight .-Color[class*=-C99] { + color: #875FFF +} + +div.highlight .-Color[class*=-BGC99] { + background-color: #875FFF +} + +div.highlight .-Color[class*=-C100] { + color: #878700 +} + +div.highlight .-Color[class*=-BGC100] { + background-color: #878700 +} + +div.highlight .-Color[class*=-C101] { + color: #87875F +} + +div.highlight .-Color[class*=-BGC101] { + background-color: #87875F +} + +div.highlight .-Color[class*=-C102] { + color: #878787 +} + +div.highlight .-Color[class*=-BGC102] { + background-color: #878787 +} + +div.highlight .-Color[class*=-C103] { + color: #8787AF +} + +div.highlight .-Color[class*=-BGC103] { + background-color: #8787AF +} + +div.highlight .-Color[class*=-C104] { + color: #8787D7 +} + +div.highlight .-Color[class*=-BGC104] { + background-color: #8787D7 +} + +div.highlight .-Color[class*=-C105] { + color: #8787FF +} + +div.highlight .-Color[class*=-BGC105] { + background-color: #8787FF +} + +div.highlight .-Color[class*=-C106] { + color: #87AF00 +} + +div.highlight .-Color[class*=-BGC106] { + background-color: #87AF00 +} + +div.highlight .-Color[class*=-C107] { + color: #87AF5F +} + +div.highlight .-Color[class*=-BGC107] { + background-color: #87AF5F +} + +div.highlight .-Color[class*=-C108] { + color: #87AF87 +} + +div.highlight .-Color[class*=-BGC108] { + background-color: #87AF87 +} + +div.highlight .-Color[class*=-C109] { + color: #87AFAF +} + +div.highlight .-Color[class*=-BGC109] { + background-color: #87AFAF +} + +div.highlight .-Color[class*=-C110] { + color: #87AFD7 +} + +div.highlight .-Color[class*=-BGC110] { + background-color: #87AFD7 +} + +div.highlight .-Color[class*=-C111] { + color: #87AFFF +} + +div.highlight .-Color[class*=-BGC111] { + background-color: #87AFFF +} + +div.highlight .-Color[class*=-C112] { + color: #87D700 +} + +div.highlight .-Color[class*=-BGC112] { + background-color: #87D700 +} + +div.highlight .-Color[class*=-C113] { + color: #87D75F +} + +div.highlight .-Color[class*=-BGC113] { + background-color: #87D75F +} + +div.highlight .-Color[class*=-C114] { + color: #87D787 +} + +div.highlight .-Color[class*=-BGC114] { + background-color: #87D787 +} + +div.highlight .-Color[class*=-C115] { + color: #87D7AF +} + +div.highlight .-Color[class*=-BGC115] { + background-color: #87D7AF +} + +div.highlight .-Color[class*=-C116] { + color: #87D7D7 +} + +div.highlight .-Color[class*=-BGC116] { + background-color: #87D7D7 +} + +div.highlight .-Color[class*=-C117] { + color: #87D7FF +} + +div.highlight .-Color[class*=-BGC117] { + background-color: #87D7FF +} + +div.highlight .-Color[class*=-C118] { + color: #87FF00 +} + +div.highlight .-Color[class*=-BGC118] { + background-color: #87FF00 +} + +div.highlight .-Color[class*=-C119] { + color: #87FF5F +} + +div.highlight .-Color[class*=-BGC119] { + background-color: #87FF5F +} + +div.highlight .-Color[class*=-C120] { + color: #87FF87 +} + +div.highlight .-Color[class*=-BGC120] { + background-color: #87FF87 +} + +div.highlight .-Color[class*=-C121] { + color: #87FFAF +} + +div.highlight .-Color[class*=-BGC121] { + background-color: #87FFAF +} + +div.highlight .-Color[class*=-C122] { + color: #87FFD7 +} + +div.highlight .-Color[class*=-BGC122] { + background-color: #87FFD7 +} + +div.highlight .-Color[class*=-C123] { + color: #87FFFF +} + +div.highlight .-Color[class*=-BGC123] { + background-color: #87FFFF +} + +div.highlight .-Color[class*=-C124] { + color: #AF0000 +} + +div.highlight .-Color[class*=-BGC124] { + background-color: #AF0000 +} + +div.highlight .-Color[class*=-C125] { + color: #AF005F +} + +div.highlight .-Color[class*=-BGC125] { + background-color: #AF005F +} + +div.highlight .-Color[class*=-C126] { + color: #AF0087 +} + +div.highlight .-Color[class*=-BGC126] { + background-color: #AF0087 +} + +div.highlight .-Color[class*=-C127] { + color: #AF00AF +} + +div.highlight .-Color[class*=-BGC127] { + background-color: #AF00AF +} + +div.highlight .-Color[class*=-C128] { + color: #AF00D7 +} + +div.highlight .-Color[class*=-BGC128] { + background-color: #AF00D7 +} + +div.highlight .-Color[class*=-C129] { + color: #AF00FF +} + +div.highlight .-Color[class*=-BGC129] { + background-color: #AF00FF +} + +div.highlight .-Color[class*=-C130] { + color: #AF5F00 +} + +div.highlight .-Color[class*=-BGC130] { + background-color: #AF5F00 +} + +div.highlight .-Color[class*=-C131] { + color: #AF5F5F +} + +div.highlight .-Color[class*=-BGC131] { + background-color: #AF5F5F +} + +div.highlight .-Color[class*=-C132] { + color: #AF5F87 +} + +div.highlight .-Color[class*=-BGC132] { + background-color: #AF5F87 +} + +div.highlight .-Color[class*=-C133] { + color: #AF5FAF +} + +div.highlight .-Color[class*=-BGC133] { + background-color: #AF5FAF +} + +div.highlight .-Color[class*=-C134] { + color: #AF5FD7 +} + +div.highlight .-Color[class*=-BGC134] { + background-color: #AF5FD7 +} + +div.highlight .-Color[class*=-C135] { + color: #AF5FFF +} + +div.highlight .-Color[class*=-BGC135] { + background-color: #AF5FFF +} + +div.highlight .-Color[class*=-C136] { + color: #AF8700 +} + +div.highlight .-Color[class*=-BGC136] { + background-color: #AF8700 +} + +div.highlight .-Color[class*=-C137] { + color: #AF875F +} + +div.highlight .-Color[class*=-BGC137] { + background-color: #AF875F +} + +div.highlight .-Color[class*=-C138] { + color: #AF8787 +} + +div.highlight .-Color[class*=-BGC138] { + background-color: #AF8787 +} + +div.highlight .-Color[class*=-C139] { + color: #AF87AF +} + +div.highlight .-Color[class*=-BGC139] { + background-color: #AF87AF +} + +div.highlight .-Color[class*=-C140] { + color: #AF87D7 +} + +div.highlight .-Color[class*=-BGC140] { + background-color: #AF87D7 +} + +div.highlight .-Color[class*=-C141] { + color: #AF87FF +} + +div.highlight .-Color[class*=-BGC141] { + background-color: #AF87FF +} + +div.highlight .-Color[class*=-C142] { + color: #AFAF00 +} + +div.highlight .-Color[class*=-BGC142] { + background-color: #AFAF00 +} + +div.highlight .-Color[class*=-C143] { + color: #AFAF5F +} + +div.highlight .-Color[class*=-BGC143] { + background-color: #AFAF5F +} + +div.highlight .-Color[class*=-C144] { + color: #AFAF87 +} + +div.highlight .-Color[class*=-BGC144] { + background-color: #AFAF87 +} + +div.highlight .-Color[class*=-C145] { + color: #AFAFAF +} + +div.highlight .-Color[class*=-BGC145] { + background-color: #AFAFAF +} + +div.highlight .-Color[class*=-C146] { + color: #AFAFD7 +} + +div.highlight .-Color[class*=-BGC146] { + background-color: #AFAFD7 +} + +div.highlight .-Color[class*=-C147] { + color: #AFAFFF +} + +div.highlight .-Color[class*=-BGC147] { + background-color: #AFAFFF +} + +div.highlight .-Color[class*=-C148] { + color: #AFD700 +} + +div.highlight .-Color[class*=-BGC148] { + background-color: #AFD700 +} + +div.highlight .-Color[class*=-C149] { + color: #AFD75F +} + +div.highlight .-Color[class*=-BGC149] { + background-color: #AFD75F +} + +div.highlight .-Color[class*=-C150] { + color: #AFD787 +} + +div.highlight .-Color[class*=-BGC150] { + background-color: #AFD787 +} + +div.highlight .-Color[class*=-C151] { + color: #AFD7AF +} + +div.highlight .-Color[class*=-BGC151] { + background-color: #AFD7AF +} + +div.highlight .-Color[class*=-C152] { + color: #AFD7D7 +} + +div.highlight .-Color[class*=-BGC152] { + background-color: #AFD7D7 +} + +div.highlight .-Color[class*=-C153] { + color: #AFD7FF +} + +div.highlight .-Color[class*=-BGC153] { + background-color: #AFD7FF +} + +div.highlight .-Color[class*=-C154] { + color: #AFFF00 +} + +div.highlight .-Color[class*=-BGC154] { + background-color: #AFFF00 +} + +div.highlight .-Color[class*=-C155] { + color: #AFFF5F +} + +div.highlight .-Color[class*=-BGC155] { + background-color: #AFFF5F +} + +div.highlight .-Color[class*=-C156] { + color: #AFFF87 +} + +div.highlight .-Color[class*=-BGC156] { + background-color: #AFFF87 +} + +div.highlight .-Color[class*=-C157] { + color: #AFFFAF +} + +div.highlight .-Color[class*=-BGC157] { + background-color: #AFFFAF +} + +div.highlight .-Color[class*=-C158] { + color: #AFFFD7 +} + +div.highlight .-Color[class*=-BGC158] { + background-color: #AFFFD7 +} + +div.highlight .-Color[class*=-C159] { + color: #AFFFFF +} + +div.highlight .-Color[class*=-BGC159] { + background-color: #AFFFFF +} + +div.highlight .-Color[class*=-C160] { + color: #D70000 +} + +div.highlight .-Color[class*=-BGC160] { + background-color: #D70000 +} + +div.highlight .-Color[class*=-C161] { + color: #D7005F +} + +div.highlight .-Color[class*=-BGC161] { + background-color: #D7005F +} + +div.highlight .-Color[class*=-C162] { + color: #D70087 +} + +div.highlight .-Color[class*=-BGC162] { + background-color: #D70087 +} + +div.highlight .-Color[class*=-C163] { + color: #D700AF +} + +div.highlight .-Color[class*=-BGC163] { + background-color: #D700AF +} + +div.highlight .-Color[class*=-C164] { + color: #D700D7 +} + +div.highlight .-Color[class*=-BGC164] { + background-color: #D700D7 +} + +div.highlight .-Color[class*=-C165] { + color: #D700FF +} + +div.highlight .-Color[class*=-BGC165] { + background-color: #D700FF +} + +div.highlight .-Color[class*=-C166] { + color: #D75F00 +} + +div.highlight .-Color[class*=-BGC166] { + background-color: #D75F00 +} + +div.highlight .-Color[class*=-C167] { + color: #D75F5F +} + +div.highlight .-Color[class*=-BGC167] { + background-color: #D75F5F +} + +div.highlight .-Color[class*=-C168] { + color: #D75F87 +} + +div.highlight .-Color[class*=-BGC168] { + background-color: #D75F87 +} + +div.highlight .-Color[class*=-C169] { + color: #D75FAF +} + +div.highlight .-Color[class*=-BGC169] { + background-color: #D75FAF +} + +div.highlight .-Color[class*=-C170] { + color: #D75FD7 +} + +div.highlight .-Color[class*=-BGC170] { + background-color: #D75FD7 +} + +div.highlight .-Color[class*=-C171] { + color: #D75FFF +} + +div.highlight .-Color[class*=-BGC171] { + background-color: #D75FFF +} + +div.highlight .-Color[class*=-C172] { + color: #D78700 +} + +div.highlight .-Color[class*=-BGC172] { + background-color: #D78700 +} + +div.highlight .-Color[class*=-C173] { + color: #D7875F +} + +div.highlight .-Color[class*=-BGC173] { + background-color: #D7875F +} + +div.highlight .-Color[class*=-C174] { + color: #D78787 +} + +div.highlight .-Color[class*=-BGC174] { + background-color: #D78787 +} + +div.highlight .-Color[class*=-C175] { + color: #D787AF +} + +div.highlight .-Color[class*=-BGC175] { + background-color: #D787AF +} + +div.highlight .-Color[class*=-C176] { + color: #D787D7 +} + +div.highlight .-Color[class*=-BGC176] { + background-color: #D787D7 +} + +div.highlight .-Color[class*=-C177] { + color: #D787FF +} + +div.highlight .-Color[class*=-BGC177] { + background-color: #D787FF +} + +div.highlight .-Color[class*=-C178] { + color: #D7AF00 +} + +div.highlight .-Color[class*=-BGC178] { + background-color: #D7AF00 +} + +div.highlight .-Color[class*=-C179] { + color: #D7AF5F +} + +div.highlight .-Color[class*=-BGC179] { + background-color: #D7AF5F +} + +div.highlight .-Color[class*=-C180] { + color: #D7AF87 +} + +div.highlight .-Color[class*=-BGC180] { + background-color: #D7AF87 +} + +div.highlight .-Color[class*=-C181] { + color: #D7AFAF +} + +div.highlight .-Color[class*=-BGC181] { + background-color: #D7AFAF +} + +div.highlight .-Color[class*=-C182] { + color: #D7AFD7 +} + +div.highlight .-Color[class*=-BGC182] { + background-color: #D7AFD7 +} + +div.highlight .-Color[class*=-C183] { + color: #D7AFFF +} + +div.highlight .-Color[class*=-BGC183] { + background-color: #D7AFFF +} + +div.highlight .-Color[class*=-C184] { + color: #D7D700 +} + +div.highlight .-Color[class*=-BGC184] { + background-color: #D7D700 +} + +div.highlight .-Color[class*=-C185] { + color: #D7D75F +} + +div.highlight .-Color[class*=-BGC185] { + background-color: #D7D75F +} + +div.highlight .-Color[class*=-C186] { + color: #D7D787 +} + +div.highlight .-Color[class*=-BGC186] { + background-color: #D7D787 +} + +div.highlight .-Color[class*=-C187] { + color: #D7D7AF +} + +div.highlight .-Color[class*=-BGC187] { + background-color: #D7D7AF +} + +div.highlight .-Color[class*=-C188] { + color: #D7D7D7 +} + +div.highlight .-Color[class*=-BGC188] { + background-color: #D7D7D7 +} + +div.highlight .-Color[class*=-C189] { + color: #D7D7FF +} + +div.highlight .-Color[class*=-BGC189] { + background-color: #D7D7FF +} + +div.highlight .-Color[class*=-C190] { + color: #D7FF00 +} + +div.highlight .-Color[class*=-BGC190] { + background-color: #D7FF00 +} + +div.highlight .-Color[class*=-C191] { + color: #D7FF5F +} + +div.highlight .-Color[class*=-BGC191] { + background-color: #D7FF5F +} + +div.highlight .-Color[class*=-C192] { + color: #D7FF87 +} + +div.highlight .-Color[class*=-BGC192] { + background-color: #D7FF87 +} + +div.highlight .-Color[class*=-C193] { + color: #D7FFAF +} + +div.highlight .-Color[class*=-BGC193] { + background-color: #D7FFAF +} + +div.highlight .-Color[class*=-C194] { + color: #D7FFD7 +} + +div.highlight .-Color[class*=-BGC194] { + background-color: #D7FFD7 +} + +div.highlight .-Color[class*=-C195] { + color: #D7FFFF +} + +div.highlight .-Color[class*=-BGC195] { + background-color: #D7FFFF +} + +div.highlight .-Color[class*=-C196] { + color: #FF0000 +} + +div.highlight .-Color[class*=-BGC196] { + background-color: #FF0000 +} + +div.highlight .-Color[class*=-C197] { + color: #FF005F +} + +div.highlight .-Color[class*=-BGC197] { + background-color: #FF005F +} + +div.highlight .-Color[class*=-C198] { + color: #FF0087 +} + +div.highlight .-Color[class*=-BGC198] { + background-color: #FF0087 +} + +div.highlight .-Color[class*=-C199] { + color: #FF00AF +} + +div.highlight .-Color[class*=-BGC199] { + background-color: #FF00AF +} + +div.highlight .-Color[class*=-C200] { + color: #FF00D7 +} + +div.highlight .-Color[class*=-BGC200] { + background-color: #FF00D7 +} + +div.highlight .-Color[class*=-C201] { + color: #FF00FF +} + +div.highlight .-Color[class*=-BGC201] { + background-color: #FF00FF +} + +div.highlight .-Color[class*=-C202] { + color: #FF5F00 +} + +div.highlight .-Color[class*=-BGC202] { + background-color: #FF5F00 +} + +div.highlight .-Color[class*=-C203] { + color: #FF5F5F +} + +div.highlight .-Color[class*=-BGC203] { + background-color: #FF5F5F +} + +div.highlight .-Color[class*=-C204] { + color: #FF5F87 +} + +div.highlight .-Color[class*=-BGC204] { + background-color: #FF5F87 +} + +div.highlight .-Color[class*=-C205] { + color: #FF5FAF +} + +div.highlight .-Color[class*=-BGC205] { + background-color: #FF5FAF +} + +div.highlight .-Color[class*=-C206] { + color: #FF5FD7 +} + +div.highlight .-Color[class*=-BGC206] { + background-color: #FF5FD7 +} + +div.highlight .-Color[class*=-C207] { + color: #FF5FFF +} + +div.highlight .-Color[class*=-BGC207] { + background-color: #FF5FFF +} + +div.highlight .-Color[class*=-C208] { + color: #FF8700 +} + +div.highlight .-Color[class*=-BGC208] { + background-color: #FF8700 +} + +div.highlight .-Color[class*=-C209] { + color: #FF875F +} + +div.highlight .-Color[class*=-BGC209] { + background-color: #FF875F +} + +div.highlight .-Color[class*=-C210] { + color: #FF8787 +} + +div.highlight .-Color[class*=-BGC210] { + background-color: #FF8787 +} + +div.highlight .-Color[class*=-C211] { + color: #FF87AF +} + +div.highlight .-Color[class*=-BGC211] { + background-color: #FF87AF +} + +div.highlight .-Color[class*=-C212] { + color: #FF87D7 +} + +div.highlight .-Color[class*=-BGC212] { + background-color: #FF87D7 +} + +div.highlight .-Color[class*=-C213] { + color: #FF87FF +} + +div.highlight .-Color[class*=-BGC213] { + background-color: #FF87FF +} + +div.highlight .-Color[class*=-C214] { + color: #FFAF00 +} + +div.highlight .-Color[class*=-BGC214] { + background-color: #FFAF00 +} + +div.highlight .-Color[class*=-C215] { + color: #FFAF5F +} + +div.highlight .-Color[class*=-BGC215] { + background-color: #FFAF5F +} + +div.highlight .-Color[class*=-C216] { + color: #FFAF87 +} + +div.highlight .-Color[class*=-BGC216] { + background-color: #FFAF87 +} + +div.highlight .-Color[class*=-C217] { + color: #FFAFAF +} + +div.highlight .-Color[class*=-BGC217] { + background-color: #FFAFAF +} + +div.highlight .-Color[class*=-C218] { + color: #FFAFD7 +} + +div.highlight .-Color[class*=-BGC218] { + background-color: #FFAFD7 +} + +div.highlight .-Color[class*=-C219] { + color: #FFAFFF +} + +div.highlight .-Color[class*=-BGC219] { + background-color: #FFAFFF +} + +div.highlight .-Color[class*=-C220] { + color: #FFD700 +} + +div.highlight .-Color[class*=-BGC220] { + background-color: #FFD700 +} + +div.highlight .-Color[class*=-C221] { + color: #FFD75F +} + +div.highlight .-Color[class*=-BGC221] { + background-color: #FFD75F +} + +div.highlight .-Color[class*=-C222] { + color: #FFD787 +} + +div.highlight .-Color[class*=-BGC222] { + background-color: #FFD787 +} + +div.highlight .-Color[class*=-C223] { + color: #FFD7AF +} + +div.highlight .-Color[class*=-BGC223] { + background-color: #FFD7AF +} + +div.highlight .-Color[class*=-C224] { + color: #FFD7D7 +} + +div.highlight .-Color[class*=-BGC224] { + background-color: #FFD7D7 +} + +div.highlight .-Color[class*=-C225] { + color: #FFD7FF +} + +div.highlight .-Color[class*=-BGC225] { + background-color: #FFD7FF +} + +div.highlight .-Color[class*=-C226] { + color: #FFFF00 +} + +div.highlight .-Color[class*=-BGC226] { + background-color: #FFFF00 +} + +div.highlight .-Color[class*=-C227] { + color: #FFFF5F +} + +div.highlight .-Color[class*=-BGC227] { + background-color: #FFFF5F +} + +div.highlight .-Color[class*=-C228] { + color: #FFFF87 +} + +div.highlight .-Color[class*=-BGC228] { + background-color: #FFFF87 +} + +div.highlight .-Color[class*=-C229] { + color: #FFFFAF +} + +div.highlight .-Color[class*=-BGC229] { + background-color: #FFFFAF +} + +div.highlight .-Color[class*=-C230] { + color: #FFFFD7 +} + +div.highlight .-Color[class*=-BGC230] { + background-color: #FFFFD7 +} + +div.highlight .-Color[class*=-C231] { + color: #FFFFFF +} + +div.highlight .-Color[class*=-BGC231] { + background-color: #FFFFFF +} + +div.highlight .-Color[class*=-C232] { + color: #080808 +} + +div.highlight .-Color[class*=-BGC232] { + background-color: #080808 +} + +div.highlight .-Color[class*=-C233] { + color: #121212 +} + +div.highlight .-Color[class*=-BGC233] { + background-color: #121212 +} + +div.highlight .-Color[class*=-C234] { + color: #1C1C1C +} + +div.highlight .-Color[class*=-BGC234] { + background-color: #1C1C1C +} + +div.highlight .-Color[class*=-C235] { + color: #262626 +} + +div.highlight .-Color[class*=-BGC235] { + background-color: #262626 +} + +div.highlight .-Color[class*=-C236] { + color: #303030 +} + +div.highlight .-Color[class*=-BGC236] { + background-color: #303030 +} + +div.highlight .-Color[class*=-C237] { + color: #3A3A3A +} + +div.highlight .-Color[class*=-BGC237] { + background-color: #3A3A3A +} + +div.highlight .-Color[class*=-C238] { + color: #444444 +} + +div.highlight .-Color[class*=-BGC238] { + background-color: #444444 +} + +div.highlight .-Color[class*=-C239] { + color: #4E4E4E +} + +div.highlight .-Color[class*=-BGC239] { + background-color: #4E4E4E +} + +div.highlight .-Color[class*=-C240] { + color: #585858 +} + +div.highlight .-Color[class*=-BGC240] { + background-color: #585858 +} + +div.highlight .-Color[class*=-C241] { + color: #626262 +} + +div.highlight .-Color[class*=-BGC241] { + background-color: #626262 +} + +div.highlight .-Color[class*=-C242] { + color: #6C6C6C +} + +div.highlight .-Color[class*=-BGC242] { + background-color: #6C6C6C +} + +div.highlight .-Color[class*=-C243] { + color: #767676 +} + +div.highlight .-Color[class*=-BGC243] { + background-color: #767676 +} + +div.highlight .-Color[class*=-C244] { + color: #808080 +} + +div.highlight .-Color[class*=-BGC244] { + background-color: #808080 +} + +div.highlight .-Color[class*=-C245] { + color: #8A8A8A +} + +div.highlight .-Color[class*=-BGC245] { + background-color: #8A8A8A +} + +div.highlight .-Color[class*=-C246] { + color: #949494 +} + +div.highlight .-Color[class*=-BGC246] { + background-color: #949494 +} + +div.highlight .-Color[class*=-C247] { + color: #9E9E9E +} + +div.highlight .-Color[class*=-BGC247] { + background-color: #9E9E9E +} + +div.highlight .-Color[class*=-C248] { + color: #A8A8A8 +} + +div.highlight .-Color[class*=-BGC248] { + background-color: #A8A8A8 +} + +div.highlight .-Color[class*=-C249] { + color: #B2B2B2 +} + +div.highlight .-Color[class*=-BGC249] { + background-color: #B2B2B2 +} + +div.highlight .-Color[class*=-C250] { + color: #BCBCBC +} + +div.highlight .-Color[class*=-BGC250] { + background-color: #BCBCBC +} + +div.highlight .-Color[class*=-C251] { + color: #C6C6C6 +} + +div.highlight .-Color[class*=-BGC251] { + background-color: #C6C6C6 +} + +div.highlight .-Color[class*=-C252] { + color: #D0D0D0 +} + +div.highlight .-Color[class*=-BGC252] { + background-color: #D0D0D0 +} + +div.highlight .-Color[class*=-C253] { + color: #DADADA +} + +div.highlight .-Color[class*=-BGC253] { + background-color: #DADADA +} + +div.highlight .-Color[class*=-C254] { + color: #E4E4E4 +} + +div.highlight .-Color[class*=-BGC254] { + background-color: #E4E4E4 +} + +div.highlight .-Color[class*=-C255] { + color: #EEEEEE +} + +div.highlight .-Color[class*=-BGC255] { + background-color: #EEEEEE +} diff --git a/branch/master/_static/play-solid.svg b/branch/master/_static/play-solid.svg new file mode 100644 index 00000000..bcd81f7a --- /dev/null +++ b/branch/master/_static/play-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/branch/master/_static/plus.png b/branch/master/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/branch/master/_static/plus.png differ diff --git a/branch/master/_static/pygments.css b/branch/master/_static/pygments.css new file mode 100644 index 00000000..84ab3030 --- /dev/null +++ b/branch/master/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #008000; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #9C6500 } /* Comment.Preproc */ +.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #E40000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #008400 } /* Generic.Inserted */ +.highlight .go { color: #717171 } /* Generic.Output */ +.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #008000 } /* Keyword.Pseudo */ +.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #B00040 } /* Keyword.Type */ +.highlight .m { color: #666666 } /* Literal.Number */ +.highlight .s { color: #BA2121 } /* Literal.String */ +.highlight .na { color: #687822 } /* Name.Attribute */ +.highlight .nb { color: #008000 } /* Name.Builtin */ +.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.highlight .no { color: #880000 } /* Name.Constant */ +.highlight .nd { color: #AA22FF } /* Name.Decorator */ +.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #0000FF } /* Name.Function */ +.highlight .nl { color: #767600 } /* Name.Label */ +.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #19177C } /* Name.Variable */ +.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #666666 } /* Literal.Number.Bin */ +.highlight .mf { color: #666666 } /* Literal.Number.Float */ +.highlight .mh { color: #666666 } /* Literal.Number.Hex */ +.highlight .mi { color: #666666 } /* Literal.Number.Integer */ +.highlight .mo { color: #666666 } /* Literal.Number.Oct */ +.highlight .sa { color: #BA2121 } /* Literal.String.Affix */ +.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */ +.highlight .sc { color: #BA2121 } /* Literal.String.Char */ +.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #BA2121 } /* Literal.String.Double */ +.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */ +.highlight .sx { color: #008000 } /* Literal.String.Other */ +.highlight .sr { color: #A45A77 } /* Literal.String.Regex */ +.highlight .s1 { color: #BA2121 } /* Literal.String.Single */ +.highlight .ss { color: #19177C } /* Literal.String.Symbol */ +.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #0000FF } /* Name.Function.Magic */ +.highlight .vc { color: #19177C } /* Name.Variable.Class */ +.highlight .vg { color: #19177C } /* Name.Variable.Global */ +.highlight .vi { color: #19177C } /* Name.Variable.Instance */ +.highlight .vm { color: #19177C } /* Name.Variable.Magic */ +.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/branch/master/_static/searchtools.js b/branch/master/_static/searchtools.js new file mode 100644 index 00000000..b08d58c9 --- /dev/null +++ b/branch/master/_static/searchtools.js @@ -0,0 +1,620 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + "Search finished, found ${resultCount} page(s) matching the search query." + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/branch/master/_static/sphinx-thebe.css b/branch/master/_static/sphinx-thebe.css new file mode 100644 index 00000000..1da27930 --- /dev/null +++ b/branch/master/_static/sphinx-thebe.css @@ -0,0 +1,129 @@ +/* Thebelab Buttons */ +.thebelab-button { + z-index: 999; + display: inline-block; + padding: 0.35em 1.2em; + margin: 0px 1px; + border-radius: 0.12em; + box-sizing: border-box; + text-decoration: none; + font-family: "Roboto", sans-serif; + font-weight: 300; + text-align: center; + transition: all 0.2s; + background-color: #dddddd; + border: 0.05em solid white; + color: #000000; +} + +.thebelab-button:hover { + border: 0.05em solid black; + background-color: #fcfcfc; +} + +.thebe-launch-button { + height: 2.2em; + font-size: 0.8em; + border: 1px black solid; +} + +/* Thebelab Cell */ +.thebelab-cell pre { + background: none; +} + +.thebelab-cell .thebelab-input { + padding-left: 1em; + margin-bottom: 0.5em; + margin-top: 0.5em; +} + +.thebelab-cell .jp-OutputArea { + margin-top: 0.5em; + margin-left: 1em; +} + +button.thebelab-button.thebelab-run-button { + margin-left: 1.5em; + margin-bottom: 0.5em; +} + +/* Loading button */ +button.thebe-launch-button div.spinner { + float: left; + margin-right: 1em; +} + +/* Remove the spinner when thebelab is ready */ +.thebe-launch-button.thebe-status-ready .spinner { + display: none; +} + +.thebe-launch-button span.status { + font-family: monospace; + font-weight: bold; +} + +.thebe-launch-button.thebe-status-ready span.status { + color: green; +} + +.spinner { + height: 2em; + text-align: center; + font-size: 0.7em; +} + +.spinner > div { + background-color: #f37726; + height: 100%; + width: 6px; + display: inline-block; + + -webkit-animation: sk-stretchdelay 1.2s infinite ease-in-out; + animation: sk-stretchdelay 1.2s infinite ease-in-out; +} + +.spinner .rect2 { + -webkit-animation-delay: -1.1s; + animation-delay: -1.1s; +} + +.spinner .rect3 { + -webkit-animation-delay: -1s; + animation-delay: -1s; +} + +.spinner .rect4 { + -webkit-animation-delay: -0.9s; + animation-delay: -0.9s; +} + +.spinner .rect5 { + -webkit-animation-delay: -0.8s; + animation-delay: -0.8s; +} + +@-webkit-keyframes sk-stretchdelay { + 0%, + 40%, + 100% { + -webkit-transform: scaleY(0.4); + } + 20% { + -webkit-transform: scaleY(1); + } +} + +@keyframes sk-stretchdelay { + 0%, + 40%, + 100% { + transform: scaleY(0.4); + -webkit-transform: scaleY(0.4); + } + 20% { + transform: scaleY(1); + -webkit-transform: scaleY(1); + } +} diff --git a/branch/master/_static/sphinx-thebe.js b/branch/master/_static/sphinx-thebe.js new file mode 100644 index 00000000..d92b1d3b --- /dev/null +++ b/branch/master/_static/sphinx-thebe.js @@ -0,0 +1,127 @@ +/** + * Add attributes to Thebe blocks to initialize thebe properly + */ +var configureThebe = () => { + // Load thebe config in case we want to update it as some point + console.log("[sphinx-thebe]: Loading thebe config..."); + thebe_config = document.querySelector("script[type=\"text/x-thebe-config\"]"); + + // If we already detect a Thebe cell, don't re-run + if (document.querySelectorAll("div.thebe-cell").length > 0) { + return; + } + + // Update thebe buttons with loading message + document.querySelectorAll(".thebe-launch-button").forEach((button) => { + button.innerHTML = ` + + `; + }); + + // Set thebe event hooks + var thebeStatus; + thebelab.on("status", function (evt, data) { + console.log("Status changed:", data.status, data.message); + + const button = document.querySelector(".thebe-launch-button "); + button.classList.replace( + `thebe-status-${thebeStatus}`, + `thebe-status-${data.status}` + ) + button.querySelector(".loading-text") + .innerHTML = ( + `Launching from mybinder.org: + ${data.status}` + ); + + // Now update our thebe status + thebeStatus = data.status; + + // Find any cells with an initialization tag and ask thebe to run them when ready + if (data.status === "ready") { + var thebeInitCells = document.querySelectorAll( + ".thebe-init, .tag_thebe-init" + ); + thebeInitCells.forEach((cell) => { + console.log("Initializing Thebe with cell: " + cell.id); + cell.querySelector(".thebelab-run-button").click(); + }); + } + }); +}; + +/** + * Update the page DOM to use Thebe elements + */ +var modifyDOMForThebe = () => { + // Find all code cells, replace with Thebe interactive code cells + const codeCells = document.querySelectorAll(thebe_selector); + codeCells.forEach((codeCell, index) => { + const codeCellId = (index) => `codecell${index}`; + codeCell.id = codeCellId(index); + codeCellText = codeCell.querySelector(thebe_selector_input); + codeCellOutput = codeCell.querySelector(thebe_selector_output); + + // Clean up the language to make it work w/ CodeMirror and add it to the cell + dataLanguage = detectLanguage(kernelName); + + // Re-arrange the cell and add metadata + if (codeCellText) { + codeCellText.setAttribute("data-language", dataLanguage); + codeCellText.setAttribute("data-executable", "true"); + + // If we had an output, insert it just after the `pre` cell + if (codeCellOutput) { + codeCellOutput.setAttribute("data-output", ""); + codeCellText.insertAdjacentElement('afterend', codeCellOutput); + } + } + + // Remove sphinx-copybutton blocks, which are common in Sphinx + codeCell.querySelectorAll("button.copybtn").forEach((el) => { + el.remove(); + }); + }); +}; + +var initThebe = () => { + // Load thebe dynamically if it's not already loaded + if (typeof thebelab === "undefined") { + console.log("[sphinx-thebe]: Loading thebe from CDN..."); + document.querySelector(".thebe-launch-button ").innerText = "Loading thebe from CDN..."; + + const script = document.createElement("script"); + script.src = `${THEBE_JS_URL}`; + document.head.appendChild(script); + + // Runs once the script has finished loading + script.addEventListener("load", () => { + console.log("[sphinx-thebe]: Finished loading thebe from CDN..."); + configureThebe(); + modifyDOMForThebe(); + thebelab.bootstrap(); + }); + } else { + console.log( + "[sphinx-thebe]: thebe already loaded, not loading from CDN..." + ); + configureThebe(); + modifyDOMForThebe(); + thebelab.bootstrap(); + } +}; + +// Helper function to munge the language name +var detectLanguage = (language) => { + if (language.indexOf("python") > -1) { + language = "python"; + } else if (language === "ir") { + language = "r"; + } + return language; +}; diff --git a/branch/master/_static/sphinx_highlight.js b/branch/master/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/branch/master/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/branch/master/_static/sphinx_lesson.css b/branch/master/_static/sphinx_lesson.css new file mode 100644 index 00000000..68cb32da --- /dev/null +++ b/branch/master/_static/sphinx_lesson.css @@ -0,0 +1,103 @@ +/* sphinx_lesson.css + * https://webaim.org/resources/contrastchecker/?fcolor=00000&bcolor=FCE762 + * */ +:root { + --sphinx-lesson-selection-bg-color: #fce762; + --sphinx-lesson-selection-fg-color: #000000; +} + +/* https://webaim.org/resources/contrastchecker/?fcolor=FFFFFF&bcolor=745315 + * when dark theme is selected the some themes use this attirbute + */ +html[data-theme='dark'], body[data-theme='dark'] { + --sphinx-lesson-selection-bg-color: #745315; + --sphinx-lesson-selection-fg-color: #ffffff; +} + +/* when browser/system theme is dark and no theme is selected */ +@media (prefers-color-scheme: dark) { + html[data-theme='auto'], body[data-theme='auto'] { + --sphinx-lesson-selection-bg-color: #745315; + --sphinx-lesson-selection-fg-color: #ffffff; + } +} + +body.wy-body-for-nav img.with-border { + border: 2px solid; +} + +.rst-content .admonition-no-content { + padding-bottom: 0px; +} + +.rst-content .demo > .admonition-title::before { + content: "\01F440"; /* Eyes */ } +.rst-content .type-along > .admonition-title::before { + content: "\02328\0FE0F"; /* Keyboard */ } +.rst-content .exercise > .admonition-title::before { + content: "\0270D\0FE0F"; /* Hand */ } +.rst-content .solution > .admonition-title::before { + content: "\02714\0FE0E"; /* Check mark */ } +.rst-content .homework > .admonition-title::before { + content: "\01F4DD"; /* Memo */ } +.rst-content .discussion > .admonition-title::before { + content: "\01F4AC"; /* Speech balloon */ } +.rst-content .questions > .admonition-title::before { + content: "\02753\0FE0E"; /* Question mark */ } +.rst-content .prerequisites > .admonition-title::before { + content: "\02699"; /* Gear */ } +.rst-content .seealso > .admonition-title::before { + content: "\027A1\0FE0E"; /* Question mark */ } + + +/* instructor-note */ +.rst-content .instructor-note { + background: #e7e7e7; +} +.rst-content .instructor-note > .admonition-title { + background: #6a6a6a; +} +.rst-content .instructor-note > .admonition-title::before { + content: ""; +} + + +/* sphinx_toggle_button, make the font white */ +.rst-content .toggle.admonition button.toggle-button { + color: white; +} + +/* sphinx-togglebutton, remove underflow when toggled to hidden mode */ +.rst-content .admonition.toggle-hidden { + padding-bottom: 0px; +} + +/* selection / highlight colour uses a yellow background and a black text */ +/*** Works on common browsers ***/ +::selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/*** Mozilla based browsers ***/ +::-moz-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/***For Other Browsers ***/ +::-o-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +::-ms-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/*** For Webkit ***/ +::-webkit-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} diff --git a/branch/master/_static/sphinx_rtd_theme_ext_color_contrast.css b/branch/master/_static/sphinx_rtd_theme_ext_color_contrast.css new file mode 100644 index 00000000..e68feb82 --- /dev/null +++ b/branch/master/_static/sphinx_rtd_theme_ext_color_contrast.css @@ -0,0 +1,47 @@ +/* The following are for web accessibility of sphinx_rtd_theme: they + * solve some of the most frequent contrast issues. Remove when this + * solved: + * https://github.com/readthedocs/sphinx_rtd_theme/issues/971 + */ +/* background: #fcfcfc, note boxes #E7F2FA */ +a { color: #2573A7; } /* original #2980B9, #1F5C84; */ +body { color: #242424; } /* original #404040, #383838 */ +.wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a { + color: #ffffff; +} /* original #fcfcfc */ +footer { color: #737373; } /* original gray=#808080*/ +footer span.commit code, footer span.commit .rst-content tt, .rst-content footer span.commit tt { + color: #737373; +} /* original gray=#808080*/ +.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal { + color: #AB2314; +} +/* Sidebar background */ +.wy-side-nav-search { background-color: #277CB4;} + +/* Same, but for pygments */ +.highlight .ch { color: #3E7A89; } /* #! line */ +.highlight .c1 { color: #3E7A89; } /* also comments */ +.highlight .nv { color: #AD3ECC; } /* variable */ +.highlight .gp { color: #B45608; } /* prompt character, $*/ +.highlight .si { color: #3975B1; } /* ${} variable text */ +.highlight .nc { color: #0C78A7; } + +/* Sphinx admonitions */ +/* warning */ +.wy-alert.wy-alert-warning .wy-alert-title, .rst-content .wy-alert-warning.note .wy-alert-title, .rst-content .attention .wy-alert-title, .rst-content .caution .wy-alert-title, .rst-content .wy-alert-warning.danger .wy-alert-title, .rst-content .wy-alert-warning.error .wy-alert-title, .rst-content .wy-alert-warning.hint .wy-alert-title, .rst-content .wy-alert-warning.important .wy-alert-title, .rst-content .wy-alert-warning.tip .wy-alert-title, .rst-content .warning .wy-alert-title, .rst-content .wy-alert-warning.seealso .wy-alert-title, .rst-content .admonition-todo .wy-alert-title, .rst-content .wy-alert-warning.admonition .wy-alert-title, .wy-alert.wy-alert-warning .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-warning .admonition-title, .rst-content .wy-alert-warning.note .admonition-title, .rst-content .attention .admonition-title, .rst-content .caution .admonition-title, .rst-content .wy-alert-warning.danger .admonition-title, .rst-content .wy-alert-warning.error .admonition-title, .rst-content .wy-alert-warning.hint .admonition-title, .rst-content .wy-alert-warning.important .admonition-title, .rst-content .wy-alert-warning.tip .admonition-title, .rst-content .warning .admonition-title, .rst-content .wy-alert-warning.seealso .admonition-title, .rst-content .admonition-todo .admonition-title, .rst-content .wy-alert-warning.admonition .admonition-title { + background: #B15E16; } +/* important */ +.wy-alert.wy-alert-success .wy-alert-title, .rst-content .wy-alert-success.note .wy-alert-title, .rst-content .wy-alert-success.attention .wy-alert-title, .rst-content .wy-alert-success.caution .wy-alert-title, .rst-content .wy-alert-success.danger .wy-alert-title, .rst-content .wy-alert-success.error .wy-alert-title, .rst-content .hint .wy-alert-title, .rst-content .important .wy-alert-title, .rst-content .tip .wy-alert-title, .rst-content .wy-alert-success.warning .wy-alert-title, .rst-content .wy-alert-success.seealso .wy-alert-title, .rst-content .wy-alert-success.admonition-todo .wy-alert-title, .rst-content .wy-alert-success.admonition .wy-alert-title, .wy-alert.wy-alert-success .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-success .admonition-title, .rst-content .wy-alert-success.note .admonition-title, .rst-content .wy-alert-success.attention .admonition-title, .rst-content .wy-alert-success.caution .admonition-title, .rst-content .wy-alert-success.danger .admonition-title, .rst-content .wy-alert-success.error .admonition-title, .rst-content .hint .admonition-title, .rst-content .important .admonition-title, .rst-content .tip .admonition-title, .rst-content .wy-alert-success.warning .admonition-title, .rst-content .wy-alert-success.seealso .admonition-title, .rst-content .wy-alert-success.admonition-todo .admonition-title, .rst-content .wy-alert-success.admonition .admonition-title { + background: #12826C; } +/* seealso, note, etc */ +.wy-alert.wy-alert-info .wy-alert-title, .rst-content .note .wy-alert-title, .rst-content .wy-alert-info.attention .wy-alert-title, .rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error .wy-alert-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content .wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .seealso .wy-alert-title, .rst-content .wy-alert-info.admonition-todo .wy-alert-title, .rst-content .wy-alert-info.admonition .wy-alert-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-info .admonition-title, .rst-content .note .admonition-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.caution .admonition-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content .wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.tip .admonition-title, .rst-content .wy-alert-info.warning .admonition-title, .rst-content .seealso .admonition-title, .rst-content .wy-alert-info.admonition-todo .admonition-title, .rst-content .wy-alert-info.admonition .admonition-title { + background: #277CB4; } +/* error, danger */ +.rst-content .danger .admonition-title, .rst-content .danger .wy-alert-title, .rst-content .error .admonition-title, .rst-content .error .wy-alert-title, .rst-content .wy-alert-danger.admonition-todo .admonition-title, .rst-content .wy-alert-danger.admonition-todo .wy-alert-title, .rst-content .wy-alert-danger.admonition .admonition-title, .rst-content .wy-alert-danger.admonition .wy-alert-title, .rst-content .wy-alert-danger.attention .admonition-title, .rst-content .wy-alert-danger.attention .wy-alert-title, .rst-content .wy-alert-danger.caution .admonition-title, .rst-content .wy-alert-danger.caution .wy-alert-title, .rst-content .wy-alert-danger.hint .admonition-title, .rst-content .wy-alert-danger.hint .wy-alert-title, .rst-content .wy-alert-danger.important .admonition-title, .rst-content .wy-alert-danger.important .wy-alert-title, .rst-content .wy-alert-danger.note .admonition-title, .rst-content .wy-alert-danger.note .wy-alert-title, .rst-content .wy-alert-danger.seealso .admonition-title, .rst-content .wy-alert-danger.seealso .wy-alert-title, .rst-content .wy-alert-danger.tip .admonition-title, .rst-content .wy-alert-danger.tip .wy-alert-title, .rst-content .wy-alert-danger.warning .admonition-title, .rst-content .wy-alert-danger.warning .wy-alert-title, .rst-content .wy-alert.wy-alert-danger .admonition-title, .wy-alert.wy-alert-danger .rst-content .admonition-title, .wy-alert.wy-alert-danger .wy-alert-title { + background: #e31704; +} + +/* Generic admonition titles */ +.wy-alert-title, .rst-content .admonition-title { + background: #277CB4; } diff --git a/branch/master/_static/tabs.css b/branch/master/_static/tabs.css new file mode 100644 index 00000000..957ba60d --- /dev/null +++ b/branch/master/_static/tabs.css @@ -0,0 +1,89 @@ +.sphinx-tabs { + margin-bottom: 1rem; +} + +[role="tablist"] { + border-bottom: 1px solid #a0b3bf; +} + +.sphinx-tabs-tab { + position: relative; + font-family: Lato,'Helvetica Neue',Arial,Helvetica,sans-serif; + color: #1D5C87; + line-height: 24px; + margin: 0; + font-size: 16px; + font-weight: 400; + background-color: rgba(255, 255, 255, 0); + border-radius: 5px 5px 0 0; + border: 0; + padding: 1rem 1.5rem; + margin-bottom: 0; +} + +.sphinx-tabs-tab[aria-selected="true"] { + font-weight: 700; + border: 1px solid #a0b3bf; + border-bottom: 1px solid white; + margin: -1px; + background-color: white; +} + +.sphinx-tabs-tab:focus { + z-index: 1; + outline-offset: 1px; +} + +.sphinx-tabs-panel { + position: relative; + padding: 1rem; + border: 1px solid #a0b3bf; + margin: 0px -1px -1px -1px; + border-radius: 0 0 5px 5px; + border-top: 0; + background: white; +} + +.sphinx-tabs-panel.code-tab { + padding: 0.4rem; +} + +.sphinx-tab img { + margin-bottom: 24 px; +} + +/* Dark theme preference styling */ + +@media (prefers-color-scheme: dark) { + body[data-theme="auto"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); + } + + body[data-theme="auto"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); + } + + body[data-theme="auto"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 1px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); + } +} + +/* Explicit dark theme styling */ + +body[data-theme="dark"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); +} + +body[data-theme="dark"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); +} + +body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 2px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); +} diff --git a/branch/master/_static/tabs.js b/branch/master/_static/tabs.js new file mode 100644 index 00000000..48dc303c --- /dev/null +++ b/branch/master/_static/tabs.js @@ -0,0 +1,145 @@ +try { + var session = window.sessionStorage || {}; +} catch (e) { + var session = {}; +} + +window.addEventListener("DOMContentLoaded", () => { + const allTabs = document.querySelectorAll('.sphinx-tabs-tab'); + const tabLists = document.querySelectorAll('[role="tablist"]'); + + allTabs.forEach(tab => { + tab.addEventListener("click", changeTabs); + }); + + tabLists.forEach(tabList => { + tabList.addEventListener("keydown", keyTabs); + }); + + // Restore group tab selection from session + const lastSelected = session.getItem('sphinx-tabs-last-selected'); + if (lastSelected != null) selectNamedTabs(lastSelected); +}); + +/** + * Key focus left and right between sibling elements using arrows + * @param {Node} e the element in focus when key was pressed + */ +function keyTabs(e) { + const tab = e.target; + let nextTab = null; + if (e.keyCode === 39 || e.keyCode === 37) { + tab.setAttribute("tabindex", -1); + // Move right + if (e.keyCode === 39) { + nextTab = tab.nextElementSibling; + if (nextTab === null) { + nextTab = tab.parentNode.firstElementChild; + } + // Move left + } else if (e.keyCode === 37) { + nextTab = tab.previousElementSibling; + if (nextTab === null) { + nextTab = tab.parentNode.lastElementChild; + } + } + } + + if (nextTab !== null) { + nextTab.setAttribute("tabindex", 0); + nextTab.focus(); + } +} + +/** + * Select or deselect clicked tab. If a group tab + * is selected, also select tab in other tabLists. + * @param {Node} e the element that was clicked + */ +function changeTabs(e) { + // Use this instead of the element that was clicked, in case it's a child + const notSelected = this.getAttribute("aria-selected") === "false"; + const positionBefore = this.parentNode.getBoundingClientRect().top; + const notClosable = !this.parentNode.classList.contains("closeable"); + + deselectTabList(this); + + if (notSelected || notClosable) { + selectTab(this); + const name = this.getAttribute("name"); + selectNamedTabs(name, this.id); + + if (this.classList.contains("group-tab")) { + // Persist during session + session.setItem('sphinx-tabs-last-selected', name); + } + } + + const positionAfter = this.parentNode.getBoundingClientRect().top; + const positionDelta = positionAfter - positionBefore; + // Scroll to offset content resizing + window.scrollTo(0, window.scrollY + positionDelta); +} + +/** + * Select tab and show associated panel. + * @param {Node} tab tab to select + */ +function selectTab(tab) { + tab.setAttribute("aria-selected", true); + + // Show the associated panel + document + .getElementById(tab.getAttribute("aria-controls")) + .removeAttribute("hidden"); +} + +/** + * Hide the panels associated with all tabs within the + * tablist containing this tab. + * @param {Node} tab a tab within the tablist to deselect + */ +function deselectTabList(tab) { + const parent = tab.parentNode; + const grandparent = parent.parentNode; + + Array.from(parent.children) + .forEach(t => t.setAttribute("aria-selected", false)); + + Array.from(grandparent.children) + .slice(1) // Skip tablist + .forEach(panel => panel.setAttribute("hidden", true)); +} + +/** + * Select grouped tabs with the same name, but no the tab + * with the given id. + * @param {Node} name name of grouped tab to be selected + * @param {Node} clickedId id of clicked tab + */ +function selectNamedTabs(name, clickedId=null) { + const groupedTabs = document.querySelectorAll(`.sphinx-tabs-tab[name="${name}"]`); + const tabLists = Array.from(groupedTabs).map(tab => tab.parentNode); + + tabLists + .forEach(tabList => { + // Don't want to change the tabList containing the clicked tab + const clickedTab = tabList.querySelector(`[id="${clickedId}"]`); + if (clickedTab === null ) { + // Select first tab with matching name + const tab = tabList.querySelector(`.sphinx-tabs-tab[name="${name}"]`); + deselectTabList(tab); + selectTab(tab); + } + }) +} + +if (typeof exports === 'undefined') { + exports = {}; +} + +exports.keyTabs = keyTabs; +exports.changeTabs = changeTabs; +exports.selectTab = selectTab; +exports.deselectTabList = deselectTabList; +exports.selectNamedTabs = selectNamedTabs; diff --git a/branch/master/_static/term_role_formatting.css b/branch/master/_static/term_role_formatting.css new file mode 100644 index 00000000..0b66095c --- /dev/null +++ b/branch/master/_static/term_role_formatting.css @@ -0,0 +1,4 @@ +/* Make terms bold */ +a.reference span.std-term { + font-weight: bold; +} diff --git a/branch/master/_static/togglebutton.css b/branch/master/_static/togglebutton.css new file mode 100644 index 00000000..54a67879 --- /dev/null +++ b/branch/master/_static/togglebutton.css @@ -0,0 +1,160 @@ +/** + * Admonition-based toggles + */ + +/* Visibility of the target */ +.admonition.toggle .admonition-title ~ * { + transition: opacity .3s, height .3s; +} + +/* Toggle buttons inside admonitions so we see the title */ +.admonition.toggle { + position: relative; +} + +/* Titles should cut off earlier to avoid overlapping w/ button */ +.admonition.toggle .admonition-title { + padding-right: 25%; + cursor: pointer; +} + +/* Hovering will cause a slight shift in color to make it feel interactive */ +.admonition.toggle .admonition-title:hover { + box-shadow: inset 0 0 0px 20px rgb(0 0 0 / 1%); +} + +/* Hovering will cause a slight shift in color to make it feel interactive */ +.admonition.toggle .admonition-title:active { + box-shadow: inset 0 0 0px 20px rgb(0 0 0 / 3%); +} + +/* Remove extra whitespace below the admonition title when hidden */ +.admonition.toggle-hidden { + padding-bottom: 0; +} + +.admonition.toggle-hidden .admonition-title { + margin-bottom: 0; +} + +/* hides all the content of a page until de-toggled */ +.admonition.toggle-hidden .admonition-title ~ * { + height: 0; + margin: 0; + opacity: 0; + visibility: hidden; +} + +/* General button style and position*/ +button.toggle-button { + /** + * Background and shape. By default there's no background + * but users can style as they wish + */ + background: none; + border: none; + outline: none; + + /* Positioning just inside the admonition title */ + position: absolute; + right: 0.5em; + padding: 0px; + border: none; + outline: none; +} + +/* Display the toggle hint on wide screens */ +@media (min-width: 768px) { + button.toggle-button.toggle-button-hidden:before { + content: attr(data-toggle-hint); /* This will be filled in by JS */ + font-size: .8em; + align-self: center; + } +} + +/* Icon behavior */ +.tb-icon { + transition: transform .2s ease-out; + height: 1.5em; + width: 1.5em; + stroke: currentColor; /* So that we inherit the color of other text */ +} + +/* The icon should point right when closed, down when open. */ +/* Open */ +.admonition.toggle button .tb-icon { + transform: rotate(90deg); +} + +/* Closed */ +.admonition.toggle button.toggle-button-hidden .tb-icon { + transform: rotate(0deg); +} + +/* With details toggles, we don't rotate the icon so it points right */ +details.toggle-details .tb-icon { + height: 1.4em; + width: 1.4em; + margin-top: 0.1em; /* To center the button vertically */ +} + + +/** + * Details-based toggles. + * In this case, we wrap elements with `.toggle` in a details block. + */ + +/* Details blocks */ +details.toggle-details { + margin: 1em 0; +} + + +details.toggle-details summary { + display: flex; + align-items: center; + cursor: pointer; + list-style: none; + border-radius: .2em; + border-left: 3px solid #1976d2; + background-color: rgb(204 204 204 / 10%); + padding: 0.2em 0.7em 0.3em 0.5em; /* Less padding on left because the SVG has left margin */ + font-size: 0.9em; +} + +details.toggle-details summary:hover { + background-color: rgb(204 204 204 / 20%); +} + +details.toggle-details summary:active { + background: rgb(204 204 204 / 28%); +} + +.toggle-details__summary-text { + margin-left: 0.2em; +} + +details.toggle-details[open] summary { + margin-bottom: .5em; +} + +details.toggle-details[open] summary .tb-icon { + transform: rotate(90deg); +} + +details.toggle-details[open] summary ~ * { + animation: toggle-fade-in .3s ease-out; +} + +@keyframes toggle-fade-in { + from {opacity: 0%;} + to {opacity: 100%;} +} + +/* Print rules - we hide all toggle button elements at print */ +@media print { + /* Always hide the summary so the button doesn't show up */ + details.toggle-details summary { + display: none; + } +} \ No newline at end of file diff --git a/branch/master/_static/togglebutton.js b/branch/master/_static/togglebutton.js new file mode 100644 index 00000000..215a7eef --- /dev/null +++ b/branch/master/_static/togglebutton.js @@ -0,0 +1,187 @@ +/** + * Add Toggle Buttons to elements + */ + +let toggleChevron = ` + + + +`; + +var initToggleItems = () => { + var itemsToToggle = document.querySelectorAll(togglebuttonSelector); + console.log(`[togglebutton]: Adding toggle buttons to ${itemsToToggle.length} items`) + // Add the button to each admonition and hook up a callback to toggle visibility + itemsToToggle.forEach((item, index) => { + if (item.classList.contains("admonition")) { + // If it's an admonition block, then we'll add a button inside + // Generate unique IDs for this item + var toggleID = `toggle-${index}`; + var buttonID = `button-${toggleID}`; + + item.setAttribute('id', toggleID); + if (!item.classList.contains("toggle")){ + item.classList.add("toggle"); + } + // This is the button that will be added to each item to trigger the toggle + var collapseButton = ` + `; + + title = item.querySelector(".admonition-title") + title.insertAdjacentHTML("beforeend", collapseButton); + thisButton = document.getElementById(buttonID); + + // Add click handlers for the button + admonition title (if admonition) + admonitionTitle = document.querySelector(`#${toggleID} > .admonition-title`) + if (admonitionTitle) { + // If an admonition, then make the whole title block clickable + admonitionTitle.addEventListener('click', toggleClickHandler); + admonitionTitle.dataset.target = toggleID + admonitionTitle.dataset.button = buttonID + } else { + // If not an admonition then we'll listen for the button click + thisButton.addEventListener('click', toggleClickHandler); + } + + // Now hide the item for this toggle button unless explicitly noted to show + if (!item.classList.contains("toggle-shown")) { + toggleHidden(thisButton); + } + } else { + // If not an admonition, wrap the block in a
block + // Define the structure of the details block and insert it as a sibling + var detailsBlock = ` +
+ + ${toggleChevron} + ${toggleHintShow} + +
`; + item.insertAdjacentHTML("beforebegin", detailsBlock); + + // Now move the toggle-able content inside of the details block + details = item.previousElementSibling + details.appendChild(item) + item.classList.add("toggle-details__container") + + // Set up a click trigger to change the text as needed + details.addEventListener('click', (click) => { + let parent = click.target.parentElement; + if (parent.tagName.toLowerCase() == "details") { + summary = parent.querySelector("summary"); + details = parent; + } else { + summary = parent; + details = parent.parentElement; + } + // Update the inner text for the proper hint + if (details.open) { + summary.querySelector("span.toggle-details__summary-text").innerText = toggleHintShow; + } else { + summary.querySelector("span.toggle-details__summary-text").innerText = toggleHintHide; + } + + }); + + // If we have a toggle-shown class, open details block should be open + if (item.classList.contains("toggle-shown")) { + details.click(); + } + } + }) +}; + +// This should simply add / remove the collapsed class and change the button text +var toggleHidden = (button) => { + target = button.dataset['target'] + var itemToToggle = document.getElementById(target); + if (itemToToggle.classList.contains("toggle-hidden")) { + itemToToggle.classList.remove("toggle-hidden"); + button.classList.remove("toggle-button-hidden"); + } else { + itemToToggle.classList.add("toggle-hidden"); + button.classList.add("toggle-button-hidden"); + } +} + +var toggleClickHandler = (click) => { + // Be cause the admonition title is clickable and extends to the whole admonition + // We only look for a click event on this title to trigger the toggle. + + if (click.target.classList.contains("admonition-title")) { + button = click.target.querySelector(".toggle-button"); + } else if (click.target.classList.contains("tb-icon")) { + // We've clicked the icon and need to search up one parent for the button + button = click.target.parentElement; + } else if (click.target.tagName == "polyline") { + // We've clicked the SVG elements inside the button, need to up 2 layers + button = click.target.parentElement.parentElement; + } else if (click.target.classList.contains("toggle-button")) { + // We've clicked the button itself and so don't need to do anything + button = click.target; + } else { + console.log(`[togglebutton]: Couldn't find button for ${click.target}`) + } + target = document.getElementById(button.dataset['button']); + toggleHidden(target); +} + +// If we want to blanket-add toggle classes to certain cells +var addToggleToSelector = () => { + const selector = ""; + if (selector.length > 0) { + document.querySelectorAll(selector).forEach((item) => { + item.classList.add("toggle"); + }) + } +} + +// Helper function to run when the DOM is finished +const sphinxToggleRunWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} +sphinxToggleRunWhenDOMLoaded(addToggleToSelector) +sphinxToggleRunWhenDOMLoaded(initToggleItems) + +/** Toggle details blocks to be open when printing */ +if (toggleOpenOnPrint == "true") { + window.addEventListener("beforeprint", () => { + // Open the details + document.querySelectorAll("details.toggle-details").forEach((el) => { + el.dataset["togglestatus"] = el.open; + el.open = true; + }); + + // Open the admonitions + document.querySelectorAll(".admonition.toggle.toggle-hidden").forEach((el) => { + console.log(el); + el.querySelector("button.toggle-button").click(); + el.dataset["toggle_after_print"] = "true"; + }); + }); + window.addEventListener("afterprint", () => { + // Re-close the details that were closed + document.querySelectorAll("details.toggle-details").forEach((el) => { + el.open = el.dataset["togglestatus"] == "true"; + delete el.dataset["togglestatus"]; + }); + + // Re-close the admonition toggle buttons + document.querySelectorAll(".admonition.toggle").forEach((el) => { + if (el.dataset["toggle_after_print"] == "true") { + el.querySelector("button.toggle-button").click(); + delete el.dataset["toggle_after_print"]; + } + }); + }); +} diff --git a/branch/master/binder/index.html b/branch/master/binder/index.html new file mode 100644 index 00000000..ffd8603f --- /dev/null +++ b/branch/master/binder/index.html @@ -0,0 +1,394 @@ + + + + + + + + + + + + + + + Binder — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Binder

+
+

Questions

+
    +

  • Why sharing code alone may not be sufficient.

    • +

  • How to share a computational environment?

    • +

  • What is Binder?

    • +

  • How to binderize my Python repository?

    • +

  • How to publish my Python repository?

    • +
+
+
+

Objectives

+
    +

  • Learn about reproducible computational environments.

    • +

  • Learn to create and share custom computing environments with Binder.

    • +

  • Learn to get a DOI from Zenodo for a repository.

    • +
+
+
+

Why is it sometimes not enough to share your code?

+../_images/python_unmasked.jpg +
+

Exercise 1

+
+

Binder-1: Discuss better strategies than only code sharing (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+
+
+
+

Sharing a computing environment with Binder

+

Binder allows you to create +custom computing environments that can be shared and used by many remote users. +It uses repo2docker to +create a container image (docker image) of a +project using information contained in included configuration files.

+

Repo2docker is a standalone package that you can install locally on your laptop +but an online Binder service is freely available. +This is what we will be using in the tutorial.

+

The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder.

+https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png +

Credit: Juliette Taka, Logilab and the OpenDreamKit project (2017)

+
+

Binder exercise/demo

+

In an earlier episode (Data visualization with Matplotlib) we have created this notebook:

+
import pandas as pd
+import matplotlib.pyplot as plt
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+data_2007 = data[data["year"] == 2007]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xscale("log")
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
+
+

We will now first share it via GitHub “statically”, +then using Binder.

+
+

Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this. This exercise (and all following) +requires git/GitHub knowledge and accounts, which wasn’t a +prerequisite of this course. Thus, this is a demo (and might even +be too fast for you to type-along). Watch the video if you +are reading this later on:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+
+
+
+

How can I get a DOI from Zenodo?

+

Zenodo is a general purpose open-access +repository built and operated by CERN and OpenAIRE that allows researchers to archive and get a +Digital Object Identifier (DOI) to data that they +share.

+ +
+ +
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/data-formats/index.html b/branch/master/data-formats/index.html new file mode 100644 index 00000000..f95cd87f --- /dev/null +++ b/branch/master/data-formats/index.html @@ -0,0 +1,703 @@ + + + + + + + + + + + + + + + In depth analysis of some selected file formats — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • In depth analysis of some selected file formats
    • +
  • + Edit on GitHub +
    • +
+
+
+
+
+ +
+

In depth analysis of some selected file formats

+

Here is a selection of file formats that are commonly used in data science. They are somewhat ordered by their intended use.

+
+

Storing arbitrary Python objects

+
+

Pickle

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: None (pickle-module is included with Python).

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: 🟨

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ❌! See warning below.

    • +

  • Best use cases: Saving Python objects for debugging.

    • +
+
+
+

Warning

+

Loading pickles that you have not created is +risky as they can contain arbitrary executable code.

+

Do not unpickle objects from sources that you do not trust!

+
+

Pickle is Python’s own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:

+
import pickle
+
+with open('data_array.pickle', 'wb') as f:
+    pickle.dump(data_array, f)
+
+with open('data_array.pickle', 'rb') as f:
+    data_array_pickle = pickle.load(f)
+
+
+
+
+
+

Exercise 1

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+ +
+
+

Storing tidy data

+
+

CSV (comma-separated values)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: numpy, pandas

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data. Small data. Data that needs to be human-readable.

    • +
+
+

CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you’re working with big data.

+

Pandas has a very nice interface for writing and reading CSV files with to_csv- and read_csv-functions:

+
dataset.to_csv('dataset.csv', index=False)
+
+dataset_csv = pd.read_csv('dataset.csv')
+
+
+

Numpy has routines for saving and loading arrays as CSV files as well:

+
np.savetxt('data_array.csv', data_array)
+
+data_array_csv = np.loadtxt('data_array.csv')
+
+
+
+

Storing data in CSVs can reduce data precision

+
+

When working with floating point numbers you should be careful to save the data with enough decimal places so that you won’t lose precision.

+

For example, double-precision floating point numbers have ~16 decimal places of precision, but if you use normal Python to write these numbers, you can easily lose some of that precision. +Let’s consider the following example:

+
import numpy as np
+test_number = np.sqrt(2)
+# Write the number in a file
+test_file = open('sqrt2.csv', 'w')
+test_file.write('%f' % test_number)
+test_file.close()
+# Read the number from a file
+test_file = open('sqrt2.csv', 'r')
+test_number2 = np.float64(test_file.readline())
+test_file.close()
+# Calculate the distance between these numbers
+print(np.abs(test_number - test_number2))
+
+
+

CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. +We can check whether our written data matches the generated data:

+
dataset.compare(dataset_csv)
+
+np.all(data_array == data_array_csv)
+
+
+

In our case some rows of dataset_csv loaded from CSV do not match the original dataset as the last decimal can sometimes be rounded due to complex technical reasons.

+

Storage of these high-precision CSV files is usually very inefficient storage-wise.

+

Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems.

+
+
+
+
+

Feather

+
+

Requires additional packages

+
+

Using Feather requires pyarrow-package to be installed.

+

You can try installing pyarrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Temporary storage of tidy data.

    • +
+
+

Feather is a file format for storing data frames quickly. +There are libraries for Python, R and Julia.

+

We can work with Feather files with to_feather- and read_feather-functions:

+
dataset.to_feather('dataset.feather')
+dataset_feather = pd.read_feather('dataset.feather')
+
+
+

Feather is not a good format for storing array data, so we won’t present an example of that here.

+
+
+

Parquet

+
+

Requires additional packages

+
+

Using Parquet requires pyarrow-package to be installed.

+

You can try installing PyArrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in tidy data format. Archival of said data.

    • +
+
+

Parquet is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.).

+

We can work with Parquet files with to_parquet- and read_parquet-functions:

+
dataset.to_parquet('dataset.parquet')
+dataset_parquet = pd.read_parquet('dataset.parquet')
+
+
+

Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won’t do that here.

+
+
+
+

Exercise 2

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+ +
+
+

Storing array data

+
+

npy (numpy array format)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Saving numpy arrays temporarily.

    • +
+
+

If you want to temporarily store numpy arrays, you can use the numpy.save()- and numpy.load()-functions:

+
np.save('data_array.npy', data_array)
+data_array_npy = np.load('data_array.npy')
+
+
+

There also exists numpy.savez()-function for storing multiple datasets in a single file:

+
np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array)
+data_arrays = np.load('data_arrays.npz')
+data_arrays['data_array0']
+
+
+

For big arrays it’s good idea to check other binary formats such as HDF5 or NetCDF4.

+

np.save- and np.savez-functions work with +sparse matrices, +but one can also use dedicated +scipy.sparse.save_npz- and +scipy.sparse.load_npz-functions. +Storing sparse matrices using these functions can give huge storage savings.

+
+
+

HDF5 (Hierarchical Data Format version 5)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy, pandas, PyTables, h5py

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format.

    • +
+
+

HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences.

+

Pandas allows you to store tables as HDF5 with PyTables, which uses HDF5 to write the files. +You can create a HDF5 file with to_hdf- and read_parquet-functions:

+
dataset.to_hdf('dataset.h5', key='dataset', mode='w')
+dataset_hdf5 = pd.read_hdf('dataset.h5')
+
+
+

For writing data that is not a table, you can use the excellent h5py-package:

+
import h5py
+
+# Writing:
+
+# Open HDF5 file
+h5_file = h5py.File('data_array.h5', 'w')
+# Write dataset
+h5_file.create_dataset('data_array', data=data_array)
+# Close file and write data to disk. Important!
+h5_file.close()
+
+# Reading:
+
+# Open HDF5 file again
+h5_file = h5py.File('data_array.h5', 'r')
+# Read the full dataset
+data_array_h5 = h5_file['data_array'][()]
+# Close file
+h5_file.close()
+
+
+
+
+

NetCDF4 (Network Common Data Form version 4)

+
+

Requires additional packages

+
+

Using NetCDF4 requires netCDF4- or h5netcdf-package to be installed. +h5netcdf is often mentioned as being faster to the official netCDF4-package, so we’ll be using it in the example.

+

A great NetCDF4 interface is provided by a xarray-package.

+

You can try installing these packages with

+
!pip install h5netcdf xarray
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, netCDF4/h5netcdf, xarray

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets.

    • +
+
+

NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs.

+

NetCDF4 is a common format for storing large data from big simulations in physical sciences.

+

Using interface provided by xarray:

+
# Write tidy data as NetCDF4
+dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf')
+# Read tidy data from NetCDF4
+import xarray as xr
+dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf')
+dataset_netcdf4 = dataset_xarray.to_pandas()
+dataset_xarray.close()
+
+
+

Working with array data is easy as well:

+
# Write array data as NetCDF4
+xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf')
+# Read array data from NetCDF4
+data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf')
+data_array_netcdf4 = data_array_xarray.to_numpy()
+data_array_xarray.close()
+
+
+

The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (x, y, z) or timestamps (t) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis.

+
+
+
+

Exercise 3

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+ +
+
+

Other file formats

+
+

JSON (JavaScript Object Notation)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: None (json-module is included with Python).

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Saving nested/relational data, storing web requests.

    • +
+
+

JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.).

+

You rarely want to keep your data in this format, unless you’re working with +nested data with multiple layers or lots of interconnections.

+

Similarly to other popular files, Pandas can write and read json files with to_json()- and read_json()-functions:

+
dataset.to_json('dataset.json')
+dataset_json = pd.read_json('dataset.json')
+
+
+
+
+

Excel

+
+

Requires additional packages

+

Using Excel files with Pandas requires openpyxl-package to be installed.

+
+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: openpyxl

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: 🟨

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data in many fields. Quick data analysis.

    • +
+
+

Excel is very popular in social sciences and economics. +However, it is not a good format for data science.

+

See Pandas’ documentation on working with Excel files.

+
+
+

Graph formats (adjency lists, gt, GraphML etc.)

+
+

Key features

+
    +

  • Type: Many different formats

    • +

  • Packages needed: Depends on a format.

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: 🟨

    • +

  • Best use cases: Saving graphs or data that can be represented as a graph.

    • +
+
+

There are plenty of data formats for storing graphs. +We won’t list them here as optimal data format depends heavily on the graph structure.

+

One can use functions in libraries such as +networkx, +graph-tool, +igraph +to read and write graphs.

+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/dependencies/index.html b/branch/master/dependencies/index.html new file mode 100644 index 00000000..fd3f0d56 --- /dev/null +++ b/branch/master/dependencies/index.html @@ -0,0 +1,859 @@ + + + + + + + + + + + + + + + Dependency management — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Dependency management

+
+

Questions

+
    +

  • Do you expect your code to work in one year? Five? What if it +uses numpy or tensorflow or random-github-package ?

    • +

  • How can my collaborators easily install my code with all the necessary dependencies?

    • +

  • How can I make it easy for my others (and me in future) to reproduce my results?

    • +

  • How can I work on two (or more) projects with different and conflicting dependencies?

    • +
+
+
+

Objectives

+
    +

  • Learn how to record dependencies

    • +

  • Be able to communicate the dependencies as part of a report/thesis/publication

    • +

  • Learn how to use isolated environments for different projects

    • +

  • Simplify the use and reuse of scripts and projects

    • +
+
+
+

How do you track dependencies of your project?

+
    +

  • Dependency: Reliance on a external component. In this case, a +separately installed software package such as numpy.

    • +
+
+
+

Exercise 1

+
+

Dependencies-1: Discuss dependency management (5 min)

+

Please discuss and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+
+
+

PyPI (The Python Package Index) and conda ecosystem

+

PyPI (The Python Package Index) and conda are popular packaging/dependency +management tools:

+
    +

  • When you run pip install you typically install from PyPI, but you can also pip install from a GitHub +repository and similar.

    • +

  • When you run conda install you typically install from Anaconda Cloud where there are conda channels maintained +by Anaconda Inc. and by various communities.

    • +
+

Why are there two ecosystems?

+
+

PyPI

+
    +

  • Installation tool: pip

    • +

  • Summary: PyPI is traditionally used for Python-only packages or +for Python interfaces to external libraries. There are also packages +that have bundled external libraries (such as numpy).

    • +

  • Amount of packages: Huge number. Old versions are supported for +a long time.

    • +

  • How libraries are handled: If your code depends on external +libraries or tools, these things need to be either included in the +pip-package or provided via some other installation system (like +operating system installer or manual installation).

    • +
  • +
    Pros:
      +

    • Easy to use

      • +

    • Package creation is easy

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Installing packages that need external libraries can be complicated

      • +
    +
    +
    +
    • +
+
+
+

Conda

+
    +

  • Installation tool: conda or mamba

    • +

  • Summary: Conda aims to be a more general package distribution tool +and it tries to provide not only the Python packages, but also libraries +and tools needed by the Python packages. Most scientific software written +in Python uses external libraries to speed up calculations and installing +these libraries can often become complicated without conda.

    • +

  • Amount of packages: Curated list of packages in defaults-channel, huge +number in community managed channels. Other packages can be installed via pip.

    • +

  • How libraries are handled: Required libraries are installed as separate +conda packages.

    • +
  • +
    Pros:
      +

    • Quite easy to use

      • +

    • Easier to manage packages that need external libraries

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Package creation is harder

      • +
    +
    +
    +
    • +
+
+
+
+

Conda ecosystem explained

+
+

Warning

+

Anaconda has recently changed its licensing terms, which affects its +use in a professional setting. This caused uproar among academia +and Anaconda modified their position in +this article.

+

Main points of the article are:

+
    +

  • conda (installation tool) and community channels (e.g. conda-forge) +are free to use.

    • +

  • Anaconda repository and Anaconda’s channels in the community repository +are free for universities and companies with fewer than 200 employees. +Non-university research institutions and national laboratories need +licenses.

    • +

  • Miniconda is free, when it does not download Anaconda’s packages.

    • +

  • Miniforge is not related to Anaconda, so it is free.

    • +
+

For ease of use on sharing environment files, we recommend using +Miniforge to create the environments and using conda-forge as the main +channel that provides software.

+
+
    +

  • Package repositories:

    + +
    • +

  • Major package channels:

    +
      +

    • Anaconda’s proprietary channels: main, r, msys2 and anaconda. +These are sometimes called defaults.

      • +

    • conda-forge is the largest open source +community channel. It has over 27,000 packages that include open-source +versions of packages in Anaconda’s channels.

      • +
    +
    • +

  • Package distributions and installers:

    +
      +

    • Anaconda is a distribution of conda packages +made by Anaconda Inc.. When using Anaconda remember to check that your +situation abides with their licensing terms.

      • +

    • Miniconda is a minimal installer +maintained by Anaconda Inc. that has conda and uses Anaconda’s channels +by default. Check licensing terms when using these packages.

      • +

    • Miniforge is an open-source +Miniconda replacement that uses conda-forge as the default channel. +Contains mamba as well.

      • +

    • micromamba +is a tiny stand-alone version of the mamba package manager written in C++. +It can be used to create and manage environments without installing +base-environment and Python. It is very useful if you want to automate +environment creation or want a more lightweight tool.

      • +
    +
    • +

  • Package managers:

    +
      +

    • conda is a package and environment management system +used by Anaconda. It is an open source project maintained by Anaconda Inc..

      • +

    • mamba is a drop in +replacement for conda. It used be much faster than conda due to better +dependency solver but nowadays conda +also uses the same solver. +It still has some UI improvements.

      • +
    +
    • +
+
+
+

Exercise 2

+
+

Dependencies-2: Package language detective (5 min)

+

Think about the following sentences:

+
    +

  1. Yes, you can install my package with pip from GitHub.

    2. +

  2. I forgot to specify my channels, so my packages came from the defaults.

    3. +

  3. I have a Miniforge installation and I use mamba to create my environments.

    4. +
+

What hidden information is given in these sentences?

+ +
+
+
+

Python environments

+

An environment is a basically a folder that contains a Python +interpreter and other Python packages in a folder structure similar +to the operating system’s folder structure.

+

These environments can be created by the +venv-module in base +Python, by a pip package called +virtualenv +or by conda/mamba.

+

Using these environments is highly recommended because they solve the +following problems:

+
    +

  • Installing environments won’t modify system packages.

    • +

  • You can install specific versions of packages into them.

    • +

  • You can create an environment for each project and you won’t encounter any +problems if different projects require different versions of packages.

    • +

  • If you make some mistake and install something you did not want or need, you +can remove the environment and create a new one.

    • +

  • Others can replicate your environment by reusing the same specification +that you used to create the environment.

    • +
+
+
+

Creating Python environments

+
+

Record channels and packages you need to a file called +environment.yml:

+
name: my-environment
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - numpy
+  - matplotlib
+  - pandas
+
+
+

The name describes the name of the environment, +channels-list tells which channels should be search for packages +(channel priority goes from top to bottom) and dependencies-list +contains all packages that are needed.

+

Using this file you can now create an environment with:

+
$ conda env create --file environment.yml
+
+
+
+

You can also use mamba

+

If you have mamba installed, you can replace conda +with mamba in each command.

+
+

You can then activate the environment with:

+
$ conda activate my-environment
+
+
+
+

conda activate versus source activate

+

conda activate will only work if you have run conda init +in the past. Running conda init will make loading environments +easier as you will always have a conda environment loaded.

+

However, this can also cause problems as programs in the +main environment will be constantly loaded and they might be used +even when they’re not supposed to be used. A common example is +not having pip installed in a conda environment which results +pip from main environment to be used instead.

+
+

You can then check e.g. installed versions of Python and numpy:

+
$ python -c 'import sys; import numpy; print(f"Python version: {sys.version}\nNumPy version: {numpy.__version__}")'
+Python version: 3.13.0 | packaged by conda-forge | (main, Oct  8 2024, 20:04:32) [GCC 13.3.0]
+NumPy version: 2.1.2
+
+
+

To deactivate the environment, you can run:

+
$ conda deactivate
+
+
+
+
+

Creating environments without environment.yml/requirements.txt

+

It is possible to create environments with manual commands, but this +is highly discouraged for continuous use.

+

Firstly, replicating the environment becomes much harder.

+

Secondly, running package installation commands manually in an +environment can result in unexpected behaviour such as:

+
    +

  • Package manager might remove an already installed packages or update them.

    • +

  • Package manager might not find a package that works with already +installed packages.

    • +
+

The reason for this behavior is that package managers does not know what +commands you ran in the past. It only knows the state of your environment +and what you’re currently telling it to install.

+

These kinds of problems can be mitigated by recording dependencies in an +environment.yml or requirements.txt and using the relevant +package manager to update / recreate the environment.

+
+
+
+

Exercise 3

+
+

Dependencies-3: Create a Python environment (15 min)

+

Use conda or venv to create the environment presented in the +example.

+
+
+
+

Adding more packages to existing environments

+

Quite often when you’re creating a new environment you might forget +to add all relevant packages to environment.yml or +requirements.txt.

+

In these cases the best practice is to add missing packages to +environment.yml or requirements.txt and to update the environment.

+
+

Add new packages that you want to install to +dependencies in +environment.yml.

+

Afterwards, run

+
$ conda env update --file environment.yml
+
+
+

to update the environment.

+
+

Sometimes the new packages are incompatible with the ones already +in the environment. Maybe they have different dependencies that are +not satisfied with the current versions, maybe the package you’re installing +is incompatible with the ones installed. In these cases the safest approach +is to re-create the environment. This will let the dependency solvers +to start from clean slate and with a full picture of what packages +need to be installed.

+
+
+

Pinning package versions

+

Sometimes your code will only work with a certain range of dependencies. +Maybe you use a function or a class that was introduced in a later version +or a newer version has modified its API.

+

In these situations, you’ll want to pin the package versions.

+

For example, there is usually a delay between doing research and that +research being published. During this time packages used in the research +might update and reviewers or interested researchers might not be able +to replicate your results or run your code if new versions are not +compatible.

+
+

When pinning versions in environment.yml one can use a +variety of comparison operators:

+
name: my-environment
+channels:
+  - conda-forge
+dependencies:
+  # Use python 3.11
+  - python=3.11
+  # numpy that is bigger or equal than version 1, but less than version 2
+  - numpy>=1,<2
+  # matplotlib greater than 3.8.2
+  - matplotlib>3.8.2
+  # pandas that is compatible with 2.1
+  - pandas~=2.1
+
+
+
+

For more information on all possible specifications, see +this page +from Python’s packaging guide.

+

See also: https://coderefinery.github.io/reproducible-research/dependencies/

+
+

To pin or not to pin? That is the question.

+

Pinning versions means that you pin the environment to +that instance in time when these specific versions of the +dependencies were being used.

+

This can be good for single-use applications, like replicating a research +paper, but it is usually bad for the long-term maintainability of the software.

+

Pinning to major versions or to compatible versions is usually the best +practice as that allows your software to co-exist with other packages even +when they are updated.

+

Remember that at some point in time you will face a situation where +newer versions of the dependencies are no longer compatible with your +software. At this point you’ll have to update your software to use the newer +versions or to lock it into a place in time.

+
+
+
+

Exporting package versions from an existing environment

+

Sometimes you want to create a file that contains the exact versions +of packages in the environment. This is often called exporting or +freezing and environment.

+

Doing this will create a file that does describe the installed +packages, but it won’t tell which packages are the most important +ones and which ones are just dependencies for those packages.

+

Using manually created environment.yml or requirements.txt +are in most cases better than automatically created ones because they +shows which packages are the important packages needed by the software.

+
+

Once you have activated the environment, you can run

+
$ conda env export > environment.yml
+
+
+

If package build versions are not relevant for the use case, +one can also run

+
$ conda env export --no-builds > environment.yml
+
+
+

which leaves out the package build versions.

+

Alternatively one can also run

+
$ conda env export --from-history > environment.yml
+
+
+

which creates the environment.yml-file based on +what packages were asked to be installed.

+
+

conda-lock

+

For even more reproducibility, you should try out +conda-lock. +It turns your environment.yml into a conda.lock +that has all information needed to exactly create +the same environment. You can use conda.lock-files +in same way as environment.yml when you create +an environment:

+
$ conda env create --file conda.lock
+
+
+
+
+
+
+

Exercise 4

+
+

Dependencies-4: Export an environment (15 min)

+

Export the environment you previously created.

+
+
+
+

Additional tips and tricks

+
+
+

conda supports installing an environment from requirements.txt.

+
$ conda env create --name my-environment --channel conda-forge --file requirements.txt
+
+
+

To create an environment.yml from this environment that mimics +the requirements.txt, activate it and run

+
+
$ conda env export --from-history > environment.yml
+
+
+
+
+
+

How to communicate the dependencies as part of a report/thesis/publication

+

Each notebook or script or project which depends on libraries should come with +either a requirements.txt or a environment.yml, unless you are creating +and distributing this project as Python package (see next section).

+
    +

  • Attach a requirements.txt or a environment.yml to your thesis.

    • +

  • Even better: put requirements.txt or a environment.yml in your Git repository along your code.

    • +

  • Even better: also binderize your analysis pipeline (more about that in a later session).

    • +
+
+
+

Version pinning for package creators

+

We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in pyproject.toml (or setup.py) +(PyPI) or meta.yaml (conda).

+

These dependencies will then be used by either other libraries (who in turn +write their own setup.py or pyproject.toml or meta.yaml) or by +people directly (filling out requirements.txt or a environment.yml).

+

Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from setup.py):

+
# ...
+install_requires=[
+   'numpy==1.19.2',
+   'matplotlib==3.3.2'
+   'pandas==1.1.2'
+   'scipy==1.5.2'
+]
+# ...
+
+
+

or you can define a range or keep them undefined like here (example taken from +setup.py):

+
# ...
+install_requires=[
+   'numpy',
+   'matplotlib'
+   'pandas'
+   'scipy'
+]
+# ...
+
+
+

Should we pin the versions here or not?

+
    +

  • Pinning versions here would be good for reproducibility.

    • +

  • However pinning versions may make it difficult for this library to be used in a project alongside other +libraries with conflicting version dependencies.

    • +

  • Therefore as library creator make the version requirements as wide as possible.

    +
      +

    • Set minimum version when you know of a reason: >=2.1

      • +

    • Sometimes set maximum version to next major version (<4) (when +you currently use 3.x.y) when you expect issues with next +major version.

      • +
    +
    • +

  • As the “end consumer” of libraries, define your dependencies as narrowly as possible.

    • +
+
+
+

See also

+

Other tools for dependency management:

+
    +

  • Poetry: dependency management and packaging

    • +

  • Pipenv: dependency management, alternative to Poetry

    • +

  • pyenv: if you need different Python versions for different projects

    • +

  • micropipenv: lightweight tool to “rule them all”

    • +

  • mamba: a drop in replacement for +conda that does installations faster.

    • +

  • miniforge: Miniconda alternative with +conda-forge as the default channel and optionally mamba as the default installer.

    • +

  • micromamba: +tiny version of Mamba as a static C++ executable. Does not need base environment or +Python for installing an environment.

    • +

  • pixi: a package management tool which builds upon the foundation of the conda ecosystem.

    • +
+

Other resources:

+ +
+

Keypoints

+
    +

  • If somebody asks you what dependencies your code has, you should be able to answer this question with a file.

    • +

  • Install dependencies by first recording them in requirements.txt or +environment.yml and install using these files, then you have a trace.

    • +

  • Use isolated environments and avoid installing packages system-wide.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/exercises/index.html b/branch/master/exercises/index.html new file mode 100644 index 00000000..97cf65be --- /dev/null +++ b/branch/master/exercises/index.html @@ -0,0 +1,2267 @@ + + + + + + + + + + + + + + + List of exercises — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

List of exercises

+
+

Full list

+

This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests.

+
+

Jupyter

+

In jupyter.ipynb:

+
+

Exercises: Jupyter-1

+

If you aren’t set up with JupyterLab yet or these things don’t work, use this time to see the installation instructions and ask us any questions you may have.

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are using Miniforge from the command line, you can navigate with cd to a directory of your choice.

      • +

    • If you are starting from the Anaconda Navigator, change to the directory you want to use.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+

In jupyter.ipynb:

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+

In jupyter.ipynb:

+ +

In jupyter.ipynb:

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

NumPy

+

In numpy.rst:

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-2

+ +
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+

In numpy.rst:

+ +
+
+

Advanced NumPy

+

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lesson before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+

In numpy-advanced.rst:

+ +
+
+

Pandas

+

In pandas.rst:

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+

In pandas.rst:

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+

In pandas.rst:

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries (you need to look at the +data and find how countries are written, and replace COUNTRY +with those strings):

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Xarray

+

In xarray.rst:

+
+

Exercises: Xarray-1

+

Download the NARR_19930313_0000.nc dataset have a look at all Data variables. Calculate the geopotential height at x=5148.3726 averaged over y and return the median value. You can use the .plot() method to check on the way whether you use the correct dimensions and indices.

+
+

In xarray.rst:

+ +

In xarray.rst:

+
+

Exercises: Xarray-2

+

Let’s change from climate science to finance for this example. Put the stock prices and trading volumes of three companies over ten days in one dataset. Create an Xarray Dataset that uses time and company as dimensions and contains two DataArrays: stock_price and trading_volume. You can choose the values for the stock prices and trading volumes yourself. As a last thing, add the currency of the stock prices as an attribute to the Dataset.

+
+

In xarray.rst:

+ +
+
+

Plotting with Matplotlib

+

In plotting-matplotlib.md:

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y * 2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset. +You can also consult this great +quick start guide.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +

  • Experiment also by using named colors (e.g. “red”) instead of the hex-codes.

    • +
+
+

In plotting-matplotlib.md:

+ +

In plotting-matplotlib.md:

+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = (
+    "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+)
+gapminder_data = pd.read_csv(url).query("year == 2007")
+
+gapminder_data
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP per capita (PPP dollars)")
+ax.set_ylabel("Life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+

In plotting-matplotlib.md:

+ +

In plotting-matplotlib.md:

+
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+

In plotting-matplotlib.md:

+ +
+
+

Plotting with Vega-Altair

+

In plotting-vega-altair.md:

+
+

Plotting-1: Using visual channels to re-arrange plots

+
    +

  1. Try to reproduce the above plots if they are not already in your notebook.

    2. +

  2. Above we have plotted the monthly precipitation for two cities side by side +using a stacked plot. Try to arrive at the following plot where months are +along the y-axis and the precipitation amount is along the x-axis:

    +
    +../_images/precipitation-stacked-y.svg +
    +
    3. +

  3. Ask the Internet or AI how to change the axis title from “precipitation” +to “Precipitation (mm)”.

    4. +

  4. Modify the temperature range plot to show the temperature ranges for the +two cities side by side like this:

    +
    +../_images/temperature-ranges-side.svg +
    +
    5. +
+ +
+

In plotting-vega-altair.md:

+ +
+
+

Working with Data

+

In work-with-data.rst:

+
+

Exercise

+

You have a model that you have been training for a while. +Lets assume it’s a relatively simple neural network (consisting of a +network structure and it’s associated weights).

+

Let’s consider 2 scenarios

+

A: You have a different project, that is supposed to take this model, and +do some processing with it to determine it’s efficiency after different +times of training.

+

B: You want to publish the model and make it available to others.

+

What are good options to store the model in each of these scenarios?

+
+

In work-with-data.rst:

+ +
+
+

Scripts

+

In scripts.rst:

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Hint: Copy the URL above (right-click) and in JupyterLab, use +File → Open from URL → Paste the URL. It will both download it to +the directory JupyterLab is in and open it for you.

    +
    2. +

  2. Open a terminal in Jupyter: File → New Launcher, then click +“Terminal” there. (if you do it this way, it will be in the right +directory. File → New → Terminal might not be.)

    3. +

  3. Convert the Jupyter script to a Python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+

In scripts.rst:

+
+

Scripts-2

+
    +

  1. Take the Python script (weather_observations.py) we have written in the preceding exercise and use +argparse to specify the input (URL) and output files and allow the start and end dates to be set.

    +
      +

    • Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on.

      • +

    • Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output.

      • +

    • Hint: The start and end dates should be optional parameters with the defaults as they are in the current script.

      • +
    +
    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). +Also try using this data for Cairo: https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv

    3. +
+
+

In scripts.rst:

+ +

In scripts.rst:

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+

In scripts.rst:

+ +
+
+

Profiling

+

In profiling.md:

+
+

Exercise: Practicing profiling

+

In this exercise we will use the Scalene profiler to find out where most of the time is spent +and most of the memory is used in a given code example.

+

Please try to go through the exercise in the following steps:

+
    +

  1. Make sure scalene is installed in your environment (if you have followed +this course from the start and installed the recommended software +environment, then it is).

    2. +

  2. Download Leo Tolstoy’s “War and Peace” from the following link (the text is +provided by Project Gutenberg): +https://www.gutenberg.org/cache/epub/2600/pg2600.txt +(right-click and “save as” to download the file and save it as “book.txt”).

    3. +

  3. Before you run the profiler, try to predict in which function the code +will spend most of the time and in which function it will use most of the +memory.

    4. +

  4. Run the scalene profiler on the following code example and browse the +generated HTML report to find out where most of the time is spent and where +most of the memory is used:

    +
    $ scalene example.py
+
    +
    +

    Alternatively you can do this (and then open the generated file in a browser):

    +
    $ scalene example.py --html > profile.html
+
    +
    +

    You can find an example of the generated HTML report in the solution below.

    +
    5. +

  5. Does the result match your prediction? Can you explain the results?

    6. +
+
"""
+The code below reads a text file and counts the number of unique words in it
+(case-insensitive).
+"""
+import re
+
+
+def count_unique_words1(file_path: str) -> int:
+    with open(file_path, "r", encoding="utf-8") as file:
+        text = file.read()
+    words = re.findall(r"\b\w+\b", text.lower())
+    return len(set(words))
+
+
+def count_unique_words2(file_path: str) -> int:
+    unique_words = []
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower())
+            for word in words:
+                if word not in unique_words:
+                    unique_words.append(word)
+    return len(unique_words)
+
+
+def count_unique_words3(file_path: str) -> int:
+    unique_words = set()
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower())
+            for word in words:
+                unique_words.add(word)
+    return len(unique_words)
+
+
+def main():
+    # book.txt is downloaded from https://www.gutenberg.org/cache/epub/2600/pg2600.txt
+    _result = count_unique_words1("book.txt")
+    _result = count_unique_words2("book.txt")
+    _result = count_unique_words3("book.txt")
+
+
+if __name__ == "__main__":
+    main()
+
+
+ +
+
+
+

SciPy

+

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+

In scipy.rst:

+ +

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+

In scipy.rst:

+ +
+
+

Library ecosystem

+

In libraries.rst:

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+

In libraries.rst:

+ +

In libraries.rst:

+
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+

In libraries.rst:

+ +
+
+

Dependency management

+

In dependencies.rst:

+
+

Dependencies-1: Discuss dependency management (5 min)

+

Please discuss and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+

In dependencies.rst:

+
+

Dependencies-2: Package language detective (5 min)

+

Think about the following sentences:

+
    +

  1. Yes, you can install my package with pip from GitHub.

    2. +

  2. I forgot to specify my channels, so my packages came from the defaults.

    3. +

  3. I have a Miniforge installation and I use mamba to create my environments.

    4. +
+

What hidden information is given in these sentences?

+ +
+

In dependencies.rst:

+
+

Dependencies-3: Create a Python environment (15 min)

+

Use conda or venv to create the environment presented in the +example.

+
+

In dependencies.rst:

+
+

Dependencies-4: Export an environment (15 min)

+

Export the environment you previously created.

+
+
+
+

Binder

+

In binder.rst:

+
+

Binder-1: Discuss better strategies than only code sharing (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+

In binder.rst:

+
+

Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this. This exercise (and all following) +requires git/GitHub knowledge and accounts, which wasn’t a +prerequisite of this course. Thus, this is a demo (and might even +be too fast for you to type-along). Watch the video if you +are reading this later on:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+

In binder.rst:

+ +

In binder.rst:

+ +
+
+

Parallel programming

+

In parallel.rst:

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+

In parallel.rst:

+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+

In parallel.rst:

+
+

Parallel-3, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+

In parallel.rst:

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+
+

Packaging

+

In packaging.rst:

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Web APIs with Python

+

In web-apis.ipynb:

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+

In web-apis.ipynb:

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+

In web-apis.ipynb:

+ +
+
+

In depth analysis of some selected file formats

+

In data-formats.rst:

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+

In data-formats.rst:

+ +
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/genindex/index.html b/branch/master/genindex/index.html new file mode 100644 index 00000000..6d4c26f6 --- /dev/null +++ b/branch/master/genindex/index.html @@ -0,0 +1,153 @@ + + + + + + + + Index — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ + +

Index

+ +
+ +
+ + +
+
+
+ +
+ +
+

© Copyright 2020-2024, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/guide/index.html b/branch/master/guide/index.html new file mode 100644 index 00000000..7d41bce4 --- /dev/null +++ b/branch/master/guide/index.html @@ -0,0 +1,289 @@ + + + + + + + + + + + + + + + Instructor’s guide — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Instructor’s guide

+
+

Learner personas

+

A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

+

A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

+

B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

+

Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren’t familiar.

+

Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter

+
+
+

About each section

+

In general, “Python for Scientific Computing could be a multi-year +course. We can’t even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path.

+
    +

  • Python intro: We can’t really replace a Python tutorial, but +here we try to outline some of the main points. We don’t go over +this in the course.

    • +

  • Jupyter: Jupyter is somewhat useful, but the main reason we go +over it is that it provides a convenient user interface for the +other programming lessons (it’s easier to spend a bit of time with +Jupyter than expect people to be able to use some +editor/IDE/shell/etc). So, we do start from the beginning, so that +people can do the other lessons, but also try to teach some advanced +tips and tricks.

    • +

  • Numpy: The basic of much of the rest of scipy, so we need to +cover it. We try to get the main principles out, but if someone +already knows it this can be a bit boring. We try to make sure +everyone comes out with an appreciation for vectorization and +broadcasting.

    • +

  • Pandas: A lot of similar goals to the Numpy section, especially +the concepts behind Dataframes that one needs to know in order to +read other documentation.

    • +

  • Visualization: Matplotlib is getting a bit old, but is still the +backbone of other plotting packages. We try to get forth the ideas +of the matplotlib API that can be seen in other packages and the +importance of scripted plots.

    • +

  • Data formats: Input/output/storage is a common task, and can +easily either be a bottleneck or a huge mess. This lessons tries to +show some best practices with data formats and, as usual, get the +idea to not “do it yourself”. Pandas is used as a common framework, +but we should point out there are plenty of other options.

    • +

  • Scripts: The most important lesson here is to break out of +Jupyter/run buttons of editors. If you can’t make actual programs +with an actual interface, you can’t scale up.

    +
      +

    • This is the first lesson to introduce the command line. We +recommend being as simple as possible: at least demonstrate the +JupyterLab terminal and discuss the bigger picture behind what it +means and why.

      • +

    • This is also the first lesson to use non-Jupyter code editor. We +recommend again being simple: use the JupyterLab code editor to +start off, and carefully explain what is going on.

      • +
    +
    • +

  • Scipy: We don’t cover much here (this is super short), but the +point is scipy exists and the concept of wrapping existing C/fortran +libraries and so on.

    • +

  • Library ecosystem: This was an overview of the types of packages +available in the “scipy ecosystem”, which is a large and ill-defined +thing. But there is another point: choosing what to use. Do you +trust a half-done thing published on someone’s personal webpage? If +it’s on Github? How do you make your code more reusable? When +coming from academic courses, you get a “build it yourself” idea, +which isn’t sustainable in research.

    • +

  • Parallel programming:

    • +

  • Dependencies: The main point here is environments, another thing +you often don’t learn in courses.

    +
      +

    • There is a lot of material here. Consider what you will demo, +what will be done as exercises, and what is advanced/optional. +However, it is the fourth-day lesson that is most interactive, so +it is OK if it take a while to go through everything.

      • +

    • If someone else installs Anaconda for a user (e.g. admin-managed +laptop), the conda environment creations (with --name, +possibly with --prefix too?) may not work. Be prepared for +this and mention it. You don’t need to solve the problem but +acknowledge that the lesson becomes a demo. The virtualenv part +should hopefully work for them.

      • +
    +
    • +

  • Binder: Binder exists and can help make code +reproducible/reusable by others.

    • +

  • Packaging: How to make your code reusable by others. By the +time we get here, people are tired and the topics get involved. We +more explicitly say “you might want to watch and take this as a +demo”.

    • +
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/index.html b/branch/master/index.html new file mode 100644 index 00000000..2c0a2f6b --- /dev/null +++ b/branch/master/index.html @@ -0,0 +1,395 @@ + + + + + + + + + + + + + + + Python for Scientific Computing — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python for Scientific Computing

+
+

Attending the course 5-7 November, 2024?

+

See the course page here +and watch at https://twitch.tv/coderefinery. +Whether you are or aren’t, the course material is below. Videos +will appear in this playlist (Last year’s videos: playlist).

+
+

Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, Matplotlib for visualization, and so on. In +addition, it talks about how python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write.

+

This course (like any course) can’t teach you Python… it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to.

+
+

Prerequisites

+ +

These are not prerequisites:

+
    +

  • Any external libraries, e.g. numpy

    • +

  • Knowing how to make scripts or use Jupyter

    • +
+
+
+

Videos and archived Q&A

+

Videos and material from past instances:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

(prereq)

Introduction to Python

30 min

Jupyter

60 min

NumPy or Advanced NumPy

60 min

Pandas

30 min

Xarray

60 min

Plotting with Matplotlib

60 min

Plotting with Vega-Altair

30 min

Working with Data

60 min

Scripts

40 min

Profiling

20 min

Productivity tools

30 min

Web APIs with Python

15 min

SciPy

30 min

Library ecosystem

45 min

Parallel programming

45 min

Dependency management

30 min

Binder

60 min

Packaging

+
+
+
+

Reference

+ +
+
+

Who is the course for?

+

The course is targeted towards these learner personas:

+
    +

  • A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able +to do their research more efficiently and make sure that they are +using the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

    • +

  • A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

    • +

  • B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves: they want to know how to reuse tools +that already exist.

    • +
+
+
+

Motivation

+
+

Why Python

+

Python has become popular, largely due to good reasons. It’s very easy +to get started, there’s lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities.

+
+
+

Why not Python for Scientific Computing

+

While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools.

+
    +

  • Implementing performance-critical kernels. Python is a very +slow language, which often doesn’t matter if you can offload the +heavy lifting to fast compiled code, e.g. by using Numpy array +operations. But if what you’re trying to do isn’t vectorizable +then you’re out of luck. An alternative to Python, albeit much less +mature and with a smaller ecosystem, but which provides very fast +generated code, is Julia.

    • +

  • Creating libraries that can be called from other languages. In this +case you’ll often want to create a library with a C interface, which +can then be called from most languages. Suitable languages for this +sort of task, depending on what you are doing, could be Rust, C, +C++, or Fortran.

    • +

  • You really like static typing, or functional programming +approaches. Haskell might be what you’re looking for.

    • +
+
+
+

Python 2 vs Python 3

+

Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard.

+

At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2.

+
+
+
+

Credits

+

This course was originally designed by Janne Blomqvist.

+

In 2020 it was completely redesigned by a team of the following:

+
    +

  • Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, …

    • +

  • Editor:

    • +

  • Testers and advisors: Enrico Glerean

    • +
+

We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

+
+
+

See also

+ +
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/installation/index.html b/branch/master/installation/index.html new file mode 100644 index 00000000..09168feb --- /dev/null +++ b/branch/master/installation/index.html @@ -0,0 +1,511 @@ + + + + + + + + + + + + + + + Software installation — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Software installation

+

This course is interactive and demonstrates many different tools. +Thus, even beyond Python, extra software (Python libraries) needs to +be installed. This page contains the instructions.

+

Once the course starts, we don’t have time to stop for installing +software.

+

Please make sure before the course that you have all the required +software installed or some other way access to it. For example, the +workshop could be done with a remote Jupyter server, as long as you +can use the terminal from the Jupyter (you need to be able to access +the command line for some lessons).

+
+

Do you need help?

+

Participants from a partner institution are invited to install help +sessions. (Hint: ask your institution to become a partner if it +isn’t already!)

+

Otherwise, if you need installation help, show this page to someone +around you and they can probably help. These are relatively +standard tools.

+

Don’t be afraid to ask for help. Installing scientific software is +harder than it should be and it helps to have someone guide you +through it.

+
+
+

Python

+

We expect you to have a working Python installation with some common +libraries. We currently recommend Miniforge, which includes the base and +packages through a different, freely usable channel. You can +explore the options in the tabs below.

+
+

Python, conda, anaconda, miniforge, etc?

+

Unfortunately there’s a lot of jargon. We’ll go over this in the +course but here is a crash course:

+
    +

  • Python is a programming language very commonly used in +science, it’s the topic of this course.

    • +

  • Conda is a package manager: it allows distributing and +installing packages, and is designed for complex scientific +code.

    • +

  • Mamba is a re-implementation of Conda to be much faster with +resolving dependencies and installing things.

    • +

  • An Environment is a self-contained collections of packages +which can be installed separately from others. They are used so +each project can install what it needs without affecting others.

    • +

  • Anaconda is a commercial distribution of Python+Conda+many +packages that all work together. It used to be freely usable for +research, but since ~2023-2024 it’s more limited. Thus, we don’t +recommend it (even though it has a nice graphical user interface).

    • +

  • conda-forge is another channel of distributing packages that +is maintained by the community, and thus can be used by anyone. +(Anaconda’s parent company also hosts conda-forge packages)

    • +

  • miniforge is a distribution of conda pre-configured for +conda-forge. It operates via the command line.

    • +

  • miniconda is a distribution of conda pre-configured to use +the Anaconda channels.

    • +
+
+
+

This is our recommended method - it can be used for any purpose +and makes a strong base for the future.

+

Follow the instructions on the miniforge web page. This installs +the base, and from here other packages can be installed.

+

Miniforge uses the command line - this gives you the most power +but can feel unfamiliar. See the command line crash course for an intro.

+
+
+
+

Starting Python

+

You need to Python in a way that activates conda/mamba.

+
+
+

Linux/MacOS: Each time you start a new command line terminal, +you can activate Miniforge by running. This is needed so that +Miniforge is usable wherever you need, but doesn’t affect any +other software on your computer (this is not needed if you +choose “Do you wish to update your shell profile to +automatically initialize conda?”, but then it will always be +active):

+
$ source ~/miniforge3/bin/activate
+
+
+
+
+
+
+

Python for SciComp software environment

+

Once Python and conda/mamba are installed, you can use it to install +an environment. An environment is a self-contained set of extra +libraries - different projects can use different environments to not +interfere with each other. This environment will have all of the +software needed for this particular course.

+
+

This environment file +contains all packages needed for the course, and can be +installed with. The following command will install an +environment named python-for-scicomp (there may be lots of +warning messages: this is OK if it still goes through):

+
+
$ mamba env create -n python-for-scicomp -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml
+
+
+
+

Each time you start a new command line, you need to activate +miniforge and this environment:

+
+
$ source ~/miniforge3/bin/activate
+$ conda activate python-for-scicomp
+
+
+
+
+
+
+

JupyterLab

+

We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need).

+
+

JupyterLab was instaled in the previous step. To run it, first, +start the Miniforge command line interface. Remember, you may +need to activate Miniforge and the environment first.

+
+
$ source ~/miniforge3/bin/activate
+$ conda activate python-for-scicomp
+$ jupyter-lab
+
+
+
+
+
+
+

Verification of Python and JupyterLab

+
+

Watch the video

+

See this verification in video form - if you can do this, you are +ready to go for day one. Your exact steps may be a bit different.

+

Remember that you need to activate the environment first - see the +step above.

+
+
+

You can start JupyterLab from the command line:

+
$ jupyter-lab
+(... Jupyter starts in a web browser)
+
+
+
+

Verify that you can start a Jupyter notebook. We will learn how to +do this in day 1, but you can try running print("Hello, world!") +if you want.

+
+../_images/jupyterlab-notebook.png +
+

Starting a Jupyter Notebook from JupyterLab.

+
+
+
+
+

Text editor

+

For one portion of the course, you will need a text editor. If you +don’t know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.

+
+

Other editors

+

Because we need to be simple in our teaching, we only teach the +most basic editors. We encourage you to try out more advanced ones +yourself.

+

For other editors, see the CodeRefinery instructions. You don’t +exactly need a terminal editor - the graphical ones, such as VSCode or +whatever you use now, will work as well.

+
+
+
+

Command line

+

You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed. If you want to +test in advance:

+
    +

  • You can start it from JupyterLab (recommended):

    +
    +../_images/jupyterlab-terminal.png + +
    +

    From the JupyterLab launcher, select “Terminal”.

    +
    +
    +
    • +
+
+

Other ways to access the command line

+
    +

  • From the Anaconda Navigator:

    +
    +../_images/anaconda-prompt.png +
    +

    From the Anaconda Navigator, you can select “environments” on the +left, then click on one, then the arrow, then “Open terminal”.

    +
    +
    +
    • +

  • From your operating system’s terminal applications, if you activate +Anaconda.

    • +
+
+
+

Verification of the command line

+

To verify command line usage, type the following commands (without the +$), and you should see the corresponding output that lists the +Python version:

+
$ python3 -V
+Python 3.8.3
+
+## Or python... if it's installed as that
+$ python -V
+Python 3.8.3
+
+
+

Any recent version of Python 3 should work for the course (for example +3.8 or higher).

+
+
+
+

Zoom

+

If this is an online workshop, it might use Zoom. You can see +CodeRefinery instructions for it.

+
+
+

Need help?

+

If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up!

+
+
+

See also

+ +
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/jupyter/index.html b/branch/master/jupyter/index.html new file mode 100644 index 00000000..02aea2b0 --- /dev/null +++ b/branch/master/jupyter/index.html @@ -0,0 +1,488 @@ + + + + + + + + + + + + + + + Jupyter — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Jupyter

+
+

Questions

+
    +

  • What is the purpose of a “Computational narrative”?

    • +

  • What role does Jupyter play in development?

    • +

  • When is Jupyter not a good tool?

    • +
+
+
+

Objectives

+

This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.

+
    +

  • Be able to use Jupyter to run examples for the rest of the course.

    • +

  • Be able to run Jupyter in a directory do your own work.

    • +

  • You won’t be a Jupyter expert after this, but should be able to do the rest of the course.

    • +
+
+
+

What is Jupyter?

+

Jupyter is a web-based interactive computing system. It is most well known for having the notebook file format and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a computational narrative.

+

Jupyter is good for data exploration and interactive work.

+

We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.

+
+
+

Getting started with Jupyter

+
    +

  • Start JupyterLab: there are different ways, depending on how you installed it. See the installation instructions. If JupyterLab isn’t working yet, you have some time to try to follow the installation instructions now.

    • +
+
+

This is the command line method we went though in our installation instructions.

+
+
$ source ~/miniforge3/bin/activate
+$ conda activate python-for-scicomp
+$ jupyter-lab
+
+
+
+
+

For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need.

+

Here, we see a tour of the JupyterLab interface:

+

Main UI tour

+
+
+

Exercises 1

+
+

Exercises: Jupyter-1

+

If you aren’t set up with JupyterLab yet or these things don’t work, use this time to see the installation instructions and ask us any questions you may have.

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are using Miniforge from the command line, you can navigate with cd to a directory of your choice.

      • +

    • If you are starting from the Anaconda Navigator, change to the directory you want to use.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+
+
+

Running code in Jupyter

+

A notebook is divided into cells. Each cell has some input, and when it is executed an output appears right below it.

+

There are different types of cells: primarily code cells and markdown cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving style to text - you can check out this reference. For example the previous sentence is:

+
Markdown is a lightweight way of giving *style* to `text` - you 
+can check out [this reference](https://commonmark.org/help/).
+
+
+

notebook UI

+

When using keyboard shortcuts, you can switch between edit mode and command mode with Enter and Esc.

+

You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:

+
    +

  • Ctrl-Enter: Run cell

    • +

  • Shift-Enter: Run cell and select cell below

    • +

  • Alt-Enter: Run cell and insert new cell below

    • +

  • a / b: insert new cell above/below

    • +

  • m / y: markdown cell / code cell

    • +

  • x: cut cell

    • +

  • c: copy cell

    • +

  • v: paste cell

    • +

  • d, d: delete cell

    • +
+

Now, let’s look at some code samples:

+
+
+
for i in range(3):
+    print(i)
+
+
+
+
+
0
+1
+2
+
+
+
+
+
+
+
print(sum(range(5)))
+
+
+
+
+
10
+
+
+
+
+

By convention, if the last thing in a cell is an object, that object gets printed:

+
+
+
sum(range(5))
+sum(range(10))
+
+
+
+
+
45
+
+
+
+
+

In addition to raw cells, there are magics, which exist outside of Python. They are a property of the runtime itself (in Python’s case, they come from IPython. For example, the following cell magic %%timeit will use the timeit module to time a cell by running it multiple times):

+
+
+
%%timeit
+for x in range(1000000):
+    x**2
+
+
+
+
+
54.1 ms ± 993 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
+
+
+
+
+

Another example is %%bash which will turn the cell into a shell script (This will only work on operating systems with the Bash shell installed - MacOS and Linux at least):

+
+
+
%%bash
+for x in $(seq 3) ; do
+    echo $x
+done
+
+
+
+
+
1
+2
+3
+
+
+
+
+
    +

  • A cell magic starts with %%, goes on the first line of a cell, and applies to the whole cell

    • +

  • A line magic starts with %, goes on any line, and applies to that line.

    • +
+
+
+

Exercises 2

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+ +
+
+

Why Jupyter?

+
    +

  • Being able to edit, check, re-edit quickly is great for prototyping and testing new ideas

    +
      +

    • Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.

      • +
    +
    • +

  • You can make a complete story - in one place. No more having code, figures, and description in different places.

    +
      +

    • Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.

      • +
    +
    • +

  • Notebook as an interactive publication itself - for example the discovery of gravitational waves data is released as a notebook.

    • +

  • Jupyter Notebooks display on Github - low-barrier way to share your analysis.

    • +

  • Teaching - great for getting difficult software distribution out of the way.

    • +
+
+
+

Why not Jupyter?

+

Jupyter is great for many things, but there are some problems if not used well:

+
    +

  • They don’t promote modularity, and once you get started in a +notebook it can be hard to migrate to modules.

    • +

  • They are difficult to test. There are things to run notebooks as +unit tests like nbval, but it’s not +perfect.

    • +

  • Notebooks can be version controlled +(nbdime helps with that), but +there are still limitations.

    • +

  • You can change code after you run it and run code out of order. +This can make debugging hard and results irreproducible if you +aren’t careful.

    • +

  • Notebooks aren’t named by default and tend to acquire a bunch of +unrelated stuff. Be careful with organization!

    • +

  • Once lots of code is in notebooks, it can be hard to change to +proper programs that can be scripted.

    • +
+

You can read more about these downsides https://scicomp.aalto.fi/scicomp/jupyter-pitfalls/.

+

But these downsides aren’t specific to Jupyter! They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.

+
+
+

Exercises 3

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Jupyter is powerful and can be used for interactive work

    • +

  • … but not the end solution when you need to scale up.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/lesson.pdf b/branch/master/lesson.pdf new file mode 100644 index 00000000..0516df6b Binary files /dev/null and b/branch/master/lesson.pdf differ diff --git a/branch/master/libraries/index.html b/branch/master/libraries/index.html new file mode 100644 index 00000000..d42058be --- /dev/null +++ b/branch/master/libraries/index.html @@ -0,0 +1,520 @@ + + + + + + + + + + + + + + + Library ecosystem — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Library ecosystem

+
+

Questions

+
    +

  • What happens when you need some method beyond what we discuss in this course, what is available?

    • +

  • How do you decide what to build on for your work?

    • +
+
+
+

Objectives

+
    +

  • Know of some other available packages, but don’t necessarily know +how to use them.

    • +

  • Be able to evaluate what you should reuse and what you should +develop yourself.

    • +
+
+

You can’t do everything yourself. In fact, once we heard a quote such +as this:

+
+

When you are a student, you are expected to do everything +yourself, and that is how you are evaluated. When you become a +researcher, you have to be able to reuse what others have done. +We don’t have much practice in doing this. +– A student

+
+

In this lesson, we’ll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types:

+
    +

  • Well-maintained libraries that are used by many others.

    • +

  • A wide variety of public code that might work but isn’t necessarily +well-maintained (for example, code from articles).

    • +
+

We’ll start with the first then go to the second.

+
+

Glossary

+
+
Library

A collection of code used by a program.

+
+
Package

A library that has been made easily installable and reusable. +Often published on public repositories such as the Python Package +Index

+
+
Dependency

A requirement of another program, not included in that program.

+
+
+
+
+

The Python/SciPy ecosystem

+

This section is nothing more than a tour of what exists in Python. +You aren’t expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work.

+

The “core” packages could be considered. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy):

+
    +

  • Python

    • +

  • Numpy - arrays, everything builds on this

    • +

  • Scipy - scientific functions (not necessarily a lot builds on this)

    • +

  • matplotlib - plotting, many other plotting tools build on this

    • +

  • pandas - data structures

    • +

  • IPython / Jupyter: interactive work

    • +
+
+

Core numerics libraries

+
    +

  • numpy - arrays and array math.

    • +

  • scipy - software +for math, science, and engineering.

    • +
+
+
+

Plotting

+
    +

  • matplotlib - base plotting package, +somewhat low level but almost everything builds on it.

    • +

  • seaborn - higher level plotting +interface; statistical graphics.

    • +

  • mayavi - 3D plotting

    • +

  • PIL - image manipulation. The +original PIL is no longer maintained, the new “Pillow” is a drop-in +replacement.

    • +
+
+
+

Data analysis and other important core packages

+ +
+
+

Interactive computing and human interface

+
    +

  • Interactive computing

    +
      +

    • IPython - nicer interactive interpreter

      • +

    • Jupyter (notebook, lab, hub, …) - +web-based interface to IPython and other languages

      • +
    +
    • +

  • Testing

    +
      +

    • pytest - automated testing interface

      • +
    +
    • +

  • Documentation

    +
      +

    • Sphinx - documentation generator +(also used for this lesson…)

      • +
    +
    • +

  • Development environments

    +
      +

    • Spyder - interactive Python +development environment.

      • +
    +
    • +

  • Binder - load any git repository in +Jupyter automatically, good for reproducible research

    • +
+
+
+

Speeding up code and parallelism

+
    +

  • PyMPI - Message +Passing Interface (MPI) in Python for parallelizing jobs.

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • numba - just in time compiling of +functions for speed-up

    • +

  • PyPy - Python written in Python so that +it can internally optimize more.

    • +

  • Dask - distributed array data structure for +distributed computation

    • +

  • Joblib - easy embarrassingly +parallel computing

    • +

  • IPyParallel - easy +parallel task engine

    • +

  • numexpr - Fast evaluation of +array expressions by automatically compiling the arithmetic.

    • +
+
+
+

Machine learning

+

If you need some machine learning, you probably already know what you +need and this list is short and irrelevant.

+ +
+
+
+

Connecting Python to other languages

+

As we discussed with Scipy, very many of the above packages aren’t +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things:

+
    +

  • Extending Python by writing your own modules in C.

    +
      +

    • It’s actually common to first have (or write) an analysis package +in C or C++, then make the Python interface. Then it can be +supported by other languages, too.

      • +

    • Or one starts an analysis package in Python, and slowly moves bits +of it to C over time as there is need.

      • +
    +
    • +

  • Embedding Python, where you have another primary application +that uses Python under the hood as an internal scripting language.

    • +
+

These features aren’t exactly unique to Python, but Python does +support them very well. Read more: Extending and embedding Python.

+
+

Tools for interfacing with other languages

+

These days, one rarely directly extends the Python interpreter, but uses

+
    +

  • cffi and ctypes - interface to C +and compatible libraries

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • f2py - interface to Fortran +code

    • +

  • swig - connect to a variety of programming languages.

    • +

  • Boost.python - Another Python/C++ interface

    • +

  • TODO: Julia modules for Python?

    • +
+
+
+
+

Evaluating Python packages for reuse

+

Above, we talked about well-maintained mainstream packages. Do you +trust random code you find online (for example included in a paper)?

+

Especially consider scientific results, which have to be correct. +Still, you also can’t build everything yourself, so you have to +carefully evaluate the situation.

+

Below are some things to consider:

+
    +

  • Are there releases? Have they been going on for a while?

    • +

  • Are releases installable without copy-paste?

    • +

  • Are dependencies handled well?

    • +

  • Does the code randomly change, so that it no longer works with your +code. Is this relevant?

    • +

  • Is there good documentation, that not just tells how to use it but +how it works?

    • +

  • Is there automated testing? What’s your evaluation of the risk of +undetectable scientific errors?

    • +

  • Is there a community, or is it one person? Is it backed by some +organization? Does it have a permanent home?

    • +

  • Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) +where a community could form?

    • +

  • Do others post issues and make contributions? Are these issues +dealt with in a timely manner? Can you search past bug reports?

    • +

  • Is the software citeable?

    • +
+
+
+

Is your work reuseable?

+

Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a CodeRefinery workshop will make +sure you have the tools to produce high-quality, reusable code.

+
+
+

What’s next?

+
    +

  • The CodeRefinery workshop mentioned +above will prepare you for others to reuse your code and for you to +contribute to other code.

    • +

  • The upcoming Dependency management lesson will teach you how to +record and manage dependencies so that anyone can seamlessly reuse +your code.

    • +
+
+
+

Exercises

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+ +
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • Almost everything you need can already be found, except your +incremental work.

    • +

  • When do you build on that other work, and when do you create +things yourself?

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/numpy-advanced/index.html b/branch/master/numpy-advanced/index.html new file mode 100644 index 00000000..037175ee --- /dev/null +++ b/branch/master/numpy-advanced/index.html @@ -0,0 +1,605 @@ + + + + + + + + + + + + + + + Advanced NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Advanced NumPy

+
+

Questions

+
    +

  • How can NumPy be so fast?

    • +

  • Why are some things fast and some things slow?

    • +

  • How can I control whether NumPy makes a copy or operates in-place?

    • +
+
+
+

Objectives

+
    +

  • Understand why NumPy has so many specialized functions for specific operations

    • +

  • Understand the underlying machinery of the Numpy ndarray object

    • +

  • Understand when and why NumPy makes a copy of the data rather than a view

    • +
+

This is intended as a follow-up to the basic NumPy lesson. The intended +audience for this advanced lesson is those who have used NumPy before and +now want to learn how to get the most out of this amazing package.

+
+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +Guide to NumPy by +Travis E. Oliphant, its initial creator.

+
+

NumPy can be really fast

+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast.

+

How fast can NumPy be? Let’s race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:

+
#include <stdlib.h>
+#include <stdio.h>
+#define N_ELEMENTS 100000000
+int main(int argc, char** argv) {
+    double* a = (double*) malloc(sizeof(double) * N_ELEMENTS);
+    int i;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        a[i] = (double) rand() / RAND_MAX;
+    }
+    double sum = 0;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        sum += a[i];
+    }
+    printf("%f", sum);
+    return 0;
+}
+
+
+
+
+

Exercise 1

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lesson before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+ +
+
+

The libraries behind the curtain: MKL and BLAS

+

NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel’s Math Kernel Library (MKL), +which are in turn derived from a Fortran library called +Basic Linear Algebra Subprograms (BLAS). +BLAS for Fortran was published in 1979 +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +specialized CPU instructions for manipulating arrays. +In other words, they are fast.

+

One of the functions inside the BLAS library is a +function +to compute the “norm” of a vector, which is the same as computing its length, using the +Pythagorean theorem: +\(\sqrt(a[0]^2 + a[1]^2 + \ldots)\).

+

Let’s race the BLAS function versus a naive “manual” version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:

+
import numpy as np
+rng = np.random.default_rng(seed=0)
+a = rng.random(100_000_000)
+
+
+

We now implement the Pythagorean theorem using basic NumPy functionality and +use %%timeit to record how long it takes to execute:

+
%%timeit
+l = np.sqrt(np.sum(a ** 2))
+print(l)
+
+
+

And here is the version using the specialized BLAS function norm():

+
%%timeit
+l = np.linalg.norm(a)
+print(l)
+
+
+
+
+

NumPy tries to avoid copying data

+

Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy’s +numpy.ndarray datastructure works behind the scenes.

+
+

An example: matrix transpose

+

Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let’s see how long NumPy’s +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +rand() matrix:

+
import numpy as np
+a = np.random.rand(10_000, 20_000)
+print(f'Matrix `a` takes up {a.nbytes / 10**6} MB')
+
+
+

Let’s time the transpose() method:

+
%%timeit
+b = a.transpose()
+
+
+

It takes mere nanoseconds to transpose 1600 MB of data! How?

+
+
+

The ndarray exposed

+

The first thing you need to know about numpy.ndarray is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector.

+../_images/01_memory_layout.svg +

NumPy is faking the second dimension behind the scenes! When we request the +element at say, [2, 3], NumPy converts this to the correct index in the +long 1D array [11].

+
+
    +

  • Converting [2, 3] → [11] is called “raveling”

    • +

  • The reverse, converting [11] → [2, 3] is called “unraveling”

    • +
+
+

The implications of this are many, so take let’s take some time to understand +it properly by writing our own ravel() function.

+
+
+
+

Exercise 2

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+ +
+
+

Strides

+

As seen in the exercise, to get to the next row, we have to skip over +n_cols indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of “strides”:

+
np.zeros((4, 8)).strides           # (64, 8)
+np.zeros((4, 5, 6, 7, 8)).strides  # (13440, 2688, 448, 64, 8)
+
+
+

The strides attribute contains for each dimension, the number of bytes (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes.

+

So now we know the mystery behind the speed of transpose(). NumPy can avoid +copying any data by just modifying the strides of the array:

+
import numpy as np
+
+a = np.random.rand(10_000, 20_000)
+b = a.transpose()
+
+print(a.strides)  # (160000, 8)
+print(b.strides)  # (8, 160000)
+
+
+
+

Another example: reshaping

+

Modifying the shape of an array through numpy.reshape() is also +accomplished without any copying of data by modifying the strides:

+
a = np.random.rand(20_000, 10_000)
+print(f'{a.strides=}')  # (80000, 8)
+b = a.reshape(40_000, 5_000)
+print(f'{b.strides=}')  # (40000, 8)
+c = a.reshape(20_000, 5_000, 2)
+print(f'{c.strides=}')  # (80000, 16, 8)
+
+
+
+
+
+

Exercises 3

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+ +
+
+

A fast thing + a fast thing = a fast thing?

+

If numpy.transpose() is fast, and numpy.reshape() is fast, then +doing them both must be fast too, right?:

+
# Create a large array
+a = np.random.rand(10_000, 20_000)
+
+
+

Measuring the time it takes to first transpose and then reshape:

+
%%timeit -n 1 -r 1
+a.T.reshape(40_000, 5_000)
+
+
+

In this case, the data actually had to be copied and it’s super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the strides:

+
a = np.array([[1, 2, 3], [4, 5, 6]])
+
+print('Original array:')
+print(a)
+
+print('\nTransposed:')
+print(a.T)
+
+print('\nTransposed and then reshaped:')
+print(a.T.reshape(2, 3))
+
+
+
+
+

Copy versus view

+

Whenever NumPy constructs a new array by modifying the strides instead of +copying data, we way it created a “view”. This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +numpy.ndarray object will have a reference to the original array in +its base attribute:

+
a = np.zeros((5, 5))
+print(a.base)  # None
+b = a[:2, :2]
+print(b.base.shape)  # (5, 5)
+
+
+
+

Warning

+

When you create a large array and select only a portion of it, the large +array will stay in memory if a view was created!

+
+

The new array b object has a pointer to the same memory buffer as the array +it has been derived from:

+
print(a.__array_interface__['data'])
+print(b.__array_interface__['data'])
+
+
+

Views are created by virtue of modifying the value of the shape attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:

+
b = a[1:3, 1:3]   # This view does not start at the beginning
+offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0]
+print('Offset:', offset, 'bytes')  # Offset: 48 bytes
+
+
+../_images/02_views.svg +

Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:

+
b[0, 0] = 1.
+print(a)  # Original matrix was modified
+
+
+

Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:

+
c = a[[0, 2]]  # Select rows 0 and 2
+print(c.base)  # None. So not a view.
+
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • The best way to make your code more efficient is to learn more about the +NumPy API and use specialized functions whenever possible.

    • +

  • NumPy will avoid copying data whenever it can. Whether it can depends on +what kind of layout the data is currently in.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/numpy/index.html b/branch/master/numpy/index.html new file mode 100644 index 00000000..0a9fbc33 --- /dev/null +++ b/branch/master/numpy/index.html @@ -0,0 +1,671 @@ + + + + + + + + + + + + + + + NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

NumPy

+
+

Questions

+
    +

  • Why use NumPy instead of pure python?

    • +

  • How to use basic NumPy?

    • +

  • What is vectorization?

    • +
+
+
+

Objectives

+
    +

  • Understand the Numpy array object

    • +

  • Be able to use basic NumPy functionality

    • +

  • Understand enough of NumPy to seach for answers to the rest of your questions ;)

    • +
+

We expect most people to be able to do all the basic exercises +here. It is probably quite easy for many people; we have advanced +exercises at the end in that case.

+
+

So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible.

+
+

What is an array?

+

For example, consider [1, 2.5, 'asdf', False, [1.5, True]] - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately.

+

NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it.

+

An array is a ‘grid’ of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has:

+
    +

  • dtype - data type. Arrays always contain one type

    • +

  • shape - shape of the data, for example 3×2 or 3×2×500 or even +500 (one dimensional) or [] (zero dimensional).

    • +

  • data - raw data storage in memory. This can be passed to C or +Fortran code for efficient calculations.

    • +
+

To test the performance of pure Python vs NumPy we can write in our jupyter notebook:

+

Create one list and one ‘empty’ list, to store the result in

+
a = list(range(10000))
+b = [ 0 ] * 10000
+
+
+

In a new cell starting with %%timeit, loop through the list a and fill the second list b with a squared

+
%%timeit
+for i in range(len(a)):
+  b[i] = a[i]**2
+
+
+

That looks and feels quite fast. But let’s take a look at how NumPy performs for the same task.

+

So for the NumPy example, create one array and one ‘empty’ array to store the result in

+
import numpy as np
+a = np.arange(10000)
+b = np.zeros(10000)
+
+
+

In a new cell starting with %%timeit, fill b with a squared

+
%%timeit
+b = a ** 2
+
+
+

We see that compared to working with numpy arrays, working with traditional python lists is actually slow.

+
+
+

Creating arrays

+

There are different ways of creating arrays (numpy.array(), numpy.ndarray.shape, numpy.ndarray.size):

+
a = np.array([1,2,3])               # 1-dimensional array (rank 1)
+b = np.array([[1,2,3],[4,5,6]])     # 2-dimensional array (rank 2)
+
+b.shape                             # the shape (rows,columns)
+b.size                              # number of elements
+
+
+

In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (numpy.zeros(), numpy.ones(), numpy.full(), numpy.eye(), numpy.arange(), numpy.linspace()):

+
np.zeros((2, 3))             # 2x3 array with all elements 0
+np.ones((1,2))               # 1x2 array with all elements 1
+np.full((2,2),7)             # 2x2 array with all elements 7
+np.eye(2)                    # 2x2 identity matrix
+
+np.arange(10)                # Evenly spaced values in an interval
+np.linspace(0,9,10)          # same as above, see exercise
+
+c = np.ones((3,3))
+d = np.ones((3, 2), 'bool')  # 3x2 boolean array
+
+
+

Arrays can also be stored and read from a (.npy) file (numpy.save(), numpy.load()):

+
np.save('x.npy', a)           # save the array a to a .npy file
+x = np.load('x.npy')          # load an array from a .npy file and store it in variable x
+
+
+

In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (numpy.ndarray.dtype, numpy.ndarray.astype()):

+
d.dtype                    # datatype of the array
+d.astype('int')            # change datatype from boolean to integer
+
+
+

In the last example, .astype('int'), it will make a copy of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed.

+
+
+

Exercises 1

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+ +
+
+

Array maths and vectorization

+

Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do.

+

By default, basic arithmetic (+, -, *, /) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is “vectorized” +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop.

+

Note that unlike Matlab, where * means matrix multiplication, NumPy uses +* to perform element-by-element multiplication and uses the @ symbol to +perform matrix multiplication:

+
a = np.array([[1,2],[3,4]])
+b = np.array([[5,6],[7,8]])
+
+# Addition
+c = a + b
+d = np.add(a,b)
+
+# Matrix multiplication
+e = a @ b
+f = np.dot(a, b)
+
+
+

Other common mathematical operations include: - (numpy.subtract), * (numpy.multiply), / (numpy.divide), .T (numpy.transpose()), numpy.sqrt, numpy.sum(), numpy.mean(), …

+
+
+

Exercises 2

+
+

Exercises: Numpy-2

+ +
+ +
+
+

Indexing and Slicing

+
+

See also

+

Numpy basic indexing docs

+
+

NumPy has many ways to extract values out of arrays:

+
    +

  • You can select a single element

    • +

  • You can select rows or columns

    • +

  • You can select ranges where a condition is true.

    • +
+

Clever and efficient use of these operations is a key to NumPy’s +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C.

+
a = np.arange(16).reshape(4, 4)  # 4x4 matrix from 0 to 15
+a[0]                             # first row
+a[:,0]                           # first column
+a[1:3,1:3]                       # middle 2x2 array
+
+a[(0, 1), (1, 1)]                # second element of first and second row as array
+
+
+

Boolean indexing on above created array:

+
idx = (a > 0)      # creates boolean matrix of same size as a
+a[idx]             # array with matching values of above criterion
+
+a[a > 0]           # same as above in one line
+
+
+
+
+

Exercises 3

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+ +
+
+

Types of operations

+

There are different types of standard operations in NumPy:

+

ufuncs, “universal functions”: These are element-by-element +functions with standardized arguments:

+
    +

  • One, two, or three input arguments

    • +

  • For example, a + b is similar to np.add(a, b) but the ufunc +has more control.

    • +

  • out= output argument, store output in this array (rather than +make a new array) - saves copying data!

    • +

  • See the full reference

    • +

  • They also do broadcasting (ref). Can you add a 1-dimensional array of shape (3) +to an 2-dimensional array of shape (3, 2)? With broadcasting you +can!

    +
    a = np.array([[1, 2, 3],
+              [4, 5, 6]])
+b = np.array([10, 10, 10])
+a + b                       # array([[11, 12, 13],
+                            #        [14, 15, 16]])
+
    +
    +

    Broadcasting is smart and consistent about what it does, which I’m +not clever enough to explain quickly here: the manual page on +broadcasting. +The basic idea is that it expands dimensions of the smaller array so +that they are compatible in shape.

    +
    • +
+

Array methods do something to one array:

+
    +

  • Some of these are the same as ufuncs:

    +
    x = np.arange(12)
+x.shape = (3, 4)
+x                    #  array([[ 0,  1,  2,  3],
+                     #         [ 4,  5,  6,  7],
+                     #         [ 8,  9, 10, 11]])
+x.max()              #  11
+x.max(axis=0)        #  array([ 8,  9, 10, 11])
+x.max(axis=1)        #  array([ 3,  7, 11])
+
    +
    +
    • +
+

Other functions: there are countless other functions covering +linear algebra, scientific functions, etc.

+
+
+

Exercises 4

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+ +
+
+

Linear algebra and other advanced math

+

In general, you use arrays (n-dimensions), not matrixes +(specialized 2-dimensional) in NumPy.

+

Internally, NumPy doesn’t invent its own math routines: it relies on +BLAS +and LAPACK to do this kind +of math - the same as many other languages.

+
    +

  • Linear algebra in numpy

    • +

  • Many, many other array functions

    • +

  • Scipy has even +more functions

    • +

  • Many other libraries use NumPy arrays as the standard data +structure: they take data in this format, and return it similarly. +Thus, all the other packages you may want to use are compatible

    • +

  • If you need to write your own fast code in C, NumPy arrays can be +used to pass data. This is known as extending Python.

    • +
+
+
+

Additional exercises

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally.

    • +

  • Be aware of some NumPy specific peculiarities

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/objects.inv b/branch/master/objects.inv new file mode 100644 index 00000000..587c6df3 Binary files /dev/null and b/branch/master/objects.inv differ diff --git a/branch/master/packaging/index.html b/branch/master/packaging/index.html new file mode 100644 index 00000000..e0a75495 --- /dev/null +++ b/branch/master/packaging/index.html @@ -0,0 +1,523 @@ + + + + + + + + + + + + + + + Packaging — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Packaging

+
+

Questions

+
    +

  • How to organize Python projects larger than one script?

    • +

  • What is a good file and folder structure for Python projects?

    • +

  • How can you make your Python functions most usable by your collaborators?

    • +

  • How to prepare your code to make a Python package?

    • +

  • How to publish your Python package?

    • +
+
+
+

Objectives

+
    +

  • Learn to identify the components of a Python package

    • +

  • Learn to create a Python package

    • +

  • Learn to publish a Python package

    • +
+
+
+

Organizing Python projects

+

Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file.

+

In the Scripts episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further.

+

Recommendations:

+ +

To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: scipy.

+

These are the 3 files:

+
+
adding.py
+
def add(x, y):
+    return x + y
+
+
+
+
+
subtracting.py
+
def subtract(x, y):
+    return x - y
+
+
+
+
+
integrating.py
+
from scipy import integrate
+
+
+def integral(function, lower_limit, upper_limit):
+    return integrate.quad(function, lower_limit, upper_limit)
+
+
+
+

We will add a fourth file:

+
+
__init__.py
+
"""
+Example calculator package.
+"""
+
+from .adding import add
+from .subtracting import subtract
+from .integrating import integral
+
+__version__ = "0.1.0"
+
+
+
+

This __init__.py file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using relative imports +(with the dot).

+

This is how we will arrange the files in the project folder/repository:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+└── README.md
+
+
+

Now we are ready to test the package. For this we need to be in the “root” +folder, what we have called the project-folder. We also need to have +scipy available in our environment:

+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+

The package is not yet pip-installable, though. We will make this possible in +the next section.

+
+
+

Testing a local pip install

+

To make our example package pip-installable we need to add one more file:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+├── README.md
+└── pyproject.toml
+
+
+

This is how pyproject.toml looks:

+
+
pyproject.toml
+
[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "calculator-myname"
+description = "A small example package"
+version = "0.1.0"
+readme = "README.md"
+authors = [
+    { name = "Firstname Lastname", email = "firstname.lastname@example.org" }
+]
+dependencies = [
+    "scipy"
+]
+
+
+
+

Note how our package requires scipy and we decided to not pin the version +here (see Version pinning for package creators).

+

Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see PyPI (The Python Package Index) and conda ecosystem)

+
+
+

Exercises 1

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Sharing packages via PyPI

+

Once we are able to pip-install the example package locally, we are ready for +upload.

+

We exercise by uploading to test-PyPI, not the +real PyPI, so that if we mess things up, nothing bad +happens.

+

We need two more things:

+
    +

  • We will do this using Twine so you need +to pip install that, too.

    • +

  • You need an account on test-PyPI.

    • +
+

Let’s try it out. First we create the distribution package:

+
$ python3 -m build
+
+
+

We need twine:

+
$ pip install twine
+
+
+

And use twine to upload the distribution files to test-PyPI:

+
$ twine upload -r testpypi dist/*
+
+Uploading distributions to https://test.pypi.org/legacy/
+Enter your username:
+Enter your password:
+
+
+

Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt “myname”):

+
$ pip install -i https://test.pypi.org/simple/ calculator-myname
+
+
+
+
+

Tools that simplify sharing via PyPI

+

The solution that we have used to create the example package (using +setuptools and twine) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using pyproject.toml as more general +alternative to the previous setup.py.

+

There are at least two tools which try to make the packaging and PyPI interaction easier:

+ +
+
+

Building a conda package and share it

+
+

Demo

+

Most people will watch and observe this, due to speed which we will +move.

+
+
+

Prerequisites

+

To create a conda package, conda-build package is required. You may install it with Anaconda Navigator or from the command line:

+
$ conda install conda-build
+
+
+
+

The simplest way for creating a conda package for your python script is to +first publish it in PyPI following the steps explained +above.

+
+

Building a python package with conda skeleton pypi

+

Once build, the conda package can be installed locally. For this example, we +will use runtest. runtest is a numerically tolerant end-to-end test +library for research software.

+
    +

  1. Create pypi skeleton:

    +
    $ conda skeleton pypi runtest
+
    +
    +

    The command above will create a new folder called runtest containing a file meta.yaml, the conda recipe for runtest.

    +
    2. +

  2. Edit meta.yaml and update requirements:

    +
    requirements:
+  host:
+    - pip
+    - python
+    - flit
+  run:
+    - python
+    - flit
+
    +
    +

    In the requirements above, we specified what is required for the host and for running the package.

    +
    +

    Remark

    +

    For pure python recipes, this is all you need for building a python package with conda. +If your package needs to be built (for instance compilation), you would need additional files e.g. build.sh (to build on Linux/Mac-OSX) and bld.bat (to build on Windows systems). You can also add test scripts for testing your package. See documentation

    +
    +
    3. +

  3. Build your package with conda

    +

    Your package is now ready to be build with conda:

    +
    $ conda-build runtest
+
    +
    +
    +

    Conda package location

    +

    Look at the messages produced while building. The location of the local conda package is given (search for anaconda upload):

    +
    ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2
+
    +
    +

    The prefix ~/anaconda3/ may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder win-64 differs too (for instance linux-64 on Linux machines).

    +

    The conda package we have created is specific to your platform (here win-64). It can be converted to other platforms using conda convert.

    +
    +
    4. +

  4. Check within new environment

    +

    It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments.

    +
    $ conda create -n local-runtest --use-local runtest
+
    +
    +

    We can then check runtest has been successfully installed in local-runtest conda environment. Open a new Terminal with local-runtest environment (either from the command line:

    +
    $ conda activate local-runtest
+
    +
    +

    or via Anaconda Navigator (Open Terminal), import runtest and +check its version:

    +
    import runtest
+print(runtest.__version__)
+
    +
    +
    5. +
+
+

Building a conda package from scratch

+

It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the conda-build documentation for more information.

+
+

To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a conda channel (see below).

+
+
+

Publishing a python package

+
    +

  • Upload your package to Anaconda.org: see instructions here. +Please note that you will have to create an account on Anaconda.

    • +

  • Upload your package to conda-forge: +conda-forge is a conda channel: it contains community-led collection of +recipes, build infrastructure and distributions for the conda package +manager. Anyone can public conda packages to conda-forge if certain +guidelines are respected.

    • +

  • Upload your package to bioconda: bioconda is +a very popular channel for the conda package manager specializing in +bioinformatics software. As for conda-forge, you need to follow their +guidelines when +building conda recipes.

    • +
+

You can also create your own conda channel +for publishing your packages.

+
+

Keypoints

+
    +

  • It is worth it to organize your code for publishing, even if only +you are using it.

    • +

  • PyPI is a place for Python packages

    • +

  • conda is similar but is not limited to Python

    • +
+
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/pandas/index.html b/branch/master/pandas/index.html new file mode 100644 index 00000000..bcc44764 --- /dev/null +++ b/branch/master/pandas/index.html @@ -0,0 +1,790 @@ + + + + + + + + + + + + + + + Pandas — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Pandas

+
+

Questions

+
    +

  • How do I learn a new Python package?

    • +

  • How can I use pandas dataframes in my research?

    • +
+
+
+

Objectives

+
    +

  • Learn simple and some more advanced usage of pandas dataframes

    • +

  • Get a feeling for when pandas is useful and know where to find more information

    • +

  • Understand enough of pandas to be able to read its documentation.

    • +
+
+

Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including:

+ +
+

A quick Pandas preview

+

Let’s get a flavor of what we can do with pandas (you won’t be able to follow everything yet). We will be working with an example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:

+
import pandas as pd
+
+
+

We can download the data from this GitHub repository +by visiting the page and saving it to disk, or by directly reading into +a DataFrame:

+
url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv"
+titanic = pd.read_csv(url, index_col='Name')
+
+
+

We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:

+
# print the first 5 lines of the dataframe
+titanic.head()
+
+
+
# print summary statistics for each column
+titanic.describe()
+
+
+

Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38% of passengers survived, etc.

+

Let’s say we’re interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn’t survive, and plot corresponding histograms of +the age distribution (pandas.DataFrame.groupby(), pandas.DataFrame.hist()):

+
print(titanic.groupby("Survived")["Age"].mean())
+
+
+
titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10),
+             layout=(2,1), zorder=2, sharex=True, rwidth=0.9);
+
+
+

Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let’s get back to basics.

+
+

Getting help

+

Series and DataFrames have a lot functionality, but +how can we find out what methods are available and how they work? One way is to visit +the API reference +and reading through the list. +Another way is to use the autocompletion feature in Jupyter and type e.g. +titanic["Age"]. in a notebook and then hit TAB twice - this should open +up a list menu of available methods and attributes.

+

Jupyter also offers quick access to help pages (docstrings) which can be +more efficient than searching the internet. Two ways exist:

+
    +

  • Write a function name followed by question mark and execute the cell, e.g. +write titanic.hist? and hit SHIFT + ENTER.

    • +

  • Write the function name and hit SHIFT + TAB.

    • +

  • Right click and select “Show contextual help”. This tab will +update with help for anything you click.

    • +
+
+
+
+

What’s in a dataframe?

+

As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +pandas.DataFrame +is composed of rows and columns:

+../_images/01_table_dataframe.svg +

Each column of a dataframe is a pandas.Series object +- a dataframe is thus a collection of series:

+
# print some information about the columns
+titanic.info()
+
+
+

Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type int64 or of type object.

+

Let’s inspect one column of the Titanic passenger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):

+
titanic["Age"]
+titanic.Age          # same as above
+
+
+
type(titanic["Age"]) # a pandas Series object
+
+
+

The columns have names. Here’s how to get them (columns):

+
titanic.columns
+
+
+

However, the rows also have names! This is what Pandas calls the index:

+
titanic.index
+
+
+

We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and +values. We can refer to columns and rows either by their name +(loc, at) or by +their index (iloc, +iat):

+
titanic.loc['Lam, Mr. Ali',"Age"]          # select single value by row and column
+titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"]  # slice the dataframe by row and column *names*
+titanic.iloc[0:2,3:6]                      # same slice as above by row and column *numbers*
+
+titanic.at['Lam, Mr. Ali',"Age"] = 42      # set single value by row and column *name* (fast)
+titanic.at['Lam, Mr. Ali',"Age"]           # select single value by row and column *name* (fast)
+titanic.iat[0,5]                           # select same value by row and column *number* (fast)
+
+titanic["is_passenger"] = True             # set a whole column
+
+
+

Dataframes also support boolean indexing, just like we saw for numpy +arrays:

+
titanic[titanic["Age"] > 70]
+# ".str" creates a string object from a column
+titanic[titanic.index.str.contains("Margaret")]
+
+
+

What if your dataset has missing data? Pandas uses the value numpy.nan +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:

+
titanic.isna()                    # returns boolean mask of NaN values
+titanic.dropna()                  # drop missing values
+titanic.dropna(how="any")         # or how="all"
+titanic.dropna(subset=["Cabin"])  # only drop NaNs from one column
+titanic.fillna(0)                 # replace NaNs with zero
+titanic.fillna(method='ffill')    # forward-fill NaNs
+
+
+
+
+

Exercises 1

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+
+
+

Tidy data

+

The above analysis was rather straightforward thanks to the fact +that the dataset is tidy.

+../_images/tidy_data.png +

In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data.

+

What would untidy data look like? Here’s an example from +some run time statistics from a 1500 m running event:

+
runners = pd.DataFrame([
+              {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240},
+              {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300},
+              {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360},
+          ])
+
+
+

What makes this data untidy is that the column names 400, 800, 1200, 1500 +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row.

+

To make untidy data tidy, a common operation is to “melt” it, +which is to convert it from wide form to a long form:

+
runners = pd.melt(runners, id_vars="Runner",
+              value_vars=[400, 800, 1200, 1500],
+              var_name="distance",
+              value_name="time"
+          )
+
+
+

In this form it’s easier to filter, group, join +and aggregate the data, and it’s also easier to model relationships +between variables.

+

The opposite of melting is to pivot data, which can be useful to +view data in different ways as we’ll see below.

+

For a detailed exposition of data tidying, have a look at +this article.

+
+
+

Working with dataframes

+

We saw above how we can read in data into a dataframe using the read_csv() function. +Pandas also understands multiple other formats, for example using read_excel, +read_hdf, read_json, etc. (and corresponding methods to write to file: +to_csv, to_excel, to_hdf, to_json, etc.)

+

But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +DataFrame docs):

+
import numpy as np
+dates = pd.date_range('20130101', periods=6)
+df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD'))
+df
+
+
+

or a dictionary (see same docs):

+
df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'],
+                   'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'],
+                   'C': np.array([3] * 8, dtype='int32'),
+                   'D': np.random.randn(8),
+                   'E': np.random.randn(8)})
+df
+
+
+

There are many ways to operate on dataframes. Let’s look at a +few examples in order to get a feeling of what’s possible +and what the use cases can be.

+

We can easily split and concatenate dataframes:

+
sub1, sub2, sub3 = df[:2], df[2:4], df[4:]
+pd.concat([sub1, sub2, sub3])
+
+
+

When pulling data from multiple dataframes, a powerful pandas.DataFrame.merge method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:

+
age = pd.DataFrame([
+    {"Runner": "Runner 4", "Age": 18},
+    {"Runner": "Runner 2", "Age": 21},
+    {"Runner": "Runner 1", "Age": 23},
+    {"Runner": "Runner 3", "Age": 19},
+])
+
+
+

We now want to use this table to annotate the original runners table from +before with their age. Note that the runners and age dataframes have a +different ordering to it, and age has an entry for Dave which is not +present in the runners table. We can let Pandas deal with all of it using +the merge method:

+
# Add the age for each runner
+runners.merge(age, on="Runner")
+
+
+

In fact, much of what can be done in SQL +is also possible with pandas.

+

groupby is a powerful method which splits a dataframe and aggregates data +in groups. To see what’s possible, let’s return to the Titanic dataset. Let’s +test the old saying “Women and children first”. We start by creating a new +column Child to indicate whether a passenger was a child or not, based on +the existing Age column. For this example, let’s assume that you are a +child when you are younger than 12 years:

+
titanic["Child"] = titanic["Age"] < 12
+
+
+

Now we can test the saying by grouping the data on Sex and then creating further sub-groups based on Child:

+
titanic.groupby(["Sex", "Child"])["Survived"].mean()
+
+
+

Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +std, min, +max, cumsum, +median, skew, +var etc.

+
+
+

Exercises 2

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+
+
+

Time series superpowers

+

An introduction of pandas wouldn’t be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv .

+

Unfortunately this API does not allow “non-browser requests”, so +pandas.read_csv will not work directly on it. Instead, we put a +local copy on Github which we can access (the original data is CC-0, +so we are allowed to do this). (Aside: if you do JupyterLab → +File → Open from URL → paste the URL above, it will open it in +JupyterLab and download a copy for your use.)

+

We can then load and explore the data:

+
nobel = pd.read_csv("https://github.com/AaltoSciComp/python-for-scicomp/raw/master/resources/data/laureate.csv")
+nobel.head()
+
+
+

This dataset has three columns for time, “born”/”died” and “year”. +These are represented as strings and integers, respectively, and +need to be converted to datetime format. pandas.to_datetime() +makes this easy:

+
# the errors='coerce' argument is needed because the dataset is a bit messy
+nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce')
+nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce')
+nobel["year"] = pd.to_datetime(nobel["year"], format="%Y")
+
+
+

Pandas knows a lot about dates (using .dt accessor):

+
print(nobel["born"].dt.day)
+print(nobel["born"].dt.year)
+print(nobel["born"].dt.weekday)
+
+
+

We can add a column containing the (approximate) lifespan in years rounded +to one decimal:

+
nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1)
+
+
+

and then plot a histogram of lifespans:

+
nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9)
+
+
+

Finally, let’s see one more example of an informative plot (boxplot()) +produced by a single line of code:

+
nobel.boxplot(column="lifespan", by="category")
+
+
+
+
+

Exercises 3

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries (you need to look at the +data and find how countries are written, and replace COUNTRY +with those strings):

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Beyond the basics

+

Larger DataFrame operations might be faster using eval() with string expressions, see:

+
import pandas as pd
+# Make some really big dataframes
+nrows, ncols = 100000, 100
+rng = np.random.RandomState(42)
+df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols))
+                      for i in range(4))
+
+
+

Adding dataframes the pythonic way yields:

+
%timeit df1 + df2 + df3 + df4
+# 80ms
+
+
+

And by using eval():

+
%timeit pd.eval('df1 + df2 + df3 + df4')
+# 40ms
+
+
+

We can assign function return lists as dataframe columns:

+
def fibo(n):
+    """Compute Fibonacci numbers. Here we skip the overhead from the
+    recursive function calls by using a list. """
+    if n < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif n < 2:
+        return n
+    memo = [0]*(n+1)
+    memo[0] = 0
+    memo[1] = 1
+    for i in range(2, n+1):
+        memo[i] = memo[i-1] + memo[i-2]
+    return memo
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = fibo(99)  # Assigns list to column
+
+
+

There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its API. You should try to get good at +searching the web for an example showing what you can do. And when +there is not, you can always +apply your own functions to the data using apply:

+
from functools import lru_cache
+
+@lru_cache
+def fib(x):
+    """Compute Fibonacci numbers. The @lru_cache remembers values we
+    computed before, which speeds up this function a lot."""
+    if x < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif x < 2:
+        return x
+    else:
+        return fib(x - 2) + fib(x - 1)
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = df['Generation'].apply(fib)
+
+
+

Note that the numpy precision for integers caps at int64 while python ints are unbounded – +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df[‘Number of Rabbits’][99] given by both functions above +is in fact <class ‘int’>.

+
+
+

Alternatives to Pandas

+

Polars

+

Polars is a DataFrame library designed to processing data with a fast lighting time. Polars is implemented in Rust Programming language and uses Apache Arrow as its memory format.

+

Dask

+

Dask is a Python package for parallel computing in Python and uses parallel data-frames for dealing with very large arrays.

+

Vaex

+

Vaex is a high performance Python library for lazy Out-of-Core DataFrames, to visualize and explore big tabular datasets.

+
+

Keypoints

+
    +

  • pandas dataframes are a good data structure for tabular data

    • +

  • Dataframes allow both simple and advanced analysis in very compact form

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/parallel-pi-multiprocessing/index.html b/branch/master/parallel-pi-multiprocessing/index.html new file mode 100644 index 00000000..346397d7 --- /dev/null +++ b/branch/master/parallel-pi-multiprocessing/index.html @@ -0,0 +1,363 @@ + + + + + + + + + + + + + + + Python multithreading solution — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python multithreading solution

+

Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare).

+
+
+
import random
+
+
+
+
+
+
+
def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+    
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+
+
+
+
+
%%timeit
+# Do it just for timing
+n, n_inside_circle = sample(10**6)
+
+
+
+
+
598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do the actual calculation (the previous result doesn't get saved)
+n, n_inside_circle = sample(10**6)
+
+
+
+
+

This is the “calculate answer” phase.

+
+
+
pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+
+
+
3.144548
+
+
+
+
+
+

Do it in parallel with multiprocessing

+

This divides the calculation into 10 tasks and runs sample on each of them. Then it re-combines the results.

+
+
+
import multiprocessing.pool
+pool = multiprocessing.pool.Pool()
+# The default pool makes one process per CPU
+
+
+
+
+
+
+
%%timeit
+# Do it once to time it
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
pool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.140768
+
+
+
+
+
+
+

Do it in “parallel” with threads

+

To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process.

+
+
+
threadpool = multiprocessing.pool.ThreadPool()
+
+
+
+
+
+
+
%%timeit -o
+# Do it once to time it
+threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
<TimeitResult : 635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)>
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
threadpool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.142388
+
+
+
+
+
+
+

Future ideas

+

You could make a separate calculate function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.

+

Notice the similarity to split-apply-combine or map-reduce which is a specialization of split-apply-combine.

+
+
+ + + + +
+
+
+ +
+ +
+

© Copyright 2020-2024, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/parallel/index.html b/branch/master/parallel/index.html new file mode 100644 index 00000000..03819732 --- /dev/null +++ b/branch/master/parallel/index.html @@ -0,0 +1,647 @@ + + + + + + + + + + + + + + + Parallel programming — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Parallel programming

+
+

Questions

+
    +

  • When you need more than one processor, what do you do?

    • +

  • How can we use more than one processor/core in Python?

    • +
+
+
+

Objectives

+
    +

  • Understand the major strategies of parallelizing code

    • +

  • Understand mechanics of the multiprocessing package

    • +

  • Know when to use more advanced packages or approaches

    • +
+
+
+

Modes of parallelism

+

You realize you do have more computation to do than you can on one processor? +What do you do?

+
    +

  1. Profile your code, identify the actual slow spots.

    2. +

  2. Can you improve your code in those areas? Use an existing library?

    3. +

  3. Are there are any low-effort optimizations that you can make?

    4. +

  4. Consider using numba or +cython to accelerate key functions.

    5. +

  5. Think about parallelizing.

    6. +
+

Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers).

+

Parallel computing is when many different tasks are carried out +simultaneously. There are three main models:

+
    +

  • Embarrassingly parallel: the code does not need to +synchronize/communicate with other instances, and you can run +multiple instances of the code separately, and combine the results +later. If you can do this, great! (array jobs, task queues, +workflow management tools)

    • +

  • Multithreading: Parallel threads need to communicate and do so via +the same memory (variables, state, etc). (OpenMP, threading)

    • +

  • Multiprocessing, message passing: Different processes manage +their own memory segments. They share data by communicating (passing +messages) as needed. (multiprocessing, MPI).

    • +
+
+

Warning

+

Parallel programming is not magic, but many things can go wrong and +you can get unexpected results or difficult to debug problems. +Parallel programming is a fascinating world to get involved in, but +make sure you invest enough time to do it well.

+

See the video by Raymond Hettinger (“See Also” at bottom +of page) for an entertaining take on this.

+
+
+
+

Multithreading and the GIL

+

The designers of the Python language made the choice +that only one thread in a process can run actual Python code +by using the so-called global interpreter lock (GIL). +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. But it’s not all bad!:

+
    +

  • External libraries (NumPy, SciPy, Pandas, etc), written in C or other +languages, can release the lock and run multi-threaded.

    • +

  • Most input/output releases the GIL, and input/output is slow. The +threading library can be used to multithread I/O.

    • +

  • Python libraries like multiprocessing and mpi4py run multiple +Python processes and this circumvents the GIL.

    • +
+

Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix:

+
import numpy as np
+import time
+
+A = np.random.random((4000,4000))
+A = A * A.T
+time_start = time.time()
+np.linalg.inv(A)
+time_end = time.time()
+print("time spent for inverting A is", round(time_end - time_start,2), 's')
+
+
+

If we run this in a Jupyter notebook or through a Python script, it +will automatically use multithreading through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either export OMP_NUM_THREADS=1 or export MKL_NUM_THREADS=1, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime.

+
+

See also

+ +
+
+
+

multiprocessing

+

As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +multiprocessing module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock.

+

To show an example, +the split-apply-combine +or map-reduce paradigm is +quite useful for many scientific workflows. Consider you have this:

+
def square(x):
+    return x*x
+
+
+

You can apply the function to every element in a list using the +map() function:

+
>>> list(map(square, [1, 2, 3, 4, 5, 6]))
+[1, 4, 9, 16, 25, 36]
+
+
+

The multiprocessing.pool.Pool class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list:

+
>>> from multiprocessing import Pool
+>>> with Pool() as pool:
+...     pool.map(square, [1, 2, 3, 4, 5, 6])
+[1, 4, 9, 16, 25, 36]
+
+
+
+

Warning

+

Running the above example interactively in a Jupyter notebook +or through an Python/IPython terminal may or may not work on your +computer! This is a feature and not a bug, as covered in the +documentation.

+

Fortunately, there is a fork of multiprocesssing called +multiprocess which does +work in interactive environments. All we have to do is install it +by pip install multiprocess and change the import statement: +from multiprocess import Pool.

+
+
+
+

Exercises, multiprocessing

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+
+
+

MPI

+

The message passing interface (MPI) approach to parallelization +is that:

+
    +

  • Tasks (cores) have a rank and are numbered 0, 1, 2, 3, …

    • +

  • Each task (core) manages its own memory

    • +

  • Tasks communicate and share data by sending messages

    • +

  • Many higher-level functions exist to distribute information to other tasks +and gather information from other tasks

    • +

  • All tasks typically run the entire code and we have to be careful to avoid +that all tasks do the same thing

    • +
+

Introductory MPI lessons where Python is included:

+ +

These blog posts are good for gentle MPI/mpi4py introduction:

+ +

Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together.

+

Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work:

+
import random
+import time
+from mpi4py import MPI
+
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x ** 2 + y ** 2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+comm = MPI.COMM_WORLD
+size = comm.Get_size()
+rank = comm.Get_rank()
+
+n = 10 ** 7
+
+if size > 1:
+    n_task = int(n / size)
+else:
+    n_task = n
+
+t0 = time.perf_counter()
+_, n_inside_circle = sample(n_task)
+t = time.perf_counter() - t0
+
+print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+n_inside_circle = comm.gather(n_inside_circle, root=0)
+print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+
+if rank == 0:
+    pi_estimate = 4.0 * sum(n_inside_circle) / n
+    print(
+        f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds"
+    )
+
+
+
+
+

Exercises, MPI

+
+

Parallel-3, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+
+
+

Coupling to other languages

+

As mentioned further up in “Multithreading and the GIL”, Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP “directly”.

+

However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don’t +need parallelism, but need to make an optimized algorithm for a small part of the code.

+

Two strategies are common:

+
    +

  • Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization:

    +
    +
      +

    • C: use the cffi package (C foreign function interface). ctypes is a similar but slightly more primitive module that is in the standard library.

      • +

    • C++: use pybind11

      • +

    • Fortran: create a C interface using iso_c_binding and then couple the C layer to Python +using cffi

      • +

    • Rust: use PyO3

      • +
    +
    +
    • +

  • Let compiled languages do the shared-memory parallelization part (as in above +point) and let Python do the MPI work and distribute tasks across nodes using +an mpi4py layer.

    • +
+

Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course.

+

Before you take this route, profile the application first to be sure where +the bottleneck is.

+

Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason.

+
+
+

Dask and task queues

+

There are other strategies that go completely beyond the manual +parallelization methods above. We won’t go into much detail.

+
+

Dask

+

Dask is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs.

+

Dask is very popular for data analysis and is used by a number of high-level Python libraries:

+
    +

  • Dask arrays scale NumPy (see also xarray

    • +

  • Dask dataframes scale Pandas workflows

    • +

  • Dask-ML scales Scikit-Learn

    • +
+

Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block.

+
+

Example from dask.org

+
# Arrays implement the Numpy API
+import dask.array as da
+x = da.random.random(size=(10000, 10000),
+                     chunks=(1000, 1000))
+x + x.T - x.mean(axis=0)
+# It runs using multiple threads on your machine.
+# It could also be distributed to multiple machines
+
+
+
+
+
+
+

Exercises, Dask

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+

Task queues

+

A task queue has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for embarrassingly parallel jobs.

+

There are different descriptions of task queues in Python. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant.

+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pure Python is not very good for highly parallel code.

    • +

  • Luckily it interfaces to many things which are good, and give +you the full control you need.

    • +

  • Combining vectorized functions (NumPy, Scipy, pandas, etc.) with +the parallel strategies listed here will get you very far.

    • +

  • Another popular framework similar to multiprocessing is +joblib.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/plotting-matplotlib/index.html b/branch/master/plotting-matplotlib/index.html new file mode 100644 index 00000000..1141f7e9 --- /dev/null +++ b/branch/master/plotting-matplotlib/index.html @@ -0,0 +1,608 @@ + + + + + + + + + + + + + + + Plotting with Matplotlib — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Plotting with Matplotlib

+
+

Questions

+
    +

  • What happens if you can’t automatically produce plots?

    • +

  • When to use Matplotlib for data visualization?

    • +

  • When to prefer other libraries?

    • +
+
+
+

Objectives

+
    +

  • Be able to create simple plots with Matplotlib and tweak them

    • +

  • Know about object-oriented vs pyplot interfaces of Matplotlib

    • +

  • Be able to adapt gallery examples

    • +

  • Know how to look for help

    • +

  • Know that other tools exist

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • Try to minimize manual post-processing. This could bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    + +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative.

    • +
+
+
+

Why are we starting with Matplotlib?

+
    +

  • Matplotlib is perhaps the most popular Python plotting library.

    • +

  • Many libraries build on top of Matplotlib (example: Seaborn).

    • +

  • MATLAB users will feel familiar.

    • +

  • Even if you choose to use another library (see above list), chances are high +that you need to adapt a Matplotlib plot of somebody else.

    • +

  • Libraries that are built on top of Matplotlib may need knowledge of Matplotlib +for custom adjustments.

    • +
+

However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code.

+

Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences.

+
+
+

Getting started with Matplotlib

+

We can start in a Jupyter Notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK.

+

Let us create our first plot using +subplots(), +scatter, and some other methods on the +Axes object:

+
import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
+# uncomment the next line if you would like to save the figure to disk
+# fig.savefig("my-first-plot.png")
+
+
+
+Result of our first plot + +
+

This is the result of our first plot.

+
+
+

When running a Matplotlib script on a remote server without a +“display” (e.g. compute cluster), you may need to add the +matplotlib.use call:

+
import matplotlib.pyplot as plt
+matplotlib.use("Agg")
+
+# ... rest of the script
+
+
+
+
+

Exercise: Matplotlib

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y * 2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset. +You can also consult this great +quick start guide.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +

  • Experiment also by using named colors (e.g. “red”) instead of the hex-codes.

    • +
+
+ + +
+
+
+

Matplotlib has two different interfaces

+

When plotting with Matplotlib, it is useful to know and understand that +there are two approaches even though the reasons of this dual approach is +outside the scope of this lesson.

+
    +

  • The more modern option is an object-oriented interface or explicit interface (the +fig and ax objects +can be configured separately and passed around to functions):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
    +
    +
    • +

  • The more traditional option mimics MATLAB plotting and uses the +pyplot interface or implicit interface (plt carries +the global settings):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+plt.scatter(x=data_x, y=data_y, c="#E69F00")
+
+plt.xlabel("we should label the x axis")
+plt.ylabel("we should label the y axis")
+plt.title("some title")
+
    +
    +
    • +
+

When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, we +recommend to learn and use the object oriented interface.

+
+

Why do we emphasize this?

+

One day you may want to write functions which wrap +around Matplotlib function calls and then you can send Figure and Axes +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions.

+

When using the pyplot interface, settings are modified for the entire +matplotlib.pyplot package. The latter is acceptable for simple scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls.

+
+
+
+
+

Styling and customizing plots

+
    +

  • Before you customize plots “manually” using a graphical program, please +consider how this affects reproducibility.

    • +

  • Try to minimize manual post-processing. This might bite you when you +need to regenerate 50 figures one day before submission deadline or +regenerate a set of figures after the person who created them left the group.

    • +

  • Matplotlib and also all the other libraries allow to customize almost every aspect of a plot.

    • +

  • It is useful to study Matplotlib parts of a figure +so that we know what to search for to customize things.

    • +

  • Matplotlib cheatsheets: https://github.com/matplotlib/cheatsheets

    • +

  • You can also select among pre-defined themes/ +style +sheets +with use, for instance:

    +
    plt.style.use('ggplot')
+
    +
    +
    • +
+
+
+

Exercises: Styling and customization

+

Here are 3 exercises where we try to adapt existing scripts to either tweak +how the plot looks (exercises 1 and 2) or to modify the input data (example 3).

+

This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice:

+
    +

  • Select an example that is close to what you have in mind

    • +

  • Being able to adapt it to your needs

    • +

  • Being able to search for help

    • +

  • Being able to understand help request answers (not easy)

    • +
+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = (
+    "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+)
+gapminder_data = pd.read_csv(url).query("year == 2007")
+
+gapminder_data
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP per capita (PPP dollars)")
+ax.set_ylabel("Life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+ +
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+ +
+
+

Discussion

+

After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on.

+
+
+
+
+

Matplotlib and pandas DataFrames

+

In the above exercises we have sent individual columns of the gapminder_data DataFrame +into ax.scatter() like this:

+
fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+
+

It is possible to do this instead and let Matplotlib “unpack” the columns:

+
fig, ax = plt.subplots()
+
+ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data)
+
+
+

Other input types are possible. See Types of inputs to plotting +functions.

+
+
+

Keypoints

+
    +

  • Minimize manual post-processing, script everything.

    • +

  • Browse a number of example galleries to help you choose the library +that fits best your work/style.

    • +

  • Figures for presentation slides and figures for manuscripts have +different requirements.

    • +

  • Think about color-vision deficiencies when choosing colors. Use +existing solutions for this problem.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/plotting-vega-altair/index.html b/branch/master/plotting-vega-altair/index.html new file mode 100644 index 00000000..cd6cc074 --- /dev/null +++ b/branch/master/plotting-vega-altair/index.html @@ -0,0 +1,831 @@ + + + + + + + + + + + + + + + Plotting with Vega-Altair — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Plotting with Vega-Altair

+
+

Objectives

+
    +

  • Be able to create simple plots with Vega-Altair and tweak them

    • +

  • Know how to look for help

    • +

  • Reading data with Pandas from disk or a web resource

    • +

  • Know how to tweak example plots from a gallery for your own purpose

    • +

  • We will build up +this notebook +(spoiler alert!)

    • +
+
+
+

Instructor note

+
    +

  • 10 min: Introduction

    • +

  • 10 min: Type-along (creating a first plot)

    • +

  • 20 min: Exercise (using visual channels)

    • +

  • 20 min: Exercise (adapting a gallery example and customizing)

    • +

  • 10 min: Key points, discussion, and Q&A

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • Try to minimize manual post-processing. This could bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    +
      +

    • Vega-Altair: +declarative visualization, statistics built in

      • +

    • Matplotlib: +probably the most standard and most widely used

      • +

    • Seaborn: +high-level interface to Matplotlib, statistical functions built in

      • +

    • Plotly: +interactive graphs

      • +

    • Bokeh: +also here good for interactivity

      • +

    • plotnine: +implementation of a grammar of graphics in Python, it is based on ggplot2

      • +

    • ggplot: +R users will be more at home

      • +

    • PyNGL: +used in the weather forecast community

      • +

    • K3D: +Jupyter Notebook extension for 3D visualization

      • +

    • …

      • +
    +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative (e.g. Vega-Altair).

    • +
+
+
+

Why are we starting with Vega-Altair?

+
    +

  • Concise and powerful

    • +

  • “Simple, friendly and consistent API” allows us to focus on the data +visualization part and get started without too much Python knowledge

    • +

  • The way it combines visual channels with data columns can feel intuitive

    • +

  • Interfaces very nicely with Pandas (earlier episode)

    • +

  • Easy to change figures

    • +

  • Good documentation

    • +

  • Open source

    • +

  • Makes it easy to save figures in a number of formats (svg, png, html)

    • +

  • Easy to save interactive visualizations to be used in websites

    • +
+
+
+

Example data: Weather data from two Norwegian cities

+

We will experiment with some example weather data obtained from Norsk +KlimaServiceSenter, Meteorologisk +institutt (MET) (CC BY 4.0). The data is in CSV format (comma-separated +values) and contains daily and monthly weather data for two cities in Norway: +Oslo and Tromsø. You can browse the data +here in the lesson repository.

+

We will use the Pandas library to read the data into a dataframe. We have learned about Pandas in an earlier episode.

+

Pandas can read from and write to a large set of formats +(overview of input/output functions and formats). +We will load a CSV file directly from the web. Instead of using a web URL we +could use a local file name instead.

+

Pandas dataframes are a great data structure for tabular data and tabular +data turns out to be a great input format for data visualization libraries. +Vega-Altair understands Pandas dataframes and can plot them directly.

+
+
+

Reading data into a dataframe

+

We can try this together in a notebook: +Using Pandas we can merge, join, concatenate, and compare +dataframes, see https://pandas.pydata.org/pandas-docs/stable/user_guide/merging.html.

+

Let us try to concatenate two dataframes: one for Tromsø weather data (we +will now load monthly values) and one for Oslo:

+
import pandas as pd
+
+url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/"
+
+data_tromso = pd.read_csv(url_prefix + "tromso-monthly.csv")
+data_oslo = pd.read_csv(url_prefix + "oslo-monthly.csv")
+
+data_monthly = pd.concat([data_tromso, data_oslo], axis=0)
+
+# let us print the combined result
+data_monthly
+
+
+

Before plotting the data, there is a problem which we may not see yet: Dates +are not in a standard date format (YYYY-MM-DD). We can fix this:

+
# replace mm.yyyy to date format
+data_monthly["date"] = pd.to_datetime(list(data_monthly["date"]), format="%m.%Y")
+
+
+

With Pandas it is possible to do a lot more (adjusting missing values, fixing +inconsistencies, changing format).

+
+
+

Plotting the data

+

Now let’s plot the data. We will start with a plot that is not optimal and +then we will explore and improve a bit as we go:

+
import altair as alt
+
+alt.Chart(data_monthly).mark_bar().encode(
+    x="date",
+    y="precipitation",
+    color="name",
+)
+
+
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year.

+
+
+
+

Let us pause and explain the code

+
    +

  • alt is a short-hand for altair which we imported on top of the notebook

    • +

  • Chart() is a function defined inside altair which takes the data as argument

    • +

  • mark_bar() is a function that produces bar charts

    • +

  • encode() is a function which encodes data columns to visual channels

    • +
+

Observe how we connect (encode) visual channels to data columns:

+
    +

  • x-coordinate with “date”

    • +

  • y-coordinate with “precipitation”

    • +

  • color with “name” (name of weather station; city)

    • +
+
+

We can improve the plot by giving Vega-Altair a bit more information that the +x-axis is temporal (T) and that we would like to see the year and +month (yearmonth):

+
alt.Chart(data_monthly).mark_bar().encode(
+    x="yearmonth(date):T",
+    y="precipitation",
+    color="name",
+)
+
+
+

Apart from T (temporal), there are other +encoding data types:

+
    +

  • Q (quantitative)

    • +

  • O (ordinal)

    • +

  • N (nominal)

    • +

  • T (temporal)

    • +

  • G (geojson)

    • +
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year.

+
+
+

Let us improve the plot with another one-line change:

+
alt.Chart(data).mark_bar().encode(
+    x="yearmonth(date):T",
+    y="precipitation",
+    color="name",
+    column="name",
+)
+
+
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side.

+
+
+

With another one-line change we can make the bar chart stacked:

+
alt.Chart(data_monthly).mark_bar().encode(
+    x="yearmonth(date):T",
+    y="precipitation",
+    color="name",
+    xOffset="name",
+)
+
+
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year +plotted as stacked bar chart.

+
+
+

This is not publication-quality yet but a really good start!

+

Let us try one more example where we can nicely see how Vega-Altair +is able to map visual channels to data columns:

+
alt.Chart(data_monthly).mark_area(opacity=0.5).encode(
+    x="yearmonth(date):T",
+    y="max temperature",
+    y2="min temperature",
+    color="name",
+)
+
+
+
+Monthly temperature ranges for two cities in Norway. +
+

Monthly temperature ranges for two cities in Norway.

+
+
+
+

What other marks and other visual channels exist?

+ +
+
+
+

Exercise: Using visual channels to re-arrange plots

+
+

Plotting-1: Using visual channels to re-arrange plots

+
    +

  1. Try to reproduce the above plots if they are not already in your notebook.

    2. +

  2. Above we have plotted the monthly precipitation for two cities side by side +using a stacked plot. Try to arrive at the following plot where months are +along the y-axis and the precipitation amount is along the x-axis:

    +
    +../_images/precipitation-stacked-y.svg +
    +
    3. +

  3. Ask the Internet or AI how to change the axis title from “precipitation” +to “Precipitation (mm)”.

    4. +

  4. Modify the temperature range plot to show the temperature ranges for the +two cities side by side like this:

    +
    +../_images/temperature-ranges-side.svg +
    +
    5. +
+ +
+
+
+

More fun with visual channels

+

Now we will try to plot the daily data and look at snow depths. We first +read and concatenate two datasets:

+
url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/"
+
+data_tromso = pd.read_csv(url_prefix + "tromso-daily.csv")
+data_oslo = pd.read_csv(url_prefix + "oslo-daily.csv")
+
+data_daily = pd.concat([data_tromso, data_oslo], axis=0)
+
+
+

We adjust the data a bit:

+
# replace dd.mm.yyyy to date format
+data_daily["date"] = pd.to_datetime(list(data_daily["date"]), format="%d.%m.%Y")
+
+# we are here only interested in the range december to may
+data_daily = data_daily[
+    (data_daily["date"] > "2022-12-01") & (data_daily["date"] < "2023-05-01")
+]
+
+
+

Now we can plot the snow depths for the months December to May for the two +cities:

+
alt.Chart(data_daily).mark_bar().encode(
+    x="date",
+    y="snow depth",
+    column="name",
+)
+
+
+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway.

+
+
+

What happens if we try to color the plot by the “max temperature” values?

+
alt.Chart(data_daily).mark_bar().encode(
+    x="date",
+    y="snow depth",
+    color="max temperature",
+    column="name",
+)
+
+
+

The result looks neat:

+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature.

+
+
+

We can change the color scheme (available color schemes):

+
alt.Chart(data_daily).mark_bar().encode(
+    x="date",
+    y="snow depth",
+    color=alt.Color("max temperature").scale(scheme="plasma"),
+    column="name",
+)
+
+
+

With the following result:

+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth.

+
+
+

Let’s try one more change to show that we can experiment with different +plot types by changing mark_bar() to something else, in this case mark_circle():

+
alt.Chart(data_daily).mark_circle().encode(
+    x="date",
+    y="snow depth",
+    color=alt.Color("max temperature").scale(scheme="plasma"),
+    column="name",
+)
+
+
+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth.

+
+
+
+
+

Themes

+

In Vega-Altair you can change the theme and +select from a long list of themes. On +top of your notebook try to add:

+
alt.themes.enable('dark')
+
+
+

Then re-run all cells. Later you can try some other themes such as:

+
    +

  • fivethirtyeight

    • +

  • latimes

    • +

  • urbaninstitute

    • +
+

You can even define your own themes!

+
+ +
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/productivity/index.html b/branch/master/productivity/index.html new file mode 100644 index 00000000..0c1cfaa7 --- /dev/null +++ b/branch/master/productivity/index.html @@ -0,0 +1,382 @@ + + + + + + + + + + + + + + + Productivity tools — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Productivity tools

+
+

Objectives

+
    +

  • Know about tools that can help you spot code problems and help you following +a consistent code style without you having to do it manually.

    • +

  • Get an overview of AI-based tools and how they can help you +writing code.

    • +
+
+
+

Instructor note

+
    +

  • Demo/discussion: 20 min

    • +
+
+
+

Linters and formatters

+

Linter: Tool that analyzes source code to detect potential errors, unused +imports, unused variables, code style violations, and to improve readability.

+ +

Formatter: Tool that automatically formats your code to a consistent style, +for instance following PEP 8.

+ +

In this course we will focus on Ruff since it +can do both checking and formatting and you don’t have to switch between +multiple tools.

+
+

Linters and formatters can be configured to your liking

+

These tools typically have good defaults. But if you don’t like the defaults, +you can configure what they should ignore or how they should format or not format.

+
+
+
+

Examples

+

This code example (which we possibly recognize from the previous section about +Profiling and Tracing) +has few problems (highlighted):

+
import re
+import requests
+
+
+def count_unique_words(file_path: str) -> int:
+    unique_words = set()
+    forgotten_variable = 13
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower()))
+            for word in words:
+                unique_words.add(word)
+    return len(unique_words)
+
+
+

Please try whether you can locate these problems using Ruff:

+
$ ruff check
+
+
+

Next, let us try to auto-format a code example which is badly formatted and also difficult +to read:

+
+
import re
+def  count_unique_words (file_path : str)->int:
+  unique_words=set()
+  with open(file_path,"r",encoding="utf-8") as file:
+    for line in file:
+      words=re.findall(r"\b\w+\b",line.lower())
+      for word in words:
+        unique_words.add(word)
+  return len(   unique_words   )
+
+
+
+
+
+

Type checking

+

A (static) type checker is a tool that checks whether the types of variables in your +code match the types that you have specified.

+ +
+
+

Integration with editors

+

Many/most of the above tools can be integrated with your editor. For instance, +you can configure your editor to automatically format your code when you save +the file. However, this only makes sense when all team members agree to follow +the same style, otherwise saving and possibly committing changes to version +control will show up changes to code written by others which you possibly +didn’t intend to make.

+
+
+

Integration with Jupyter notebooks

+

It is possible to automatically format your code in Jupyter notebooks! +For this to work you need +the following three dependencies installed:

+
    +

  • jupyterlab-code-formatter

    • +

  • black

    • +

  • isort

    • +
+

More information and a screen-cast of how this works can be found at +https://jupyterlab-code-formatter.readthedocs.io/.

+
+
+

Integration with version control

+

If you use version control and like to have your code checked or formatted +before you commit the change, you can use tools like pre-commit.

+
+
+

AI-assisted coding

+

We can use AI as an assistant/apprentice:

+
    +

  • Code completion

    • +

  • Write a test based on an implementation

    • +

  • Write an implementation based on a test

    • +
+

Or we can use AI as a mentor:

+
    +

  • Explain a concept

    • +

  • Improve code

    • +

  • Show a different (possibly better) way of implementing the same thing

    • +
+
+Screenshot of ChatGPT + +
+

Example for using a chat-based AI tool.

+
+
+
+Screen-cast of working with GitHub Copilot + +
+

Example for using AI to complete code in an editor.

+
+
+
+

AI tools open up a box of questions

+
    +

  • Legal

    • +

  • Ethical

    • +

  • Privacy

    • +

  • Lock-in/ monopolies

    • +

  • Lack of diversity

    • +

  • Will we still need to learn programming?

    • +

  • How will it affect learning and teaching programming?

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/profiling/index.html b/branch/master/profiling/index.html new file mode 100644 index 00000000..f3b16cee --- /dev/null +++ b/branch/master/profiling/index.html @@ -0,0 +1,463 @@ + + + + + + + + + + + + + + + Profiling — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Profiling

+
+

Objectives

+
    +

  • Understand when improving code performance is worth the time and effort.

    • +

  • Knowing how to find performance bottlenecks in Python code.

    • +

  • Try scalene as one of many tools to profile Python code.

    • +
+
+
+

Instructor note

+
    +

  • Discussion: 20 min

    • +

  • Exercise: 20 min

    • +
+
+
+

Should we even optimize the code?

+

Classic quote to keep in mind: “Premature optimization is the root of all evil.” [Donald Knuth]

+
+

Discussion

+

It is important to ask ourselves whether it is worth it.

+
    +

  • Is it worth spending e.g. 2 days to make a program run 20% faster?

    • +

  • Is it worth optimizing the code so that it spends 90% less memory?

    • +
+

Depends. What does it depend on?

+
+
+
+

Measure instead of guessing

+

Before doing code surgery to optimize the run time or lower the memory usage, +we should measure where the bottlenecks are. This is called profiling.

+

Analogy: Medical doctors don’t start surgery based on guessing. They first measure +(X-ray, MRI, …) to know precisely where the problem is.

+

Not only programming beginners can otherwise guess wrong, but also experienced +programmers can be surprised by the results of profiling.

+
+
+

One of the simplest tools is to insert timers

+

Below we will list some tools that can be used to profile Python code. +But even without these tools you can find time-consuming parts of your code +by inserting timers:

+
import time
+
+
+# ...
+# code before the function
+
+
+start = time.time()
+result = some_function()
+print(f"some_function took {time.time() - start} seconds")
+
+
+# code after the function
+# ...
+
+
+
+
+

Many tools exist

+

The list below here is probably not complete, but it gives an overview of the +different tools available for profiling Python code.

+

CPU profilers:

+ +

Memory profilers:

+ +

Both CPU and memory:

+ +

In the exercise below, we will use Scalene to profile a Python program. Scalene +is a sampling profiler that can profile CPU, memory, and GPU usage of Python.

+
+
+

Tracing profilers vs. sampling profilers

+

Tracing profilers record every function call and event in the program, +logging the exact sequence and duration of events.

+
    +

  • Pros:

    +
      +

    • Provides detailed information on the program’s execution.

      • +

    • Deterministic: Captures exact call sequences and timings.

      • +
    +
    • +

  • Cons:

    +
      +

    • Higher overhead, slowing down the program.

      • +

    • Can generate larger amount of data.

      • +
    +
    • +
+

Sampling profilers periodically samples the program’s state (where it is +and how much memory is used), providing a statistical view of where time is +spent.

+
    +

  • Pros:

    +
      +

    • Lower overhead, as it doesn’t track every event.

      • +

    • Scales better with larger programs.

      • +
    +
    • +

  • Cons:

    +
      +

    • Less precise, potentially missing infrequent or short calls.

      • +

    • Provides an approximation rather than exact timing.

      • +
    +
    • +
+
+

Analogy: Imagine we want to optimize the London Underground (subway) system

+

We wish to detect bottlenecks in the system to improve the service and for this we have +asked few passengers to help us by tracking their journey.

+
    +

  • Tracing: We follow every train and passenger, recording every stop +and delay. When passengers enter and exit the train, we record the exact time +and location.

    • +

  • Sampling: Every 5 minutes the phone notifies the passenger to note +down their current location. We then use this information to estimate +the most crowded stations and trains.

    • +
+
+
+
+

Choosing the right system size

+

Sometimes we can configure the system size (for instance the time step in a simulation +or the number of time steps or the matrix dimensions) to make the program finish sooner.

+

For profiling, we should choose a system size that is representative of the real-world +use case. If we profile a program with a small input size, we might not see the same +bottlenecks as when running the program with a larger input size.

+

Often, when we scale up the system size, or scale the number of processors, new bottlenecks +might appear which we didn’t see before. This brings us back to: “measure instead of guessing”.

+
+
+

Exercises

+
+

Exercise: Practicing profiling

+

In this exercise we will use the Scalene profiler to find out where most of the time is spent +and most of the memory is used in a given code example.

+

Please try to go through the exercise in the following steps:

+
    +

  1. Make sure scalene is installed in your environment (if you have followed +this course from the start and installed the recommended software +environment, then it is).

    2. +

  2. Download Leo Tolstoy’s “War and Peace” from the following link (the text is +provided by Project Gutenberg): +https://www.gutenberg.org/cache/epub/2600/pg2600.txt +(right-click and “save as” to download the file and save it as “book.txt”).

    3. +

  3. Before you run the profiler, try to predict in which function the code +will spend most of the time and in which function it will use most of the +memory.

    4. +

  4. Run the scalene profiler on the following code example and browse the +generated HTML report to find out where most of the time is spent and where +most of the memory is used:

    +
    $ scalene example.py
+
    +
    +

    Alternatively you can do this (and then open the generated file in a browser):

    +
    $ scalene example.py --html > profile.html
+
    +
    +

    You can find an example of the generated HTML report in the solution below.

    +
    5. +

  5. Does the result match your prediction? Can you explain the results?

    6. +
+
"""
+The code below reads a text file and counts the number of unique words in it
+(case-insensitive).
+"""
+import re
+
+
+def count_unique_words1(file_path: str) -> int:
+    with open(file_path, "r", encoding="utf-8") as file:
+        text = file.read()
+    words = re.findall(r"\b\w+\b", text.lower())
+    return len(set(words))
+
+
+def count_unique_words2(file_path: str) -> int:
+    unique_words = []
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower())
+            for word in words:
+                if word not in unique_words:
+                    unique_words.append(word)
+    return len(unique_words)
+
+
+def count_unique_words3(file_path: str) -> int:
+    unique_words = set()
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower())
+            for word in words:
+                unique_words.add(word)
+    return len(unique_words)
+
+
+def main():
+    # book.txt is downloaded from https://www.gutenberg.org/cache/epub/2600/pg2600.txt
+    _result = count_unique_words1("book.txt")
+    _result = count_unique_words2("book.txt")
+    _result = count_unique_words3("book.txt")
+
+
+if __name__ == "__main__":
+    main()
+
+
+ +
+
+
+

Additional resources

+ +
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/python/index.html b/branch/master/python/index.html new file mode 100644 index 00000000..2c791240 --- /dev/null +++ b/branch/master/python/index.html @@ -0,0 +1,337 @@ + + + + + + + + + + + + + + + Introduction to Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Introduction to Python

+
+

Questions

+
    +

  • What are the basic blocks of Python language?

    • +

  • How are functions and classes defined in Python?

    • +
+
+
+

Objectives

+
    +

  • Get a very short introduction to Python types and syntax

    • +

  • Be able to follow the rest of the examples in the course, even if you don’t understand everything perfectly.

    • +
+

We expect everyone to be able to know the following basic material +to follow the course (though it is not everything you need to +know about Python).

+
+

If you are not familiar with Python, here is a very short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise.

+
+

See also

+

This page contains an overview of the basics of Python. You can +also refer to This Python overview from a different lesson +which is slightly more engaging.

+
+
+

Scalars

+

Scalar types, that is, single elements of various types:

+
i = 42       # integer
+i = 2**77    # Integers have arbitrary precision
+g = 3.14     # floating point number
+c = 2 - 3j   # Complex number
+b = True     # boolean
+s = "Hello!" # String (Unicode)
+q = b'Hello' # bytes (8-bit values)
+
+
+

Read more: int, float, complex, +bool, str, bytes.

+
+
+

Collections

+

Collections are data structures capable of storing multiple values.

+
l = [1, 2, 3]                      # list
+l[1]                               # lists are indexed by int
+l[1] = True                        # list elements can be any type
+d = {"Janne": 123, "Richard": 456} # dictionary
+d["Janne"]
+s = set(("apple", "cherry", "banana", "apple")) # Set of unique values
+s
+
+
+

Read more: list, tuple, dict, set.

+
+
+

Control structures

+

Python has the usual control structures, that is conditional +statements and loops. For example, the The if statement statement:

+
x = 2
+if x == 3:
+    print('x is 3')
+elif x == 2:
+    print('x is 2')
+else:
+    print('x is something else')
+
+
+

While loops loop until some condition is met:

+
x = 0
+while x < 42:
+    print('x is ', x)
+    x += 0.2
+
+
+

For loops loop over some collection of values:

+
xs = [1, 2, 3, 4]
+for x in xs:
+    print(x)
+
+
+

Often you want to loop over a sequence of integers, in that case the +range function is useful:

+
for x in range(9):
+    print(x)
+
+
+

Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the enumerate() +function:

+
xs = [1, 'hello', 'world']
+for ii, x in enumerate(xs):
+    print(ii, x)
+
+
+
+
+

Functions and classes

+

Python functions are defined by the Function definitions keyword. They take a +number of arguments, and return a number of return values.

+
def hello(name):
+    """Say hello to the person given by the argument"""
+    print('Hello', name)
+    return 'Hello ' + name
+
+hello("Anne")
+
+
+

Classes are defined by the Class definitions keyword:

+
class Hello:
+    def __init__(self, name):
+        self._name = name
+    def say(self):
+        print('Hello', self._name)
+
+h = Hello("Richard")
+h.say()
+
+
+
+
+

Python type system

+

Python is strongly and dynamically typed.

+

Strong here means, roughly, that it’s not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior).

+
x = 42
+type(x)
+x + "hello"
+
+
+

Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type:

+
x = 42
+x = "hello"
+
+
+

Jargon: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation.

+

??? (lesson here)

+
+

Keypoints

+
    +

  • Python offers a nice set of basic types as many other programming languages

    • +

  • Python is strongly typed and dynamically typed

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/quick-reference/index.html b/branch/master/quick-reference/index.html new file mode 100644 index 00000000..9c35bfd0 --- /dev/null +++ b/branch/master/quick-reference/index.html @@ -0,0 +1,192 @@ + + + + + + + + + + + + + + + Quick reference — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Quick reference

+ +
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/scipy/index.html b/branch/master/scipy/index.html new file mode 100644 index 00000000..01013dbb --- /dev/null +++ b/branch/master/scipy/index.html @@ -0,0 +1,350 @@ + + + + + + + + + + + + + + + SciPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

SciPy

+
+

Questions

+
    +

  • When you need more advanced mathematical functions, where do you +look?

    • +
+
+
+

Objectives

+
    +

  • Understand that SciPy exists and what kinds of things it has.

    • +

  • Understand the importance of using external libraries and how to +use them.

    • +

  • Understand the purpose of wrapping existing C/Fortran code.

    • +

  • Non-objective: know details of everything (or anything) in SciPy.

    • +
+
+
+

See also

+ +
+

SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms.

+
+

What’s in SciPy?

+

Briefly, it contains functionality for

+
    +

  • Special functions (Bessel, Gamma, etc.)

    • +

  • Numerical integration

    • +

  • Optimization

    • +

  • Interpolation

    • +

  • Fast Fourier Transform (FFT)

    • +

  • Signal processing

    • +

  • Linear algebra (more complete than in NumPy)

    • +

  • Sparse matrices

    • +

  • Statistics

    • +

  • More I/O routine, e.g. Matrix Market format for sparse matrices, +MATLAB files (.mat), etc.

    • +
+

Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages.

+

Most functions are documented ridiculously well from a scientific +standpoint: you aren’t just using some unknown function, but have a +full scientific description and citation to the method and +implementation.

+
+
+

Exercises: use SciPy

+

These exercises do not exist because you might need these +functions someday. They are because you will need to read +documentation and understand documentation of an an external library +eventually.

+
+

1: Numerical integration

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+ +
+
+

2: Sparse matrices

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+ +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • When you need advance math or scientific functions, let’s just +admit it: you do a web search first.

    • +

  • But when you see something in SciPy come up, you know your +solutions are in good hands.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/scripts/index.html b/branch/master/scripts/index.html new file mode 100644 index 00000000..a9a4ddec --- /dev/null +++ b/branch/master/scripts/index.html @@ -0,0 +1,589 @@ + + + + + + + + + + + + + + + Scripts — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Scripts

+
+

Questions

+
    +

  • Why are command line programs useful, compared to Jupyter +notebooks and similar?

    • +

  • How to create a Python script?

    • +

  • How to generalize a Python script?

    • +
+
+
+

Objectives

+
    +

  • Learn how to streamline your Python notebooks by creating repeatable Python scripts

    • +

  • Learn how to import other Python files

    • +

  • Learn to parse command line arguments in Python

    • +
+
+
+

Why scripts?

+

So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work.

+

But after several weeks of hard work with Python, you may end up:

+
    +

  • either with 10 different notebooks (so that you can run them concurrently)

    • +

  • or with a very long notebook which is becoming hardly readable!

    • +
+

Let’s imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks?

+

In this episode, we will learn how to automate your work using Python scripts so that

+
    +

  • you do not need to manually configure your notebooks to be able to run with different parameters

    • +

  • can easily run you work via other tools, such as on computing clusters.

    • +
+
+
+

From Jupyter notebooks to Python scripts

+
+
+

Save as Python script

+

Jupyter notebooks can be parameterized for instance using papermill. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See CodeRefinery’s lesson on Modular code development.

+

You need to convert the notebook to a Python file. +Check the JupyterLab documentation for more information. +You can get a command line by (File → New Launcher → Terminal - if you +go through New Launcher, your command line will be in the directory +you are currently browsing), you can convert files in the terminal by running:

+
$ jupyter nbconvert --to script your_notebook_name.ipynb
+
+
+

If nbconvert doesn’t work, within JupyterLab, you can export any +Jupyter notebook to a Python +script, but this downloads it to your own computer and then you need +to copy it to a place you are working (maybe upload it back to +JupyterLab?):

+
+JupyterLab screenshot as described in caption. + +
+

Select File (top menu bar) → Export Notebook as → Export notebook to Executable Script.

+
+
+
+
+

Exercises 1

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Hint: Copy the URL above (right-click) and in JupyterLab, use +File → Open from URL → Paste the URL. It will both download it to +the directory JupyterLab is in and open it for you.

    +
    2. +

  2. Open a terminal in Jupyter: File → New Launcher, then click +“Terminal” there. (if you do it this way, it will be in the right +directory. File → New → Terminal might not be.)

    3. +

  3. Convert the Jupyter script to a Python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+
+
+

Command line arguments with sys.argv

+

We now have a Python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +What we need is to allow the code to do something different based on something outside the code itself: in this case, to +plot information for different time ranges. This can be achieved by +using Pythons sys package, which provides access to arguments given to the Python interpreter at +startup in the sys.argv list. The first (i.e. sys.argv[0] entry of this array is the script that is running, +and any further argument (separated by space) is appended to this list, like such:

+
$ python my_script.py A B
+$ # sys.argv[1] is 'A'
+$ # sys.argv[2] is 'B'
+
+
+

Lets see how it works: We modify the weather_observations.py script such that we allow start +and end times as well as the output file to be passed in as arguments +to the function. Open it (find the .py file from the JupyterLab +file browser) and make these edits:

+
import sys
+import pandas as pd
+
+# define the start and end time for the plot
+start_date = pd.to_datetime(sys.argv[1], dayfirst=True)
+end_date = pd.to_datetime(sys.argv[2], dayfirst=True)
+...
+
+# select the data
+weather = weather[weather['Local time'].between(start_date,end_date)]
+...
+
+# save the figure
+output_file_name = sys.argv[3]
+fig.savefig(output_file_name)
+
+
+

We can try it out (see the file spring_in_tapiola.png made in the +file browser):

+
$ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png
+
+
+
+

Discussion

+
    +

  • Does it work?

    • +

  • Why is this better than modifying the script every time I want it to +plot data for a different period?

    • +

  • What problems do you expect when using this approach (using sys.argv)?

    • +
+
+

This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time:

+
    +

  • argparse: +built-in to Python, this is the one that we will show below.

    • +

  • doctopt: you write the help text and this generates a parser for you.

    • +

  • click: another nice +library for command line interfaces - very easy to use.

    • +
+
+
+

Parsing command line arguments with argparse

+

Argparse not only gives you descriptive command line arguments, it also automatically +generates a --help option for you. To use argparse you first set up a parser +by calling parser = argparse.ArgumentParser() and then you add arguments using +parser.add_argument(args). There are two different types of arguments:

+
    +

  • Positional arguments

    • +

  • Optional arguments

    • +
+

Positional arguments are detected by their order, while optional arguments need to be +given with their respective flags ( like --name or -n). +The following example would parse a positional argument Name of type string +and an optional argument date of type string which defaults to 01/01/2000.

+
import argparse
+
+parser = argparse.ArgumentParser()
+# One positional and one optional argument
+parser.add_argument('name', type=str, metavar="N",
+                    help="The name of the subject")
+parser.add_argument('-d', '--date', type=string, default="01/01/2000",
+                    help="Birth date of the subject")
+
+args = parser.parse_args()
+
+print(args.name + " was born on " + args.date)
+
+
+

If this code was in birthday.py and we would call python birthday.py --help it +would show the following message:

+
$ python birthday.py --help
+usage: birthday.py [-h] [-d DATE] N
+
+positional arguments:
+  N                     The name of the subject
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d DATE, --date DATE  Birth date of the subject
+
+
+
+
+

Exercises 2

+
+

Scripts-2

+
    +

  1. Take the Python script (weather_observations.py) we have written in the preceding exercise and use +argparse to specify the input (URL) and output files and allow the start and end dates to be set.

    +
      +

    • Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on.

      • +

    • Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output.

      • +

    • Hint: The start and end dates should be optional parameters with the defaults as they are in the current script.

      • +
    +
    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). +Also try using this data for Cairo: https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv

    3. +
+
+ +
+

Discussion

+

What was the point of doing this?

+

Now you can do this:

+
$ python weather_observations.py --help
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png
+$ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png
+$ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv temperature_cairo.png
+
+
+
    +

  • We can now process different input files without changing the script.

    • +

  • We can select multiple time ranges without modifying the script.

    • +

  • We can easily save these commands to know what we did.

    • +

  • This way we can also loop over file patterns (using shell loops or similar) or use +the script in a workflow management system and process many files in parallel.

    • +

  • By changing from sys.argv to argparse we made the script more robust against +user input errors and also got a help text (accessible via --help).

    • +
+
+
+
+

Load larger option lists using config files

+

In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line:

+
$ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021
+
+
+

This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple Parameter = Value +format, and parse it yourself, or you can use e.g. the JSON or YAML formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won’t go into the details of the formats, and will only give +a short example using YAML here.

+

The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (yaml) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the json package).

+

The Python module optionsparser.py provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values.

+

In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation …), set the labels and titles explicitly etc.

+

In the YAML format, names and values are separated by :. Our above example would therefore translate to the following YAML file:

+
input:        https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv
+output:       rain_in_cairo.png
+xlabel:       Days in June
+ylabel:       Rainfall in mm
+title:        Rainfall in Cairo
+data_column:  RRR
+start:        01/06/2021
+end:          30/06/2021
+
+
+
+
+

Exercises 3 (optional)

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+ +

What did this config file parser get us? Now, we have separated the +code from the configuration. We could save all the configuration in +version control - separately and have one script that runs them. If +done right, our work could be much more reproducible and +understandable.

+
+

Further reading

+ +
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/search/index.html b/branch/master/search/index.html new file mode 100644 index 00000000..2a5c0652 --- /dev/null +++ b/branch/master/search/index.html @@ -0,0 +1,167 @@ + + + + + + + + Search — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+
+ +
+ +
+

© Copyright 2020-2024, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/branch/master/searchindex.js b/branch/master/searchindex.js new file mode 100644 index 00000000..855c83ea --- /dev/null +++ b/branch/master/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"alltitles": {"(advanced) Parallel-2 Running on a cluster": [[3, "exercise-1"], [13, "exercise-1"]], "1: Numerical integration": [[21, "numerical-integration"]], "2: Sparse matrices": [[21, "sparse-matrices"]], "A fast thing + a fast thing = a fast thing?": [[10, "a-fast-thing-a-fast-thing-a-fast-thing"]], "A quick Pandas preview": [[12, "a-quick-pandas-preview"]], "AI tools open up a box of questions": [[17, null]], "AI-assisted coding": [[17, "ai-assisted-coding"]], "API which requires parameters": [[23, "api-which-requires-parameters"]], "About each section": [[4, "about-each-section"]], "Accessing and manipulating data in Xarray": [[25, "accessing-and-manipulating-data-in-xarray"]], "Adding more packages to existing environments": [[2, "adding-more-packages-to-existing-environments"]], "Additional exercises": [[9, "additional-exercises"]], "Additional resources": [[18, "additional-resources"]], "Additional tips and tricks": [[2, "additional-tips-and-tricks"]], "Advanced NumPy": [[3, "advanced-numpy"], [10, null]], "Advanced Topics": [[25, "advanced-topics"]], "After exercises: Saving retrieved data to disk": [[23, "after-exercises-saving-retrieved-data-to-disk"]], "Alternatives to Pandas": [[12, "alternatives-to-pandas"]], "An example: matrix transpose": [[10, "an-example-matrix-transpose"]], "Analogy: Imagine we want to optimize the London Underground (subway) system": [[18, "discussion-1"]], "Analyze the Nobel prize dataset": [[3, "exercise-2"], [12, "exercise-2"]], "Analyze the Titanic passenger list dataset": [[3, "exercise-1"], [12, "exercise-1"]], "Another example: reshaping": [[10, "another-example-reshaping"]], "Array maths and vectorization": [[9, "array-maths-and-vectorization"]], "Attending the course 5-7 November, 2024?": [[5, null]], "Bad things": [[24, "bad-things"], [24, "id2"]], "Beyond the basics": [[12, "beyond-the-basics"]], "Binary File formats": [[24, "binary-file-formats"]], "Binder": [[0, null], [3, "binder"]], "Binder exercise/demo": [[0, "binder-exercise-demo"]], "Binder-1: Discuss better strategies than only code sharing (10 min)": [[0, "exercise-0"], [3, "exercise-0"]], "Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)": [[0, "exercise-1"], [3, "exercise-1"]], "Binder-3: Link a Github repository with Zenodo (optional)": [[0, "exercise-2"], [3, "exercise-2"]], "Binder-4: Link Binder with Zenodo (10 min)": [[0, "exercise-3"], [3, "exercise-3"]], "Building a conda package and share it": [[11, "building-a-conda-package-and-share-it"]], "Building a conda package from scratch": [[11, "callout-3"]], "Building a python package with conda skeleton pypi": [[11, "building-a-python-package-with-conda-skeleton-pypi"]], "CSV (comma-separated values)": [[1, "csv-comma-separated-values"]], "Case study: Converting untidy data to tidy data": [[24, "case-study-converting-untidy-data-to-tidy-data"]], "Choosing the right system size": [[18, "choosing-the-right-system-size"]], "Collections": [[19, "collections"]], "Command line": [[6, "command-line"]], "Command line arguments with sys.argv": [[22, "command-line-arguments-with-sys-argv"]], "Conda": [[2, null]], "Conda ecosystem explained": [[2, "conda-ecosystem-explained"]], "Conda package location": [[11, "callout-2"]], "Connecting Python to other languages": [[8, "connecting-python-to-other-languages"]], "Control structures": [[19, "control-structures"]], "Converting Xarray objects to NumPy, Pandas and NetCDF": [[25, "converting-xarray-objects-to-numpy-pandas-and-netcdf"]], "Copy versus view": [[10, "copy-versus-view"]], "Core numerics libraries": [[8, "core-numerics-libraries"]], "Coupling to other languages": [[13, "coupling-to-other-languages"]], "Create a Binder link for your Zenodo DOI": [[0, "create-a-binder-link-for-your-zenodo-doi"]], "Creating Python environments": [[2, "creating-python-environments"]], "Creating arrays": [[9, "creating-arrays"]], "Creating environments without environment.yml/requirements.txt": [[2, null]], "Creating your own Xarray Dataset": [[25, "creating-your-own-xarray-dataset"]], "Credits": [[5, "credits"]], "Dask": [[13, "dask"]], "Dask and task queues": [[13, "dask-and-task-queues"]], "Dask-Examples (optional)": [[3, "exercise-3"], [13, "exercise-3"]], "Data analysis and other important core packages": [[8, "data-analysis-and-other-important-core-packages"]], "Data type vs. data structure vs. file format": [[24, null]], "Demo": [[11, "demo-0"]], "Dependencies-1: Discuss dependency management (5 min)": [[2, "exercise-0"], [3, "exercise-0"]], "Dependencies-2: Package language detective (5 min)": [[2, "exercise-1"], [3, "exercise-1"]], "Dependencies-3: Create a Python environment (15 min)": [[2, "exercise-2"], [3, "exercise-2"]], "Dependencies-4: Export an environment (15 min)": [[2, "exercise-3"], [3, "exercise-3"]], "Dependency management": [[2, null], [3, "dependency-management"]], "Discussion": [[15, "discussion-2"], [18, "discussion-0"], [22, "discussion-0"], [22, "discussion-1"]], "Do it in parallel with multiprocessing": [[14, "do-it-in-parallel-with-multiprocessing"]], "Do it in \u201cparallel\u201d with threads": [[14, "do-it-in-parallel-with-threads"]], "Do you need help?": [[6, null]], "Evaluating Python packages for reuse": [[8, "evaluating-python-packages-for-reuse"]], "Example data: Weather data from two Norwegian cities": [[16, "example-data-weather-data-from-two-norwegian-cities"]], "Example from dask.org": [[13, "discussion-0"]], "Example walk-through for the slider cutoff example": [[3, "solution-1"], [16, "solution-1"]], "Examples": [[17, "examples"]], "Excel": [[1, "excel"]], "Exercise": [[1, "exercise-0"], [1, "exercise-1"], [1, "exercise-2"], [3, "exercise-0"], [3, "exercise-0"], [3, "exercise-1"], [3, "exercise-0"], [3, "exercise-1"], [3, "exercise-2"], [21, "exercise-0"], [21, "exercise-1"], [24, "exercise"], [24, "exercise-0"]], "Exercise 1": [[0, "exercise-1"], [1, "exercise-1"], [2, "exercise-1"], [10, "exercise-1"]], "Exercise 2": [[1, "exercise-2"], [2, "exercise-2"], [10, "exercise-2"]], "Exercise 3": [[1, "exercise-3"], [2, "exercise-3"]], "Exercise 4": [[2, "exercise-4"]], "Exercise Customization-1: log scale in Matplotlib (15 min)": [[3, "exercise-1"], [15, "exercise-1"]], "Exercise Customization-2: preparing a plot for publication (15 min)": [[3, "exercise-2"], [15, "exercise-2"]], "Exercise Matplotlib-1: extend the previous example (15 min)": [[3, "exercise-0"], [15, "exercise-0"]], "Exercise WebAPIs-1: Request different activity suggestions from the Bored API": [[3, "exercise-0"], [23, "exercise-0"]], "Exercise WebAPIs-2: Examine request and response headers": [[3, "exercise-1"], [23, "exercise-1"]], "Exercise WebAPIs-3: Scrape links from a webpage (Advanced)": [[3, "exercise-2"], [23, "exercise-2"]], "Exercise: Adapting a gallery example": [[16, "exercise-adapting-a-gallery-example"]], "Exercise: Matplotlib": [[15, "exercise-matplotlib"]], "Exercise: Numpy-3": [[3, "exercise-2"], [9, "exercise-2"]], "Exercise: Practicing profiling": [[3, "exercise-0"], [18, "exercise-0"]], "Exercise: Using visual channels to re-arrange plots": [[16, "exercise-using-visual-channels-to-re-arrange-plots"]], "Exercises": [[8, "exercises"], [18, "exercises"]], "Exercises 1": [[7, "exercises-1"], [9, "exercises-1"], [11, "exercises-1"], [12, "exercises-1"], [22, "exercises-1"], [23, "exercises-1"], [25, "exercises-1"]], "Exercises 2": [[7, "exercises-2"], [9, "exercises-2"], [12, "exercises-2"], [22, "exercises-2"], [23, "exercises-2"], [25, "exercises-2"]], "Exercises 3": [[7, "exercises-3"], [9, "exercises-3"], [10, "exercises-3"], [12, "exercises-3"], [23, "exercises-3"]], "Exercises 3 (optional)": [[22, "exercises-3-optional"]], "Exercises 4": [[9, "exercises-4"]], "Exercises, Dask": [[13, "exercises-dask"]], "Exercises, MPI": [[13, "exercises-mpi"]], "Exercises, multiprocessing": [[13, "exercises-multiprocessing"]], "Exercises: Jupyter-1": [[3, "exercise-0"], [7, "exercise-0"]], "Exercises: Jupyter-2": [[3, "exercise-1"], [7, "exercise-1"]], "Exercises: Jupyter-3": [[3, "exercise-2"], [7, "exercise-2"]], "Exercises: Numpy-1": [[3, "exercise-0"], [9, "exercise-0"]], "Exercises: Numpy-2": [[3, "exercise-1"], [9, "exercise-1"]], "Exercises: Numpy-4": [[3, "exercise-3"], [9, "exercise-3"]], "Exercises: Numpy-Advanced-1": [[3, "exercise-0"], [10, "exercise-0"]], "Exercises: Numpy-Advanced-2": [[3, "exercise-1"], [10, "exercise-1"]], "Exercises: Numpy-Advanced-3": [[3, "exercise-2"], [10, "exercise-2"]], "Exercises: Styling and customization": [[15, "exercises-styling-and-customization"]], "Exercises: Xarray-1": [[3, "exercise-0"], [25, "exercise-0"]], "Exercises: Xarray-2": [[3, "exercise-1"], [25, "exercise-1"]], "Exercises: use SciPy": [[21, "exercises-use-scipy"]], "Exploring dataframes": [[3, "exercise-0"], [12, "exercise-0"]], "Exporting package versions from an existing environment": [[2, "exporting-package-versions-from-an-existing-environment"]], "Feather": [[1, "feather"]], "From Jupyter notebooks to Python scripts": [[22, "from-jupyter-notebooks-to-python-scripts"]], "Full list": [[3, "full-list"]], "Functions and classes": [[19, "functions-and-classes"]], "Further considerations": [[24, "further-considerations"]], "Further reading": [[22, null]], "Future ideas": [[14, "future-ideas"]], "Getting help": [[12, "callout-0"]], "Getting started with Jupyter": [[7, "getting-started-with-jupyter"]], "Getting started with Matplotlib": [[15, "getting-started-with-matplotlib"]], "Glossary": [[8, "glossary"]], "Good things": [[24, "good-things"], [24, "id1"]], "Graph formats (adjency lists, gt, GraphML etc.)": [[1, "graph-formats-adjency-lists-gt-graphml-etc"]], "HDF5 (Hierarchical Data Format version 5)": [[1, "hdf5-hierarchical-data-format-version-5"]], "How can I get a DOI from Zenodo?": [[0, "how-can-i-get-a-doi-from-zenodo"]], "How do you track dependencies of your project?": [[2, "how-do-you-track-dependencies-of-your-project"]], "How to communicate the dependencies as part of a report/thesis/publication": [[2, "how-to-communicate-the-dependencies-as-part-of-a-report-thesis-publication"]], "In depth analysis of some selected file formats": [[1, null], [3, "in-depth-analysis-of-some-selected-file-formats"]], "Indexing and Slicing": [[9, "indexing-and-slicing"]], "Instructor note": [[16, "instructor-note-0"], [17, "instructor-note-0"], [18, "instructor-note-0"]], "Instructor\u2019s guide": [[4, null]], "Integration with Jupyter notebooks": [[17, "integration-with-jupyter-notebooks"]], "Integration with editors": [[17, "integration-with-editors"]], "Integration with version control": [[17, "integration-with-version-control"]], "Interactive computing and human interface": [[8, "interactive-computing-and-human-interface"]], "Introduction to Python": [[19, null]], "Is your work reuseable?": [[8, "is-your-work-reuseable"]], "JSON (JavaScript Object Notation)": [[1, "json-javascript-object-notation"]], "Jupyter": [[3, "jupyter"], [7, null]], "JupyterLab": [[6, "jupyterlab"]], "Key features": [[1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null]], "Key points": [[24, null]], "Keypoints": [[0, "keypoints-0"], [2, "keypoints-0"], [7, "keypoints-0"], [8, "keypoints-0"], [9, "keypoints-0"], [10, "keypoints-0"], [11, "keypoints-0"], [12, "keypoints-0"], [13, "keypoints-0"], [15, "keypoints-0"], [16, "keypoints-0"], [19, "keypoints-0"], [21, "keypoints-0"], [23, "keypoints-0"], [24, "keypoints-0"]], "Learner personas": [[4, "learner-personas"]], "Let us pause and explain the code": [[16, "discussion-0"]], "Libraries 1.1": [[3, "solution-0"], [8, "solution-0"]], "Libraries 1.1: Libraries in your work": [[3, "exercise-0"], [8, "exercise-0"]], "Libraries 1.2": [[3, "solution-1"], [8, "solution-1"]], "Libraries 1.2: Evaluating packages": [[3, "exercise-1"], [8, "exercise-1"]], "Library ecosystem": [[3, "library-ecosystem"], [8, null]], "Linear algebra and other advanced math": [[9, "linear-algebra-and-other-advanced-math"]], "Linters and formatters": [[17, "linters-and-formatters"]], "Linters and formatters can be configured to your liking": [[17, "discussion-0"]], "List of exercises": [[3, null]], "Load larger option lists using config files": [[22, "load-larger-option-lists-using-config-files"]], "MPI": [[13, "mpi"]], "Machine learning": [[8, "machine-learning"]], "Many tools exist": [[18, "many-tools-exist"]], "Matplotlib and pandas DataFrames": [[15, "matplotlib-and-pandas-dataframes"]], "Matplotlib has two different interfaces": [[15, "matplotlib-has-two-different-interfaces"]], "Measure instead of guessing": [[18, "measure-instead-of-guessing"]], "Modes of parallelism": [[13, "modes-of-parallelism"]], "More fun with visual channels": [[16, "more-fun-with-visual-channels"]], "Motivation": [[5, "motivation"]], "Multithreading and the GIL": [[13, "multithreading-and-the-gil"]], "Need help?": [[6, "need-help"]], "NetCDF4 (Network Common Data Form version 4)": [[1, "netcdf4-network-common-data-form-version-4"]], "NumPy": [[3, "numpy"], [9, null]], "NumPy can be really fast": [[10, "numpy-can-be-really-fast"]], "NumPy tries to avoid copying data": [[10, "numpy-tries-to-avoid-copying-data"]], "Numpy-5": [[3, "exercise-4"], [9, "exercise-4"]], "Objectives": [[0, "objectives-0"], [2, "objectives-0"], [7, "objectives-0"], [8, "objectives-0"], [9, "objectives-0"], [10, "objectives-0"], [11, "objectives-0"], [12, "objectives-0"], [13, "objectives-0"], [15, "objectives-0"], [16, "objectives-0"], [17, "objectives-0"], [18, "objectives-0"], [19, "objectives-0"], [21, "objectives-0"], [22, "objectives-0"], [23, "objectives-0"], [24, "objectives-0"], [25, "objectives-0"]], "One of the simplest tools is to insert timers": [[18, "one-of-the-simplest-tools-is-to-insert-timers"]], "Organizing Python projects": [[11, "organizing-python-projects"]], "Other editors": [[6, null]], "Other file formats": [[1, "other-file-formats"]], "Other ways to access the command line": [[6, null]], "Packaging": [[3, "packaging"], [11, null]], "Packaging-1": [[3, "exercise-0"], [11, "exercise-0"]], "Pandas": [[3, "pandas"], [12, null]], "Parallel programming": [[3, "parallel-programming"], [13, null]], "Parallel-1, multiprocessing": [[3, "exercise-0"], [13, "exercise-0"]], "Parallel-3, MPI": [[3, "exercise-2"], [13, "exercise-2"]], "Parquet": [[1, "parquet"]], "Parsing command line arguments with argparse": [[22, "parsing-command-line-arguments-with-argparse"]], "Pickle": [[1, "pickle"]], "Pinning package versions": [[2, "pinning-package-versions"]], "Plotting": [[8, "plotting"]], "Plotting data in Xarray": [[25, "plotting-data-in-xarray"]], "Plotting the data": [[16, "plotting-the-data"]], "Plotting with Matplotlib": [[3, "plotting-with-matplotlib"], [15, null]], "Plotting with Vega-Altair": [[3, "plotting-with-vega-altairhttpsaltair-vizgithubio"], [16, null]], "Plotting-1: Using visual channels to re-arrange plots": [[3, "exercise-0"], [16, "exercise-0"]], "Plotting-2: Adapting a gallery example": [[3, "exercise-1"], [16, "exercise-1"]], "Prerequisites": [[5, "prerequisites-0"], [11, "callout-0"]], "Productivity tools": [[17, null]], "Profiling": [[3, "profiling"], [18, null]], "Pros and cons": [[24, "pros-and-cons"]], "Publishing a python package": [[11, "publishing-a-python-package"]], "PyPI": [[2, null]], "PyPI (The Python Package Index) and conda ecosystem": [[2, "pypi-the-python-package-index-and-conda-ecosystem"]], "Python": [[6, "python"]], "Python 2 vs Python 3": [[5, "python-2-vs-python-3"]], "Python environments": [[2, "python-environments"]], "Python for SciComp software environment": [[6, "python-for-scicomp-software-environment"]], "Python for Scientific Computing": [[5, null]], "Python multithreading solution": [[14, null]], "Python type system": [[19, "python-type-system"]], "Python, conda, anaconda, miniforge, etc?": [[6, null]], "Questions": [[0, "questions-0"], [2, "questions-0"], [7, "questions-0"], [8, "questions-0"], [9, "questions-0"], [10, "questions-0"], [11, "questions-0"], [12, "questions-0"], [13, "questions-0"], [15, "questions-0"], [19, "questions-0"], [21, "questions-0"], [22, "questions-0"], [23, "questions-0"], [24, "questions-0"], [25, "questions-0"]], "Quick reference": [[20, null]], "Reading data into a dataframe": [[16, "reading-data-into-a-dataframe"]], "Reference": [[5, null]], "Remark": [[11, "callout-1"]], "Repeatability/reproducibility": [[15, "repeatability-reproducibility"], [16, "repeatability-reproducibility"]], "Requests": [[23, "requests"]], "Requires additional packages": [[1, null], [1, null], [1, null], [1, null]], "Retrieve data from API": [[23, "retrieve-data-from-api"]], "Running code in Jupyter": [[7, "running-code-in-jupyter"]], "Save as Python script": [[22, "save-as-python-script"]], "Scalars": [[19, "scalars"]], "SciPy": [[3, "scipy"], [21, null]], "Scripts": [[3, "scripts"], [22, null]], "Scripts-1": [[3, "exercise-0"], [22, "exercise-0"]], "Scripts-2": [[3, "exercise-1"], [22, "exercise-1"]], "Scripts-3": [[3, "exercise-2"], [22, "exercise-2"]], "See also": [[2, "see-also"], [5, "see-also"], [6, "see-also"], [7, "see-also"], [8, "see-also"], [9, "see-also"], [10, "see-also"], [13, "see-also"], [21, "see-also"], [24, "see-also"]], "Sharing a computing environment with Binder": [[0, "sharing-a-computing-environment-with-binder"]], "Sharing packages via PyPI": [[11, "sharing-packages-via-pypi"]], "Should we even optimize the code?": [[18, "should-we-even-optimize-the-code"]], "Software installation": [[6, null]], "Solution": [[1, "solution-0"], [1, "solution-1"], [1, "solution-2"], [2, "solution-0"], [3, "solution-0"], [3, "solution-1"], [3, "solution-2"], [3, "solution-0"], [3, "solution-1"], [3, "solution-2"], [3, "solution-0"], [3, "solution-0"], [3, "solution-0"], [3, "solution-1"], [3, "solution-0"], [3, "solution-0"], [3, "solution-1"], [3, "solution-0"], [3, "solution-0"], [3, "solution-1"], [3, "solution-2"], [3, "solution-0"], [3, "solution-1"], [3, "solution-2"], [12, "solution-0"], [12, "solution-1"], [12, "solution-2"], [13, "solution-0"], [13, "solution-1"], [13, "solution-2"], [15, "solution-0"], [15, "solution-1"], [15, "solution-2"], [16, "solution-0"], [18, "solution-0"], [21, "solution-0"], [21, "solution-1"], [22, "solution-0"], [22, "solution-1"], [24, "solution-0"]], "Solution Numpy-5": [[3, "solution-4"], [9, "solution-4"]], "Solution: Numpy-3": [[3, "solution-2"], [9, "solution-2"]], "Solution: Numpy-4": [[3, "solution-3"], [9, "solution-3"]], "Solutions: Jupyter-2": [[3, "solution-0"], [7, "solution-0"]], "Solutions: Numpy-1": [[3, "solution-0"], [9, "solution-0"]], "Solutions: Numpy-2": [[3, "solution-1"], [9, "solution-1"]], "Solutions: Numpy-Advanced-1": [[3, "solution-0"], [10, "solution-0"]], "Solutions: Numpy-Advanced-2": [[3, "solution-1"], [10, "solution-1"]], "Solutions: Numpy-Advanced-3": [[3, "solution-2"], [10, "solution-2"]], "Solutions: Xarray-1": [[3, "solution-0"], [25, "solution-0"]], "Solutions: Xarray-2": [[3, "solution-1"], [25, "solution-1"]], "Speeding up code and parallelism": [[8, "speeding-up-code-and-parallelism"]], "Starting Python": [[6, "starting-python"]], "Storing arbitrary Python objects": [[1, "storing-arbitrary-python-objects"]], "Storing array data": [[1, "storing-array-data"]], "Storing data in CSVs can reduce data precision": [[1, null]], "Storing tidy data": [[1, "storing-tidy-data"]], "Strides": [[10, "strides"]], "Styling and customizing plots": [[15, "styling-and-customizing-plots"]], "Task queues": [[13, "task-queues"]], "Testing a local pip install": [[11, "testing-a-local-pip-install"]], "Text editor": [[6, "text-editor"]], "Textual formats": [[24, "textual-formats"]], "The Python/SciPy ecosystem": [[8, "the-python-scipy-ecosystem"]], "The libraries behind the curtain: MKL and BLAS": [[10, "the-libraries-behind-the-curtain-mkl-and-blas"]], "The ndarray exposed": [[10, "the-ndarray-exposed"]], "Themes": [[16, "themes"]], "Things to remember": [[24, "things-to-remember"]], "Tidy data": [[12, "tidy-data"]], "Time series superpowers": [[12, "time-series-superpowers"]], "To pin or not to pin? That is the question.": [[2, null]], "Tools for interfacing with other languages": [[8, "tools-for-interfacing-with-other-languages"]], "Tools that simplify sharing via PyPI": [[11, "tools-that-simplify-sharing-via-pypi"]], "Tracing profilers vs. sampling profilers": [[18, "tracing-profilers-vs-sampling-profilers"]], "Type checking": [[17, "type-checking"]], "Types of operations": [[9, "types-of-operations"]], "Verification of Python and JupyterLab": [[6, "verification-of-python-and-jupyterlab"]], "Verification of the command line": [[6, "verification-of-the-command-line"]], "Version pinning for package creators": [[2, "version-pinning-for-package-creators"]], "Videos and archived Q&A": [[5, null]], "Watch the video": [[6, null]], "Web APIs with Python": [[3, "web-apis-with-python"], [23, null]], "What is Jupyter?": [[7, "what-is-jupyter"]], "What is Xarray?": [[25, "what-is-xarray"]], "What is a data format?": [[24, "what-is-a-data-format"]], "What is an array?": [[9, "what-is-an-array"]], "What other marks and other visual channels exist?": [[16, "discussion-1"]], "What to look for in a file format?": [[24, "what-to-look-for-in-a-file-format"]], "What\u2019s in SciPy?": [[21, "what-s-in-scipy"]], "What\u2019s in a dataframe?": [[12, "what-s-in-a-dataframe"]], "What\u2019s next?": [[8, "what-s-next"]], "Who is the course for?": [[5, "who-is-the-course-for"]], "Why Jupyter?": [[7, "why-jupyter"]], "Why Python": [[5, "why-python"]], "Why are we starting with Matplotlib?": [[15, "why-are-we-starting-with-matplotlib"]], "Why are we starting with Vega-Altair?": [[16, "why-are-we-starting-with-vega-altair"]], "Why do we emphasize this?": [[15, "discussion-1"]], "Why is it sometimes not enough to share your code?": [[0, "why-is-it-sometimes-not-enough-to-share-your-code"]], "Why not Jupyter?": [[7, "why-not-jupyter"]], "Why not Python for Scientific Computing": [[5, "why-not-python-for-scientific-computing"]], "Why scripts?": [[22, "why-scripts"]], "Why these colors?": [[15, "discussion-0"]], "Working with Data": [[3, "working-with-data"], [24, null]], "Working with dataframes": [[12, "working-with-dataframes"]], "Wrap-up": [[23, "wrap-up"]], "Xarray": [[3, "xarray"], [25, null]], "You can also use mamba": [[2, null]], "Zoom": [[6, "zoom"]], "conda activate versus source activate": [[2, "callout-0"]], "conda-lock": [[2, null]], "multiprocessing": [[13, "multiprocessing"]], "npy (numpy array format)": [[1, "npy-numpy-array-format"]]}, "docnames": ["binder", "data-formats", "dependencies", "exercises", "guide", "index", "installation", "jupyter", "libraries", "numpy", "numpy-advanced", "packaging", "pandas", "parallel", "parallel-pi-multiprocessing", "plotting-matplotlib", "plotting-vega-altair", "productivity", "profiling", "python", "quick-reference", "scipy", "scripts", "web-apis", "work-with-data", "xarray"], "envversion": {"sphinx": 62, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.intersphinx": 1, "sphinx.ext.todo": 2}, "filenames": ["binder.rst", "data-formats.rst", "dependencies.rst", "exercises.md", "guide.rst", "index.rst", "installation.rst", "jupyter.ipynb", "libraries.rst", "numpy.rst", "numpy-advanced.rst", "packaging.rst", "pandas.rst", "parallel.rst", "parallel-pi-multiprocessing.ipynb", "plotting-matplotlib.md", "plotting-vega-altair.md", "productivity.md", "profiling.md", "python.rst", "quick-reference.rst", "scipy.rst", "scripts.rst", "web-apis.ipynb", "work-with-data.rst", "xarray.rst"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"": [0, 1, 2, 3, 5, 6, 7, 9, 10, 11, 13, 14, 16, 18, 19, 22, 23, 24, 25], "0": [0, 1, 2, 3, 5, 7, 9, 10, 11, 12, 13, 14, 15, 16, 19, 21, 22, 23, 24, 25], "000": [2, 3, 10], "006138": [3, 16], "0061383899407406": [3, 16], "0078": 25, "009e73": [3, 15], "01": [3, 16, 21, 22, 25], "01624": 25, "02": [3, 16, 25], "03": [3, 16, 22, 25], "0302": 25, "04": [2, 3, 15, 16, 25], "0475": 25, "05": [3, 16, 21, 22, 25], "05283": 25, "052e": 25, "06": [3, 16, 22, 25], "060877914676249": [3, 16], "07": [3, 16, 25], "07874": 25, "08": [3, 13, 16, 25], "084e": 25, "09": [3, 16, 25], "1": [5, 6, 14, 18, 19, 24], "10": [1, 2, 7, 8, 9, 10, 12, 13, 14, 15, 16, 21, 22, 24, 25], "100": [3, 9, 10, 12, 16, 23, 25], "1000": [1, 3, 13, 22, 23, 24, 25], "10000": [3, 9, 13, 21, 25], "100000": [1, 3, 12, 24], "1000000": [3, 7], "10000000": [3, 13], "100000000": [3, 10], "100_000_000": [3, 10], "100_000_000_000": [3, 10], "101": [3, 25], "10832": 25, "10_000": [3, 10], "11": [2, 3, 9, 10, 13, 15, 25], "11533": 25, "116b": 25, "117e": 25, "119": 25, "11_l100": 25, "12": [2, 3, 9, 12, 13, 15, 16, 22], "1200": 12, "1214": [3, 25], "123": 19, "125": 25, "1256": 25, "128": 12, "128kb": 25, "13": [2, 3, 9, 15, 17, 25], "131": 25, "13440": 10, "14": [3, 9, 15, 19], "140768": 14, "1410176": [3, 13], "14124": 25, "141722": [3, 13], "142388": 14, "144548": 14, "14658": 25, "148e": [3, 25], "14kb": 25, "15": [5, 9, 10, 16, 25], "150": 25, "1500": [3, 12, 25], "150065": [3, 16], "153": 25, "155178": [3, 16], "15mb": 25, "16": [1, 3, 9, 10, 13, 22], "160": 12, "1600": 10, "160000": 10, "1600m": [3, 21], "1622": 25, "16379": 25, "17": [3, 16], "1725": 25, "18": 12, "1881": 25, "18_923": [3, 10], "19": [2, 3, 10, 12, 16], "192": 12, "195": 25, "1979": 10, "1993": 25, "1d": [3, 9, 10, 25], "1e": 25, "1kb": 25, "1x1": [3, 13], "1x2": 9, "2": [11, 14, 18, 19, 24], "20": [2, 3, 5, 10, 16, 17, 18, 25], "200": [2, 3, 25], "2000": 22, "2007": [0, 3, 15], "2008": [5, 15], "201": 25, "20130101": [1, 3, 12, 24], "2017": 0, "2019": [3, 13, 22], "202": 25, "2020": [3, 5, 9, 22], "20207": 25, "2021": [3, 5, 22], "2022": [5, 16], "2023": [3, 5, 6, 16, 25], "2024": [2, 6], "20_000": [3, 10], "21": 12, "2116": 24, "217": [3, 25], "2177": 25, "219": 25, "23": 12, "23332": 25, "235": 25, "24": [3, 15], "240": 12, "240b": [3, 25], "24895": 25, "249": 25, "25": [3, 10, 12, 13, 16, 23], "254": 25, "255kb": 25, "259": 25, "26": [3, 15, 16], "2600": [3, 18], "262": 25, "268": 25, "2688": 10, "27": 2, "275": 25, "276": 25, "277": 25, "27s_quartet": [3, 15], "28": [14, 22, 23], "287": [3, 12], "288": [12, 25], "28879": 25, "289": 25, "29": [12, 14, 25], "292": 25, "292e": 25, "293": 25, "294": 25, "2950148716254297": [3, 16], "295015": [3, 16], "2d": [3, 9, 10, 24, 25], "2x2": 9, "2x3": 9, "3": [6, 11, 14, 15, 16, 19, 21, 25], "30": [3, 5, 16, 22, 23], "300": 12, "30956": 25, "31": 22, "311e": 25, "32": 2, "320": 14, "324e": 25, "3259": 25, "3292": 25, "33": [3, 15], "3427": 25, "343e": 25, "35805": 25, "358449851840048": [3, 16], "358450": [3, 16], "36": [2, 13], "360": 12, "365": [3, 12], "37044": 25, "3726": [3, 25], "37395": 25, "38": [12, 14], "384652": [3, 16], "3886864": [0, 3], "38957": 25, "3925910": [3, 13], "3926634": [3, 13], "3943506": [3, 23], "395": [3, 7], "3_465": [3, 10], "3d": [8, 15, 16, 25], "3f": [3, 21], "3j": 19, "3x2": [3, 9], "4": [5, 10, 12, 13, 14, 15, 16, 19, 21, 25], "40": [5, 10], "400": 12, "4000": 13, "40000": 10, "400b": [3, 25], "407525459336549": [3, 16], "40_000": 10, "40m": 12, "41139": 25, "416233": [3, 16], "42": [3, 12, 16, 19, 25], "42378": 25, "42m": [3, 21], "4338": [3, 25], "43617": 25, "4395": [3, 25], "448": 10, "45": [5, 7], "456": 19, "4578": [3, 25], "46": 25, "46936": 25, "47": 2, "476b": 25, "47711": 25, "48": 10, "4806111169875615": [3, 16], "487": [3, 25], "49059": 25, "496714": [3, 16], "4967141530112327": [3, 16], "4976": 25, "49895": 25, "4b": [3, 25], "4mb": 25, "4x4": [3, 9], "4x8": [3, 9], "5": [0, 7, 10, 12, 13, 14, 15, 16, 18, 21, 25], "50": [3, 15, 16, 25], "500": 9, "512": 12, "51215": 25, "51457": 25, "5148": [3, 25], "52075": 25, "5281": [0, 3], "529168": [3, 16], "5291682463487657": [3, 16], "5302": 25, "54": 7, "5447": 25, "54985": 25, "56b4e9": [3, 15], "572e": [3, 25], "57516": 25, "5757": 25, "58": [3, 15], "58218": 25, "58566": 25, "59436": 25, "598": 14, "5_000": 10, "6": [3, 9, 10, 12, 13, 14, 15, 16, 25], "60": 5, "60b": [3, 25], "61": 11, "6156": 25, "61667": 25, "6256": 25, "6285": 25, "63498": 25, "635": 14, "63957": 25, "64": [10, 11, 12], "6400907301836405": [3, 16], "64m": [3, 21], "65115": 25, "65167": 25, "666108129242815": 25, "67082": 25, "68": [3, 15], "681": 25, "6861": [3, 25], "68645": 25, "6881": 25, "6958": [3, 25], "69_318_923": [3, 10], "7": [3, 7, 9, 10, 12, 13, 14, 15, 16, 25], "70": 12, "70374": 25, "71204": 25, "712354": [3, 16], "714": 25, "735": 25, "74": [3, 15], "74866": 25, "74895": 25, "75": [3, 9], "75244": 25, "753308882144761": 25, "75998": 25, "76752": 25, "77": [3, 15, 19], "78186": 25, "7854305": [3, 13], "78638": 25, "7911": [3, 25], "79501": 25, "7m": [3, 21], "8": [2, 3, 6, 9, 10, 12, 15, 16, 17, 18, 19, 22, 23, 25], "80": 12, "800": 12, "80000": 10, "80202": 25, "80m": 12, "81": [3, 12, 15], "82": [3, 15], "82195": 25, "82874": 25, "8308828962289": 25, "83649": 25, "84": [3, 15], "84436": 25, "8505": 25, "86": 25, "87395": 25, "8796": 25, "88242040519995": 25, "88446": 25, "88957": 25, "8b": 25, "8x4": [3, 9], "9": [3, 9, 12, 13, 14, 15, 16, 19], "90": 18, "90222": 25, "90686": 25, "91678": 25, "924868": 25, "927": 24, "938051073401597": [3, 16], "940b": [3, 25], "95": [3, 15, 16], "950": 25, "956": [3, 12], "96": [3, 12, 15, 16], "96936": 25, "97": [3, 16], "975": 25, "98": [3, 16], "99": [3, 12, 16], "993": 7, "A": [1, 2, 3, 4, 7, 8, 9, 11, 13, 16, 17, 22, 24, 25], "And": [5, 10, 11, 12], "As": [1, 2, 3, 8, 10, 11, 12, 13, 18, 24, 25], "At": [2, 3, 5, 13, 15, 25], "BY": 16, "Be": [0, 2, 3, 4, 7, 8, 9, 15, 16, 19], "Being": [7, 15, 16], "But": [3, 4, 5, 7, 8, 9, 12, 13, 15, 17, 18, 21, 22], "By": [3, 4, 7, 9, 10, 13, 14, 22], "For": [1, 2, 3, 6, 7, 9, 10, 11, 12, 13, 15, 17, 18, 19, 21, 22, 23, 24, 25], "If": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 13, 16, 17, 18, 19, 22, 23, 24, 25], "In": [0, 2, 4, 5, 7, 8, 9, 10, 11, 12, 15, 16, 17, 18, 19, 22, 23, 24, 25], "Into": [2, 3], "It": [0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 18, 19, 21, 22, 23, 24], "No": [3, 7, 16], "Not": [4, 12, 18, 24], "Of": 13, "On": [3, 7, 16], "One": [1, 2, 3, 9, 10, 12, 15, 16, 22, 25], "Or": [6, 8, 17], "That": [3, 9, 15, 25], "The": [0, 1, 3, 4, 5, 6, 7, 9, 11, 12, 13, 14, 15, 16, 18, 19, 21, 22, 23, 24, 25], "Then": [0, 3, 8, 12, 13, 14, 15, 16, 21], "There": [1, 2, 3, 4, 6, 7, 9, 11, 12, 13, 15, 16, 22, 24, 25], "These": [2, 3, 5, 6, 8, 9, 10, 11, 12, 13, 17, 21, 23, 25], "To": [0, 3, 6, 9, 10, 11, 12, 13, 14, 15, 22, 23, 25], "Will": 17, "With": [9, 12, 16], "_": [3, 13], "__array_interface__": 10, "__init__": [11, 19], "__main__": [3, 18], "__name__": [3, 18], "__version__": [2, 11], "_name": 19, "_result": [3, 18], "a2": [4, 5], "aalto": [2, 7], "aaltoscicomp": [3, 6, 12, 16, 22], "aapl": [3, 25], "ab": 1, "abcd": 12, "abid": 2, "abil": 12, "abl": [2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 15, 16, 19, 22, 24], "about": [0, 2, 3, 5, 7, 8, 9, 10, 12, 13, 15, 16, 17, 19, 21, 22, 24, 25], "abov": [3, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 22, 23, 24, 25], "abstract": 15, "academ": 4, "academia": 2, "acceler": [13, 25], "accept": [15, 23], "access": [0, 3, 12, 14, 22, 23], "accessor": 12, "accomplish": 10, "accordingli": 25, "account": [0, 3, 11], "achem": [3, 12], "achiev": [11, 22], "acknowledg": 4, "acquir": [5, 7], "across": [13, 25], "act": 12, "action": [3, 8], "activ": [5, 6, 7, 8, 11, 18], "actual": [3, 4, 6, 8, 9, 10, 13, 14, 23, 25], "ad": [0, 3, 11, 12, 16, 18, 23, 25], "adapt": [11, 15], "add": [0, 1, 2, 3, 7, 9, 10, 11, 12, 15, 16, 17, 18, 22, 25], "add_argu": [3, 22], "add_param": [3, 16], "addit": [3, 5, 7, 10, 11, 22, 25], "addition": [3, 24], "address": [0, 3, 25], "adel": [3, 12], "adjust": [3, 9, 15, 16, 22], "admin": 4, "admit": 21, "adopt": 5, "advanc": [4, 5, 6, 7, 12, 21], "advantag": [1, 3, 10, 13, 18, 25], "advisor": [5, 7], "advoc": [0, 3], "affect": [2, 6, 10, 15, 17], "afraid": 6, "after": [0, 2, 3, 7, 9, 10, 13, 15, 16, 18, 22, 24], "afterward": 2, "ag": [3, 12], "again": [1, 3, 4, 7, 9, 14, 23], "against": [6, 10, 22], "age_nobel": [3, 12], "agent": [3, 23], "agg": 15, "aggfunc": [3, 12], "aggreg": [12, 25], "agre": 17, "ahead": 10, "ai": [3, 16], "aim": 2, "aka": 2, "albeit": 5, "alert": 16, "algebra": [3, 10, 21], "algorithm": [3, 10, 13, 21], "ali": 12, "aliv": 23, "all": [0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 23, 24, 25], "allclos": [3, 9], "alloc": [9, 24], "allow": [0, 1, 2, 3, 6, 10, 12, 13, 15, 16, 21, 22, 23, 24, 25], "almost": [5, 8, 15, 16], "alon": [0, 2], "along": [0, 2, 3, 7, 10, 16, 19, 22, 25], "alongsid": 2, "alpha": [0, 3, 12, 15], "alreadi": [2, 3, 4, 5, 6, 8, 9, 12, 16, 18, 22, 24, 25], "also": [0, 1, 3, 4, 11, 12, 15, 16, 17, 18, 19, 22, 23, 25], "alt": [3, 7, 16], "altair": [5, 15], "altern": [2, 3, 5, 11, 18], "although": 15, "alwai": [2, 3, 6, 9, 10, 12, 22, 23, 24, 25], "am": [3, 16], "amaz": 10, "american": 25, "among": [2, 3, 12, 15], "amount": [1, 2, 3, 5, 10, 16, 18, 23], "an": [0, 1, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25], "anaconda": [2, 3, 4, 5, 7, 11], "anaconda3": 11, "analysi": [2, 5, 7, 10, 12, 13, 15, 16, 24, 25], "analyt": [5, 13], "analyz": [0, 17, 23], "ancient": [3, 8], "ani": [2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 16, 19, 22, 24], "anim": [0, 3], "ann": [5, 19], "annot": 12, "anoth": [3, 4, 6, 7, 8, 9, 11, 12, 13, 15, 16, 19, 22, 23, 24, 25], "anscomb": [3, 15], "answer": [2, 3, 9, 13, 14, 15, 24], "anticip": [0, 3], "anybodi": 5, "anymor": [3, 8], "anyon": [6, 8, 11], "anyth": [3, 8, 12, 21], "anywher": 11, "apach": 12, "apart": 16, "api": [1, 2, 4, 5, 10, 12, 13, 16, 24], "apipheni": 23, "appear": [5, 7, 18], "append": [3, 18, 22, 23, 24], "appl": [1, 3, 19, 24], "appli": [7, 10, 12, 13, 14, 25], "applic": [0, 1, 2, 3, 6, 8, 13, 23], "applicaiton": 7, "appreci": 4, "apprentic": 17, "approach": [2, 5, 11, 13, 15, 22], "appropri": [3, 10], "approxim": [12, 13, 18], "ar": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 18, 19, 21, 22, 23, 24, 25], "arang": [3, 9, 12], "arbitrari": [3, 10, 19, 24], "archiv": [0, 1, 2, 3, 24], "area": [0, 3, 5, 13], "aren": [3, 4, 5, 7, 8, 14, 21], "arg": [3, 22], "argc": 10, "argpars": 3, "argsort": [3, 9], "argument": [3, 9, 12, 13, 14, 16, 19, 21, 23, 25], "argumentpars": [3, 22], "argv": [3, 10], "arithmet": [8, 9], "around": [3, 6, 10, 12, 13, 15, 21], "arrai": [3, 5, 8, 10, 12, 13, 21, 22, 24, 25], "arrang": 11, "arriv": [3, 15, 16], "arrow": [6, 12], "articl": [2, 8, 12, 21], "as_strid": [3, 10], "asdf": 9, "asid": 12, "ask": [2, 3, 6, 7, 13, 16, 18], "aspect": 15, "assign": [3, 7, 12], "associ": [3, 19, 24], "assum": [3, 5, 12, 21, 24, 25], "astyp": [3, 9], "athlet": 12, "attach": 2, "attempt": 10, "attr": [3, 25], "attract": 22, "attribut": [3, 10, 12, 23, 25], "audienc": 10, "authent": 23, "author": [0, 3, 5, 8, 11, 24, 25], "auto": 17, "autocomplet": [3, 12], "autoflak": 17, "autofmt_xd": [3, 22], "autogener": [15, 16], "autom": [2, 3, 8, 11, 15, 16, 22], "automat": [0, 2, 3, 6, 8, 13, 15, 17, 22, 23, 25], "avail": [0, 2, 3, 4, 6, 8, 10, 11, 12, 16, 18, 21, 22, 23, 24], "averag": [3, 12, 24, 25], "avoid": [1, 2, 3, 9, 11, 13], "awar": [0, 3, 9, 13], "ax": [0, 3, 15, 22, 25], "axi": [3, 9, 13, 15, 16, 25], "b": [3, 4, 5, 7, 9, 10, 12, 17, 18, 19, 22, 24], "back": [0, 1, 3, 8, 10, 12, 18, 22], "backbon": 4, "backend": 11, "background": [9, 13], "backward": 12, "bad": [2, 3, 8, 10, 11, 13], "badg": [0, 3], "badli": 17, "balanc": 7, "ball": [0, 3], "banana": [1, 3, 19, 24], "bar": [7, 16, 22], "bare": 25, "barrier": 7, "base": [2, 3, 6, 7, 8, 10, 12, 15, 16, 17, 18, 22], "baselin": [4, 5], "bash": 7, "basi": 5, "basic": [2, 3, 4, 5, 6, 9, 10, 13, 14, 16, 19, 21, 23, 25], "bast": 5, "bat": 11, "batch": [3, 18], "battl": [5, 21], "beat": [3, 10], "beauti": [3, 23], "beautifulsoup": 23, "becam": [3, 5, 7], "becaus": [2, 3, 5, 6, 7, 9, 10, 12, 13, 14, 18, 21], "becom": [2, 3, 4, 5, 6, 8, 9, 10, 22], "been": [2, 3, 4, 5, 6, 8, 10, 11, 13, 22, 24], "befor": [3, 6, 9, 10, 11, 12, 13, 15, 16, 17, 18], "beforehand": 23, "begin": [3, 4, 7, 10], "beginn": 18, "behav": [3, 9], "behavior": [2, 19], "behaviour": 2, "behind": 4, "being": [0, 1, 2, 3, 4, 6, 9, 10], "below": [0, 1, 3, 5, 6, 7, 8, 10, 11, 12, 13, 16, 18, 21, 22, 23, 24, 25], "benefit": [9, 22, 24], "bessel": 21, "best": [1, 2, 3, 4, 5, 7, 8, 9, 10, 15, 16, 21], "better": [2, 5, 7, 8, 17, 18, 21, 22, 24], "between": [1, 2, 3, 7, 9, 12, 17, 22, 23, 25], "beyond": [6, 8, 13], "big": [1, 3, 8, 10, 12], "bigger": [2, 4, 24], "bin": [2, 3, 6, 7, 12, 22], "binari": [1, 3], "bind": [3, 16], "binder": [2, 4, 5, 8], "binding_rang": [3, 16], "bioconda": 11, "bioinformat": 11, "biologi": [0, 3], "birth": 22, "birthdai": 22, "bit": [3, 4, 5, 6, 8, 12, 13, 16, 19], "bitbucket": 8, "bite": [15, 16], "bla": 9, "black": [2, 17, 24], "bld": 11, "block": [2, 3, 11, 13, 16, 19, 21, 24], "blog": [13, 25], "blomqvist": 5, "blue": [3, 16], "boi": 10, "bokeh": [15, 16], "bold": [3, 7], "book": [3, 18], "bool": [9, 19], "boolean": [3, 9, 12, 19], "boost": 8, "border": [3, 9], "bore": 4, "boredapi": [3, 23], "born": [3, 12, 22], "borncountri": [3, 12], "borncountrycod": [3, 12], "both": [0, 2, 3, 5, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18, 22], "bother": 5, "bottleneck": [4, 13, 18], "bottom": [2, 3, 9, 13, 23, 25], "box": 24, "boxplot": 12, "br": 23, "break": [4, 25], "breakout": [0, 3], "brief": 12, "briefli": 21, "bring": 18, "brittl": 22, "broadcast": [4, 9], "broader": [5, 8], "brows": [3, 7, 15, 16, 18, 22], "browser": [3, 6, 7, 12, 18, 22, 23], "bs4": [3, 23], "bsr": [3, 21], "buffer": 10, "bug": [8, 13, 22], "build": [2, 4, 8, 10, 15, 16, 21], "build_meta": 11, "built": [0, 11, 15, 16, 22], "bullet": [0, 3, 7], "bunch": [7, 25], "bundl": 2, "button": [0, 3, 4, 7], "byte": [10, 19], "bz2": 11, "c": [1, 2, 3, 4, 5, 7, 8, 9, 10, 12, 13, 15, 19, 21, 25], "cabin": 12, "cach": [3, 18], "cairo": [3, 22], "cake": 11, "calcul": [1, 2, 3, 9, 11, 12, 13, 14, 21, 24, 25], "call": [2, 3, 5, 7, 10, 11, 12, 13, 15, 16, 18, 22, 23, 25], "callabl": 22, "came": [2, 3, 5], "can": [3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 18, 19, 21, 22, 23, 24, 25], "cannot": [1, 3, 24], "cap": 12, "capabl": [19, 25], "capita": [0, 3, 15], "captur": 18, "care": [1, 7, 13], "career": [4, 5], "carefulli": [4, 8], "carpentri": 5, "carri": [9, 13, 15], "carrot": [1, 3, 24], "case": [1, 2, 3, 5, 7, 9, 10, 12, 13, 16, 18, 19, 22, 23], "cast": [3, 9, 17], "cat": [12, 23], "categori": [3, 12], "catfact": 23, "catplot": [3, 12], "caught": [3, 16], "caus": 2, "caveat": 24, "cc": [12, 16], "cd": [3, 7], "cdm": 25, "ceil": [3, 9], "cell": [3, 7, 9, 12, 13, 14, 16], "celsiu": [3, 22], "centimet": [3, 15], "cern": 0, "certain": [2, 11, 24, 25], "certainli": 5, "cf": 25, "cff": [0, 3], "cffi": [8, 13], "chanc": [9, 12, 15], "chang": [2, 3, 5, 7, 8, 9, 10, 12, 13, 15, 16, 17, 22, 24, 25], "channel": [2, 6, 11], "chapter": 25, "char": 10, "charact": 23, "chart": [3, 16], "chat": 17, "cheap": 10, "cheatsheet": [12, 15, 20], "check": [0, 1, 2, 3, 7, 8, 9, 11, 13, 18, 21, 22, 23, 24, 25], "checker": 17, "chemistri": [3, 12], "cherri": 19, "child": 12, "children": 12, "choic": [1, 2, 3, 5, 7, 12, 13, 24], "choos": [0, 3, 4, 6, 15, 16, 24, 25], "chose": 12, "chunk": 13, "circl": [3, 13], "circumv": [13, 19], "citat": [0, 3, 21], "citeabl": 8, "citi": 3, "clarifi": 15, "class": [2, 3, 4, 5, 9, 10, 12, 13], "classic": 18, "classifi": 8, "clau": [15, 16], "clauswilk": 15, "clean": [2, 24], "clear": 24, "clearli": [3, 8, 9, 12], "clever": [9, 10, 25], "cleverli": 9, "click": [0, 3, 6, 12, 18, 22], "climat": [3, 25], "clone": 2, "close": [1, 3, 7, 14, 15, 16, 25], "closer": [10, 24], "cloud": [0, 2, 3], "clue": [3, 15], "cluster": [15, 22], "cm": 16, "co": [2, 3, 9], "code": [1, 2, 4, 5, 6, 9, 10, 11, 12, 13, 15, 21, 22, 23, 24, 25], "coderefineri": [2, 5, 6, 7, 8, 22], "coerc": [3, 12], "col": [3, 10, 12], "collabor": [0, 2, 3, 5, 11], "colleagu": 6, "collect": [3, 6, 8, 10, 11, 12, 13, 23, 24], "color": [3, 16, 24], "colorblind": 15, "column": [3, 9, 10, 12, 15, 16, 24, 25], "columnar": [1, 8], "com": [0, 2, 3, 6, 8, 12, 15, 16, 22, 23, 24], "combin": [3, 7, 9, 12, 13, 14, 16, 25], "come": [2, 3, 4, 6, 7, 10, 15, 16, 21, 25], "comm": [3, 13], "comm_world": 13, "comma": [3, 16], "command": [2, 3, 4, 5, 7, 11, 12, 25], "comment": [3, 7, 16, 22], "commerci": 6, "commit": [0, 3, 17], "common": [2, 4, 6, 8, 9, 10, 12, 13, 19, 21, 23, 24], "commonli": [1, 6, 24], "commonmark": 7, "commun": [3, 5, 6, 8, 11, 12, 13, 15, 16, 23], "compact": [12, 15], "compani": [2, 3, 6, 25], "compar": [1, 3, 9, 13, 14, 16, 21, 22, 25], "comparison": [2, 11, 24, 25], "compat": [2, 5, 8, 9], "competit": 12, "compil": [5, 8, 11, 13, 19, 21], "complet": [1, 3, 5, 7, 10, 12, 13, 17, 18, 21], "complex": [1, 6, 19, 22], "complic": [1, 2, 24], "compon": [2, 11], "component_of_wind_isobar": 25, "compos": 12, "comprehens": [4, 5, 8], "comput": [2, 3, 4, 6, 7, 9, 10, 12, 13, 14, 15, 21, 22, 23, 24, 25], "con": [2, 18], "concat": [12, 16], "concaten": [3, 9, 10, 12, 16], "concept": [4, 9, 10, 17], "concis": 16, "concret": [11, 25], "concurr": [13, 22], "conda": [3, 4, 7, 25], "condit": [3, 9, 13, 16, 19], "conduct": 5, "confg": [3, 22], "config": 3, "configur": [0, 6, 15, 18, 22], "conflict": 2, "conform": 8, "confus": 11, "connect": [16, 23], "consid": [1, 3, 4, 8, 9, 13, 15, 16, 23, 24, 25], "consist": [3, 9, 10, 11, 16, 17, 24, 25], "consol": 2, "constantli": 2, "construct": [10, 23], "consult": [3, 15], "consum": [2, 18], "contact": 5, "contain": [0, 1, 2, 3, 6, 7, 9, 10, 11, 12, 16, 18, 19, 21, 22, 23, 24, 25], "content": [3, 7, 9, 23, 24], "contest": 10, "contextu": 12, "contigu": 24, "continu": [2, 3, 10], "contribut": [8, 12], "control": [7, 9, 10, 13, 22], "conveni": [4, 6, 22], "convent": [7, 25], "convention": [3, 13], "convers": [8, 22, 25], "convert": [3, 10, 11, 12, 21, 22], "coo": [3, 21], "cookbook": 12, "coord": [3, 25], "coordin": [3, 16, 25], "copi": [0, 3, 6, 7, 8, 9, 12, 13, 16, 22], "core": [3, 12, 13], "correct": [3, 8, 10, 25], "correspond": [0, 3, 6, 12, 23, 25], "could": [3, 4, 5, 6, 8, 9, 13, 14, 15, 16, 22, 23, 25], "count": [3, 12, 18], "count_unique_word": 17, "count_unique_words1": [3, 18], "count_unique_words2": [3, 18], "count_unique_words3": [3, 18], "countless": 9, "countri": [3, 12, 23, 24], "countries_df": 24, "countries_json": 24, "countries_list": 24, "country1": [3, 12], "country2": [3, 12], "country3": [3, 12], "country4": [3, 12], "cours": [0, 3, 4, 6, 7, 8, 9, 10, 13, 16, 17, 18, 19, 25], "cover": [3, 4, 5, 9, 12, 13, 25], "cprofil": 18, "cpu": [3, 9, 10, 13, 14, 18], "crash": [4, 5, 6], "creat": [1, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 15, 16, 18, 21, 22, 23, 24], "create_dataset": 1, "creation": [2, 4], "creation_d": 25, "creator": [10, 11], "credit": 0, "criterion": 9, "critic": 5, "crowd": 18, "csc": [3, 21], "csr": [3, 21], "csv": [0, 3, 12, 15, 16, 22, 24], "ctrl": 7, "ctype": [8, 13], "cud": 15, "cumsum": [3, 12, 16], "cupi": 25, "curat": 2, "currenc": [3, 25], "current": [2, 3, 6, 10, 16, 18, 22], "custom": [0, 8, 16, 22, 23, 25], "cut": 7, "cycl": 23, "cython": [8, 13], "d": [3, 7, 9, 12, 16, 19, 21, 22, 25], "da": 13, "dai": [3, 4, 5, 6, 8, 12, 15, 16, 18, 22, 25], "daili": 16, "dark": [16, 25], "darst": 5, "dart": [3, 13], "dask": [8, 12, 25], "data": [0, 4, 5, 7, 9, 13, 15, 18, 19, 22], "data2_i": [3, 15], "data2_y_sc": [3, 15], "data_2007": 0, "data_arrai": [1, 3, 24], "data_array0": 1, "data_array1": 1, "data_array_csv": 1, "data_array_h5": 1, "data_array_netcdf4": 1, "data_array_npi": [1, 3], "data_array_pickl": 1, "data_array_xarrai": 1, "data_column": [3, 22], "data_daili": 16, "data_i": [3, 15], "data_monthli": [3, 16], "data_oslo": 16, "data_tromso": 16, "data_var": [3, 25], "data_x": [3, 15], "dataarrai": [1, 3, 25], "databas": 8, "datacamp": 20, "datafil": 12, "datafram": [1, 4, 13, 24, 25], "dataset": [0, 1, 15, 16, 22, 24], "dataset_csv": [1, 3], "dataset_feath": 1, "dataset_hdf5": 1, "dataset_json": 1, "dataset_netcdf4": 1, "dataset_parquet": 1, "dataset_xarrai": 1, "dataslic": 25, "datastructur": 10, "datatyp": [3, 9], "dataviz": 15, "date": [3, 8, 12, 16, 22], "date_rang": [1, 3, 12, 24], "datetim": [3, 12], "datetime64": 25, "dateutil": 8, "datum": [3, 16], "dave": 12, "dayfirst": [3, 22], "dd": [3, 16, 22], "deactiv": 2, "deadlin": [15, 16], "deal": [1, 12, 25], "dealt": 8, "debug": [1, 7, 13], "decemb": 16, "decent": 10, "decid": [3, 8, 9, 11, 24], "decim": [1, 3, 9, 12], "declar": [15, 16], "decod": 23, "dedic": [0, 1, 24], "deep": 5, "def": [3, 10, 11, 12, 13, 14, 17, 18, 19, 21], "defacto": 5, "default": [2, 3, 7, 9, 12, 13, 14, 16, 17, 22, 23], "default_rng": 10, "defici": 15, "defin": [2, 3, 4, 10, 12, 15, 16, 19, 21, 22, 23, 25], "definit": [6, 10, 19, 23], "deflat": 23, "delai": [2, 13, 18], "delet": 7, "demo": [1, 4, 13, 17, 23], "demonstr": [0, 3, 4, 6, 15], "dens": [3, 21], "densiti": [3, 21], "depend": [1, 4, 5, 6, 7, 8, 9, 10, 11, 13, 17, 18, 24], "deposit": [0, 3], "depth": [5, 16, 24], "deriv": [10, 22], "describ": [2, 3, 5, 11, 12, 24, 25], "descript": [0, 3, 7, 11, 13, 21, 22, 25], "design": [3, 5, 6, 12, 13, 14, 15, 24, 25], "desir": [3, 10], "detail": [8, 11, 12, 13, 18, 21, 22, 25], "detect": [17, 18, 22, 25], "determin": [3, 19, 24], "determinist": 18, "dev": [3, 7, 12, 14], "develop": [2, 3, 5, 7, 8, 10, 12, 22, 23], "df": [3, 12, 16, 25], "df1": 12, "df2": 12, "df3": 12, "df4": 12, "dftlib": [3, 8], "di": 12, "diagon": 10, "dict": [19, 22, 23], "dictionari": [12, 19, 22, 23, 24, 25], "did": [2, 3, 7, 13, 22, 23], "didn": [12, 17, 18, 25], "differ": [1, 2, 5, 6, 7, 9, 11, 12, 13, 16, 17, 18, 19, 21, 22, 24, 25], "difficult": [2, 7, 13, 17, 23, 24], "digit": 0, "dim": 25, "dimens": [1, 3, 9, 10, 18, 25], "dimension": [3, 9, 24, 25], "dimention": 25, "direct": [4, 5], "directli": [2, 3, 8, 9, 10, 12, 13, 16, 22, 25], "directori": [3, 7, 22], "disadvantag": [3, 18], "disappear": [3, 8], "discourag": 2, "discoveri": 7, "discuss": [4, 5, 7, 8, 16, 17, 25], "disk": [1, 3, 8, 12, 15, 16, 24], "displai": [3, 7, 15, 16, 23], "dist": 11, "distanc": [1, 12], "distribut": [2, 3, 5, 6, 7, 8, 11, 12, 13], "dive": 10, "divers": 17, "divid": [7, 9, 13, 14], "do": [1, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 16, 17, 18, 19, 21, 22, 23, 24, 25], "doc": [3, 5, 9, 12, 16, 21], "docker": 0, "docstr": [3, 11, 12], "doctopt": 22, "doctor": 18, "document": [0, 1, 2, 3, 4, 7, 8, 11, 12, 13, 16, 21, 22, 23, 24, 25], "doe": [1, 2, 3, 6, 7, 8, 9, 10, 11, 12, 13, 15, 18, 21, 22, 23, 25], "doesn": [3, 5, 6, 8, 9, 13, 14, 18, 22], "dog": 12, "doi": 3, "dok": [3, 21], "dollar": [3, 15], "don": [3, 4, 5, 6, 7, 8, 10, 12, 13, 16, 17, 18, 19, 23, 24, 25], "donald": 18, "done": [2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 22, 24], "dot": [3, 9, 11, 21], "doubl": [1, 10], "down": [0, 3, 7, 13, 18, 23, 25], "download": [0, 2, 3, 5, 6, 12, 18, 22, 23, 25], "downsid": 7, "draw": 15, "drawback": 24, "drop": [0, 2, 3, 8, 12], "dropna": 12, "dt": [3, 12], "dtype": [3, 9, 12, 25], "dual": 15, "due": [1, 2, 3, 5, 9, 11], "dump": [1, 3], "durat": 18, "dure": [2, 3, 10, 19], "dynam": 19, "dynbench": [3, 8], "e": [1, 2, 3, 4, 5, 9, 10, 11, 12, 13, 15, 16, 18, 21, 22, 23, 24], "e69f00": [3, 15], "each": [0, 2, 3, 6, 7, 9, 10, 11, 12, 13, 14, 15, 21, 22, 23, 24, 25], "earli": [4, 5], "earlier": [0, 16, 25], "eas": 2, "easi": [0, 1, 2, 5, 7, 8, 9, 12, 15, 16, 22, 24], "easier": [2, 3, 4, 5, 6, 11, 12, 22, 23, 24, 25], "easili": [1, 2, 3, 4, 7, 8, 12, 19, 22, 24, 25], "echo": 7, "econom": 1, "ecosystem": [4, 5, 11], "edit": [0, 3, 5, 6, 7, 11, 22], "editor": [3, 4, 5, 7, 16], "educ": [3, 5, 10, 23], "effici": [1, 3, 4, 5, 9, 10, 12, 24], "effort": [10, 13, 18, 24], "eg": [3, 9], "either": [2, 3, 4, 6, 7, 11, 12, 13, 15, 16, 22, 25], "eleg": 24, "element": [3, 9, 10, 13, 15, 18, 19, 21], "elementwis": [3, 9], "elif": [12, 19], "els": [3, 4, 12, 13, 15, 16, 19, 23, 24], "email": [0, 3, 11], "emb": 23, "embark": 13, "embarrassingli": [8, 13], "embed": 8, "embrac": 5, "employe": 2, "empti": 9, "en": [3, 15, 23], "enabl": [3, 9, 12, 16], "encc": 18, "encod": [3, 16, 17, 18, 23], "encount": 2, "encourag": 6, "end": [2, 3, 7, 9, 10, 11, 13, 15, 22, 23], "end_dat": [3, 22], "endpoint": [23, 24], "enforc": 6, "engag": 19, "engin": [1, 8], "enhanc": 15, "enjoi": [0, 3], "enough": [1, 3, 4, 5, 9, 12, 13, 19, 22, 24], "enrico": 5, "ensur": [0, 3, 4, 5, 12], "enter": [7, 11, 12, 18], "entertain": 13, "entir": [13, 15, 25], "entri": [12, 22, 24], "enumer": 19, "env": [2, 3, 6, 22], "environ": [4, 7, 8, 11, 13, 18, 24, 25], "episod": [0, 11, 16, 22], "epub": [3, 18], "equal": [2, 3, 9], "equival": [13, 23], "erron": 12, "error": [1, 3, 8, 9, 12, 16, 17, 22, 23, 24], "esc": 7, "especi": [1, 4, 8, 9, 24], "espoo": [3, 22], "estim": [3, 13, 18], "etc": [3, 4, 5, 8, 9, 10, 12, 13, 21, 22, 23], "ethic": 17, "eval": 12, "even": [0, 1, 2, 3, 4, 6, 8, 9, 11, 13, 14, 15, 16, 19, 22, 23, 25], "evenli": 9, "event": [3, 12, 18], "eventu": 21, "ever": [2, 3, 23], "everi": [8, 9, 13, 15, 18, 22, 24], "everybodi": 24, "everyon": [3, 4, 7, 8, 19], "everyth": [0, 3, 4, 5, 6, 7, 8, 12, 13, 14, 15, 16, 19, 21, 22, 25], "evil": 18, "exact": [2, 6, 18], "exactli": [2, 3, 6, 8, 9], "exampl": [1, 2, 5, 6, 7, 8, 9, 11, 12, 18, 19, 21, 22, 23, 24, 25], "excel": [5, 12, 24], "except": 8, "excess": 23, "execut": [0, 1, 2, 3, 7, 9, 10, 12, 18, 22], "exercis": [4, 5, 6], "exist": [0, 1, 3, 4, 5, 7, 8, 10, 12, 13, 15, 21, 22, 24], "exit": [18, 22], "expand": 9, "expect": [0, 2, 3, 4, 5, 6, 8, 9, 15, 19, 22, 25], "expens": 10, "experi": [3, 13, 15, 16, 22], "experienc": [2, 3, 18], "expert": [5, 7], "expertis": 24, "explain": [3, 4, 9, 11, 17, 18], "explan": [3, 18], "explicit": [15, 24], "explicitli": [4, 22], "explor": [0, 6, 7, 9, 10, 13, 16], "export": [13, 22, 24], "exposit": [12, 13], "express": [2, 3, 8, 12, 23], "expressj": [3, 23], "extend": [8, 9, 25], "extens": [7, 8, 13, 15, 16], "extern": [2, 4, 5, 11, 13, 21], "extra": [3, 6, 9, 23], "extract": [3, 9, 12, 23, 24, 25], "extrem": 5, "ey": [3, 9, 16], "f": [1, 2, 3, 6, 9, 10, 13, 18, 21, 23], "f2py": 8, "face": 2, "fact": [8, 12, 23], "fairli": [3, 13, 21], "fake": 10, "fall": [3, 13], "fals": [1, 3, 9, 16], "famili": [3, 12, 15, 16], "familiar": [4, 5, 15, 19], "far": [1, 13, 22], "fare": [3, 12], "fascin": 13, "fashion": 13, "fast": [0, 3, 5, 8, 9, 12, 13, 18, 21, 24], "faster": [1, 2, 3, 6, 9, 10, 12, 13, 14, 18, 24], "fastest": [3, 7], "feather": 24, "featur": [3, 8, 10, 12, 13, 24, 25], "featuretyp": 25, "feed": [3, 16], "feel": [3, 6, 8, 9, 12, 15, 16], "fetch": [3, 15, 25], "few": [3, 9, 12, 13, 15, 16, 17, 18, 22], "fewer": 2, "ffill": 12, "fft": 21, "fi": [2, 7], "fib": 12, "fibo": 12, "fibonacci": [3, 7, 12], "field": [1, 24], "fig": [0, 3, 15, 22], "figsiz": [3, 12], "figur": [3, 7, 15, 16, 21, 22], "file": [0, 2, 5, 6, 7, 8, 9, 11, 12, 13, 16, 17, 18, 21, 23, 25], "file_path": [3, 17, 18], "filenam": [3, 22], "filepath": [3, 25], "fill": [0, 2, 3, 9, 10, 12], "fillna": 12, "filter": 12, "final": [0, 3, 5, 9, 10, 12, 13, 14], "financ": [3, 25], "find": [0, 2, 3, 5, 6, 7, 8, 12, 13, 15, 16, 18, 22, 23, 24, 25], "find_al": 23, "findal": [3, 17, 18], "fine": [3, 8], "finish": [3, 13, 18, 24], "finland": 23, "finnish": 23, "first": [0, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 18, 21, 22, 23, 25], "firstli": 2, "firstnam": [3, 11, 12], "fit": [13, 15, 16, 25], "five": 2, "fivethirtyeight": 16, "fix": 16, "flag": 22, "flake8": 17, "flash": 12, "flat": 10, "flavor": 12, "flexibl": 9, "flit": 11, "float": [1, 3, 9, 10, 19, 24], "float32": [3, 25], "float64": [1, 3, 9, 25], "floor": [3, 9], "fly": [3, 12], "focu": [16, 17], "folder": [2, 3, 11, 22], "follow": [0, 1, 2, 3, 5, 6, 7, 10, 11, 12, 13, 16, 17, 18, 19, 21, 22, 24, 25], "font": [3, 15], "fontsiz": [3, 15], "footnot": [3, 8], "forc": [13, 22], "forecast": [15, 16], "foreign": 13, "forg": [2, 3, 6, 11, 25], "forget": 2, "forgot": [2, 3], "forgotten_vari": 17, "fork": [0, 13], "form": [0, 3, 5, 6, 8, 12], "format": [4, 5, 7, 8, 9, 12, 16, 17, 21, 22, 23], "formatt": 2, "forth": 4, "fortran": [3, 4, 5, 8, 9, 10, 13, 21], "fortun": [13, 25], "forward": 12, "fouilloux": 5, "found": [8, 17, 23, 24], "foundat": 2, "fourier": 21, "fourth": [4, 11], "fraction": 4, "frame": [1, 12], "framework": [4, 5, 9, 13, 24], "free": [2, 6, 23], "freeli": [0, 6], "freez": 2, "freq": [1, 3, 12, 24], "friend": [15, 16], "friendli": [15, 16], "from": [1, 4, 5, 6, 7, 8, 9, 10, 12, 15, 17, 18, 19, 21, 24, 25], "from_dict": 24, "full": [1, 2, 6, 7, 9, 13, 21, 24], "fulli": [0, 1, 3, 6, 22], "function": [1, 2, 3, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 21, 22, 23, 24, 25], "functool": 12, "fundament": [15, 16], "further": [1, 3, 5, 11, 12, 13, 16, 23, 25], "futur": [2, 3, 6, 7, 8, 24], "g": [1, 2, 3, 4, 5, 9, 11, 12, 13, 15, 16, 18, 19, 21, 22, 23, 24], "galleri": 15, "gamma": 21, "gapminder_data": [3, 15], "gapminder_with_cod": [0, 3, 15], "gather": [3, 13], "gcc": 2, "gdp": [0, 3, 15], "gdppercap": [0, 3, 15], "gener": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 18, 21, 22, 23, 24], "generating_process_or_model": 25, "gentl": 13, "geojson": 16, "geopotenti": [3, 25], "geopotential_height_isobar": [3, 25], "geospatial_lat_max": 25, "geospatial_lat_min": 25, "geospatial_lon_max": 25, "geospatial_lon_min": 25, "get": [3, 4, 5, 6, 8, 9, 10, 13, 14, 16, 17, 18, 19, 21, 22, 23, 24, 25], "get_paramet": [3, 22], "get_rank": 13, "get_siz": 13, "get_text": 23, "ggplot": [15, 16], "ggplot2": [15, 16], "git": [0, 2, 3, 8], "github": [2, 4, 7, 8, 12, 13, 15, 16], "githubusercont": [0, 3, 6, 12, 15, 16, 22], "gitlab": 8, "give": [0, 1, 3, 6, 7, 9, 10, 12, 13, 15, 16, 18, 22, 23], "given": [2, 3, 9, 11, 12, 13, 18, 19, 22], "glanc": 13, "glerean": 5, "global": [3, 13, 15, 21], "glue": 5, "go": [0, 3, 4, 5, 6, 8, 11, 13, 15, 16, 18, 22, 23, 25], "goal": 4, "goe": [2, 3, 5, 6, 7, 8, 9, 11, 13], "good": [0, 1, 2, 3, 5, 7, 8, 9, 11, 12, 13, 15, 16, 17, 18, 21, 22, 25], "googl": [3, 25], "got": [22, 25], "gpu": [18, 25], "grammar": [15, 16], "graph": [8, 15, 16, 24], "graphic": [6, 8, 15, 16], "gravit": 7, "great": [1, 3, 7, 8, 13, 15, 16, 25], "greater": 2, "greatli": 9, "green": [3, 8], "grib1_cent": 25, "grib1_level_desc": 25, "grib1_level_typ": 25, "grib1_paramet": 25, "grib1_subcent": 25, "grib1_tablevers": 25, "grib_table_vers": 25, "grib_variable_id": 25, "gribcollect": 25, "grid": [1, 9, 25], "grid_map": 25, "group": [0, 3, 7, 8, 12, 15, 16], "groupbi": [3, 12], "grow": [3, 11, 18], "guess": [3, 13], "guid": [2, 3, 5, 6, 10, 12, 15], "guidelin": 11, "guppi": 18, "gutenberg": [3, 18], "gzip": [3, 23], "h": [10, 19, 22], "h5": 1, "h5_file": 1, "h5netcdf": 1, "h5py": [1, 8], "ha": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 17, 19, 21, 23, 24, 25], "hackmd": [3, 8], "had": [3, 4, 5, 8, 10], "half": 4, "halfwai": [3, 9], "hand": [3, 7, 16, 21], "handi": 25, "handl": [2, 8, 9, 12, 13], "happen": [3, 7, 8, 9, 10, 11, 13, 15, 16], "hard": [7, 10, 22, 24], "harder": [2, 6], "hardli": 22, "hardwar": 13, "haskel": 5, "hasn": [4, 5], "have": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25], "haven": 25, "hdf5": [8, 24], "head": [3, 7, 12, 24], "heapi": 18, "heard": 8, "heatmap": [3, 12, 16], "heavi": [5, 10], "heavili": [1, 10], "height": [3, 25], "hello": [6, 19], "help": [3, 4, 5, 7, 15, 16, 17, 18, 22, 24, 25], "helper": 3, "henc": [3, 9, 12], "her": [0, 3], "here": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 22, 23, 24, 25], "hetting": 13, "hex": [3, 15], "hidden": [2, 3], "high": [1, 3, 4, 5, 8, 9, 12, 13, 15, 16, 24], "higher": [6, 8, 13, 18], "highli": [2, 13], "highlight": [3, 13, 17], "hint": [3, 6, 7, 12, 22], "hipolab": 23, "hist": [3, 12], "histogram": [3, 12, 16, 25], "histori": [2, 25], "hit": 12, "hold": 11, "home": [6, 8, 15, 16], "homepag": 23, "hood": [3, 8, 13, 25], "hopefulli": [4, 7, 25], "host": [6, 8, 11], "hour": 6, "hous": 2, "how": [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 21, 22, 24, 25], "howev": [1, 2, 3, 4, 12, 13, 15, 17, 22, 23, 24], "hpa": 25, "hpc": 22, "href": 23, "html": [3, 5, 15, 16, 18, 23], "http": [0, 2, 3, 5, 6, 7, 8, 11, 12, 13, 15, 16, 17, 18, 22, 23, 24], "hub": 8, "huge": [1, 2, 4, 5, 10], "human": [1, 3, 24], "humid": 25, "humidity_data": 25, "hundr": 23, "i": [1, 3, 4, 6, 10, 11, 12, 13, 14, 15, 16, 17, 19, 21, 22, 23], "iat": 12, "id": [3, 4, 9, 23], "id_var": 12, "idea": [1, 3, 4, 7, 8, 9, 12, 24], "ideal": [3, 15], "ident": [3, 9, 13], "identif": [3, 23], "identifi": [0, 11, 13], "idx": 9, "ifram": 23, "ignor": [5, 17], "igraph": 1, "ii": 19, "ill": 4, "illustr": [3, 10, 13, 25], "iloc": [3, 12], "imag": [0, 3, 8, 10, 18, 24, 25], "imagin": [3, 5, 11, 16, 22, 25], "imgur": 23, "implement": [3, 5, 6, 9, 10, 12, 13, 15, 16, 17, 21], "implic": 10, "implicit": 15, "import": [0, 1, 2, 3, 4, 6, 7, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 21, 22, 23, 24, 25], "imposs": [3, 7, 15, 16], "impract": 10, "improv": [2, 3, 8, 13, 16, 17, 18], "inc": 2, "inch": [3, 15], "includ": [0, 1, 2, 3, 6, 8, 9, 10, 12, 13, 21, 25], "incompat": 2, "inconsist": 16, "inconveni": 22, "increas": [3, 18, 24], "increment": [3, 7, 8], "inde": 24, "independ": [3, 7, 24], "index": [1, 3, 8, 10, 11, 12, 16, 19, 25], "index_col": 12, "indic": [3, 9, 10, 12, 25], "indirect": [3, 9], "individu": [6, 15, 23, 24, 25], "ineffect": 24, "ineffici": 1, "inevit": 10, "infal": 1, "infer": [0, 3], "infinit": [3, 10], "info": [12, 24], "inform": [0, 2, 3, 8, 11, 12, 13, 16, 17, 18, 21, 22, 23, 24, 25], "infrastructur": 11, "infrequ": 18, "init": 2, "initi": [3, 6, 9, 10, 23, 24], "inlin": [3, 7, 12], "inner": [3, 12], "input": [3, 4, 7, 9, 10, 13, 14, 15, 16, 18, 22], "insensit": [3, 18], "insert": [3, 7, 21], "insid": [3, 9, 10, 16], "inspect": [1, 12, 23], "instal": [0, 1, 2, 3, 4, 5, 7, 8, 12, 13, 17, 18, 23, 25], "install_requir": 2, "instanc": [2, 3, 5, 11, 13, 15, 17, 18, 19, 22], "instead": [0, 2, 3, 7, 9, 10, 12, 13, 15, 16, 21, 22, 24], "institut": [2, 6], "institutt": 16, "instruct": [3, 6, 7, 9, 10, 11], "instructor": [0, 3, 5], "int": [3, 9, 10, 12, 13, 17, 18, 19], "int32": [12, 25], "int64": [3, 9, 12, 25], "integ": [1, 3, 9, 10, 12, 19, 24], "integr": [3, 7, 11, 25], "intel": 10, "intend": [1, 3, 10, 17, 24], "intens": [0, 3], "interact": [3, 4, 5, 6, 7, 11, 13, 15, 16], "interconnect": 1, "interest": [2, 3, 11, 12, 13, 16, 25], "interfac": [1, 2, 4, 5, 6, 7, 11, 13, 16, 21, 22, 23], "interfer": 6, "interleav": 7, "intermediari": [3, 24], "intern": [8, 9], "internet": [3, 12, 15, 16], "interpol": 21, "interpret": [2, 8, 10, 13, 22], "interv": [3, 9, 21, 22], "intro": [4, 6, 12], "introduc": [2, 4, 5, 15, 25], "introduct": [4, 5, 10, 12, 13, 16, 21, 25], "introductori": 13, "intuit": 16, "inv": 13, "invent": 9, "invers": 13, "invert": 13, "invest": 13, "investig": [3, 12], "invit": 6, "invok": 19, "involv": [4, 10, 13], "io": [2, 3, 13, 16, 17, 23, 24], "iosp": 25, "ipynb": [3, 22], "ipyparallel": 8, "ipython": [7, 8, 13, 23], "irrelev": 8, "irreproduc": 7, "is_passeng": 12, "isel": 25, "isin": [3, 12], "isn": [3, 4, 5, 6, 7, 8, 25], "isna": 12, "iso_c_bind": 13, "isobar": 25, "isobaric1": 25, "isol": [2, 11], "isort": 17, "issu": [2, 6, 8, 23], "ital": [3, 7], "iter": 19, "ito": 15, "its": [1, 2, 3, 6, 9, 10, 11, 12, 13, 16, 23], "itself": [3, 7, 9, 22], "j": [3, 23], "jann": [5, 19], "januari": [3, 22], "jargon": [6, 19], "java": 1, "job": [8, 13], "joblib": [8, 13], "join": [0, 3, 12, 16], "journei": 18, "json": [0, 3, 22, 23, 24], "json_norm": 24, "jsonl": 23, "jsonlin": 23, "julia": [1, 5, 8], "juliett": 0, "june": [3, 22], "jupyt": [4, 5, 6, 8, 9, 11, 12, 13, 15, 16, 23], "jupyterlab": [3, 4, 7, 12, 17, 20, 22, 25], "jupytext": 22, "just": [0, 2, 3, 5, 8, 9, 10, 12, 13, 14, 16, 21, 22, 24, 25], "k": [15, 25], "k3d": [15, 16], "kaggl": 12, "keep": [1, 2, 3, 8, 9, 18, 23, 24, 25], "kei": [3, 7, 9, 13, 16, 23], "kept": [0, 3], "kernel": [3, 5, 7, 10], "keyboard": 7, "keyword": [19, 23], "kind": [2, 3, 9, 10, 12, 21], "klimaservicesent": 16, "know": [2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 15, 16, 17, 18, 19, 21, 22, 25], "knowledg": [0, 3, 10, 15, 16], "known": [3, 7, 9, 10], "knuth": 18, "kth": 13, "kz": [3, 22], "l": [10, 19], "lab": [6, 7, 8], "label": [3, 15, 22, 25], "labels": [3, 15], "laboratori": 2, "lack": 17, "laid": 10, "lam": 12, "lambda": [3, 11, 12], "lambertconformal_project": 25, "languag": [1, 5, 6, 7, 9, 10, 12, 15, 16, 19, 21], "lapack": 9, "laptop": [0, 4], "larg": [1, 3, 4, 5, 6, 8, 10, 12, 13, 16, 18, 22, 25], "larger": [3, 11, 12, 15, 18, 23, 24], "largest": [2, 3, 12, 24], "last": [1, 3, 5, 7, 9, 25], "lastnam": 11, "lat": 25, "late": [4, 5], "later": [0, 1, 2, 3, 10, 13, 16, 23, 25], "latest": 23, "latim": 16, "latitud": 25, "latter": 15, "launch": [0, 3], "launcher": [3, 6, 22], "laureat": [3, 12], "layer": [1, 3, 13, 16], "layout": [10, 12], "lazi": [12, 13], "ldot": 10, "le": 25, "lea": [0, 3], "lead": [22, 24], "learn": [0, 2, 3, 4, 5, 6, 10, 11, 12, 13, 15, 16, 17, 18, 20, 22, 23, 24, 25], "learner": [5, 13], "least": [4, 7, 11, 19], "leav": [2, 3, 9], "lectur": [3, 22, 25], "led": 11, "left": [3, 5, 6, 7, 9, 10, 15, 16, 25], "legaci": 11, "legal": 17, "legend": [3, 15, 16], "len": [3, 9, 17, 18], "length": [3, 10, 15], "leo": [3, 18], "less": [2, 3, 5, 7, 9, 10, 15, 18, 23], "lesson": [3, 4, 5, 6, 7, 8, 10, 12, 13, 15, 16, 19, 22, 25], "let": [1, 2, 3, 5, 7, 9, 10, 11, 12, 13, 15, 17, 21, 22, 23, 24, 25], "level": [4, 5, 8, 9, 13, 15, 16], "lib": [3, 10], "librari": [1, 2, 4, 5, 6, 9, 11, 12, 13, 15, 16, 21, 22, 23, 24, 25], "licens": [2, 5, 6, 11], "life": [0, 3, 15, 16], "lifeexp": [0, 3, 15], "lifespan": [3, 12], "lift": [5, 10], "light": 12, "lightweight": [2, 7, 23], "like": [2, 3, 4, 5, 7, 8, 9, 10, 12, 13, 15, 16, 22, 23, 24, 25], "lil": [3, 21], "limit": [6, 7, 11, 12], "linalg": [10, 13], "line": [3, 4, 5, 7, 9, 11, 12, 13, 15, 16, 17, 18, 21, 23], "line_profil": 18, "linear": [3, 10, 15, 21], "liner": 12, "linewidth": [3, 12], "link": [8, 18, 22], "linspac": [3, 9], "linux": [2, 6, 7, 11], "list": [0, 2, 5, 6, 7, 8, 9, 10, 13, 14, 15, 16, 18, 19, 23, 25], "littl": [3, 4, 5, 8, 10], "live": [3, 10], "ll": [1, 2, 3, 5, 6, 8, 12, 22, 24], "load": [1, 2, 3, 8, 9, 12, 13, 16, 23, 24], "load_npz": 1, "loadtxt": 1, "loc": [3, 12, 25], "local": [0, 3, 12, 16, 22], "locat": [3, 8, 17, 18, 25], "location1": 25, "location2": 25, "location3": 25, "lock": [13, 17], "log": [0, 18, 23], "logic": 5, "logilab": 0, "lon": 25, "long": [0, 1, 2, 3, 6, 8, 10, 12, 16, 21, 22, 24], "long_nam": 25, "longer": [2, 3, 8, 10, 13, 16], "longitud": 25, "longitudin": 23, "look": [0, 3, 5, 7, 8, 9, 10, 11, 12, 13, 15, 16, 21, 22, 23, 25], "lookup": [3, 18], "loop": [3, 7, 9, 14, 19, 22, 23], "lose": [1, 24], "lot": [1, 3, 4, 5, 6, 7, 8, 12, 13, 16, 21, 22, 24, 25], "low": [3, 7, 8, 12, 13, 15], "lower": [3, 17, 18], "lower_limit": 11, "lru_cach": 12, "luck": 5, "luckili": 13, "lvalu": 19, "m": [2, 7, 9, 11, 12, 14, 15, 16, 24], "mac": [2, 11], "machin": [5, 11, 13], "machineri": 10, "maco": [6, 7], "macro": [3, 21], "made": [2, 3, 8, 12, 13, 22], "magic": [3, 7, 13, 14], "mai": [0, 2, 3, 4, 5, 6, 7, 9, 11, 13, 15, 16, 22, 23], "main": [0, 2, 3, 4, 5, 7, 10, 13, 15, 16, 18, 21], "mainli": 3, "mainstream": 8, "maintain": [2, 3, 6, 7, 8, 18], "major": [2, 3, 13, 15, 24], "make": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 21, 22, 23, 24, 25], "malloc": 10, "mamba": [3, 6], "manag": [4, 5, 6, 8, 10, 11, 13, 22], "mani": [0, 1, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 19, 21, 22, 23, 24], "manipul": [8, 10], "manner": [4, 5, 8], "manual": [0, 2, 3, 6, 9, 10, 13, 15, 16, 17, 22, 23, 25], "manuscript": 15, "map": [13, 14, 16], "margaret": 12, "mark": 12, "mark_area": [3, 16], "mark_bar": [3, 16], "mark_circl": 16, "mark_point": [3, 16], "markdown": [3, 7], "market": 21, "mask": 12, "master": [0, 2, 3, 6, 10, 12, 15, 16, 22], "mat": 21, "match": [1, 3, 9, 17, 18], "materi": [4, 5, 12, 19], "math": [8, 10, 21], "mathemat": [9, 10, 21], "matlab": [1, 9, 15, 21], "matplotlib": [0, 2, 4, 5, 8, 16, 20, 22, 25], "matric": [1, 3], "matrix": [3, 9, 13, 18, 21], "matrix2": [3, 21], "matter": [5, 15], "matur": 5, "max": [3, 9, 12, 16, 25], "max_popul": 24, "maximum": [2, 3, 12, 16], "maxpric": 23, "mayavi": 8, "mayb": [2, 3, 9, 22], "mb": 10, "md": [0, 3, 7, 11], "me": [2, 3, 16], "mean": [2, 3, 4, 5, 7, 9, 10, 12, 13, 14, 19, 24, 25], "meant": [0, 2, 3, 5], "measur": [3, 10, 12, 21, 25], "mechan": 13, "median": [3, 12, 25], "medic": 18, "melt": 12, "member": [3, 12, 17], "memo": 12, "memori": [3, 9, 10, 12, 13, 18, 24, 25], "memory_profil": 18, "mention": [1, 4, 6, 8, 12, 13, 24], "mentor": 17, "menu": [0, 3, 7, 12, 22], "mere": [3, 9, 10], "merg": [12, 16], "mess": [4, 11], "messag": [6, 8, 11, 13, 22], "messi": 12, "met": [16, 19], "meta": [2, 3, 11, 17, 23], "metadata": [0, 1, 3, 24, 25], "metavar": 22, "meteorologisk": 16, "method": [2, 3, 6, 7, 8, 9, 10, 12, 13, 15, 21, 23, 25], "micromamba": 2, "micropipenv": 2, "microsoft": 17, "mid": [4, 5], "middl": [9, 10], "might": [0, 1, 2, 3, 4, 5, 6, 8, 11, 12, 15, 18, 21, 22, 23, 24, 25], "migrat": 7, "million": [3, 10, 23], "mimic": [2, 15], "min": [5, 12, 16, 17, 18, 25], "mind": [15, 16, 18], "miniconda": [2, 3, 6], "miniforg": [2, 3, 7], "miniforge3": [6, 7], "minim": [2, 3, 7, 8, 9, 15, 16], "minimum": 2, "minoconda": 6, "minor": [3, 15], "minpric": 23, "minut": [0, 3, 12, 18], "mirror": 2, "miss": [2, 3, 4, 8, 12, 16, 18], "mistak": 2, "mitig": 2, "mix": 15, "mkl_num_thread": 13, "ml": 13, "mm": [3, 16, 22], "mode": [1, 7, 23], "model": [3, 12, 13, 24], "modern": [5, 10, 15], "modif": [3, 16], "modifi": [2, 3, 10, 15, 16, 21, 22, 25], "modul": [1, 2, 3, 7, 8, 10, 11, 13, 16, 21, 22, 23], "modular": [7, 22], "modulenotfounderror": [3, 16], "monopoli": 17, "month": [3, 16], "monthli": [3, 16], "more": [1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 17, 19, 21, 22, 23, 24, 25], "most": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 13, 15, 16, 17, 18, 21, 25], "mostli": 25, "move": [8, 10, 11, 15], "mpi": 8, "mpi4pi": [3, 13], "mpi_test": [3, 13], "mpiexec": [3, 13], "mpirun": [3, 13], "mr": [3, 12], "mri": 18, "msft": [3, 25], "msys2": 2, "much": [2, 4, 5, 6, 7, 8, 11, 12, 13, 16, 18, 22, 23, 24, 25], "multi": [3, 4, 13, 16, 24], "multidimension": [1, 9, 25], "multipl": [1, 3, 7, 9, 10, 12, 13, 14, 17, 19, 22, 24, 25], "multipli": [3, 9, 10, 15, 21], "multiprocesss": 13, "multithread": 3, "must": [3, 10, 16, 22, 24], "my": [0, 2, 3, 8, 9, 12, 15, 16, 24], "my_object": [1, 3], "my_pickled_object": [1, 3], "my_script": 22, "mybind": [0, 3, 13], "mydata": [3, 16], "myfunct": [3, 21], "mynam": 11, "mypi": 17, "mysteri": 10, "n": [1, 3, 6, 7, 9, 10, 11, 12, 13, 14, 16, 18, 22, 24, 25], "n_col": [3, 10], "n_element": 10, "n_inside_circl": [3, 13, 14], "n_inside_circle_sum": 14, "n_row": [1, 3, 10, 24], "n_sum": 14, "n_task": [3, 13], "naiv": 10, "name": [2, 3, 4, 6, 7, 11, 12, 13, 15, 16, 19, 21, 22, 24], "nan": 12, "nanosecond": 10, "narr": 7, "narr_19930313_0000": [3, 25], "narrow": 23, "narrowli": 2, "nasser": [3, 12], "nation": [2, 25], "nativ": 1, "natur": [8, 9, 24], "navig": [3, 6, 7, 11], "nbconvert": [3, 22], "nbdime": 7, "nbval": 7, "nbviewer": [3, 16], "nbyte": 10, "nc": [1, 3, 25], "ncol": 12, "ndarrai": 9, "nearest": [3, 9], "neat": 16, "necessari": [2, 10, 11, 13], "necessarili": 8, "need": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 21, 22, 23, 24, 25], "neg": [3, 9, 12], "nest": [1, 24], "netcdf4": [24, 25], "network": [3, 8, 24], "networkx": [1, 3, 8], "neural": [3, 24], "new": [0, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 18, 22], "new_a": [3, 7], "new_b": [3, 7], "newer": 2, "newli": [0, 3], "next": [0, 2, 3, 7, 9, 10, 11, 13, 15, 16, 17, 23], "nice": [1, 3, 6, 12, 16, 19, 22, 23], "nicer": [3, 8, 22], "nichola": [3, 12], "ninja": 23, "nlargest": 24, "nltk": 8, "nnumber": 13, "nnumpi": 2, "nobelpr": 12, "node": [3, 13], "nomin": 16, "non": [2, 3, 4, 7, 9, 12, 21], "none": [1, 3, 10, 13], "norm": 10, "normal": [1, 3, 13, 21, 23, 25], "norsk": 16, "north": 25, "norwai": 16, "note": [2, 3, 6, 9, 11, 12, 13, 22, 23, 25], "notebook": [2, 6, 7, 8, 9, 11, 12, 13, 15, 16, 23, 24], "noth": [8, 11], "notic": [3, 8, 9, 13, 14], "notifi": 18, "notimplementederror": 12, "now": [0, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 16, 22, 24, 25], "nowadai": 2, "np": [1, 3, 9, 10, 12, 13, 16, 24, 25], "np_arrai": [3, 9], "npy": [3, 9, 24], "npz": 1, "nrow": 12, "ntranspos": 10, "numba": [8, 13], "number": [0, 1, 2, 3, 7, 9, 10, 12, 13, 15, 16, 18, 19, 21, 22, 24, 25], "number_in_circl": [3, 13, 14], "numer": [5, 11, 12], "numexpr": 8, "numgrid": [3, 8], "numpi": [2, 4, 5, 8, 12, 13, 16, 20, 21, 24], "numpyi": [3, 9], "nxm": 24, "o": [3, 9, 13, 14, 15, 16, 18, 21], "obj": 23, "object": [3, 5], "observ": [3, 11, 12, 16, 22], "obtain": [3, 10, 16, 22], "occas": 9, "oct": 2, "octob": [3, 22], "off": [4, 10], "offer": [12, 19, 25], "offici": 1, "offload": 5, "offset": 10, "often": [1, 2, 3, 4, 5, 8, 9, 11, 12, 13, 15, 16, 18, 19, 23, 24], "ok": [4, 6, 12, 15, 24, 25], "okab": 15, "old": [2, 3, 4, 5, 7, 8, 12], "older": [3, 8], "oliph": 10, "omp_num_thread": 13, "onc": [2, 3, 6, 7, 8, 11, 14, 22, 24, 25], "one": [1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 21, 22, 23, 24, 25], "ones": [2, 3, 6, 9, 10], "onli": [2, 5, 6, 7, 10, 11, 12, 13, 15, 16, 17, 18, 22, 24, 25], "onlin": [0, 3, 6, 8], "onnx": [3, 24], "onto": [3, 13], "oo": [3, 9], "opac": [3, 16], "open": [0, 1, 2, 3, 5, 6, 8, 11, 12, 16, 18, 21, 22, 23, 25], "open_dataarrai": 1, "open_dataset": [1, 3, 25], "openair": 0, "opendreamkit": 0, "openmp": 13, "openmpi": [3, 13], "openpyxl": 1, "oper": [0, 2, 3, 5, 6, 7, 10, 11, 12, 13, 18, 25], "oppos": 13, "opposit": 12, "optim": [1, 8, 10, 13, 15, 16, 21], "option": [2, 4, 6, 7, 9, 12, 15, 16, 21, 24], "optionspars": [3, 22], "order": [1, 3, 4, 7, 9, 12, 22, 25], "ordin": 16, "org": [0, 2, 3, 5, 7, 8, 11, 12, 15, 16, 18, 20], "organ": [6, 7, 8, 24], "organis": 12, "orient": [5, 15], "origin": [1, 3, 5, 8, 9, 10, 12, 22, 23], "originating_or_generating_cent": 25, "originating_or_generating_subcent": 25, "oslo": 16, "osx": [2, 11], "other": [0, 2, 3, 4, 5, 7, 10, 11, 12, 15, 17, 19, 22, 23, 24], "otherwis": [6, 17, 18, 19], "ou": [0, 3], "our": [1, 3, 6, 7, 9, 10, 11, 12, 13, 14, 15, 22, 23, 24, 25], "ourselv": 18, "out": [2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 15, 16, 18, 21, 22, 24], "outlin": 4, "outperform": 9, "output": [3, 4, 6, 7, 9, 10, 13, 16, 22, 25], "output_file_nam": 22, "outsid": [3, 7, 11, 15, 22], "outsourc": 10, "over": [2, 3, 4, 6, 8, 9, 10, 12, 15, 16, 18, 19, 22, 25], "overcom": 13, "overhead": [12, 18], "overview": [3, 4, 12, 15, 16, 17, 18, 19], "own": [1, 2, 3, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 22, 23, 24], "packag": [0, 4, 5, 6, 9, 10, 12, 13, 15, 22, 23, 25], "page": [0, 2, 3, 5, 6, 7, 9, 12, 13, 19, 21, 22, 23, 24], "pair": [12, 23], "palett": 15, "panda": [0, 1, 2, 4, 5, 8, 13, 16, 20, 22, 24], "paper": [0, 2, 3, 8, 9, 25], "papermil": 22, "paradigm": 13, "parallel": [4, 5, 12, 22, 25], "parallelis": [3, 13], "param": [3, 16, 23], "paramet": [3, 9, 12, 22], "parameter": 22, "parent": 6, "parquet": 24, "pars": 3, "parse_arg": [3, 22], "parser": [3, 22, 23], "part": [3, 4, 7, 9, 10, 13, 15, 16, 18, 23], "partial": 24, "particip": [3, 6, 23], "particular": [3, 6, 9, 21, 23, 25], "particularli": [5, 8], "partner": 6, "pass": [3, 8, 9, 13, 15, 22, 23, 25], "passeng": 18, "password": [3, 11, 23], "past": [0, 2, 3, 5, 7, 8, 12, 16, 22, 24], "path": [3, 4, 8, 11, 23], "pattern": 22, "pcd": [3, 8], "pd": [0, 1, 3, 12, 15, 16, 22, 24], "pdc": 13, "peac": [3, 18], "peculiar": 9, "peopl": [2, 3, 4, 7, 9, 11, 12, 15, 24], "pep": 17, "per": [0, 3, 7, 13, 14, 15], "perf_count": 13, "perfect": [3, 7, 8, 15, 16], "perfectli": 19, "perfetto": 18, "perform": [1, 3, 5, 9, 10, 12, 13, 18, 21], "perhap": [8, 15], "period": [1, 3, 12, 18, 22, 24], "perman": [0, 8], "permiss": [3, 13], "person": [0, 2, 3, 4, 8, 15, 16, 19], "persona": 5, "pg2600": [3, 18], "phase": [7, 14], "phd": [0, 3, 4, 5], "phone": 18, "physic": [1, 3, 12, 25], "pi": [3, 13, 14], "pi_estim": 13, "pick": 24, "pickl": [3, 24], "pictur": [2, 4], "piec": [13, 24], "pil": 8, "pillow": 8, "pin": 11, "pint": 25, "pip": [1, 2, 3, 13], "pipelin": [2, 15, 16], "pipenv": 2, "piqu": [3, 12], "pitfal": [7, 15], "pivot": [3, 12], "pivot_t": [3, 12], "pixel": 24, "pixi": 2, "place": [1, 2, 3, 7, 9, 10, 11, 22], "plai": [3, 7, 10, 12], "plain": 25, "plan": 5, "plasma": 16, "platform": 11, "playlist": 5, "pleas": [2, 3, 5, 6, 11, 15, 17, 18], "plenti": [1, 4, 24], "plot": [4, 5, 7, 12, 22, 24], "plotli": [0, 3, 15, 16], "plotnin": [15, 16], "plt": [0, 3, 15, 22, 25], "png": [3, 15, 16, 22, 24], "poetri": [2, 11], "point": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 13, 14, 15, 16, 19, 22, 23], "pointer": 10, "polar": 12, "polici": 5, "pool": [3, 13, 14], "poor": [3, 12], "popul": 24, "popular": [1, 2, 5, 11, 13, 15, 17], "portion": [6, 10, 25], "posit": [2, 3, 9, 16, 22, 25], "possibl": [0, 1, 2, 3, 4, 7, 9, 10, 11, 12, 13, 15, 16, 17, 19, 23, 24], "possibli": [0, 3, 4, 5, 17], "post": [8, 13, 15, 16, 25], "potenti": [17, 18, 24], "power": [6, 7, 9, 12, 16, 24, 25], "ppp": [3, 15], "practic": [0, 2, 4, 5, 7, 8, 11, 15, 16, 22, 23], "pre": [6, 15, 17], "preced": [3, 22], "precipit": [3, 16, 22], "precis": [10, 12, 18, 19, 24], "predict": [3, 8, 18], "prefer": [3, 8, 15, 23], "prefix": [4, 11], "prematur": 18, "prepar": [4, 5, 8, 11], "preprocess": [3, 22, 24], "prereq": 5, "prerequisit": [0, 3, 4], "present": [0, 1, 2, 3, 5, 12, 15, 23], "pressur": 25, "pressure_data": 25, "pressure_df": 25, "pressure_numpi": 25, "pretend": 4, "pretti": [3, 8, 21], "prevent": [3, 7, 13], "previou": [6, 7, 11, 14, 17, 22, 24], "previous": [2, 3, 24], "price": [3, 12, 23, 25], "primari": 8, "primarili": 7, "primit": 13, "principl": 4, "print": [1, 2, 3, 6, 7, 9, 10, 11, 12, 13, 15, 16, 18, 19, 21, 22, 23, 24, 25], "printer": [15, 16], "printf": 10, "priorit": 24, "prioriti": 2, "privaci": 17, "pro": [2, 18], "probabl": [2, 3, 6, 8, 9, 12, 13, 15, 16, 18, 21], "problem": [0, 1, 2, 3, 4, 7, 13, 15, 16, 17, 18, 22, 24, 25], "proce": 13, "procedur": [15, 16, 24], "process": [3, 5, 8, 10, 12, 13, 14, 15, 16, 18, 21, 22, 23, 24], "processor": [13, 18], "produc": [3, 8, 10, 11, 12, 15, 16], "product": [3, 5, 21], "profession": 2, "profil": [5, 6, 13, 17], "program": [1, 2, 4, 5, 6, 7, 8, 10, 12, 15, 17, 18, 19, 22, 23, 24], "programm": 18, "project": [0, 3, 5, 6, 8, 16, 18, 24], "promot": 7, "prompt": [6, 7], "prone": [23, 24], "proper": [7, 10], "properli": 10, "properti": 7, "proprietari": 2, "prototyp": [7, 22], "provid": [0, 1, 2, 3, 4, 5, 6, 9, 12, 13, 15, 18, 22, 23, 25], "psf": 2, "public": [0, 7, 8, 11, 16, 25], "publish": [0, 2, 3, 4, 8, 10, 24], "pull": [3, 8, 12], "pure": [3, 9, 11, 13, 24, 25], "purpos": [0, 6, 7, 16, 21], "push": [0, 3, 7], "put": [2, 3, 8, 9, 12, 22, 25], "py": [2, 3, 7, 11, 13, 18, 22, 25], "py38_0": 11, "pyarrow": 1, "pybind11": 13, "pycodestyl": 17, "pydata": [16, 20], "pyenv": 2, "pyflak": 17, "pyinstrument": 18, "pylint": 17, "pympi": 8, "pympler": 18, "pyngl": [15, 16], "pyo3": 13, "pypi": [3, 8], "pyplot": [0, 3, 15, 22, 25], "pyproject": [2, 11], "pyre": 17, "pyright": 17, "pytabl": [1, 8], "pytest": 8, "pythagorean": 10, "pythia": 25, "pythia_dataset": [3, 25], "python": [0, 4, 7, 9, 10, 12, 13, 15, 16, 18, 21, 24, 25], "python3": [3, 6, 11, 22], "pytorch": 8, "pytz": 8, "q": [16, 19], "quad": [3, 11, 21], "quadpack": [3, 21], "qualit": 15, "qualiti": [8, 15, 16], "quantit": 16, "quantiti": 25, "queri": [3, 15, 23], "question": 3, "quick": [1, 3, 5, 15, 21, 25], "quickli": [1, 3, 7, 9, 25], "quit": [2, 9, 10, 13, 22, 25], "quot": [8, 18], "r": [1, 2, 3, 9, 10, 11, 15, 16, 17, 18, 23], "rabbit": 12, "race": 10, "radovan": 5, "rai": 18, "rain_in_cairo": 22, "rain_in_tapiola": 22, "rainfal": 22, "rais": 12, "ran": [2, 12], "rand": [3, 9, 10, 12, 16, 21, 25], "rand_max": 10, "randint": [3, 9, 25], "randn": [3, 12, 16], "random": [1, 2, 3, 8, 9, 10, 12, 13, 14, 16, 21, 23, 24, 25], "randomli": [3, 8, 23, 24], "randomst": [3, 12, 16], "rang": [1, 2, 3, 7, 9, 12, 13, 14, 16, 19, 22, 23, 24], "rank": [3, 9, 13], "rantahar": 13, "rare": [1, 8], "rate": [3, 12], "rather": [0, 3, 9, 10, 12, 18, 22], "ravel": [3, 10], "raw": [0, 3, 5, 6, 7, 9, 12, 15, 16, 22, 23, 25], "raymond": 13, "rb": [1, 3], "re": [1, 2, 5, 6, 7, 8, 9, 12, 13, 14, 17, 18, 22, 24], "read": [0, 1, 3, 4, 5, 7, 8, 9, 10, 12, 17, 18, 19, 21, 23, 24, 25], "read_csv": [0, 1, 3, 12, 15, 16, 22], "read_excel": 12, "read_feath": 1, "read_hdf": [1, 12], "read_json": [1, 12], "read_parquet": 1, "readabl": [1, 3, 17, 22, 24, 25], "reader": 23, "readi": [0, 3, 6, 11, 15, 16], "readlin": 1, "readm": [0, 2, 3, 11], "readthedoc": [17, 23], "real": [0, 3, 11, 15, 16, 18, 25], "realiz": [3, 13, 15], "realli": [3, 4, 5, 6, 12, 13, 16], "reanalysi": 25, "reason": [1, 2, 3, 4, 5, 13, 15, 16], "recal": [3, 9], "receiv": [3, 12], "recent": [2, 3, 6, 11, 16], "recip": 11, "recogn": 17, "recommend": [0, 2, 3, 4, 6, 10, 11, 13, 15, 18, 22, 23, 24], "record": [2, 3, 8, 10, 18], "recreat": 2, "recurs": 12, "red": [3, 15, 16], "redefin": 19, "redesign": 5, "redirect": [0, 3], "reduc": [5, 13, 14, 16], "redund": 13, "ref": 9, "refer": [3, 7, 9, 10, 12, 19], "refin": [3, 16], "regard": [3, 23], "regardless": 14, "regener": [15, 16], "region": 25, "regist": [0, 3], "register_dataset_accessor": 25, "regular": 9, "reifi": 19, "rel": [3, 6, 8, 11, 15, 24], "relat": [1, 2, 5, 11], "relationship": 12, "releas": [0, 3, 7, 8, 13], "relet": [3, 7], "relev": [2, 3, 8, 21, 23], "reli": 9, "relianc": 2, "rememb": [2, 6, 8, 12, 15, 16], "remind": [3, 10], "remot": [0, 6, 15], "remov": 2, "render": [0, 3], "repeat": [3, 7, 9, 10, 22], "replac": [2, 3, 4, 8, 12, 16], "replic": [2, 3, 23], "repo": [0, 2, 3], "repo2dock": 0, "report": [3, 8, 18, 22], "repositori": [2, 8, 11, 12, 16], "repositorio": 2, "repres": [1, 3, 10, 12, 18, 21, 24, 25], "represent": [3, 21], "reproduc": [2, 4, 5, 8, 22, 24], "request": [1, 8, 10, 12, 13, 15, 17, 24], "requests_documentation_url": 23, "requir": [0, 3, 6, 8, 11, 12, 13, 15, 18, 22, 24], "requiremnt": 7, "rerun": 22, "research": [0, 2, 4, 5, 6, 8, 11, 12, 22, 24], "resembl": [3, 25], "reserv": [0, 3], "reshap": [3, 9], "resolv": 6, "resourc": [2, 3, 8, 12, 16, 22], "respect": [11, 12, 22], "respons": 24, "response_cont": 23, "response_json": 23, "rest": [1, 4, 7, 9, 15, 19, 24], "restrict": 23, "result": [1, 2, 3, 7, 8, 9, 10, 12, 13, 14, 15, 16, 18, 21, 24, 25], "return": [3, 9, 10, 11, 12, 13, 14, 17, 18, 19, 21, 23, 25], "reus": [2, 3, 5, 13], "reusabl": [4, 8], "reveal": [3, 16], "revers": [3, 9, 10], "review": 2, "rich": [3, 12], "richard": [5, 19], "ridicul": 21, "right": [3, 4, 5, 7, 8, 9, 10, 12, 13, 22, 24, 25], "risk": [8, 15], "riski": 1, "rkdarst": [3, 8], "rng": [10, 12], "robust": 22, "role": [7, 9], "room": [0, 3], "root": [3, 11, 13, 18], "roughli": 19, "round": [1, 3, 9, 12, 13], "rout": 13, "routin": [1, 9, 21], "row": [1, 3, 9, 10, 12, 16, 25], "rp5": [3, 22], "rrr": 22, "rst": 3, "ruff": 17, "rule": [2, 3, 10, 21], "run": [0, 2, 4, 6, 10, 11, 12, 14, 15, 16, 18, 22, 25], "runner": [12, 13], "runtest": 11, "runtim": [7, 13, 19], "rust": [5, 12, 13], "rvalu": 19, "rwidth": [3, 12], "s2c2": [3, 9], "safe": 13, "safest": 2, "sai": [2, 3, 4, 8, 9, 10, 12, 19, 21, 23], "said": [1, 23, 24], "same": [1, 2, 3, 7, 9, 10, 12, 13, 14, 16, 17, 18, 19, 22, 23, 24, 25], "sampl": [3, 7, 13, 14, 23], "sampleapi": 24, "sandbox": [0, 3], "satisfi": 2, "save": [1, 3, 7, 9, 12, 14, 15, 16, 17, 18, 24, 25], "save_npz": 1, "savefig": [3, 15, 22], "savetxt": 1, "savez": 1, "saw": 12, "scalabl": 13, "scale": [4, 5, 7, 13, 16, 18, 25], "scalen": [3, 18], "scatter": [0, 3, 15], "scenario": [3, 24], "scene": 10, "schedul": [3, 13], "scheme": 16, "scicomp": [2, 3, 7, 12, 16, 22, 25], "scienc": [0, 1, 3, 5, 6, 8, 12, 13, 25], "scientif": [2, 3, 4, 6, 8, 9, 13, 21], "scientist": [9, 25], "scikit": [8, 13, 20], "scipi": [1, 2, 4, 5, 9, 11, 13, 24], "scope": [13, 15], "scratch": [12, 25], "screen": [3, 15, 17], "script": [2, 4, 5, 7, 8, 10, 11, 13, 15, 16, 24, 25], "scroll": 22, "se": 13, "seaborn": [3, 8, 12, 15, 16], "seach": 9, "seamlessli": 8, "search": [2, 3, 8, 11, 12, 15, 16, 21, 23], "second": [2, 3, 8, 9, 10, 13, 15, 18, 23, 25], "secondli": 2, "section": [2, 3, 7, 8, 11, 17], "see": [0, 1, 3, 11, 12, 15, 16, 18, 22, 23, 25], "seed": 10, "seem": [3, 8, 16, 21], "seen": [4, 10, 24, 25], "segment": 13, "sel": [3, 25], "select": [0, 5, 6, 7, 9, 10, 12, 15, 16, 22, 25], "selector": 9, "self": [6, 19], "send": [7, 13, 15, 23], "sens": [3, 17, 22], "sent": [15, 16], "sentenc": [2, 3, 7], "sep": 2, "separ": [2, 3, 6, 9, 12, 13, 14, 15, 16, 22, 24], "septemb": 5, "seq": 7, "sequenc": [18, 19], "serial": 1, "seriou": [10, 23], "serv": [10, 13], "server": [0, 6, 15, 23], "servic": [0, 18, 25], "session": [2, 3, 6, 7, 13], "set": [0, 2, 3, 6, 7, 10, 12, 13, 15, 16, 17, 18, 19, 22, 24, 25], "set_titl": [3, 15, 22], "set_xlabel": [0, 3, 15, 22], "set_xscal": [0, 3, 15], "set_ylabel": [0, 3, 15, 22], "setup": [2, 11], "setuptool": 11, "sever": [3, 5, 8, 22], "sex": 12, "sh": 11, "shall": 25, "shape": [3, 9, 10], "share": [1, 2, 7, 10, 13, 24], "shareabl": 1, "sharex": 12, "she": [0, 3], "sheet": 15, "shell": [4, 6, 7, 22, 25], "shift": [7, 12], "short": [4, 5, 8, 12, 16, 18, 19, 22], "shortcut": 7, "should": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 14, 15, 16, 17, 22, 24, 25], "shouldn": 13, "show": [2, 3, 4, 5, 6, 8, 11, 12, 13, 16, 17, 22, 23, 25], "shown": [0, 3, 25], "shut": [3, 7], "sibl": 12, "sibsp": [3, 12], "side": [3, 16], "sidebar": [3, 7], "signal": 21, "significantli": 13, "similar": [2, 3, 4, 8, 9, 11, 13, 14, 22, 23, 25], "similarli": [1, 9, 12, 23, 24], "simpl": [3, 4, 6, 7, 8, 11, 12, 13, 14, 15, 16, 22, 23, 24, 25], "simplest": 11, "simpli": [2, 3, 16], "simplifi": [2, 3, 16, 25], "simul": [1, 18], "simultan": [3, 13], "sin": [3, 9], "sinc": [3, 6, 9, 10, 12, 14, 15, 17, 22, 23, 24, 25], "singl": [1, 2, 3, 5, 9, 10, 11, 12, 19, 22, 23, 24, 25], "site": 8, "situat": [1, 2, 3, 8, 13], "size": [1, 3, 9, 12, 13, 15, 21, 24, 25], "sizeof": 10, "skew": 12, "skip": [10, 12], "slate": 2, "sleep": 23, "slice": [3, 12], "slide": [3, 15], "slider_cutoff": [3, 16], "slightli": [3, 5, 7, 13, 19, 22], "slow": [3, 5, 7, 9, 10, 13, 18, 21, 24], "slower": [3, 9], "slowest": [3, 18], "slowli": 8, "slurm": [3, 13], "slurm_cpus_per_task": [3, 13], "small": [0, 1, 3, 4, 8, 9, 10, 11, 13, 15, 18], "smaller": [5, 9, 10], "smart": 9, "sn": [3, 12], "snippet": [3, 15], "snow": 16, "so": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 18, 22, 24], "social": [1, 23], "softwar": [0, 2, 3, 5, 7, 8, 11, 18], "solut": 11, "solv": [2, 3, 4, 7, 24], "solver": 2, "some": [2, 4, 5, 6, 7, 8, 9, 10, 12, 13, 15, 16, 18, 19, 21, 22, 23, 24, 25], "some_funct": 18, "somebodi": [2, 15], "somedai": 21, "someon": [4, 6], "someth": [2, 9, 13, 16, 19, 21, 22, 24], "sometim": [1, 2, 3, 12, 13, 18], "somewhat": [1, 4, 8], "somewher": [3, 8, 10, 12, 23], "soon": 22, "sooner": 18, "sort": [3, 5, 8, 9], "soup": [3, 23], "sourc": [1, 3, 5, 6, 7, 8, 11, 12, 16, 17, 21, 23, 24], "space": [1, 5, 9, 22, 24], "spare": [3, 21], "spars": [1, 3], "spatial": 1, "special": [9, 10, 11, 12, 14, 21], "specif": [2, 3, 7, 9, 10, 11, 13, 21, 22, 24, 25], "specifi": [0, 2, 3, 11, 13, 17, 22, 23, 24, 25], "speed": [2, 9, 10, 11, 12], "spend": [3, 4, 18], "spent": [3, 13, 18], "sphinx": 8, "split": [3, 12, 13, 14], "spoiler": 16, "spot": [13, 17], "spous": 12, "spread": [3, 7], "spreadsheet": [3, 12], "spring_in_tapiola": 22, "spy": 18, "spyder": 8, "sql": 12, "sqrt": [1, 9, 10], "sqrt2": 1, "squar": [3, 9, 13, 14], "stabl": 16, "stack": [3, 16], "stai": 10, "stand": 2, "standalon": 0, "standard": [1, 3, 5, 6, 9, 10, 13, 15, 16, 18, 24], "standpoint": 21, "start": [0, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 18, 22, 24], "start_dat": [3, 22], "startup": 22, "state": [2, 13, 18], "statement": [3, 7, 13, 19], "static": [0, 2, 3, 5, 17, 19], "station": [16, 18], "statist": [8, 12, 15, 16, 18, 21], "statsmodel": 8, "std": [3, 7, 12, 14], "stdio": 10, "stdlib": 10, "step": [3, 6, 11, 12, 13, 16, 18, 24], "stick": [3, 12], "still": [2, 3, 4, 5, 6, 7, 8, 9, 11, 17, 22, 25], "stochast": [3, 13, 14], "stock": [3, 25], "stock_pric": [3, 25], "stop": [6, 18], "storag": [1, 4, 9, 24], "store": [3, 9, 10, 16, 18, 19, 21, 22, 23, 24, 25], "stori": 7, "str": [3, 12, 17, 18, 19, 22], "straightforward": 12, "strategi": [7, 13, 15, 16], "stream": [13, 25], "streamlin": 22, "strength": 15, "stride": 3, "stride_trick": [3, 10], "string": [1, 3, 11, 12, 19, 22, 23, 24], "strong": [6, 19], "strongli": [19, 22], "structur": [1, 2, 3, 8, 9, 11, 12, 16, 18, 22, 25], "stuck": [3, 16], "student": [0, 3, 4, 5, 8], "studi": [7, 15, 23], "stuff": [3, 7], "style": [7, 16, 17, 22], "sub": [11, 12], "sub1": 12, "sub2": 12, "sub3": 12, "subject": 22, "submiss": [15, 16], "subplot": [0, 3, 15, 22], "subprogram": 10, "subset": [3, 12], "subset_physchem": [3, 12], "substanti": 24, "subtract": [3, 9, 11], "succe": 10, "success": [3, 7], "successfulli": 11, "suffer": 1, "suffici": [0, 3, 23], "suit": 1, "suitabl": [5, 24], "sum": [3, 7, 9, 10, 12, 13, 14, 25], "summar": 12, "summari": [0, 2, 3, 12], "super": [4, 10], "supercomput": 13, "supervisor": [0, 3], "support": [2, 3, 6, 8, 12, 13, 21, 24, 25], "suppos": [2, 3, 22, 24], "sure": [3, 4, 5, 6, 7, 8, 13, 18, 24, 25], "surfac": 25, "surgeri": 18, "surnam": [3, 12], "surpris": [15, 18], "surprisingli": 10, "surviv": [3, 12], "sustain": 4, "svg": 16, "swarm": [3, 12], "swarmplot": [3, 12], "sweden": [3, 12], "swig": 8, "switch": [3, 7, 15, 16, 17], "sy": [2, 3], "symbol": [8, 9], "symmetr": 13, "sympi": 8, "synchron": 13, "syntax": [4, 5, 19, 22, 25], "system": [2, 3, 6, 7, 11, 13, 22], "t": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25], "t0": 13, "tab": [3, 6, 7, 12, 23], "tabl": [1, 3, 12, 24], "tabular": [12, 16, 25], "taka": 0, "take": [0, 1, 3, 4, 7, 9, 10, 11, 12, 13, 14, 16, 19, 21, 22, 23, 24, 25], "taken": [2, 3, 13], "talk": [2, 5, 8, 23], "tapiola": [3, 22], "tar": 11, "target": 5, "task": [3, 4, 5, 8, 9, 14, 15, 22], "teach": [3, 4, 5, 6, 7, 8, 17], "team": [5, 17], "technic": [1, 6], "tell": [1, 2, 3, 8, 10, 12, 16, 23], "temperatur": [3, 16, 22, 25], "temperature_cairo": 22, "temperature_data": 25, "temperature_isobar": 25, "temperature_numpi": 25, "temperature_tapiola": 22, "temperature_tapiola_dec": 22, "temperature_tapiola_feb": 22, "tempor": [1, 16], "temporari": 1, "temporarili": 1, "ten": [3, 7, 25], "tend": 7, "tensorflow": [2, 8], "term": [0, 1, 2, 3, 15, 24], "termin": [3, 4, 6, 11, 13, 22, 25], "termnial": 6, "test": [0, 1, 3, 5, 6, 7, 8, 9, 10, 12, 13, 17, 21, 22, 23], "test_fil": 1, "test_numb": 1, "test_number2": 1, "tester": 5, "testpypi": 11, "text": [0, 1, 2, 3, 5, 7, 12, 18, 22, 23, 24], "than": [2, 4, 5, 6, 8, 9, 10, 11, 12, 13, 18, 19, 21, 22, 24, 25], "thank": 12, "thei": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 21, 22, 24], "them": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 18, 21, 22, 23, 25], "theme": 15, "themselv": [4, 5], "theorem": 10, "theoret": [4, 5], "therefor": [0, 2, 3, 22], "thi": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 21, 22, 23, 24, 25], "thin": [3, 7], "thing": [2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 15, 16, 17, 21, 25], "think": [2, 3, 13, 15, 16, 22], "third": [3, 9, 25], "thor": 5, "thorough": 12, "those": [1, 2, 3, 9, 10, 12, 13], "though": [3, 6, 7, 11, 13, 14, 15, 19], "thousand": 23, "thread": [3, 13], "threadpool": [3, 13, 14], "three": [3, 9, 12, 13, 17, 23, 25], "through": [4, 6, 9, 10, 12, 13, 18, 22, 24], "throughout": 24, "throw": 24, "thu": [0, 3, 6, 8, 9, 12, 21, 24], "thumb": [3, 21], "tick_param": [3, 15], "ticket": 12, "tickmark": [3, 15], "time": [0, 2, 3, 4, 6, 7, 8, 9, 10, 13, 14, 15, 16, 18, 19, 21, 22, 23, 24, 25], "time1": 25, "time_end": 13, "time_ful": [3, 21], "time_spars": [3, 21], "time_start": 13, "timeit": [3, 7, 9, 10, 12, 13, 14, 21], "timeitresult": 14, "timestamp": [1, 3, 24, 25], "timezon": 8, "tini": 2, "tip": 4, "tire": 4, "titl": [3, 7, 15, 16, 22, 23], "to_csv": [1, 3, 12, 16], "to_datafram": 25, "to_datetim": [3, 12, 16, 22], "to_excel": 12, "to_feath": 1, "to_hdf": [1, 12], "to_json": [1, 12], "to_netcdf": [1, 25], "to_numpi": [1, 25], "to_panda": 1, "to_parquet": 1, "to_xarrai": 1, "toarrai": [3, 21], "todai": [5, 10], "todo": 8, "togeth": [3, 5, 6, 10, 13, 16, 20, 25], "toggl": [0, 3], "token": [3, 23], "told": [0, 3], "toler": 11, "tolstoi": [3, 18], "toml": [2, 11], "too": [0, 3, 4, 7, 8, 10, 11, 13, 15, 16, 25], "took": 18, "tool": [1, 2, 3, 4, 5, 6, 7, 9, 12, 13, 15, 22, 23, 24, 25], "tooltip": [3, 16], "top": [0, 2, 3, 9, 12, 15, 16, 21, 22, 25], "top_population_countri": 24, "topic": [4, 6, 8, 10], "topic_fold": 5, "total": [3, 10], "tour": [7, 8, 23], "toward": [5, 11], "trace": [2, 17], "tracemalloc": 18, "track": [3, 18, 25], "trade": [3, 25], "trading_volum": [3, 25], "tradit": [9, 15], "tradition": 2, "train": [3, 12, 18, 24], "transform": [21, 25], "transit": 5, "translat": [22, 25], "transpar": [3, 15], "transpos": [3, 9], "transposit": 10, "travers": [3, 18], "travi": 10, "trend": 11, "tri": [2, 4], "trial": [3, 13, 14, 23], "trick": [4, 10], "trigger": [0, 3], "trivial": [3, 7, 10], "tromso": [3, 16], "troms\u00f8": 16, "troubl": [3, 10], "true": [3, 9, 12, 19, 22], "trunc": [3, 9], "trust": [1, 4, 8], "try": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 15, 16, 17, 18, 22, 23, 24], "tupl": [3, 7, 9, 19], "turn": [2, 7, 10, 16, 24, 25], "tutori": [0, 4, 12, 13], "tv": 5, "tweak": [15, 16], "twice": [3, 12, 13], "twine": 11, "twitch": 5, "two": [0, 2, 3, 7, 8, 9, 11, 12, 13, 22, 24, 25], "txt": [0, 3, 6, 18], "type": [0, 1, 3, 4, 5, 6, 7, 8, 12, 15, 16, 21, 22, 23], "typic": [2, 3, 4, 13, 15, 17, 19, 24, 25], "u": [3, 5, 7, 10, 12, 13, 15, 17, 18, 21, 22, 23, 25], "u10": [3, 25], "u5": [3, 25], "ufunc": [3, 9, 10], "ui": 2, "unbound": 12, "uncom": [3, 15], "undefin": [2, 19], "under": [0, 3, 8, 12, 13, 25], "undergradu": [4, 5], "underli": [10, 25], "underscor": [3, 13], "understand": [3, 9, 10, 12, 13, 15, 16, 18, 19, 21, 22, 23, 24, 25], "undetect": 8, "unexpect": [2, 13], "unfamiliar": 6, "unfortun": [6, 12, 25], "unicod": 19, "uniform": [1, 3, 24], "unimport": [3, 13], "uniqu": [3, 8, 12, 18, 19], "unique_word": [3, 17, 18], "unit": [7, 25], "univers": [2, 5, 6, 9, 15, 23], "unix": 13, "unknown": 21, "unless": [1, 2, 3, 7, 8, 9, 13], "unlik": [9, 12], "unmaintain": 5, "unnecessari": 22, "unpack": 15, "unpickl": 1, "unravel": 10, "unrel": [7, 15], "unsupport": 5, "untidi": 12, "until": [5, 13, 19], "unus": 17, "up": [0, 2, 3, 4, 5, 6, 7, 10, 11, 12, 13, 14, 16, 18, 21, 22, 24, 25], "upcom": 8, "updat": [0, 2, 3, 6, 11, 12], "upgrad": 5, "upload": [0, 2, 3, 11, 22], "upon": 2, "upper_limit": 11, "uproar": 2, "upset": [3, 13], "urbaninstitut": 16, "url": [0, 2, 3, 12, 15, 16, 22, 23, 24], "url_prefix": 16, "us": [0, 1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 18, 19, 23, 24, 25], "usabl": [1, 3, 6, 8, 11], "usag": [3, 6, 9, 12, 13, 18, 22], "usd": [0, 3, 12, 25], "user": [0, 3, 4, 6, 12, 13, 15, 16, 22, 23], "user_guid": 16, "usernam": 11, "usr": [3, 22], "usual": [1, 2, 3, 4, 7, 19, 22, 23, 24, 25], "utf": [3, 17, 18, 22, 23], "util": 5, "v": [3, 6, 7, 9, 15, 21, 25], "v1": [0, 3, 12], "v3": 25, "vaex": 12, "valid": 23, "valu": [3, 9, 10, 12, 13, 15, 16, 19, 22, 23, 24, 25], "value_nam": 12, "value_var": 12, "var": 12, "var_7": 25, "var_nam": 12, "vari": [3, 21], "variabl": [1, 3, 7, 9, 12, 13, 17, 19, 21, 25], "varieti": [2, 3, 8, 21, 22, 24], "variou": [1, 2, 11, 19, 24], "ve": [3, 13, 24], "vector": [3, 4, 10, 13, 21], "vectoriz": 5, "vega": [5, 15], "vega_dataset": [3, 16], "venv": [2, 3], "veri": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 19, 22, 24], "verifi": [3, 6, 10, 16], "version": [0, 3, 5, 6, 7, 10, 11, 13, 22, 24], "via": [0, 2, 3, 6, 8, 13, 20, 22], "video": [0, 3, 13], "view": [3, 9, 12, 18], "violat": 17, "violinplot": [3, 12], "virtu": 10, "virtual": [2, 3, 6, 11], "virtualenv": [2, 4], "vision": 15, "visit": [0, 3, 12], "visual": [0, 1, 4, 5, 12, 15, 25], "viz": [3, 16], "volum": [3, 25], "vpython": [3, 8], "vscode": 6, "w": [1, 3, 17, 18], "wa": [2, 3, 4, 5, 6, 8, 9, 10, 12, 17, 22, 23, 25], "wai": [0, 2, 3, 7, 9, 10, 11, 12, 13, 16, 17, 21, 22, 23, 24, 25], "want": [0, 1, 2, 3, 4, 5, 6, 7, 9, 10, 12, 13, 15, 16, 19, 22, 23, 24, 25], "war": [3, 18], "warmer": 16, "warn": [1, 6], "wasn": [0, 3], "watch": [0, 3, 4, 5, 10, 11], "wave": 7, "wb": [1, 3], "we": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 17, 19, 21, 22, 23, 24, 25], "weather": [3, 15, 22, 25], "weather_cairo": [3, 22], "weather_data": 25, "weather_observ": [3, 22], "weather_tapiola": 22, "web": [1, 5, 6, 7, 8, 11, 12, 15, 16, 21, 24], "webhook": [0, 3], "webpag": [4, 8], "websit": [3, 8, 16, 23], "week": 22, "weekdai": 12, "weight": [3, 24], "well": [1, 2, 3, 5, 6, 7, 8, 13, 21, 22, 23], "went": 7, "were": [2, 3, 5, 6, 8, 25], "what": [0, 2, 3, 4, 5, 6, 10, 11, 13, 15, 17, 18, 19, 22, 23], "whatev": [3, 6, 7, 12, 13], "when": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 21, 22, 23, 24, 25], "whenev": [10, 22], "where": [1, 2, 3, 4, 5, 8, 9, 10, 12, 13, 15, 16, 18, 21, 24, 25], "wherev": 6, "whether": [1, 3, 5, 10, 12, 17, 18, 21, 24, 25], "which": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 24, 25], "while": [3, 4, 5, 8, 9, 10, 11, 12, 19, 22, 24], "white": 24, "who": [0, 2, 3, 4, 8, 10, 12, 13, 15, 16], "whole": [3, 7, 12, 15, 18, 21, 24], "why": [2, 3, 4, 9, 10, 13, 23], "wide": [2, 8, 12, 15, 16, 25], "wikfeldt": 5, "wiki": [3, 15], "wikipedia": [3, 15, 22], "wilk": [15, 16], "willing": 22, "win": 11, "window": [2, 6, 7, 11], "wise": 1, "wish": [3, 6, 8, 16, 18], "within": [11, 15, 16, 22], "without": [0, 3, 5, 6, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 22, 23, 24], "women": 12, "won": [1, 2, 7, 12, 13, 22], "word": [3, 10, 17, 18], "work": [0, 1, 2, 4, 5, 6, 7, 9, 10, 13, 15, 16, 17, 22, 25], "workaround": 13, "workflow": [3, 8, 13, 22], "workshop": [0, 3, 6, 7, 8, 18], "world": [6, 13, 18, 19, 25], "worri": [3, 10, 13], "worth": [3, 10, 11, 18, 21], "would": [2, 3, 5, 6, 8, 9, 10, 11, 12, 13, 15, 16, 19, 22, 24, 25], "wouldn": 12, "wrap": [4, 15, 21], "write": [0, 1, 2, 3, 5, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 22, 23, 24], "writer": 23, "written": [1, 2, 3, 8, 9, 12, 13, 17, 21, 22, 24], "wrong": [13, 18], "www": [3, 13, 18, 23], "x": [0, 1, 2, 3, 7, 9, 11, 12, 13, 14, 15, 16, 18, 19, 21, 22, 25], "xarrai": [1, 5, 13], "xkcd": 24, "xlabel": [3, 15, 22], "xoffset": 16, "xr": [1, 3, 25], "xval": [3, 16], "y": [0, 1, 2, 3, 7, 9, 11, 12, 13, 14, 15, 16, 22, 25], "y2": [3, 16], "yaml": [2, 11, 22], "yapf": 17, "yappi": 18, "ye": [2, 3, 10], "year": [0, 2, 3, 4, 5, 8, 10, 12, 15, 16, 23], "yearmonth": [3, 16], "yesterdai": 25, "yet": [3, 6, 7, 10, 11, 12, 16], "yield": [12, 15], "ylabel": [3, 15, 22], "yml": [3, 6], "yoffset": [3, 16], "you": [0, 1, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25], "younger": 12, "your": [1, 4, 5, 6, 7, 9, 10, 11, 12, 13, 15, 16, 18, 21, 22, 23, 24], "your_notebook_nam": 22, "yourself": [3, 4, 5, 6, 8, 10, 22, 25], "youtub": 5, "yval": [3, 16], "yyyi": [3, 16, 22], "z": [1, 3, 9], "zero": [3, 9, 10, 12, 21], "zip": [0, 2, 3], "zorder": 12, "\u00b5": 7}, "titles": ["Binder", "In depth analysis of some selected file formats", "Dependency management", "List of exercises", "Instructor\u2019s guide", "Python for Scientific Computing", "Software installation", "Jupyter", "Library ecosystem", "NumPy", "Advanced NumPy", "Packaging", "Pandas", "Parallel programming", "Python multithreading solution", "Plotting with Matplotlib", "Plotting with Vega-Altair", "Productivity tools", "Profiling", "Introduction to Python", "Quick reference", "SciPy", "Scripts", "Web APIs with Python", "Working with Data", "Xarray"], "titleterms": {"": [4, 8, 12, 21], "1": [0, 1, 2, 3, 7, 8, 9, 10, 11, 12, 13, 15, 16, 21, 22, 23, 25], "10": [0, 3], "15": [0, 2, 3, 15], "2": [0, 1, 2, 3, 5, 7, 8, 9, 10, 12, 13, 15, 16, 21, 22, 23, 25], "2024": 5, "3": [0, 1, 2, 3, 5, 7, 9, 10, 12, 13, 22, 23], "4": [0, 1, 2, 3, 9], "5": [1, 2, 3, 5, 9], "7": 5, "A": [5, 10, 12], "In": [1, 3], "One": 18, "That": 2, "The": [2, 8, 10], "To": 2, "about": 4, "access": [6, 25], "activ": [2, 3, 23], "ad": 2, "adapt": [3, 16], "addit": [1, 2, 9, 18], "adjenc": 1, "advanc": [3, 9, 10, 13, 23, 25], "after": 23, "ai": 17, "algebra": 9, "also": [2, 5, 6, 7, 8, 9, 10, 13, 21, 24], "altair": [3, 16], "altern": 12, "an": [2, 3, 9, 10], "anaconda": 6, "analogi": 18, "analysi": [1, 3, 8], "analyz": [3, 12], "anoth": 10, "anyon": [0, 3], "api": [3, 23], "ar": [15, 16], "arbitrari": 1, "archiv": 5, "argpars": 22, "argument": 22, "argv": 22, "arrai": [1, 9], "arrang": [3, 16], "assist": 17, "attend": 5, "avoid": 10, "bad": 24, "basic": 12, "behind": 10, "better": [0, 3], "beyond": 12, "binari": 24, "binder": [0, 3], "bla": 10, "bore": [3, 23], "box": 17, "build": 11, "can": [0, 1, 2, 10, 17], "case": 24, "channel": [3, 16], "check": 17, "choos": 18, "citi": 16, "class": 19, "cluster": [3, 13], "code": [0, 3, 7, 8, 16, 17, 18], "collect": 19, "color": 15, "comma": 1, "command": [6, 22], "common": 1, "commun": 2, "comput": [0, 5, 8], "con": 24, "conda": [2, 6, 11], "config": 22, "configur": 17, "connect": 8, "consider": 24, "control": [17, 19], "convert": [24, 25], "copi": 10, "core": 8, "coupl": 13, "cours": 5, "creat": [0, 2, 3, 9, 25], "creator": 2, "credit": 5, "csv": 1, "curtain": 10, "custom": [3, 15], "cutoff": [3, 16], "dask": [3, 13], "data": [1, 3, 8, 10, 12, 16, 23, 24, 25], "datafram": [3, 12, 15, 16], "dataset": [3, 12, 25], "demo": [0, 3, 11], "depend": [2, 3], "depth": [1, 3], "detect": [2, 3], "differ": [3, 15, 23], "discuss": [0, 2, 3, 15, 18, 22], "disk": 23, "do": [2, 6, 14, 15], "doi": 0, "each": 4, "ecosystem": [2, 3, 8], "editor": [6, 17], "emphas": 15, "enough": 0, "environ": [0, 2, 3, 6], "etc": [1, 6], "evalu": [3, 8], "even": 18, "examin": [3, 23], "exampl": [3, 10, 13, 15, 16, 17], "excel": 1, "exercis": [0, 1, 2, 3, 7, 8, 9, 10, 11, 12, 13, 15, 16, 18, 21, 22, 23, 24, 25], "exist": [2, 16, 18], "explain": [2, 16], "explor": [3, 12], "export": [2, 3], "expos": 10, "extend": [3, 15], "fast": 10, "feather": 1, "featur": 1, "file": [1, 3, 22, 24], "form": 1, "format": [1, 3, 24], "formatt": 17, "from": [0, 2, 3, 11, 13, 16, 22, 23], "full": 3, "fun": 16, "function": 19, "further": [22, 24], "futur": 14, "galleri": [3, 16], "get": [0, 7, 12, 15], "gil": 13, "github": [0, 3], "glossari": 8, "good": 24, "graph": 1, "graphml": 1, "gt": 1, "guess": 18, "guid": 4, "ha": 15, "hdf5": 1, "header": [3, 23], "help": [6, 12], "hierarch": 1, "how": [0, 2], "human": 8, "i": [0, 2, 5, 7, 8, 9, 18, 24, 25], "idea": 14, "imagin": 18, "import": 8, "index": [2, 9], "insert": 18, "instal": [6, 11], "instead": 18, "instructor": [4, 16, 17, 18], "integr": [17, 21], "interact": 8, "interfac": [8, 15], "introduct": 19, "javascript": 1, "json": 1, "jupyt": [3, 7, 17, 22], "jupyterlab": 6, "kei": [1, 24], "keypoint": [0, 2, 7, 8, 9, 10, 11, 12, 13, 15, 16, 19, 21, 23, 24], "languag": [2, 3, 8, 13], "larger": 22, "learn": 8, "learner": 4, "let": 16, "librari": [3, 8, 10], "like": 17, "line": [6, 22], "linear": 9, "link": [0, 3, 23], "linter": 17, "list": [1, 3, 12, 22], "load": 22, "local": 11, "locat": 11, "lock": 2, "log": [3, 15], "london": 18, "look": 24, "machin": 8, "make": [0, 3], "mamba": 2, "manag": [2, 3], "mani": 18, "manipul": 25, "mark": 16, "math": 9, "matplotlib": [3, 15], "matric": 21, "matrix": 10, "measur": 18, "min": [0, 2, 3, 15], "miniforg": 6, "mkl": 10, "mode": 13, "more": [2, 16], "motiv": 5, "mpi": [3, 13], "multiprocess": [3, 13, 14], "multithread": [13, 14], "ndarrai": 10, "need": 6, "netcdf": 25, "netcdf4": 1, "network": 1, "next": 8, "nobel": [3, 12], "norwegian": 16, "notat": 1, "note": [16, 17, 18], "notebook": [0, 3, 17, 22], "novemb": 5, "npy": 1, "numer": [8, 21], "numpi": [1, 3, 9, 10, 25], "object": [0, 1, 2, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25], "onli": [0, 3], "open": 17, "oper": 9, "optim": 18, "option": [0, 3, 13, 22], "org": 13, "organ": 11, "other": [1, 6, 8, 9, 13, 16], "own": 25, "packag": [1, 2, 3, 8, 11], "panda": [3, 12, 15, 25], "parallel": [3, 8, 13, 14], "paramet": 23, "parquet": 1, "pars": 22, "part": 2, "passeng": [3, 12], "paus": 16, "persona": 4, "pickl": 1, "pin": 2, "pip": 11, "plot": [3, 8, 15, 16, 25], "point": 24, "practic": [3, 18], "precis": 1, "prepar": [3, 15], "prerequisit": [5, 11], "preview": 12, "previou": [3, 15], "prize": [3, 12], "pro": 24, "product": 17, "profil": [3, 18], "program": [3, 13], "project": [2, 11], "public": [2, 3, 15], "publish": 11, "pypi": [2, 11], "python": [1, 2, 3, 5, 6, 8, 11, 14, 19, 22, 23], "q": 5, "question": [0, 2, 7, 8, 9, 10, 11, 12, 13, 15, 17, 19, 21, 22, 23, 24, 25], "queue": 13, "quick": [12, 20], "re": [3, 16], "read": [16, 22], "realli": 10, "reduc": 1, "refer": [5, 20], "remark": 11, "rememb": 24, "repeat": [15, 16], "report": 2, "repositori": [0, 3], "reproduc": [0, 3, 15, 16], "request": [3, 23], "requir": [1, 2, 23], "reshap": 10, "resourc": 18, "respons": [3, 23], "retriev": 23, "reus": 8, "reuseabl": 8, "right": 18, "run": [3, 7, 13], "sampl": 18, "save": [22, 23], "scalar": 19, "scale": [3, 15], "scicomp": 6, "scientif": 5, "scipi": [3, 8, 21], "scrape": [3, 23], "scratch": 11, "script": [3, 22], "section": 4, "see": [2, 5, 6, 7, 8, 9, 10, 13, 21, 24], "select": [1, 3], "separ": 1, "seri": 12, "share": [0, 3, 11], "should": 18, "simplest": 18, "simplifi": 11, "size": 18, "skeleton": 11, "slice": 9, "slider": [3, 16], "softwar": 6, "solut": [1, 2, 3, 7, 9, 10, 12, 13, 14, 15, 16, 18, 21, 22, 24, 25], "some": [1, 3], "sometim": 0, "sourc": 2, "spars": 21, "speed": 8, "start": [6, 7, 15, 16], "store": 1, "strategi": [0, 3], "stride": 10, "structur": [19, 24], "studi": 24, "style": 15, "subwai": 18, "suggest": [3, 23], "superpow": 12, "sy": 22, "system": [18, 19], "task": 13, "test": 11, "text": 6, "textual": 24, "than": [0, 3], "theme": 16, "thesi": 2, "thi": 15, "thing": [10, 24], "thread": 14, "through": [3, 16], "tidi": [1, 12, 24], "time": 12, "timer": 18, "tip": 2, "titan": [3, 12], "tool": [8, 11, 17, 18], "topic": 25, "trace": 18, "track": 2, "transpos": 10, "tri": 10, "trick": 2, "two": [15, 16], "txt": 2, "type": [9, 17, 19, 24], "u": 16, "underground": 18, "untidi": 24, "up": [8, 17, 23], "us": [2, 3, 16, 21, 22], "v": [5, 18, 24], "valu": 1, "vector": 9, "vega": [3, 16], "verif": 6, "version": [1, 2, 17], "versu": [2, 10], "via": 11, "video": [5, 6], "view": 10, "visual": [3, 16], "wai": 6, "walk": [3, 16], "want": 18, "watch": 6, "we": [15, 16, 18], "weather": 16, "web": [3, 23], "webapi": [3, 23], "webpag": [3, 23], "what": [7, 8, 9, 12, 16, 21, 24, 25], "which": 23, "who": 5, "why": [0, 5, 7, 15, 16, 22], "without": 2, "work": [3, 8, 12, 24], "wrap": 23, "xarrai": [3, 25], "yml": 2, "you": [2, 6], "your": [0, 2, 3, 8, 17, 25], "zenodo": [0, 3], "zoom": 6}}) \ No newline at end of file diff --git a/branch/master/singlehtml/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb b/branch/master/singlehtml/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb new file mode 100644 index 00000000..3c1ecd2a --- /dev/null +++ b/branch/master/singlehtml/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb @@ -0,0 +1,96 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "url = \"https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv\"\n", + "weather = pd.read_csv(url,comment='#')\n", + "\n", + "# define the start and end time for the plot \n", + "start_date=pd.to_datetime('01/06/2021', dayfirst=True)\n", + "end_date=pd.to_datetime('01/10/2021', dayfirst=True)\n", + "\n", + "# The date format in the file is in a day-first format, which matplotlib does nto understand.\n", + "# so we need to convert it.\n", + "weather['Local time'] = pd.to_datetime(weather['Local time'], dayfirst=True)\n", + "# select the data\n", + "weather = weather[weather['Local time'].between(start_date,end_date)]\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, we have the data loaded, and adapted to our needs. So lets get plotting" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYUAAAEcCAYAAAAoSqjDAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAABtDElEQVR4nO2dd7gcVdnAf+/evSU9pBcggRCE0CHSpSNKERQbKkX9wM+GYPsQsWBFUSwgIgLSwYIoItKbhBJCS0JNgJBCSC83N7lt93x/zJzZs7Nnd2f7bHJ+z3Ofuzs7O/vu7Mx5z1vO+4pSCofD4XA4ABKNFsDhcDgc8cEpBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA4HA5HgFMKDkcDEZHJIqJEJNloWUpBRD4pIvc2Wg5H9XFKwWFFRDYYf2kR2WQ8/2Sj5SsHEVkgIkfV+TOnicgdIrJORDpF5CERObCeMlSKTXEppW5SSr23kXI5aoNTCg4rSqnB+g9YCJxgbLup0fKFqcdMu9TPEJEpwAxgDrAdMAG4HbhXRA6ovoR55RARcfe6IxLuQnGUhIgkROQ8EXldRFaJyF9EZIT/mp5RflpEFonIGhH5XxF5t4jMFpG1InKZcawzRGSGiFzmz6RfEZEjjdeHicjVIrJURJaIyI9EpCX03l+JyCrg+yIyRUQe9OVaKSI3ichwf/8bgG2Bf/nWzjdF5DARWRz6foE1ISLfF5G/iciNIrIeOKOQTBa+DzyhlPq2Umq1UqpTKfVb4AbgZ6F9PyMib/vH/bohz74iMktE1ovIMhG5xHhtfxF53D+vL4jIYcZrD4vIj0VkBrAR+IaIzAp913NF5A7/8XEi8pz/OYtE5PvGro/6/9f65+4A//w/ZhzrQBF52v8dnzatIV+WH/q/V6eI3Csio/zXOvzzu8r/Hk+LyNg859NRD5RS7s/9FfwDFgBH+Y+/AjwJbA20A38AbvFfmwwo4AqgA3gv0A38AxgDTASWA4f6+58B9APnAq3Ax4B1wAj/9dv94w/y3z8T+FzovV8GksAAYAfgaF+u0XiD2a9t38N/fhiwuMB3/T7QB5yEN4EaUEgmy3l7B/i0ZfvhQMo/nj5nt/jH3A1YYcjwBHCq/3gwsL//eCKwCjjWl+1o//lo//WH8Sy8XfzzMwzoBKYacjwNfNw4F7v5x9odWAacFPpdk8Z7zwAe8x+PANYAp/qfdYr/fKQhy+vAjv53fhi4yH/tc8C/gIFAC7APMLTR1/yW/OcsBUep/C/wbaXUYqVUD97A+eGQa+WHSqlupdS9QBee0liulFoC/BfYy9h3Od7A3aeU+jPwKnCcP1s8FjhHKdWllFoO/Ar4uPHet5VSlyql+pVSm5RS85VS9ymlepRSK4BLgEMr/L5PKKX+oZRKA0MjyGQyClhq2b4Ub/AdYWy70D/mHOBPeAMreEppBxEZpZTaoJR60t/+KeAupdRdSqm0Uuo+YJYvn+ZapdSL/vlZB/xTH1dEpgI7AXcAKKUeVkrN8Y81G09JRT13xwHzlFI3+J91C/AKcIKxz5+UUq8ppTYBfwH2NL7fSGAHpVRKKfWMUmp9xM911ACnFBylMgm43Tf11wIv4816TZN/mfF4k+X5YOP5EqWUWZXxLTzf+yQ862Gp8Vl/wJudaxaZgonIWBG51XfrrAduxBuYK8H8jCgymawExlu2jwfSeLNp2+focwDwWbwZ9iu+a+V4Q5aPaDl8WQ4OfV7W+QFuJqNsPgH8Qym1EUBE9hMvCL5CRNbhKf+o526CL7PJW3jWjOYd4/FGMtfADcA9wK2+++znItIa8XMdNcApBUepLALer5Qabvx1+FZAOUwUETGebwu87X9ODzDK+JyhSqldjH3DJX5/4m/bTSk1FG82LQX278JzWwDgxwZGh/Yx3xNFJpP7gY9Ytn8UzwLZaGzbxniszwFKqXlKqVPwFM/PgL+JyCBflhtCv8MgpdRFBb7vfcBoEdkTTzncbLx2M57VsI1SahieC1Cfu2KllN/GU1Im2wJFrwnfQrxQKTUNOBA4Hjit2PsctcMpBUepXAH8WEQmAYjIaBE5sYLjjQHOFpFWEfkIsDOeW2QpcC/wSxEZKl6Ae4qIFHJpDAE2AOtEZCLwjdDry4DtjeevAR1+kLUVuAAvHmGlDJkuBA70A74jRGSIiHwZb9D7v9C+3xGRgSKyC/Bp4M8AIvIpERntu6/W+vum8aygE0TkGBFp8QO2h4nI1gXk7wP+ClyM57q6z3h5CLBaKdUtIvviWRKaFf5nmufO5C5gRxH5hIgkReRjwDTgznyyaETkcBHZzVfI6/HcSeli73PUDqcUHKXyG7wZ5b0i0okXdN6vguM9BUzFc7X8GPiwUmqV/9ppQBvwEp6r5W/Y3TGaC4G98YLV/wb+Hnr9p8AFvrvl676f/QvAVXiz2i5gMYWJLJNSah6eS2cPvAD2UuBk4Bil1IzQ7o8A84EHgF/48RiA9wEvisgGvHP/cT9+sgg4ETgfb9BehKcEi93TNwNHAX9VSvUb278A/MD/Tb+L5/fX32Mj3m8zwz93+4e+5yq8Gf7X8ILd3wSOV0qtLCILwDi8c7gezxX5CJ5LydEgJNud63DUDxE5A/gfpdTBjZbF4XB4OEvB4XA4HAFOKTgcDocjwLmPHA6HwxHgLAWHw+FwBDRVud4wo0aNUpMnT260GA6Hw9FUPPPMMyuVUuE1OUCTK4XJkycza9as4js6HA6HI0BEwivQA5z7yOFwOBwBTik4HA6HI8ApBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA0HU++sYrnFq4pvqPD4SiZpl6n4Ngy+fiVXkfKBRcd12BJHI7ND2cpOBwOhyOg7krB7xA1U0ReEJEXReRCf/t2IvKUiMwXkT+LSFu9ZXM4HI4tnUZYCj3AEUqpPYA9gff5nZx+BvxKKbUDXkerzzZANofD4diiqbtSUB4b/Ket/p8CjsBrywdwHXBSvWVrVv40401+dOdLjRbD4XBsBjQkpuA3Gn8eWI7XPPx1YK3RM3YxMDHPe88SkVkiMmvFihV1kTfuXPivl7jqsTcbLYbD4dgMaIhSUEqllFJ7AlsD+wI7lfDeK5VS05VS00ePtlZ+dWyGvLWqixnzo/SBdzgcldDQlFSl1FoReQg4ABguIknfWtgaWNJI2Rzx4tCLHwZcGqrDUWsakX00WkSG+48HAEcDLwMPAR/2dzsd+Ge9ZXM4HI4tnUa4j8YDD4nIbOBp4D6l1J3A/wFfFZH5wEjg6gbI1nQ0e4/t+cs7uWvO0sj796fSweNX3+nkvpeW1UIsh2OLpe7uI6XUbGAvy/Y38OILjhJIGzohlVa0JKRxwpTBBy6bwcbeFG/85FgSEWTf2JcKHh/z60cB51JyOKqJW9Hc5PQZM+fe/nSBPePJxl5vkF/e2RNp//Wb+nK2Nbu15HDECacUmpyUYSr09KcK7BlPRg1uB2DJ2o2R9u/s7s/Z1tXbfN/b4YgrTik0Of0pUyk0n6XQnvQuwa6e3IF9fXcfk8/7N3+dtSjYtmZjb85+6yzWg8PhKA+nFJqUnv4Ui1ZvpC+dUQTdfc03Y25t8eIImyyyL169CYCrjYV5y9fnupnWbXRKweGoFk4pNCnf/Nts3vPzh+jqybhT+tPN51vXgXGbQhNL3HnZ+u6cbc3oNnM44opTCk3Kw696JT5MH3szBlyTCe8StCkF/XXMr2ULSKeb8Hs7HHHFKYUmRWdv9hrZR/98/m3e8/MHSTeRxaAthU2WYHF/OjdGsmpDrlIw4yq1ZPbitVmBfYdjc8QphSbFNphe+uB8Fq3eRFdvboZOXMnEFHIVgA6cKzIDsS37KFUHS+H5RWv5wGUz+P3D82v+WQ5HI3FKoUlJ+A73jZYZti1oG1dE8geabesubPtZDIqq8846L5Yxe/G62n+Yw9FAnFJoUrSlsNFiFdhcMXFFu2N6LIO9DiCbhoBNCdrcTNVGu+uc98ixudPQKqmO8tGWgk0B2HL+44pekd1niQtYLQXL961loHljb39gJdT6sxyOOOAshSYlYynY3EfNE1PQSsE22NoW4220fLdUDQ2FL938HEf88hHeWuWtuHZKwbG545RCkxIEmi1ulxffXl9vccpGr60opBTMV2yWQqqG7qMHX1kOwDv++gjnPnJs7jil0KRoH7ctpvDdf75YZ2k8+lNpPnj5DB55LXqb1D5/4LeletqsCJtlVEtLQbPBz3pqxrUgDkcpOKXQJOhBM51WKKWs2UeD2loA2G+7EfUXEFi7qY/nFq7l3D8/H/k9fYGlkPua/s6mwrAqhToM1Bv8lePNVprc4SgVpxSagDdXdjHl/Lv49+ylbH/+XXzr73Os6xR0sFZXHi2Xfz6/hLfXbir5fXps7iuhMJ9ummNbcJfJTCp8vHos1gtcWc5QcGzmOKXQBDz+utew/pHXPP/2rU8vsloKenVzJatue/vTfOXW5znwogcjv+eGJxZw5C8fzmQSpdOs29TH/OWdRd+rFZktpqC/R7F1F2bNp9/cP4+P/uGJyLJHpRrn1uFoBlxKahOgZ+0Thg8ItulicbaaQZVkyJRTXO47fgxDp5D2pRQf/v3jzFu+oWhXNK1Iwi6g9d19kZWCaSn86v7XShM+Ir3+eemtRwDD4WggzlJoAvS6g8HtuTq82+KqqUQp2NYLREWXoEilFfOWb4j4ebnuowdeXsbu37+XmW+uBop3lKtHTEHL0Izd7RyOUnBKoQnQVoGtNLZtJfDTC9Yw+bx/s2h1tG5mJpUMems35TbAKUQqrYIAs/nVdPbSCxFLStSjZLhWln3OUnBs5tRdKYjINiLykIi8JCIvishX/O3fF5ElIvK8/3dsvWWLK4KnFfotA5JtgZfuRPb0gtUlf1Y5SiHpB73XWJrdFErhNAdYc7avA8u6WF4xbIFm27mqBC2rsxQcmzuNsBT6ga8ppaYB+wNfFJFp/mu/Ukrt6f/d1QDZYkmikKVQYJAa0tFa8mf1pjKWR9Sc/Da/peZaS6vMQoFZ8/uk04rfPTSft9duotv33ycjKgXbZ9jcapWQiZc4peDYvKm7UlBKLVVKPes/7gReBibWW45mQruPzAFJb7O5jzRDOkrPIzCVjBlUfW1ZJ3OX2N05GaWQaynYFNmm3hSTz/s3f3z0jWDb/OUbuPieV/n8Tc8GlkLC1nqN3I5sKzf0MPm8f3P7c4uDbdVuTdrjYgqOLYSylYKITBGRdv/xYSJytogML/EYk4G9gKf8TV8Skdkico2IbJXnPWeJyCwRmbViRfSVs9Vk+fpuDrroQd5YES2YWim6vLQtX7+QpZCMsNDqV/e9xgX/mBM8Nwc9cw3Ee3/1KMdf+pj1GG0t3mW0xmIp2JSCXgj2mwfmBdu0wuvq6Q8yoPIN7K2J7Mv2jRVdAPz2gUyvg2orBa0ge+vU0MfhaBSVWAq3ASkR2QG4EtgGuDnqm0VksH+Mc5RS64HfA1OAPYGlwC9t71NKXamUmq6Umj569OgKxC+fu+YsZcnaTVz3+IK6fJ6eGdvSIQulkEaJv/7mgXnc+ORC7/j96azso+4ii8Y07a3eZbTOYin09ae54B9z+OusRcE2m7vHVEZakeT7/LBbSdclMvtVR5U9KpmYQvNUoHU4yqESpZBWSvUDHwQuVUp9Axgf5Y0i0oqnEG5SSv0dQCm1TCmVUkqlgT8C+1YgW02p+1zR/0CrpVBg8CulTs+cxevY8YL/8MDLy4JtOrX18fkrC763kKWwvLOHG59cyDf+NjvYZvPLd/lWiWAsWsvTFyJsAS1d563jGGy4y6puKRhrMByOzZlKFq/1icgpwOnACf62opFN8XwhVwMvK6UuMbaPV0ot9Z9+EJhbgWw14bzbZrNyQw8HThkFZNw6tUYPkjZLobtCS0Fzv68MHjMUgFYKr6/sKvjetqRXc8mWfbS6K6MolFLMemsNIwe15eynZ/kihb8vQGtL9lzGXjm18sHbzGoK1im4QLNjM6cSS+HTwAHAj5VSb4rIdsANEd53EHAqcEQo/fTnIjJHRGYDhwPnViBbTbj16UXc//Lyun+uHptMV1FQZ6jAzLUUS2GZ74IZYQzY+u260F6+FNF2P9CsU2FNzIykO154m49c8QR/fWZxzn5ZmUhF5A67j/RAbVpN1VjQ1pfOdWml0ipQON19Kc798/NZTXgcjmanbEtBKfUScLbx/E3gZxHe9xhgG11cCmoe9CBp+t2jTISL7WPOhPVqZDPjR4+rxWbd2ptjcx+tNrYtXuO5eQr1exCk6OclQ4FmrRjNMuKVWgr3vvgOA9vst0dfKk1LooX7XlrG7c8tobc/ze8+uXdFn+dwxIWylYKIvInFva6U2r4iiRw5BNVCDaUQpbFMsRm36QrRfY7NOkP6/fYGOClueWohB+0wKphF21JSzW3aotjQnbufRqS4iyZssejzYxYH7C/i++/pT/Hoays5aucxVjfgWTc8k/e9vak0Ha0tgRxu7YJjc6KSmMJ043EH8BGgMYX8a8zKDT0M9F0oUP9Asx6Us5VCcSmKKQVzMNODqOmf1+/Xu5mH+91Dr/NbP6V05/FD836G6VJqb/XOYaEe0qm0Klq2Itli93r2ZFlShY/xpZuf476XlnHfuYcwdeyQgvuG0aXBtcVSjzIbDke9qMR9tCq06dci8gzw3cpEih/Tf3Q/O4wZHDzXvvo6xZnLVgqFxkWlVJY7Ss+yTReMfrv2z5uHW2MEkAuVlDCP1+4P5ht6srvFtSUTgSy2Jjphoqy/KDZQP+rXVyq0ziMf2pJJOkvBsRlSifvIdKIm8CyHzbYU93xL1U+xhkaqT5CN019aIDXfbHnhqo0ccvFD/PRDuwXb9OBtWgpa+enYgxm4HjesI3hcaAA2B3kdKO8KtRBtN5RCZ3dfsEI6H8VeN2XOR6He0MUUbl+/97qOvxRzVTkczUQlg7i5uKwfWAB8tCJpHFb0GGUunErlGYhaEplAbb6x7YXFawG41FhRrAPNZkzh7bXdjBzUbh0kTXfayg09eWU3lYzuuxA+XnuyhU68z1/f3c+A1hYKUQ1LQctg28/W99pE14fScZj+CPEdh6NZqMR9dHg1BXHkJ20JNJuDWUIyCqAjmQgWginl9XPuS6ms2bVOPzV982t937+pFE67ZiZtLQm++b535chkWi1aodgo1iAHMgHoqO8JZx/ZiBKIB7tFUcyF1duvy2hn/3c4NgdKVgoi8iml1I0i8lXb6+aCtM0V7XGIElO4/6VlbD96ENuPHlx85zykrCmpmYGoLZkIyjq0t7YESiGt4Cd3vcwf//smr//kWOYuWUdnd3/Qp6CjNTO46sVj4fIQval0MKs2h76ofvQoMYL21tKWy0SpnhrVzW+zgrp6ilkK2RVTnaXg2Jwox1IY5P8vLWWjSSllAZiN/7l+FkDRtpSFyCxes1sKrS0ZpdBhzLqVUtz0lFfXqLO7jxN/NwOAHcd6CspUAIUCrrb4RdRqobYBNjw7b08WdhdpWluEvpTKm31kEnWgtimFfJZKW0uC3lQ6owx0f2mnExybESUrBaXUH/z/F1ZfnPhRKOhYbL5aqULRpG2BZsNl0Z5M0KkfG/74tIKO1hY29qaConGQSQmNWh8oE2j2Zscbe1KRq4XaLIWwAgq7j/KRTCToS6VojRBTiNqS1Kbw8hXTa096SsGVvHBszlRSOvvnIjJURFpF5AERWSEin6qmcHHA5i9WEVcqVGvQyCxeMzN5Msc2awGZA2xaqSBo+/SCNcF2nf0TVSmYX+N7d7zIHj+4t6iLRRNOP4Xc4G5kpeC7jaK4j6JmBNmUfr4eFdrN1RuyFOIWUXj0tRVByq3DUSqV1D56r1/y+ni8zKMdgG9UQ6g40VfAN1AsprCxwCKtUsisLM5sMxWOGUTuyLIUVDCQvfZOZ7B9gx8YjtqdzJxN6yqqs95aY903nC4aRXl0FMk20mjlZ7qP2vK4kiJbCtaubXmUgu/minsXttOumclp18xstBiOJqUSpaBdT8cBf1VKReuy3mTYZpzFxptnF67hhEsfY2YZPZJtFBvgzIHRDB4rRWApmGmj/RZ3VMHPNwbOYQO8Qrjv+OWqwwxqyx7gowSaB7VHUwo6FdV0H+WzMkxrpKunP2/arFUpFHAfAcxdso6P/uEJOv1yHdVyE67p6uWDl89g0eqNZR+jWrI4tlwqUQp3isgrwD7AAyIyGtjsykXaVusWu+3+M2cpc5as4/6XlhXZMxrFFlNlu4+yLQU9C1+1IbdYXeTPNwaaoM6RpSIqwKD20nMXJg4fEGk/rRRajJTUfJlL5jk75tePMv1H91v3syncfG41bQVd+uB8Zr65Oq+1VC53zn6b5xau5YpHXi/7GKa7zikIRzmUrRSUUucBBwLTlVJ9QBdwYrUEiwu2uIAecPL1U9D+/nJKKNgoVtEi231kxhTslkLJn28IEPjR88g0uAylsPVWAyPtp91GZpw5X+aSqRR0dVYbtsVreS2FkJsraiwkKvq7VHLdmDGwKFaawxGmnHUKH7JsM5/+vRKB4obNfVTMl6zr+q8vUA20FEpxH5mD5Nf/+gJ7bjMcqEwp9GcphcLffUBbNFeQyTYj8lsKOg0UMgFms7x3voE5aulsu/soX0wh+7N0sb/wzzN3yTp2mTC05CZM2uqppGuc+X16+9MMai/7UI4tlHLWKZxQ4DXF5qYULIFmrRTy3fI6S2hDgZW+pVBsgMtnKQA8v2gt4JWPKJesaqpFex2UXg9q6pj8S16SLYKe8Lb6biNzQXN49q6JqhTSSrGpN5WlzPLN1MNKYaXvkjPPzwuL1nLi72bwjWPexRcP3yGSDBqt3CuxFMwJRKEkCYcjH+WsU/h0LQSJK7aU1GIB2g1+1lHYv1vqzPGuOUuZNn5oUUvBHNDyNYapBHPQK5ZN1GJRCmYVVBtbbzWA0w6YxOD2JJc/nO1PN4+XSUXNbMtXHK+Q8jJ97W+t2sjO372bn35oN07Zd1sgvyUYdlVp68t0Mep033tefKdkpdAfpB6XP5ib37saLUkdWx6VrFMYKyJXi8h//OfTROSz1RMtHtjcR8WUwqY+b2AwawKVc6N/4aZnOfKSR4qumDVnsFEzeUrBlL2riJ/aphSKFbgTEX5w4q7sM2mrnNfMILq2QrJjCvndR/OXd7J4TW4mjzlWLvD7T//juSXBtnxKIWyF6QZC5v5a35QT2NfXVT4X3RdvepbPXPu09TWlFI+/vtIa/3E4SqGSSNm1wD3ABP/5a8A5FcoTO2yBZj1I5pvB69LKnUZMIWrQL5VWrDL8/6m0Klom23TZ1MZSiD64mJlBehY/MGKcIWFRKOZ3aw0CzYalkGedQldvP0dd8iifuuqprO0rOnuyZtBaXtOPn2/RYTIh2Lxj5vnRx0kkvHLrZ9/yHOs29vH5G58p2stZf24+g/Lfc5by4Cv2HuF/f3YJn/jjU/x11qJgm2v+4yiHSpTCKKXUX4A0gFKqH2jKdIcn31jFvS++Y33NNmvTN2++mKt+vdNwtURdAfy7h+azz4/uZ3lnZgAppRNZtTNiINNpLArJhARrFYZ2eGsaoioFWzwiy1JoybUUbIoEMhlHC1ZlLIXl67t594/v55L7Xgu2aavOrHeklXqYhEiWPJn9M+dHZy61iHDm9bO444W3ueyhefxn7jtcfM+r1uNqtKVQTp+ON32LZ6GxxiFqpViHw6SSEaRLREbip+2LyP5AUy5g+/iVT+btyWsbkINCaPksBV8pmC9HKSENMNuvYDpj/krj8wrf3MkIi7nClBLeKGXlbkKE+792KM9ccBSDfVdWVOulxSKUWdJC+/TN2Ey+wLYtyK9jPOY6AB3/MS25vN9X7DEM07IILAWRYKDW7rNiZU8CpVDkt3n1nU4mn/dvnluYWSehr1PTinIlvR3lUIlS+CpwBzBFRGYA1wNfLvYmEdlGRB4SkZdE5EUR+Yq/fYSI3Cci8/z/uQ7mOvLi29mrVk36Aksh+6bTg4DNlxs1zXDsUC+HcHVX5nOL+YbNgSp6xdHoP30pNZySCWH8sAGMHNweLGQbO7SD1hZhu1GDGDW4Le97bbN+M0ahffrmwJfIM4Laai7ZlLi24FYb7UXzKYWEiFXpmvvrEhlZ38WXsZjFle88L1vfnWVp/neeV9fon8+/HWyzTRziFmhesnZTVv0uRzypZPHas8CheAvYPgfsopSaHeGt/cDXlFLTgP2BL4rINOA84AGl1FTgAf95XTEH7h/86yVmvrmaJ9/ILVWhB4H/zM24nJ54fRWH/+Jh/vbMYuugctecd/j37KVFZdCDtSlLsdRCXXoCorWqhPy+eBtRymHosdkcxLVSGDmojbkXHsODXzuUySMH2d6e81792LYGwxxv830Nm6VgmznrwXZjb4rH5q3kpqfeyjvDFuxKN60yA7DpPgoT1VIIs99PHuB0o5aRPq9mhzibRRun2kw9/SkOuuhBvvm3KEOEo5GUrBRE5FMicip4cQSl1ItKqbnAx0XkE8Xer5Ra6isUlFKdwMvARLzV0Nf5u10HnFSqbJVizhaHdHg33jpLOQc9aJjtMXUM4Hv/nGu9+a945HW+ePOzeT978nn/5pt/eyFwh2Td8EUsBVMpRCWq8oBomVN6DUGWUvBjCW3JBO3JFkQkbwwAsmf9+jjmOoTAUrAojzDW6qyW82ju96mrn+Lbt8/l9RXZ/bi1WAmRnAwkjR6AtTI3dYKuulpMufZaLFC9ANIsqaFjNF1GwUVtBZmutafeXM3k8/4drFVpJFpJu+qt8accS+HLwO2W7X8HvlbKgURkMrAX8BQwVimlp9LvAGPzvOcsEZklIrNWrKjuBWaa6Ho2ZgZ8NWbMoLc/zezFaxnqD8xdvamig/iarl4WrspNlfzLrMVB0Nic6RaLKQw1lEJUN1VrhPLTpRxTD85Ji6VguqoKrW3LyjTyHw9ozbUURGCncUP4yD5bB9lD4e9jc/vp3som5m8+xJc3PIgGqbCJ3IquegzWA3omLpCRRyueYpZC0DfauH50cTyz0KA+9oaefr59+xy+9fc5wUTFVEY6ecKMTzUKnZ5dLD3Z0XjKUQqtSqkN4Y1KqS4g8pRVRAYDtwHn+CW4zWMp8tSdU0pdqZSarpSaPnr06NIkL4KZg6/dz+s32dwQmSYrn73uaT5w2QxWrO/Jed1GT3+Kw37xMIdc/BDg3djmYirdq8HMXOor4hs2LYVCAW1beqeNsGspiqWQGTgzn6HrILUm88cAzKfZC9U8GcxBRPvzBeHucw7h4o/sgdYFYZltloLte5h1jnbbepjlm5k9oSVHKQzyg+g6XqAHdvMa0EHsYpaCfq+pPPT1N6Qj8xvr4yjgpqcWcsvMhUGmkRk20d83X9ylnmilELVMuqNxlKMUBohIjmNYRIYA+aOI2fu24imEm5RSuizGMhEZ778+HrAnZNeQjcZAogdXW2As07A9zX/nebOwFcbagkIzwg3d/YFLav7yTnb93j38ddbi4HXdUc2cwRazFEylMKFAxVHzhiwUUwg3senuS+WUxA7T0pJrKeiso3bjs8LunnxBY30cc7W2lt9scqSVUGvIHWbTo7ZB2ZY5FMZcNBd2H+nFgvqa0GtKTKUQWAoRlUKfRSbzN9HHMX+mzGro3EZM5ZQeqTbacnNKIf6UoxSuBv4mIpP0Bt8NdKv/WkHEs32vBl5WSl1ivHQHcLr/+HTgn2XIVhFdvSmO+dWj/PSul9nUq5VC/tpH5sCzdmMmHlHIfWQOQnf7gWqz74K+uU1/cSkxhfdOG8vNZ+5n3c8c0Ap1LwtbEd19qaIlsW2WgsZ8r3Z9tFrWHNhKWnQkcy0F83wEPRYiBM5tg7Lpv8+3wFDLIpItDxiWQigeYH5WVwXuIz05MZW4HvjN8xUOdJv7mUp0eWc3LzQgxrA+sBTsv9Pxl/6Xb/19Tj1FcuShZKWglPoF3oD9qIisEpFVwCPAnUqpiyMc4iDgVOAIEXne/zsWuAg4WkTmAUf5z+tCixHcfXVZJ3949I3ghrINJDb30JqNfQVfD14zFka9scJLYR01OFPKUgcMN2S5jzLHs3kChg1o5Y4vHcRtnz8QEeHdk0dYP9ucdetB1Aw46zEm7J/v7ktblYItWyiZNVClsz4LMrNb25qDLKVgCVzrWaZpOdmylPJNjIsNynktBWMldXimO7A9ew2CbbbfVcR9lE4rb6W1xcooZCmYlpXNUtD7mROM826bw4m/m1F0dXW10d+pL6X4/I3P8EYomD93yXpumbmw6p+rlGL5+s2uzUtNKasmglLqCuAK32Wks4iivvcx8hcYPbIceSqlrSXBpnQqeyBO6ZlX7kBhm7lnWQoFYgBmsPNtv3uZmeGUsRSys49E8vcwGDagNcttFPYhtycT9PSnGdia+bn1QN3ekilW19ri7ZdMhCyF/pS1plJLQoJBUL/HNlCZA5p+vaM1wYae7MHcZilklcn2Z5lmjEW/biq3ZIu9AF8x900+S6E1kZElvE5BxzyiWAr5Jgu/eWAev3lgHkfsNMZ7r7GfthTM8iH62KYVq92O5jZtNZjXks6smr98A+OGdVjlqQV6sjNnyTrmLFnH0nXd/OOLB9X8c391/zx++8A8Zp5/JGOG1u/7NjMV1URQSnWWohDiih5slq0zS0vk3nga24zTtBQK0WtYClq5rDeUgr65zc/oT6tg8LFp03AZifBMeZAl4KsHUXPA1gO0uR94ysi2KtnMxU9aYgp6gDQHe20ZaEvBnHknsyyFTMaPRiuylNV9lPs9whQtZGgoBfN4ZhmRsMLXCxa1BagHP/P307GqfJaIdiPqqqtZ7iNfJlOe3mDWbV4j/vVqfIbNBaqvI1sgvpboa0HHpvRCtrvn2svLVIvbnvHidfX+vs1M9QvlNCF6EHnbVAqWmZfGNuMzLYVCmIOFPs7aTZn3Bi6E0OfaUvku/+Te3HzmfjklucPPtdLIKlbXkuue0cHa1kTuZWEGmvVbkhb3UYsxeH1gD69W4v7bjzT28/5rRZwvzqEVgK2khelO0zGMbEvBbogWcx9tNAZUU7EkDUtBy3X2EV5Z7PfvOj7r2P2B+ygzsOsByXTj2OTSVo+5RiWz7iHznWyDvf4Mc5tNebQ3WCloK29FZw8X/ecV/vfGZ5j5Zu4C0WpRSXOpLRWnFMj46U0/a28oxdBk2frcC21tREsh21/sPTbdR7a0RMjMqM3BYdywDg6cMqroZ+pgqDmI60F0pVHiuVDQ1owp6NdNBRAsXjPkO3CHUSy46DimjB4cbAvcPS1aKZiWQq4rybR6RgzyktvMstQtkitzvqBz1OwfsCsZEThkR+98H7LjaBZcdBzH7uYphSD5wD+GLYDdm0pbs9nCcq3v7g+26WvEjKPo68U8lr7+rJatsU1ngkUt0FgttAVlfo/X/ZhaLWXpKXAfO+xUVGdZRA4EJpvHUUpdX6FMdUdbBSs6M4N9qf0P8jWyD2PeoNpfbCoUm08a7FkbhVINj542lvteWgZkgqHmgD3csgq6NY/7yPv87HTWnv501vESlkCzjXC8w/xeNpeNub/u5Wz2SNCKyZzZt+aRoZQaTllKIYiXwIl7TmTf7UYwftiArP30jN42+Jgup66eVE6pDNuMfnVXL+OGdQTXiOl6WuNbpWamUWZbrtLpybIU/MWRdbcUvP/m6ekzYlm1xhUHjE4lTXZuAH4BHAy82/+bXiW56oq+ac21BqUW7oo6E7Hlxa+3WArhi7jDElMotCjp0lP2Ch7rhU8tFkvBJIgzWNxHNivDln5arHyGfo8+52aKZ5Yry3DZfO3oHZk8ciCTRw1EhKyOZi15As02/masBymGebzWwFLw/muFABm33hl/eppl67uLXgf2mkzZq6Eh4/bIKAVTAeRaCmv8Aoo2pdDbn2buknVZ+3dWqVVsVGw9QcK9t2uJra2uw04llsJ0YJpSRTrANAH6RjZrH22K2BSnVGyWgrmSWl+84bhFxn2U2VboZjKzZIb6dZzMsV4f58tH7MClD873jmcJ2mpMy0nP7ExFoR8VVQr+jpNGDGT+8g2csMeE4DWbC0gEvnzkVL585FQA3vzpcVnHa7G4vPKV8HjDDwpHISumYMgSxrR0Hnl1RdGGSLc+vZAJwwdw8t5bc8E/5nL+sTsF14St7Wm3xVLQ16mpKPQAa7Nwl63v5vhLH+PEPScEn9HTn+KWmQtpa0lw8j5bF5S5uy+FSPQKvDbSFmVpU4a1wlkK0alEKcwFxgHFS3/GHNssoljbyXIxb4Cevlx/px4XwlkuepDyGrDoNND8SsGMPWhLwZZKa1obgfvIMtM2ByXtXrIVsCvmCtAz+0kjBzH3wmOyAtimpaDdHLZqo1nHs7itquGOyFpbkcj9vpoBIfmLWQq6B3V7MsFtzy4mIRhKIfPeniCmkNvvYaXv5rS6iiwDrHYVPfjycnYcNwTwrgW9WMymFLr7Ulz/xAI+fdB27PSduxkzpJ2Z3z6q4HcrhO286O8dtSthJRSrCuDIUMndMwp4SUTuEZE79F+1BKsn9exla8sOMcnXLcs2A49a02bogKR/7Mz3/Mj0bdhqYCsf2ntisE3PsE33ywF+5pD5+VpBZa0/sGQB2dDvaW0RBrcn8zbMaS/gojLRSsOWuVQJ7Zbva5PEzApLtkjexkthdOB+fXefsfAsHVgj+jrRFqtZ06rTkmmksQ2+2uro7OkPZufF3Ck3PvkWP7nrFa57fAEAyzsry+KxyaVlMbOtaoVrTRqdSiyF71dLiEailKrrBVOs4mi+AHcw2JruI4vv38aIgV7WTn9a0Zb0FnZtN3IQz333vVn7BaucjQH2tAMm8cQbq/jU/pOCpi5B9pGZkmpJU7Wh1zvYBm5TQZgVUQuRsMzi87nV9HePQpYS1ArKIkw4eyrqBEOXZjd9+739KQa1JdnQ0x/4/00XUZio38VMhdXXn7leZvbitey+9fCs92il9dLbWbUqy8bmVtObamWVm8Spt0TcKVspKKUeqaYgjaLWEZFkQrKUTjGlsN5S8hnsM/CWiAE6ncrZn05z91few9+eWczwgbnZR7pm/wNGc/h9Jm3F/B+/P8t60LK0WNxHxdAz8GKzeVuXNRtJi1KwrbOA0nzX9kBz7n7todTVfJbC4PZkVsaPPl+mUuhLKYZ0ePtpZRC1jWshzM/VmW7rjLUx85ZtyFEK2gLqqtIs3mYp6HO1qYaWQkKymyA5ilOynS0ij/n/O0VkvfHXKSLVmVbUkSiXStQBz0Z41losgG0r1Q2Z/HLzaMX87d96/0588fApwYKl/pRi+9GD+eb7dspZ4GZijmsikpPNY7MU9KBcTMlqBTmgrfClZ+uyZsMWU6hGNkurNdCce1xzmyow+ITLhOjZu7lwsS+VDhYaZiyFVM6K9Sh85qDtrNv19fegofhtbsygEmuVKqzaAs16S75FfdVAy+8CzdEppyDewf7/IUqpocbfEKXU0OqLWDu+9pcXuOaxN4vuZxt8ozapCbt4is381uRZGW2zFIoNfp87dArfOGanYDYbdbZkprPaBoVM7MGiFIocWwf8ilkKZu+EQujPNQfnUrrK5cO+ornwe/rTafKNPYNCZUL0AjRzIV5/WgXuNZ2EsLqrl10mlH5bTRo50Lpdz/yz1gsYSmFFZw+ru3qDtQ1hS+1jf3giUlvZMIXcR7WMKejrwqWkRmeLXtF827OL+fFdLxfdz5bKGTU9LzyoFlMK+fLHbX7tqF2sgpLTEZWCuQLZrhDzu4+KWQq9/qhZVCn47iNVRM1oxWTuFy5al49CPSXM/gz6exZTUN+/48WsFq0mOoagWeZX7gxn3miL4qf/eZln3lrD8s4e9pk0ouDn2shnXRTrM/HuH9/P3j+8L9hmWmB9qTRPvbm6YFvZfNgshcB9VKGLLJVW1uNDRpGHu9n99K6X875nS2eLVgpRMWf72l8ddeAJB16jtssMo2eQps86asMSvV9Un7o5gInxNW/7/AF8dPrWwazXzAzSj4sN4npWWmhA9l73XV5FblxbzKEtosK2WXv6dzUbAyWKWArfev9OgFcy5Mk3Vlu/m9k5DeDttZusx+oIqq4qTv7944AX1ymVUtw+hUpjmL/xxgrcPIUshULB9ChMOf8uTv/TzKxtj7y2gvnLO4Prw7SGvnLrc/zh0Td4aWnTebvrglMKETDvLz0zjeqiKDWmkI+t/MCweQNHvfFHDfYCzflcU2GGGgOYaQ3sM2kEP//wHlY/vv6axSZfn9hvWwAOnlq4ZpNeC1FsNmc7BzaFbTtVtpXPet1BtmvM+58vDHPinhOznrdbSpLotGBNPqVgy97acexgy56FiZIFNaDAZCFo5GP2mvbdPMUUug1b8o9e92pOlMpdC6s7IGpOv2YmR13yaKAUzMmFji+4NFU7FSkFEZkkIkf5jwfo/grNQCnZCNnNX7zH0S2F0mIK+dhqYKROp1bG+WUZ8i0SuuXM/bnlzP2D56alYHNR6XHCnKUfsfNYAPYMZbGE2XvbrVhw0XEF24ZCZuApduMGv42xm01h29xVmcV6RjzCUnNJf0a+4HxY8dvO2ZD2bEshX3C1JXS9tCcTQc0nk2IDczGLDTxXVWuLFAw0m6d/nZ+5VE4g35aVlakoa1YOrnygNhWL/snMxWva+nEZSXbKTkkVkTOBs4ARwBRga+AKGtQop1RKceOYN2rQnKaIi0Kvbg3PZMs1lcM+6VIY7Oec7zrRHrA8YIq3QO2WM/fn2YVrrG4hk8BSMAaHY3YZy8l7T7T2XSgH/fsUO89W95FRhkMPPG1+o6Hs/STYvy+l+xbkZhplgtl2GcIpsOYq50FtLXT1pnJ+v748gc/wWD9l9GCrNTS4I5lVliXM8btP4Nm31tKWTHDDk29Z9xnQ1sLG3lSgAMyBM1MlOLNNp0uX0/PZNgDbij/2p9O0lTBXtR13vRGX07JmWdi++PUor9GMVHIHfxHYF3gKQCk1T0TGVEWqOlDKjN28UfVAaHMRZL/HUwrhG6hcSyGRyAxM5VjYD339sGC9Qj4OmDIyUBAFZdGriI3BMCFSNYUAsMof8EYWkVlbBeZNr624jtaWIEffNrPW7qPWZAJ6U1nvtfWOzrdmIjxzNov8DfCVwtBQVdp87p2wApiax3U0flhHQaUwsK2Fn314dy5/eH7efQa0ttCWTAQzddN6eWaht2bFtNRe8X3w5WR3FVrRbFoHff0KSjCKbfeT2dtEK3mb27UeK6mbkUrcRz1KqeDsi0iSaGn/saAUSyFrtWzEQLNWBrmWQvbnRvXPJkS46X/246GvHRZp/zDbjRrEMEu57HLIZGBlZK9ONru3ghoyN/GYoe2Fdg9iLeYAmbHmchfcmbQalkJ4P3P8179/vgly2DXVYVoKvpU2ONTjOl/zl7Di2WG0XSlsvVV+95tIxtIpdH0NH9hGm9G6tLMns3DytXe8hormYP7IayuA7J7iUbG5j/RvnNV4qsTUUdvAbvYn0fehed9lmhnVfiV1M1LJ1O4RETkfGCAiRwNfAP5VHbFqT7lKIcjRL1JiQgfoclJSQxfi0AHJrEY3+WWAg3Yo3lCnWvzuE3vn9R3r72ZmP0Wtw1SMCz+wCxd+YBdWd/UypD0ZNLHJh461rLHMDos13tGuqWIlLQL3UR7VF85iGmIoAO02GtDm+e/1rHjpOnsz+fB53Da03mCvbYfz3MK1WXGGcPkOMzhcaFY/fdJWvL12U/BeW48F01LQE/rRQ0pXCtaCeJYqqaXWITMzopat7+ampxZykGHtpizBbH1PbupN8ezCNbz2Ticf33fbkj53c6YSpfB/wP8Ac4DPAXcBVxV7k4hcAxwPLFdK7epv+z5wJrDC3+18pdRdFchWlHJ9+0HzF+NeM292TYtlgddA34drMnJQe0SlkDnOC999b9ESzZVy3O75B+NEoBQSOdsqRc9wRw5u51vH7lx0/7F+M/aJwwfwij+7zVRxzexnSz/Vvn9bsb/sQLP3P18Ji3AA2rQK9ORhcHuSViN2kY+wNTIu1Gz+L587gLfXbuK2Z5cE24YPaGV5Z0+gHMw4UCFLYfLIQbQlE7y+sosnXl+Vda3q60s3agKzblLp947t3OlN2YHm0o5tuo++cutzPPnG6qw1GtpqsN3v3f0pPnS5l/brlEKGstxHItICvKyU+qNS6iNKqQ/7j6OMVNcC77Ns/5VSak//r6YKAXKzWgqld5oKwFprx3LjtVj87kM7WukM1TYaOTiaA9Ucd4YNbC0aH6gl+iuZKZ1S1pVUOaOHtHPjZ/fjko/tGWxrswSLbb+RzhIq6j7S2SoFLu+9th0ePB5sBJW1i2TU4PZIGWRh5TpumKcUPrjXRLYdMZDWlgSTRg7K6i6nj6sHQ1tDJBsD2loY2NbCC4vWcsofn8xqAGSbsdvcPVEplOlTiVIw91+02kvzNSdeWhmYloKtkdVm0BamapR1KyulUsCrIlKyelVKPQqsLudzq0m4RHXB3gQUHlysSsESUxg7tD0rMwKi+2erNROvBmZ7Sk0j5Tt46qiseImtNpMtBqTdX+ZrrTZLQYqvmbjpf/YLHps9Inr8wWjEoLZoE4DQaZzop+7+6mN78ug3Dw+2mwp5mB9XGdia23bVphT0MaeOHZyVHNBpuI9sqcA9FVgKhcZ6c3DuT6uSjp/V6tSPL9jiNd3GMbX1YGZbVbqAbnOikvndVsCLIvJAlfopfElEZovINSKSdwmniJwlIrNEZNaKFSvy7VaUsLsnMxjk7mtbvGaLM5jYGs+PCbkCwG4p2GSoVmGyahDMpo0RLA7iTfBn1bbf0mop2NxHRvaRjgfoc18orX1gWzIIercbsZZdJg4DPKUQZQJgXlffPnbnvK1FzWtuvP+9g0G9yPc+Zd9tePrbR7HTuKFZrq7Zi9YWlC2wFCIM2nfOfpul6zIL9Ar1mTCPd+vMRex4wX9YtHpj3v1NTAtEZ32ttPR+0JZCfyoduBlNhbLzd+/mb89Eb9e6OVOJUvgOXmzgB8Avjb9y+D3eWoc98Tq55T2OUupKpdR0pdT00aNHl/lxueZxMogB2FbDGgogketesPYXsCx4sqVX2gYKe6+B3O/QKNosaZtxsGTu+sp7+PfZBwcDZsIyYzZdRQP8mIhNKYgID339MO4555DMqtgiro1tRnjBX9Py+NnJu3H7Fw5k9JB2timQMaRJCJxx4GT23nY4Zx6yfd79zGtkz22GA5kB0rRorM2ZEhIEi03/+1VFikMGMQXjPMxdso4p59+VtUK7pz/Fl25+jk9e9RQAb6zYwO3PLSEfpgvoz08vBGBhRKVg3sf6u9gshaCFaVbnw+z4ztf/+gILSmjZurkSi34KSqkgmiUifwTurNax8xGumqhdItZy1BZLwZw1mj2L9Y1pq6wZTksEu6JobcldaBWHQVdjW+AVB4YPbGP4wLZglmnOToMGQslEMKhZYwpGP+ZRg9sZNbidmW+uAmBFkYQA7dtva0lwxaf2ZurYIQxsS7LXtp7he+AOo7juCftCMk1ChO9/YJei39UMCn90+jYkRFi/qY9f3vda1gy4vUC8C6LXzwK7pXDr0wtJpRX3v7yM0w6YDGTWO7zjZ1j9o4BCgGwl0xVaL1IM01IY6BcTXLY+Vyk889YaNvb2ZykCM3XVJku9+cldL3PUzmPZd7sRDZMBKrAUQv0UukUkVW4/BRExU10+iNf/uaaELYXM7DJ3X3NAfm2ZZ3o++lrGdZW05LvbOoLpomhmUHKQRVHYXEVxUgqZqqul12GqB3qhmOki1JlS5mCjB8Tsjm+5rjGd/rl4TeHZq65w2t6a4H27js+qNgtw1M5j8/Y50ERVtNn9HoTTD5wcNE5KFbEUzN+qlFIPZvbRg68sY+abq4Pr16zuq9t/Fur5bdJncUdFLXdhrmvQSv5t322l70ftBtzQ3Z816NuUQiO58tE3+Ogfnmi0GOUrBbOfAjAAOBm4vNj7ROQW4AngXSKyWEQ+C/xcROaIyGzgcODccuWKSo6lYHE5BDIbj4+z5M3ri89abtl484hB3k07PCsomvt5tm0xGnMzdYlSuTPxOKDrDJm/sV6TYFMKJrZBdN/tRrDdqEGcfeTUgp+rg7b50kBbEsJ3T5hWMCMo6u9sXiP6mm0LlLVdKWhL1aYEo2Aqhc9cO4uP/uEJBvvfucsIUmsF0dqS4OWl65m5wMsrue3zBwb7mPeFTQF05ylBHiYVClJDJtVVTw50gccuo6QHZJTCZw/OKOpGte2MUxnvqtQl8FNR/yEi3wPOK7LvKZbNV1dDjlIIZ1cE9WuKWArH7T4hxwVguo80ZmmE+849hPXd/cxf7lkZ5ie3JBLcetb+tLYkglLJZuaSnsnFyVWjB5q4drPSmUjeIO25EoKS2IYi0IFmZXEzmdsGtSd56OuHRf7cYr9VoYE/qkVoKuGWkFLIt9+wAa1s6OnHnHOcsu+23Pr0IqaOGcy85RsKfqa+ZXqMgXNge65SyJQWEd7/m/8CsMuEoUFAHPT6HO+3sblswv7+fJj3cfYkRYIYw2BDRlMJrvWVghnXy9cjvdbEqWJrJQXxPmQ8TQDTAfsyzRiS6z7SboMMuqCaeZ/aJoHaysi6UY1A89SxXvFYPRjst91IHn51RXC8/bcfGVqan3F16JzrOFkK+nv2p9Nc9om9Ijf7qRfbjBjA147ekeP3mMDhv3gYyFhx5qCg5TbvRz2wFsqWyccn9tuW9Zv6OHLnwiXACg38UX/nrLpTCe2+LGz5jB/WwZK1m7LcR3tsM5w3f3oszy9aywf9hVzFMGfTWsH0GSdxvX8tm5bzhOEDslylxToXdvelue2ZxUwYPqBgPS7T/WXK1ZFsCVyG2n3kKa6MDPOXeUpw6piMm6+nQampcarYWomlcILxuB9YAJxYkTR1JGwmZjp9ZWhtSdCfToVmfsIZB05mx7FDOP/2Od5+Ce07zexnCzTvte1WPPKNwxg+sI2f3f0KkKnAaloZ+jjZSiE+WiFjKaQ5fvcJDZYmFxHhyyFXj3bpmBVM9QzSFpAux4swZfRgLv7IHkX3K/RbRrUIbW4fWyVd05U1YfgAeGtNTuVbEbFWo7WtwIfsgoxdltcfm+/1Nhg7tIO3VnlxmHFDO7JWwBeLQW3qS/Gtv3v314KLjsu7n+kizAqwtyaC76TdSBt7U1nZhZ2+5bCHn70FmT4S9SZO7UIrUQpXKaVmmBtE5CBgeZ79Y0VYMwc3WVZWkbCpL5x6SZAdEiiFZK6lEFQ1DX3upJGDskxtW+G8pJEpk/ncOCqF+MxuiqFlNnsl68BwltshWJNQu+9W6KeM+jPbqvSOG5a7DsZUHvr7FjueVgYD25JFi8bZCtItXuMFes1J0qjB7da+1/nIV5vsrOtnsee2w/nCYTsA2fexmTLc1pIILHitLC99cB5vr812Zuw8fmgQoIcGuo9idC9VEh28NOK2WNKXoxR8/7KxTbd1tFXMNLFlWSQN91EY23oGeyOfzE0cI50QlCYuVtY6TugByszL14Fmc2BJWmIK1cbWuU4TVfnbguQ2pWArCmgbgEzloQOzhZSIRqefmqdr3Sbv+ljZmUnhHTm4LeteiGIp2Lj3pWX8/O5XAVjR2ZP1XUxLoTelgliLVgrPLlzLO+uzlcJuE4dlnSMXUyjDUhCRA4ADgdEi8lXjpaFAvJzLBQgvRLKZ422WjCQJWQ1plfHvtkac2WeX4s4dIJKG+0gTp5RPnWUTpfdCXGi1uI+00jVN98AKquFNGvSjaJGcwSDqz9xhcfcMaU/y4X22ZvvRg4JtprWpz4Etw0afi2RCgoVe244YGLh/8qGDyuYx1/od2sxFZOG6T/naqOpBWXd5y8c9L77D5254hj22HhZsMxVEKp0pDDioQJ+PXSZkN56KGuCuNnGKKZRjKbQBg/EUyhDjbz3w4eqJVlvCsyVbgFEP8rYuXJDxSbclcwd2fQPa3BDFVj4HgeYaVCGtBh/aayJ/Pmt/PrBH/OIJ+bBZc/r8mgOz9nvbcuerhf75beXXo1sKtlXvwi8+skfgWgG7UrBl++j9WlsS/PRDuzF1zGB2mzgsd79QpkWXTSn4gWbdKOmsQ7bnmF3GZr3P9j1NhV2sn/hCX1m97JesgNz4gj7PhZo/TfRXmd/+BS9dtnGWQhPHFPyVzI+IyLVKqcLLM2NMeIamZ+UqK6aQm5FkXss7jRvKzAWrA7+rrRCZbQaQVUvJMjBkAs1mv4ICX6bOJBLCfts3h5Xw0NcP47VlncEgYvq59W9u5q4HzexrmK8uhqWQ77ViRF2J3NqSYOzQdsYO7Qi+u819pL/36QdO5uR9tubkfbbmN/fPy9lvSEcyGOwhE2jW51AplTPLP2aXsXlrOGV9p2QL4L13rXGMhas28ot7X+XnH9492Bbcv8ZX6UupoIx9Kq0CxVPIDTZykJeOuq1foqSWsaRCxMlSqCTQvFFELgZ2AQJnplLqiIqlqgNh95EtxztTW99ITzVUxG9P2YvLHprHmCEdXoqpcT8Hq34tN2Ax36reZs4G47ROoZnYbtQgths1iGtn6Lo+mfM42s9Pnz55q6BImlbEtVzElLEUyl+kWEp5isf+z7slf//w64D9u7UlE8z78futZbd1n2nwYgNZSiFkKWzsTdGbSmf1GNExChPb9Wxe72aNokMufgggyzINlJChFfpTaYZ0tLK6q5d+oz+6aYEAbD9qEG/4NY5GDfHcWnpy1p9SzFm8jjdWbuDEPSfmyFgr4hRTqCTQfBPwCrAdcCFeSurTVZCpLuQLNOdzHw0NFiZl3jNuWAc/Omm3YNGSebO1F7AUTGyzRW3uxq0KaTNjCyCPGdrB/V89lO8en6k11GaxHqqNrcd1+LVi2NxH+WhtSQR/kN8Kam1JhHpQeI/NK3hsqNKvVgr3v7ycB19ZxqlXe0XwdhqX8dWb/alP3X8SZ+Up9GcqOlv2UZeR6bSxTyuj7ECzDiqn0ir4LgNDSuHK06Zz9enTec/UUYGloJti9afTnHDZY3zl1uetMtaKzSX7aKRS6mqgTyn1iFLqM0BTWAmQ20+hcKAZdvcDWp3duSl4elGOufAlU3Kg8OBisxR0ipx5E8QpptCM5Bvsdxgz2FoltZa+Zf1b2mtcRTuGLdBcDD3I9/VHG4AyNa4U0ydtBeQWdTSv0c9cO4tnF64Fsjv3mSmfPzxpV87P01HPXG1uC/iavUi6Lamy/WkVuMF2nTA0WFhnnqs7vnQQO4wZzJE7j+WGz+6XkwnWqBl7nGIKlSgF7fRbKiLHichewIgqyFQX8gWazY5mmZIHcMlH9+QLh01hb6OYnUbfKGa9lkxmSxFLwTIK6EwNcz2DUwqVMdSfQYabHIXRA2dNLYVE9meZj6O6CcML0KJgLjosZf90WgX9wcOTp64ee7bOrhOGcekpe3HpKXtZF8bZpO8wjm1rerPeWPVvWz+RSiveNW4IXzhsCleeNt2a7m02YzLR92GqzjP27r4UP7zzJZaujU8xiEpiCj8SkWHA1/DWJwylDoXsqkV44ZW+UbYa2BY0VQ+CxUoxYlAb33zfTtZjaZN1k3GhthWIKZjYZou6WYt5wzmdUBnar93Z3YdIdkKBSRB8rmlMIXewakl4Pvha/s4f2GMC/3rhbT53qN19E8YssGdbOwOZlFSTc4/akYOnjipZviz3kWVl8XqjlW2+dQzJRCK4T7WCNedl+ZSC/i1qmYps476XlnH1Y2/y4CvxWfNblqXg92ieqpRap5Saq5Q6XCm1j1LqjirLVzPC7qNJI73c7nOOypRHCNJKi1woej/TytCDS7H1BVal4B/HvOHKmRk6Mmi/9vrufp46/0j+/oUDrfsVyuWvFvqXtBW1q6VFOHxgG3/93wODUuDFMFM537frOAA++u5tsvYJW1R/+dwBfOWowtVk82GeD2tMwbgf8rn3zCQnfcuYccIhlqA3eArEU8z1deO8tcoLeK81UnC7+1K8aqTa1puylILfo9lW7bRpCM8IthrYxoKLjuO9u4wLtpk+1UKM8btYnbJvpmV1Ju+7dKWwna+gzCJ5TidUxtZ+PvrR08YyZkgHe/uNb8JM8PsXv3faOOvr1UAslkKm/0bNPrZkhhjxg6ljh7DgouOs7lOzKYytkZSNsO7zFoJm7jOb+2hTb2ZbvomabQ2QmexRaJKWTAidhjVSy1Xtmk1Bm9DMZ512zUyO+fWjDSvjXYn7aIaIXAb8GQh62Cmlnq1YqjrQn0pnuRFsEzRtzhb7cSaPGsTz3z2a4QPbuOAfXn8grRSK5WfbMlB0L+fJIweywM+vz2f2OqIxfGAbs7//3qD+fz5GDW7nhe+9N2tArBXmtWFbxNhobA2gbPKZcYaoSiGMWSYe7JaCWWcp33oCU77vnbALHckWjp421rpvmGRCWLfJ/AwoMqerGJ2cssH4bjPf9PpPbOjuD7wG9aSSK39P//8PjG2KJslA6k8r2oy2l7YJhE77i5IuNnyg/ccrxVIY3J706t0nhPu/eihbDWxlnx/dDxRelemIhi1fXnP2kVN5eel6oPYKWP/iZpJBog7uo1IZbKm6aqO1JcHQjiTru/utlVoL0dbitUdNiGQN9Db3kKko8t2S5gLSsUM7uORje0aWpSUhWW6cvlSalkRtK/fo2IlNx23o6Wfh6o1MHjmIYQPrNymspEfz4dUUpN70pxRtSbMXsmUxjV7IVEa6mDZvi3UkMweGoR2eUhC8VEnwUug2FalU6aicrx69Y90/096UKfr7p40fyivvrK+2WAFRraXWFm8S8/CrKyLPbPXY3e73zG5JSNHKqWZwOZ9rpxL3W7IlkbWSuh7pqYX6NyxZu4mPX/kkR08byx9Pm15zWTSVNNkZC/wEmKCUer+ITAMO8NcuxJ7+dJr2ZAIdzinoPoqY1519/GhKwbQUhg5o5e113VkB5t23Hl7yZzuaA3PhYjmB5ju/fHDVZTLJF5S95KN7MGP+Km57djHgVRMeM7QjJwgdhfbWBJ093vcOrzwOY8YZ8i0KrSQhI5mQrGB2uOpBLegukPo8w+9LoUuR14tK1ilcC9wD6LXnrwHnVChP3ehLqaziXrabMSiOVsbFoW+oSSMKZ3qYs6Mff3BXdho3JKfhu2PzpM0aU4j+/kRCapqVlm+Q/tDeW/OLj2TqEBVzkRZCp7gmpHjpjiz3Ub5AcwXut2RCsj6jPpZCfi/Ayg2eK6ve7c8r+bhRSqm/AGkApVQ/0DR+jlRaZa1ktV1KA3w/fjk56wfvMIrffWJvvvG+dxXcz7QU9pk0grvPOaTojMmxeWDrlxGnmALAf77yHqtFIiLBpClcOTUKuoSLrlTbkhBG5InLaUz3Ub6U1HxKctTgdg7dcXTB47e0SNbM3RZL7Eulg+KKS9dtsjYZCvP22k15XcCFLAXtMdjUm+KR11bw+RufKZoeXw0qUQpdIjISvzSKiOwPrIvyRhG5RkSWi8hcY9sIEblPROb5/+05g1Wgpz/FwtUbs5WC5VrSi8jKqUvSkvCW+ttWc5rEKdvEUV/M668cS6Ee7Dx+KLtaSmhDZmZvKyYZFX1/tCSEc47ekS8enl01YOzQ9uBxdxSlkOcEzrrgKK77zL4FZUkmElmDd18qnTMIX/ivFznk4odY09XLAT99kNOunlnwmAAHXvQgn7nWXhaukKWg3VfdfWm+cutz/GfuO9z69KKin1cplSiFrwJ3AFNEZAZwPfDliO+9FnhfaNt5wANKqanAA/7zmnD9428xf/mGrIU3tmtJ12wpry5JzO5uR2zQFTqzS6jHL/uoGLrOUDmWgo6nmIX9Brcn+cYxO2Vl2n3n+GnBY3PAztdLuRJXSzIhWSupr/rvG2x//l1Z64UeeNlbebzaz1Ka9daagsfUAfEn3lhlfb2QpaDdV5v6Uozz09Qfea32K58ryT56VkQOBd6FNwK+qpQq3C4p895HRWRyaPOJwGH+4+uAh4H/K1e+QuhyuWYdHNuMXaeZltOLuInubUeDMK8r07feLOj1CQPLWJugu6FlmlFlXusI9YvWmANovqydSpRqS0KyUkOve+ItwHMT6TRlnTa7JGLwt5jrOYqlsLG3n1Vd3vd6Z31P3v2rRdl6VUQ6gLOBH+KVzv6iv61cxiqllvqP3wGsK05E5CwRmSUis1asWFHWB43y6+ibBbZsl5IuohYuvRuF4W6xmSMPB/gNisxeANq33ozuxHLuDx030wFjc42CGXAe0JpROKZlb7qPLjguU3W1EqUQLmOvD2UW39Nj/KI1hduUamwrs00KVePVlkJ3X5oVnZ4yeGHRWn5450s1bcpTifvoerwGO5cCl/mPb6iGUMqzuazfWil1pVJqulJq+ujRhQNH+dA11M3sAtvNuO2IQXxor4nc8aWDSv6MEU3U1N5RXw7fybtuzVmpnnU3k/tI3z6DylAK+j06s8/03ZtKJp/C6elPsc2IAZy6/ySmGX2WKzl/4XLk+ljmgjbtDlq4OppSMN1cvf1prnz09azj9fSlGJlnrAhnPW4/yit/c/Vjb3LBP+ZE+vxyqEQp7KqU+qxS6iH/70w8xVAuy0RkPID/v2bOs0kjBzJ55EDOPSqzYMl2KbUlE1zysT3ZYcyQkj+jGWd8jvrQZpRkD7Y1oftIz+4HlLHaXruc9OzfnPgOMCyF9jzNhHr60+w0big/PGnXrDIblcQUwqux9U+xpquPuUvWsXJDT2DF5Ct1PXvxWlZ3mYN+ZmC/7vEF/OSuV7hlZiZY3N2fDvpEhwknuJy8z9bB41tmLsqKdVSTSpTCs37GEQAish8wq4Lj3QGc7j8+HfhnBccqyKD2JA9/4/Csao7mDOM9ZZT91dx9znu45cz9i+/o2GLRHf1Ml0kzWgpa/HLcR+/3q67qYnpmMseAIN4geYPYvf3pYE2CWT+sknUbr4Qqk2pPwsa+FMdf+hgn//7xwO21qsvu2//AZTM48XePBc+1pdCSEF5d5h3fHMx7+lJBscYw4aKdU8cMZsFFx3H5J/cGvFTXWlBJQZ19gMdFZKH/fFvgVRGZg+cB2j3fG0XkFryg8igRWQx8D7gI+IuIfBZ4C/hoBbKVjHkvXl8kda0QZhtCh8NGYCkY27RSaCKdYFgKpSuF90wdzRs/OZY75yzl+ifeygq6a0tBkILprloXmLGASpSqrTcEwKoNngJ4a9VGdh4/1N/Wm7VPXyodWBaLVmcGax1TaEkIC/ysM3Mw7+5PM2FYPkvB3kdeN+Fas7E35z3VoBKlEE4pjYxSKl/Z7SPLPWalmJeSc/04aom+ubPdR7mKIu7okhBbFVl0lo9EQoJuaylLTKE3lS6Y7qoVgK0vRVny5HnvW6sy8QPdh2WloRT+8dwSzvnz88EM3kRbCsmEBGmsnd19nHfbbB6bv5JUWmX1sDbJ1x1yq0He/mu6YuY+Ukq9BawHhgEj9Z9S6i3/tabCKQJHvcj4wDM3va7gum5jbW70WqBTurctUsqlELbSFgPbM9sKWgoF+lKUw5eP2MG6Xc/sE5JJIzbdR7pr2pwluWt3A0tBJMh27OpNcevTi4KaRh154ibhQHN7nSyFSlJSfwjMBn4L/NL/+0WV5Ko7Tic46oWe2ZqzY10VVy9sawZ0n4KtKijrbFMKZonzQgUltTJoNWMKFdzH//Mee5tSHQNIq8xAbVp5Ol1U/zcxMxz1cbpCbqp8VQ/C1ZnbWrz9hg9s5QN7TGCbCpRxISpxH30UmKKUqo26qjNOJzjqxUE7jOKIncZwwXE789CrjwBw0l4TeWzeSv43Yv/kOHDZJ/aiqydVkZVtmyWb/SwKWQr6Y7OqzdYgfctcz2QrjjnXtxCWW5SCTrXt6u0PMqwWrspOZx2eR6nmcx+1J1v47Sl7RZS+dCpRCnOB4dQwdbSe1Nt9NOO8I1yfhC2UjtYWrjnj3VnbBrcnueLUfRokUXm0J1uK1vYqhs1SMJVCoR4LQfaRoRRqcR+b2UK2Omid/sx/+fpMmuqm3hRvrNwQBOPNRKLOkKWQb8YfrqTQXkGNqVKo5FN+CjwnIveIyB36r1qC1Zt654dPHD4gcBk4HFsq4QVjkK0URIRff2xPa4XTINCcqE6gGeChrx/GN47JrmzcZUzeCpWtMN1HX//bCxz328dy1hKY7UpP3ttbd6B7socJ11yrpPBgKVTyKdcBP8NLJf2l8deUuJiCw1F/bOms4TagJ+01kR3H5k6gdFC5Jct9VJk8240axEl7Tcz7eqGKyauMRWtPveH1WTYXsgFMGJ6pBPTDk3Zh9vffm7dbXSqP+6jWVPIpG5VSv/VXMz+i/6omWd1xWsHhqDe2cjC2xXA2N5W27k1LoRruo9YCboNNfamssh75elJrMVaG1jPsMiFThnxgWzIIqn/T0nclHGgeXEbhwXKoRCn8V0R+KiIHiMje+q9qktWZZiov4HBsLtgCwzaXki0grd9ra2taCcki5sZ+fkFDgMPeNca6jw4w64Vvmn0m2dvEfOGwHfjRSbtmbQtbJcU601WLSlSPDn+bNR0UcEQFx2wYbp2Cw9EYfvPxPbN6KNjWGtgtBV3mwlynULk8xTKYRg+2N/4x0VlKYffRiEFtXHDczllF/DThxXP1aAdqo5J+CodXU5BG41SCw9EYTtwzvw9fM3ZYblV+PYiaE7pq1I4q1nPaTCE996gd6e5L0duf5qk3VwfbdbntcGC6JSF510Pk00X7Th7BAVNG2l+sAZUsXhsrIleLyH/859P8ukVNiTMUHI74stc2w3O22QbRaqxTSFrMjW1GZOoTjTIshWkThnLDZ/dj1JD2rP31LL831C+hUIptPoV285n7ce7RO1pfqwWVGFvXAvcAE/znrwHnVChPw2im6pQOx5aGLchqUwDVuI9tA/f2owYH/aJtqeT5ekqEF7sVUlr5RK/32FSyUhAR/euMUkr9BUgDKKX6gaZdjeV0gsMRX2xBVlscsBoDaCIhweCtlVFLQjhyZ6+sh2k1aAbm6SkRXoBms0KCz80je73HpnJiCjOBvYEuERmJX9XL762QWxGqSTBNQoejXjx1/pF0djdPEbx68dDXD8vy7ZureVtbhL6Usq5JqFaZi9YWIZVWnLDHeB59bSVnHzmVaeOHcvzu461Nt/L1lAi7jwrJZ9MXIvVPgilHKWgJv4rXGGeKiMwARgMfrpZg9cYpBUcjGDu0g7FDK2ltvnmy3ajsVb5mRlIykaAvlbLOrKuVWt6aSNBNmonDBzDjvExC5YFTvAZcV58+nQnDMxbDYe8aw+UPv55znLD7KNwHOus1i1ZohFu7HKUwWkS+6j++HbgLT1H0AEfhVU5tGiYOH8CStZtqUkjL4XBUn2SLQF/2rDuZEPrTqqLS2SZ6lXRLHnePdiVp9t1uBOccNZX+lOKyh+YH23tKsBRstY0aMSyVoxRagMHkZnHWpo5rjfn32QfT2W3vuORwOOJHsGjNGDE7WlvY0NNftZl1poFP9OOdc9SOvPpOZ5ZSyLEUCozytjIWjVg/VY5SWKqU+kHVJWkQwwe2MbzMzlEOh6P+BIvWjKBCezLBhp7qrGg2KXUVcbjsRSnZRzal0AhLoZyUVOdncTgcDcO2klkP3tVY0Qyg/JLXlSqF3HUK+QUstGq7npRzChvWR9nhcGy5nHXI9px/7E5B1pGpFNr92kjVGkR1Imm+Vpn5GNyezFrxHE5JLT2m0ARKQSm1uvheDofDUV3OP3ZnzjpkitFcx3QfebPsaiWM6HabtuJ8hRAR9t42U/QuXOai1JhCswSaa4qILAA68RbC9SulpjdWIofDESfEEgTWM/pqj6HlVCbdeqvcxW2aki2FBmiF2CkFn8OVUisbLYTD4YgfemA100X1jD6cAlouetZeqvsIYPyw/Eqh0DoFu6XQBO4jh8PhaCRaKWStePYH73ylrEtluN8StJxuZ/l6JkDhQHObZYl2s2Qf1RoF3Csiz4jIWeEXReQsEZklIrNWrFjRAPEcDkcj0QNl0mIpdPdVx1IY7Vc9Led47568FT87eTerq6hQ97T2iPWdak0clcLBSqm9gfcDXxSRQ8wXlVJXKqWmK6Wmjx6d28zb4XBs3mTcR5kBc/pkb3Y+blh1ytX88qN7cOr+k9hr2+Elv1dE+Ni7t2WcpXxJIXdUXCyF2MUUlFJL/P/LReR2YF/g0cZK5XA44oK2EEz30WcP3o4Dp4yydjQrh/HDBvDDUHvMUrFZCoVm/ub3EfEyoKQBy8JiZSmIyCARGaIfA+8F5jZWKofDESf0bNtMSRWRqimEalEo/dSGqTAG+aW4W5Mu+2gscLt/cpLAzUqpuxsrksPhiBPB6uWY11YoJ0itGdjm1XKyuZRqTayUglLqDWCPRsvhcDjii1YKPVUKKteK7UcP4pV3Ost676D2JHT20NoApRAr95HD4XAUQy/yqtaahFoxeeSg4jvlYahfQ6kSa6NcnFJwOBxNxYBWnX4a7+6/lQzoQwe0Ft+pRsTKfeRwOBzFOO/YnUgpxft3G9doUQpSietnmK8UwgX16oFTCg6Ho6kYM6SD33x8r0aLUZRwg55SivVllEL9XWTOfeRwOBw1IFzSohyl0O+UgsPhcGwehC2FI941JvJ7hzr3kcPhcGxe6MV1yYRw31cPZfyw3LIX+Wik+8gpBYfD4agB5orm7UZFS09tSybo7U+zzVYDAVjV1VsT2Qrh3EcOh8NRA8rJPhriV1GdNNJTCql0/d1HTik4HA5HDdBKoZRhXVd7bU8m+OR+23LVafVvPOncRw6Hw1EDCnVZy8evPrYnzy9ay5ihHfz4g7vVQKriOEvB4XA4akA4+ygKA9uSHDhlVA2kiY5TCg6Hw1EDCrXejDPNKbXD4XDEHO0+Uqr+weJKcErB4XA4akAjeiFUg+aU2uFwOGKOzj5qQFZpRTil4HA4HDVgSEdzJnc6peBwOBw1YFgDeyJUglMKDofDUQMa2SinEpxScDgcjhrQiP7K1SBWUovI+0TkVRGZLyLnNVoeh8PhqISJwwfwuUO3b7QYJRGbSIiItAC/A44GFgNPi8gdSqmXGiuZw+FwlMeM845otAglEydLYV9gvlLqDaVUL3ArcGKDZXI4HI4tijgphYnAIuP5Yn9bFiJylojMEpFZK1asqJtwDofDsSUQJ6UQCaXUlUqp6Uqp6aNHj260OA6Hw7FZESelsATYxni+tb/N4XA4HHUiTkrhaWCqiGwnIm3Ax4E7GiyTw+FwbFHEJvtIKdUvIl8C7gFagGuUUi82WCyHw+HYooiNUgBQSt0F3NVoORwOh2NLRZqt1reJiKwA3irz7aOAlVUUpxLiJIuNOMkXJ1mKERdZ4yJHFOIka5xksVGJfJOUUtZMnaZWCpUgIrOUUvXvim0hTrLYiJN8cZKlGHGRNS5yRCFOssZJFhu1ki9OgWaHw+FwNBinFBwOh8MRsCUrhSsbLYBBnGSxESf54iRLMeIia1zkiEKcZI2TLDZqIt8WG1NwOBwORy5bsqXgcDgcjhBOKTgcDocjwCkFh8PhcAQ4pVAnRORDIrJVo+VoBty5Kh0ROUJEBjVajmbCXWd2NkulICJnisjlIjIlBrJ8SkSeBA4GuhstTxh3rkrH7+nxQxEZEANZPikizwCHA32Nlicf7jqLTqPPVaxqH1WCiAiekvsw8E1gKbCfiCxRStX9h/flOQO4CjhQKfVUvWXIhztXpePLmAT+B/g/vMHkXuC/DZInCZwDfBt4v1LqyUbIUQh3nUUnTudqs7AURKRDeaSAZ4H9gN8DhwA7N0Im5eX6Pg3cAvSISEJETheRhsijceeqdESkzT9nfXjnbGfgD8CnRWRkI2RSSvUD84AbgbdEpE1EThaRCY2QJ4y7zqITt3PV9EpBRL4D3C0iXxaRXZRS85RSq4G/AQK8p15+QxG5UESOMzbNxysFfifwAnAAcI2I/NTfv67n352r0hGR7wE3i8gZIjJCKfWUUmoT3k27NXBUvWQTkfNFZD9j0xN4BSH/gzeYfBC4TkS+7e/fqHPmrrPo8sXmXAUopZr2D/gM8DCeZv0B8A9gsvH6e4HrgCND75MqyzECb3XhGrwLrdV4bWvgAmCK/3wHPNNwgjtX8TxXhjzn4rmIjgRuAH4DjDdePwX4J7B9jeUYD9wGrAXmhV47APgJsLX/fFf/3I5s0Dlz11mTnavwX9NaCr4PbhvgcuX5Bn8OzAV+qvdRSt0LLAB2E5HjROSL/vZqL+PuAv6hlNoKr4XoV43X3gZ+ppR63f/s+cDjwKQqy5AXd65KR0RagL2AC5VSDwA/BDbi+fHx5bsFWA8cKiLvFpFP1kicdcBflVLDgbUiYp6zp30ZF/syzQXuxiurXFfcdRadmJ2rbOqpGWugab8H3Gk8Hw3MBA4zth0ALMe7EM6toSyD/f/vxjNRx1v2GQD8GngIGObOVWzPlS7/cjHwJ/9xwpf3DmAfY9+jgU3AIuCzNZRpiP//YGAV0KblMvZpBS4F/g101OMcxeE6KyBLLK6zOJ2rSPLW40OqcFKPAMaFTzLQDrwEHKK3A2cDPzFO8n+Bq4GBtZDF9uP7n3dV6LXD8GYjv66WLHlk+ASwh3E+GnmusmSJ27kyPm+48dgcZKcC9+ErAf8cXYA/+OO5HZ4E/ljFc2aVJXTO/o7XrtZ87URgVh3PWUse2RpxnbUUeK3h1xkwwJSnkecqkrz1+qAyT+aBwIvA9cAOoROb9B9/EXjKeO2LwNeMk14V32oRWRL+Yy3TaOAVf1A5ANgdGApMrOG5Osq/gJYDZzT4XBWSpeHnypDn/cAjwE3At4ztLf7/Nrz0wD8br/2WjFIYQZ4JQhVlSRiDiD5nY4HVeC6iXYBt8fzkk+twzo7DC9L+BDjIPGcNuM4KydLw6wwvJvA43qD+SWN7st7nqiS56/2BJZzQFuBPwCdC282Z3Hj//4PARXim9T3ANxohC4Y2xwtKpoHngXfX6BwJnvn7F7yA1THA5cAX9MVXr3NVqiz1PlcWefcFngI+ABwK/BXYNbTPaF/W+/HWA0zxz9npDZKlw3h+lX/Ongam1emc7YPn3jgW+DheIPeM0D71uicjydKo68z/vZ4ETsLzLtyBoezrea5Klr2RH17kpG4FXAsMx5uxnYpnrnf4r1+Cp4UnA9sD/4s30/p2g2R5FM93KcDxwJvAN+t0rk40Hn8KeMJ4nsQLYtXrXEWRpWHnypDlXOBi//H2wK14Sk3PMC/Hyywahzcb/zGee+a7DZDld3iZKdPwLIdT8QKQdR088Bbt/dJ/PAAvY+ZZfJcX8Ms6XmdRZGnIdeZ/3q7AH4xt0/Csu9H+87qNXyXL32gBjJN2Np5vVpvmI/0f9VD/5vwL8Ge8RUOD8Mz4rULHaIuDLHgm6rA6nKszQ9tbgIPwZpHb+Nve5V+AtT5XZclS63OVT05gN7yslEuBxf7vey3wHTz3zPWWc9YeB1mA6Rixhzqes32B14AR/vPv4AVov+/fI7+u13VWqix1uCdPB442nk8G5mC4f4Ar8FJMh+BZLTU5VxV/l0YL4J+MM/BMrffhacsL8LT/RXhZAx/19xuCl3mxh/HevEGmBsiSrKYsEeX7FkaePJ6v9Gn8bJXQe2t9rkqRpebnqoCc38Gz+rYCfgWc4O83DS/wt2Mdz1kpsjTynH0bGIOnuO7Eixn9Cc9NeAWGwqzDOStFlpqeM/93+xveOofZ5nfHU+bXGc9H+PfDNrU6V9X4i8s6hSPx8obvBr4GdABfAL6LN/gOAVBKdQI3482eEBFR3tLwuMjSX2VZosjXjuemwZdrNl5dno9puQz5an2uSpGlHucqn5ytwJeVUmvwZpBv+fu9AszA/41FJFGHc1aKLI08Zx3AaUqpL+PdDz9QSn0a6MGb4fb4ctbrnowqS03Pmf+73YtXjuIZvHFC8yXgWBF5t/98A/AcoAz5qn2uKqahSsFYUv4cns8PpdQs4DE8P+544BvAMSJygohcgOeSeMnfV22OspQo35PARBE52N9P8IJVA/yLTlVbvjjJUqacjwOTRGQaXpDvKhEZiDcD3RVvzQFKqfTmKEuZcs4AdhSR9yilFiql7vP3OxZ4Q7+/TtdZ3WXJI5/4D69XSq3Fi0N9SEQm+Z+/HrgQ+I6InI7nddgF6KyHfOVSd6Vg1hYxLvQZQEJEDvGfz8W7GfZRSl2PZxIejJd6d7zyV29uTrJUKN/beEpLX2hjgK4a3aANl6VKci4GdlJKXQK8iucCmAZ8SCm1fHOTpUpyvo0XeEdEDhGRR/Csmys2R1kiyKcnOd3+/6fx6lD92NjnMrz4xj54K6Y/opRaV0sZK6UupbNFZF9gf6XUb80Zj28Sp/GqPb4IfExEZiilFovIGLwfGaXUgyLycDVmS3GSpYryjcMrwaD5ulKqd3OSpQZyjsULfAN8Fi91ce3mJEuN5NS/7QK8dOMXNydZSpRPL0Qzx4LLgL+IyC7ASrx42oMi8kgcXUU2am4piMg5wO3ABSLyfn9bC2TNBDrxgkXtwC9EpBUvgLNCH6dKCiE2stRAvlWGfNVQCLGRpYZyLtMyVkkhxEaWGsq50t9vYZUUQmxkKUM+pZRKi8gAERmsZfH3n4MXFB/qb28KhQDUPvsIb/n9XsDJwCOW1y/EW6yzE57b4Vo83/QfqH4WQ2xkibt8cZKlWeSMkyzNImecZClTvu/hlR3Z3X9+Cl6ywM8xKrM2018tTuIJeFH3/f3nLf5fB3AXcLa/PYGXn30zfglbY3tOCmOzyxJ3+eIkS7PIGSdZmkXOOMlSI/n2B7ar9W9a0+uliidzPPAvPDPvO8DLwDH+a7p2y5F4tc1HWd6f2Bxlibt8cZKlWeSMkyzNImecZKmRfLFbb1D2uajiST0BYwk58Dng9vAPi2f2Xeg/39c86ZujLHGXL06yNIuccZKlWeSMkyzNKF89/yo9kafhlZ9tBwaS3ZXqI2RKwJqF47bBW9C0Dq/eR1VOaJxkibt8cZKlWeSMkyzNImecZGlG+Rr1V3JKqp+GNQ7Pl5YGXgfOBL6ilFoqIq3Ka3A+Hi9DAOVF6AWvyuSf8PKOz1FKzSn18+MqS9zli5MszSJnnGRpFjnjJEszyhcLStSsus78jsCNehteDZK/h/b5F3CU/1gXrRoDHF4NbRYnWeIuX5xkaRY54yRLs8gZJ1maUb64/EWyFPy83B8CLSJyF17ubQq8/FsR+QrwtogcqpR6RETa8PL6XxORHwPHi8jhyludWdEKzTjJEnf54iRLs8gZJ1maRc44ydKM8sWNoovXRORQvEJPW+FVCf0h0AccLt5KP5S3yOT7eDnF4KVvnQE8gFfQ6yil1OpKhY2TLHGXL06yNIuccZKlWeSMkyzNKF8siWByvQc41Xh+OfB5vJP2jL8tgeen+wteW8B98crG7llNsyZOssRdvjjJ0ixyxkmWZpEzTrI0o3xx/ItyUgfiRee1r+2TwE/9x8/jlf0Fr/HHrTX+gWMjS9zli5MszSJnnGRpFjnjJEszyhfHv6LuI6XURqVUj8rU7jiaTB2gTwM7i8idwC14ZppZUraqxEmWuMsXJ1maRc44ydIscsZJlmaUL45ETkn1gzUKr6nMHf7mTuB8vLrvbyqllkBd6pjHRpa4yxcnWQoRJznjJEsh4iRnnGRpRvniRClVUtN4XaJWArv72vU7QFop9Zg+oXUiTrLYiJN8cZKlEHGSM06yFCJOcsZJFhtxly8+lOJrwiv2lMbrRvbZRvq94iRL3OWLkyzNImecZGkWOeMkSzPKF5c/XegpEiKyNXAqcIny+6A2ijjJYiNO8sVJlkLESc44yVKIOMkZJ1lsxF2+uFCSUnA4HA7H5k3dezQ7HA6HI744peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwqOWCIiKRF5XkReFJEXRORrIlLwehWRySLyiSrKcLaIvCwiN0Xc/wwRuaxan18uInKSiEwznv9ARI5qpEyO5qHkzmsOR53YpJTaE0BExuB1yhoKfK/AeyYDn/D3rQZfwCubvLhKxysZEUkqpfpLfNtJwJ3ASwBKqe9WWy7H5ouzFByxR3nNTc4CviQek0XkvyLyrP93oL/rRcB7fAvjXBFpEZGLReRpEZktIp+zHV9Evioic/2/c/xtVwDbA/8RkXND+3eIyJ9EZI6IPCcihxsvbyMiD4vIPBH5nr//IBH5t2/xzBWRj/nb9xGRR0TkGRG5R0TG+9sfFpFfi8gs4Nsi8pa2kvxjLRKRVhE50/9uL4jIbSIy0D8XHwAu9s/DFBG5VkQ+7L//SF/mOSJyjYi0+9sXiMiF/vmcIyI7VfzDOZqTRi+pdn/uz/YHbLBsW4tX0Gwg0OFvmwrM8h8fBtxp7H8WcIH/uB2YBWwXOuY+wBxgEDAYeBHYy39tATDKIsfXgGv8xzsBC8k0ZlkKjAQGAHPxSjKfDPzReP8wvDo8jwOj/W0fM475MHC5sf8/8dtA+vtd5T8eaezzIzJloK8FPmy8di3wYV/GRcCO/vbr8XoN6++q3/8F/Rnub8v7c5aCoxlpBf4oInOAvwLT8uz3XuA0EXkeeApvsJ4a2udg4HalVJdSagPwd7zGLIU4GLgRQCn1CvAWXt9fgPuUUquUUpv8Yx2Mp3SOFpGfich7lFLrgHfhVee8z5fvArwGL5o/hx5/zH/8ceO1XX2LaQ5en4Bdisj9LrxqoK/5z68DDjFe/7v//xk8V5xjC8TFFBxNgYhsj9dXdzleXGEZsAeeC7Q739vwZr/31EVIj3DdGKWUek1E9gaOBX4kIg8AtwMvKqUOyHOcLuPxHcBPRGQEnmXzoL/9WuAkpdQLInIGnqVUCboeUAo3NmyxOEvBEXtEZDRwBXCZUkrhuV+WKq+37qlAi79rJ15PXc09wOdFpNU/zo4iMih0+P8CJ/n++EHAB/1thfgv3swcEdkR2BZ41X/taBEZISID8AK+M0RkArBRKXUjcDGwt7//aBE5wD9Oq4hYZ/q+BfM08Bs895huGDMEWOp/v08abwmfB82rwGQR2cF/firwSJHv6tjCcLMBR1wZ4LtVWoF+4AbgEv+1y4HbROQ04G4ys+rZQEpEXsCbRf8Gzw3yrIgIXsetk8wPUUo9KyLXAjP9TVcppZ4rItvlwO99t00/cIZSqsf7CGYCt+G5gm5USs0SkWPwAr9pvKbxn1dK9frB39+KyDC8e/HXeDENG3/Gc5UdZmz7Dp5bbIX/XyuCW/Hca2fjxRL0d+0WkU8DfxWRJJ6iuaLId3VsYbgqqQ6Hw+EIcO4jh8PhcAQ4peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwoOh8PhCHBKweFwOBwB/w9rIgmvO/MuNQAAAABJRU5ErkJggg==\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "# start the figure.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(weather['Local time'], weather['T'])\n", + "# label the axes\n", + "ax.set_xlabel(\"Date of observation\")\n", + "ax.set_ylabel(\"Temperature in Celsius\")\n", + "ax.set_title(\"Temperature Observations\")\n", + "# adjust the date labels, so that they look nicer\n", + "fig.autofmt_xdate()\n", + "# save the figure\n", + "fig.savefig('weather.png')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/master/singlehtml/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py b/branch/master/singlehtml/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py new file mode 100644 index 00000000..8742b5f6 --- /dev/null +++ b/branch/master/singlehtml/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py @@ -0,0 +1,38 @@ +import yaml + +def get_parameters(config_file, required, defaults): + ''' + Parameters: + Optionfile: FileName of the yaml file containing the options + required: Dict of required argument names and their object types. + defaults: Dict of default parameters mapping to their default values + + Returns: An object with fields named according to required and optional values. + ''' + f = open(config_file) + options = yaml.safe_load(f) + # create a parameters object that allows setting attributes. + parameters = type('Options', (), {})() + # check required arguments + for arg in required: + if not arg in options: + raise Exception("Could not find required Argument " + arg + " aborting...") + else: + if not isinstance(options[arg],required[arg]): + raise Exception("Expected input of type " + str(required[arg]) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + # check the default values. + for arg in defaults: + if arg in options: + if not isinstance(options[arg],type(defaults[arg])): + #Wrong type for the parameter + raise Exception("Expected input of type " + str(type(defaults[arg])) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + else: + print( arg + " not found in option file. Using default: " +str(defaults[arg])) + setattr(parameters,arg,defaults[arg]) + return parameters + + diff --git a/branch/master/singlehtml/_images/01_memory_layout.svg b/branch/master/singlehtml/_images/01_memory_layout.svg new file mode 100644 index 00000000..93da7c68 --- /dev/null +++ b/branch/master/singlehtml/_images/01_memory_layout.svg @@ -0,0 +1,584 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How you see a matrix: + How NumPy sees a matrix: + [0,] + [1,] + [2,] + [3,] + [,0] + [,1] + [,2] + [,3] + [0] + [1] + [2] + [3] + [4] + [5] + [6] + [7] + [8] + [9] + [10] + [11] + [12] + [13] + [14] + [15] + + + + diff --git a/branch/master/singlehtml/_images/01_table_dataframe.svg b/branch/master/singlehtml/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/branch/master/singlehtml/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/branch/master/singlehtml/_images/02_views.svg b/branch/master/singlehtml/_images/02_views.svg new file mode 100644 index 00000000..925354e0 --- /dev/null +++ b/branch/master/singlehtml/_images/02_views.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + array "a" + array "b" + .shape.strides + .shape.strides + + + + + data pointer + data pointer + memory buffer + + diff --git a/branch/master/singlehtml/_images/anaconda-navigator-jupyterlab.png b/branch/master/singlehtml/_images/anaconda-navigator-jupyterlab.png new file mode 100644 index 00000000..4ea0854f Binary files /dev/null and b/branch/master/singlehtml/_images/anaconda-navigator-jupyterlab.png differ diff --git a/branch/master/singlehtml/_images/anaconda-prompt.png b/branch/master/singlehtml/_images/anaconda-prompt.png new file mode 100644 index 00000000..e4fcf79b Binary files /dev/null and b/branch/master/singlehtml/_images/anaconda-prompt.png differ diff --git a/branch/master/singlehtml/_images/binder.jpg b/branch/master/singlehtml/_images/binder.jpg new file mode 100644 index 00000000..d04c467d Binary files /dev/null and b/branch/master/singlehtml/_images/binder.jpg differ diff --git a/branch/master/singlehtml/_images/chatgpt.png b/branch/master/singlehtml/_images/chatgpt.png new file mode 100644 index 00000000..67948010 Binary files /dev/null and b/branch/master/singlehtml/_images/chatgpt.png differ diff --git a/branch/master/singlehtml/_images/code-completion.gif b/branch/master/singlehtml/_images/code-completion.gif new file mode 100644 index 00000000..e0bed42f Binary files /dev/null and b/branch/master/singlehtml/_images/code-completion.gif differ diff --git a/branch/master/singlehtml/_images/exercise.png b/branch/master/singlehtml/_images/exercise.png new file mode 100644 index 00000000..6bfedfb4 Binary files /dev/null and b/branch/master/singlehtml/_images/exercise.png differ diff --git a/branch/master/singlehtml/_images/exercise1.png b/branch/master/singlehtml/_images/exercise1.png new file mode 100644 index 00000000..ddfe4352 Binary files /dev/null and b/branch/master/singlehtml/_images/exercise1.png differ diff --git a/branch/master/singlehtml/_images/gapminder-larger-font.png b/branch/master/singlehtml/_images/gapminder-larger-font.png new file mode 100644 index 00000000..cf7270ef Binary files /dev/null and b/branch/master/singlehtml/_images/gapminder-larger-font.png differ diff --git a/branch/master/singlehtml/_images/gapminder-linear.png b/branch/master/singlehtml/_images/gapminder-linear.png new file mode 100644 index 00000000..78b30e77 Binary files /dev/null and b/branch/master/singlehtml/_images/gapminder-linear.png differ diff --git a/branch/master/singlehtml/_images/gapminder-log.png b/branch/master/singlehtml/_images/gapminder-log.png new file mode 100644 index 00000000..7b6c3208 Binary files /dev/null and b/branch/master/singlehtml/_images/gapminder-log.png differ diff --git a/branch/master/singlehtml/_images/getting-started.png b/branch/master/singlehtml/_images/getting-started.png new file mode 100644 index 00000000..8690a86f Binary files /dev/null and b/branch/master/singlehtml/_images/getting-started.png differ diff --git a/branch/master/singlehtml/_images/jupyterlab-notebook.png b/branch/master/singlehtml/_images/jupyterlab-notebook.png new file mode 100644 index 00000000..900fdfd9 Binary files /dev/null and b/branch/master/singlehtml/_images/jupyterlab-notebook.png differ diff --git a/branch/master/singlehtml/_images/jupyterlab-terminal.png b/branch/master/singlehtml/_images/jupyterlab-terminal.png new file mode 100644 index 00000000..33a6b02a Binary files /dev/null and b/branch/master/singlehtml/_images/jupyterlab-terminal.png differ diff --git a/branch/master/singlehtml/_images/main-ui.png b/branch/master/singlehtml/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/branch/master/singlehtml/_images/main-ui.png differ diff --git a/branch/master/singlehtml/_images/notebook-ui.png b/branch/master/singlehtml/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/branch/master/singlehtml/_images/notebook-ui.png differ diff --git a/branch/master/singlehtml/_images/precipitation-on-top-yearmonth.svg b/branch/master/singlehtml/_images/precipitation-on-top-yearmonth.svg new file mode 100644 index 00000000..40a99519 --- /dev/null +++ b/branch/master/singlehtml/_images/precipitation-on-top-yearmonth.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)050100150200250300350precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/precipitation-on-top.svg b/branch/master/singlehtml/_images/precipitation-on-top.svg new file mode 100644 index 00000000..a977ebc6 --- /dev/null +++ b/branch/master/singlehtml/_images/precipitation-on-top.svg @@ -0,0 +1 @@ +OctoberNovemberDecember2023FebruaryMarchAprilMayJuneJulyAugustSeptemberOctoberdate050100150200250300350precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/precipitation-side.svg b/branch/master/singlehtml/_images/precipitation-side.svg new file mode 100644 index 00000000..095c23bd --- /dev/null +++ b/branch/master/singlehtml/_images/precipitation-side.svg @@ -0,0 +1 @@ +name050100150200250precipitationOslo - BlindernTromso - LangnesOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/precipitation-stacked-x.svg b/branch/master/singlehtml/_images/precipitation-stacked-x.svg new file mode 100644 index 00000000..c0992433 --- /dev/null +++ b/branch/master/singlehtml/_images/precipitation-stacked-x.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)050100150200250precipitationOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/precipitation-stacked-y.svg b/branch/master/singlehtml/_images/precipitation-stacked-y.svg new file mode 100644 index 00000000..78092adf --- /dev/null +++ b/branch/master/singlehtml/_images/precipitation-stacked-y.svg @@ -0,0 +1 @@ +050100150200250precipitationOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023Nov 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/python_unmasked.jpg b/branch/master/singlehtml/_images/python_unmasked.jpg new file mode 100644 index 00000000..57e3cc47 Binary files /dev/null and b/branch/master/singlehtml/_images/python_unmasked.jpg differ diff --git a/branch/master/singlehtml/_images/snow-depth-circles.svg b/branch/master/singlehtml/_images/snow-depth-circles.svg new file mode 100644 index 00000000..c54504ed --- /dev/null +++ b/branch/master/singlehtml/_images/snow-depth-circles.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - Langnes2023FebruaryMarchAprildate2023FebruaryMarchAprildate−5051015max temperature \ No newline at end of file diff --git a/branch/master/singlehtml/_images/snow-depth-color.svg b/branch/master/singlehtml/_images/snow-depth-color.svg new file mode 100644 index 00000000..7a821dd4 --- /dev/null +++ b/branch/master/singlehtml/_images/snow-depth-color.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate−5051015max temperature \ No newline at end of file diff --git a/branch/master/singlehtml/_images/snow-depth-plasma.svg b/branch/master/singlehtml/_images/snow-depth-plasma.svg new file mode 100644 index 00000000..d5ec8d5e --- /dev/null +++ b/branch/master/singlehtml/_images/snow-depth-plasma.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate−5051015max temperature \ No newline at end of file diff --git a/branch/master/singlehtml/_images/snow-depth.svg b/branch/master/singlehtml/_images/snow-depth.svg new file mode 100644 index 00000000..75581931 --- /dev/null +++ b/branch/master/singlehtml/_images/snow-depth.svg @@ -0,0 +1 @@ +name020406080100120snow depthOslo - BlindernTromso - LangnesDecember2023FebruaryMarchAprilMaydateDecember2023FebruaryMarchAprilMaydate \ No newline at end of file diff --git a/branch/master/singlehtml/_images/temperature-ranges-combined.svg b/branch/master/singlehtml/_images/temperature-ranges-combined.svg new file mode 100644 index 00000000..abc39623 --- /dev/null +++ b/branch/master/singlehtml/_images/temperature-ranges-combined.svg @@ -0,0 +1 @@ +Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)−20−15−10−505101520253035max temperature, min temperatureOslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/temperature-ranges-side.svg b/branch/master/singlehtml/_images/temperature-ranges-side.svg new file mode 100644 index 00000000..aa67e29e --- /dev/null +++ b/branch/master/singlehtml/_images/temperature-ranges-side.svg @@ -0,0 +1 @@ +name−20−15−10−505101520253035max temperature, min temperatureOslo - BlindernTromso - LangnesOct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)Oct 2022Nov 2022Dec 2022Jan 2023Feb 2023Mar 2023Apr 2023May 2023Jun 2023Jul 2023Aug 2023Sep 2023Oct 2023date (year-month)Oslo - BlindernTromso - Langnesname \ No newline at end of file diff --git a/branch/master/singlehtml/_images/tidy_data.png b/branch/master/singlehtml/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/branch/master/singlehtml/_images/tidy_data.png differ diff --git a/branch/master/singlehtml/_images/xarray_1d_plot.png b/branch/master/singlehtml/_images/xarray_1d_plot.png new file mode 100644 index 00000000..0e0b6a79 Binary files /dev/null and b/branch/master/singlehtml/_images/xarray_1d_plot.png differ diff --git a/branch/master/singlehtml/_images/xarray_2d_plot.png b/branch/master/singlehtml/_images/xarray_2d_plot.png new file mode 100644 index 00000000..15afca26 Binary files /dev/null and b/branch/master/singlehtml/_images/xarray_2d_plot.png differ diff --git a/branch/master/singlehtml/_images/xarray_dataset_image.png b/branch/master/singlehtml/_images/xarray_dataset_image.png new file mode 100644 index 00000000..e3556dea Binary files /dev/null and b/branch/master/singlehtml/_images/xarray_dataset_image.png differ diff --git a/branch/master/singlehtml/_images/xarray_hist.png b/branch/master/singlehtml/_images/xarray_hist.png new file mode 100644 index 00000000..de6b24b6 Binary files /dev/null and b/branch/master/singlehtml/_images/xarray_hist.png differ diff --git a/branch/master/singlehtml/_static/_sphinx_javascript_frameworks_compat.js b/branch/master/singlehtml/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..81415803 --- /dev/null +++ b/branch/master/singlehtml/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,123 @@ +/* Compatability shim for jQuery and underscores.js. + * + * Copyright Sphinx contributors + * Released under the two clause BSD licence + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/branch/master/singlehtml/_static/basic.css b/branch/master/singlehtml/_static/basic.css new file mode 100644 index 00000000..f316efcb --- /dev/null +++ b/branch/master/singlehtml/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/branch/master/singlehtml/_static/check-solid.svg b/branch/master/singlehtml/_static/check-solid.svg new file mode 100644 index 00000000..92fad4b5 --- /dev/null +++ b/branch/master/singlehtml/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/branch/master/singlehtml/_static/clipboard.min.js b/branch/master/singlehtml/_static/clipboard.min.js new file mode 100644 index 00000000..54b3c463 --- /dev/null +++ b/branch/master/singlehtml/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/branch/master/singlehtml/_static/copybutton.css b/branch/master/singlehtml/_static/copybutton.css new file mode 100644 index 00000000..f1916ec7 --- /dev/null +++ b/branch/master/singlehtml/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/branch/master/singlehtml/_static/copybutton.js b/branch/master/singlehtml/_static/copybutton.js new file mode 100644 index 00000000..b3987037 --- /dev/null +++ b/branch/master/singlehtml/_static/copybutton.js @@ -0,0 +1,248 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copier dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = ``; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = 'div.highlight pre'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} + + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '.linenos, .gp'; + + let text = filterText(target, exclude); + return formatCopyText(text, '', false, true, true, true, '', '') +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) \ No newline at end of file diff --git a/branch/master/singlehtml/_static/copybutton_funcs.js b/branch/master/singlehtml/_static/copybutton_funcs.js new file mode 100644 index 00000000..dbe1aaad --- /dev/null +++ b/branch/master/singlehtml/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/branch/master/singlehtml/_static/css/badge_only.css b/branch/master/singlehtml/_static/css/badge_only.css new file mode 100644 index 00000000..88ba55b9 --- /dev/null +++ b/branch/master/singlehtml/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px} \ No newline at end of file diff --git a/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Bold.woff b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Bold.woff2 b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Regular.woff b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Regular.woff2 b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.eot b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.svg b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.ttf b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.woff b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.woff2 b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-bold-italic.woff b/branch/master/singlehtml/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-bold-italic.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-bold-italic.woff2 b/branch/master/singlehtml/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-bold.woff b/branch/master/singlehtml/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-bold.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-bold.woff2 b/branch/master/singlehtml/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-bold.woff2 differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-normal-italic.woff b/branch/master/singlehtml/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-normal-italic.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-normal-italic.woff2 b/branch/master/singlehtml/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-normal.woff b/branch/master/singlehtml/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-normal.woff differ diff --git a/branch/master/singlehtml/_static/css/fonts/lato-normal.woff2 b/branch/master/singlehtml/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/master/singlehtml/_static/css/fonts/lato-normal.woff2 differ diff --git a/branch/master/singlehtml/_static/css/theme.css b/branch/master/singlehtml/_static/css/theme.css new file mode 100644 index 00000000..0f14f106 --- /dev/null +++ b/branch/master/singlehtml/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search .wy-dropdown>aactive,.wy-side-nav-search .wy-dropdown>afocus,.wy-side-nav-search>a:hover,.wy-side-nav-search>aactive,.wy-side-nav-search>afocus{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon,.wy-side-nav-search>a.icon{display:block}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.switch-menus{position:relative;display:block;margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-side-nav-search>div.switch-menus>div.language-switch,.wy-side-nav-search>div.switch-menus>div.version-switch{display:inline-block;padding:.2em}.wy-side-nav-search>div.switch-menus>div.language-switch select,.wy-side-nav-search>div.switch-menus>div.version-switch select{display:inline-block;margin-right:-2rem;padding-right:2rem;max-width:240px;text-align-last:center;background:none;border:none;border-radius:0;box-shadow:none;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-size:1em;font-weight:400;color:hsla(0,0%,100%,.3);cursor:pointer;appearance:none;-webkit-appearance:none;-moz-appearance:none}.wy-side-nav-search>div.switch-menus>div.language-switch select:active,.wy-side-nav-search>div.switch-menus>div.language-switch select:focus,.wy-side-nav-search>div.switch-menus>div.language-switch select:hover,.wy-side-nav-search>div.switch-menus>div.version-switch select:active,.wy-side-nav-search>div.switch-menus>div.version-switch select:focus,.wy-side-nav-search>div.switch-menus>div.version-switch select:hover{background:hsla(0,0%,100%,.1);color:hsla(0,0%,100%,.5)}.wy-side-nav-search>div.switch-menus>div.language-switch select option,.wy-side-nav-search>div.switch-menus>div.version-switch select option{color:#000}.wy-side-nav-search>div.switch-menus>div.language-switch:has(>select):after,.wy-side-nav-search>div.switch-menus>div.version-switch:has(>select):after{display:inline-block;width:1.5em;height:100%;padding:.1em;content:"\f0d7";font-size:1em;line-height:1.2em;font-family:FontAwesome;text-align:center;pointer-events:none;box-sizing:border-box}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel,.rst-content .menuselection{font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .guilabel,.rst-content .menuselection{border:1px solid #7fbbe3;background:#e7f2fa}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/branch/master/singlehtml/_static/doctools.js b/branch/master/singlehtml/_static/doctools.js new file mode 100644 index 00000000..4d67807d --- /dev/null +++ b/branch/master/singlehtml/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/branch/master/singlehtml/_static/documentation_options.js b/branch/master/singlehtml/_static/documentation_options.js new file mode 100644 index 00000000..89003c67 --- /dev/null +++ b/branch/master/singlehtml/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'singlehtml', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/branch/master/singlehtml/_static/file.png b/branch/master/singlehtml/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/branch/master/singlehtml/_static/file.png differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bold.eot b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.eot new file mode 100644 index 00000000..3361183a Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.eot differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bold.ttf b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.ttf new file mode 100644 index 00000000..29f691d5 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.ttf differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bold.woff b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.woff differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bold.woff2 b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bold.woff2 differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.eot b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.eot new file mode 100644 index 00000000..3d415493 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.eot differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.ttf b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.ttf new file mode 100644 index 00000000..f402040b Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.ttf differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.woff b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.woff differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.woff2 b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-bolditalic.woff2 differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-italic.eot b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.eot new file mode 100644 index 00000000..3f826421 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.eot differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-italic.ttf b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.ttf new file mode 100644 index 00000000..b4bfc9b2 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.ttf differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-italic.woff b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.woff differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-italic.woff2 b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-italic.woff2 differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-regular.eot b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.eot new file mode 100644 index 00000000..11e3f2a5 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.eot differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-regular.ttf b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.ttf new file mode 100644 index 00000000..74decd9e Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.ttf differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-regular.woff b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.woff differ diff --git a/branch/master/singlehtml/_static/fonts/Lato/lato-regular.woff2 b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/Lato/lato-regular.woff2 differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot new file mode 100644 index 00000000..79dc8efe Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf new file mode 100644 index 00000000..df5d1df2 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot new file mode 100644 index 00000000..2f7ca78a Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf new file mode 100644 index 00000000..eb52a790 Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff differ diff --git a/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/master/singlehtml/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 differ diff --git a/branch/master/singlehtml/_static/jquery.js b/branch/master/singlehtml/_static/jquery.js new file mode 100644 index 00000000..c4c6022f --- /dev/null +++ b/branch/master/singlehtml/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0
"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t +
Languages
+ ${config.projects.translations + .map( + (translation) => ` +
+ ${translation.language.code} +
+ `, + ) + .join("\n")} + + `; + return languagesHTML; + } + + function renderVersions(config) { + if (!config.versions.active.length) { + return ""; + } + const versionsHTML = ` +
+
Versions
+ ${config.versions.active + .map( + (version) => ` +
+ ${version.slug} +
+ `, + ) + .join("\n")} +
+ `; + return versionsHTML; + } + + function renderDownloads(config) { + if (!Object.keys(config.versions.current.downloads).length) { + return ""; + } + const downloadsNameDisplay = { + pdf: "PDF", + epub: "Epub", + htmlzip: "HTML", + }; + + const downloadsHTML = ` +
+
Downloads
+ ${Object.entries(config.versions.current.downloads) + .map( + ([name, url]) => ` +
+ ${downloadsNameDisplay[name]} +
+ `, + ) + .join("\n")} +
+ `; + return downloadsHTML; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const flyout = ` +
+ + Read the Docs + v: ${config.versions.current.slug} + + +
+
+ ${renderLanguages(config)} + ${renderVersions(config)} + ${renderDownloads(config)} +
+
On Read the Docs
+
+ Project Home +
+
+ Builds +
+
+ Downloads +
+
+
+
Search
+
+
+ +
+
+
+
+ + Hosted by Read the Docs + +
+
+ `; + + // Inject the generated flyout into the body HTML element. + document.body.insertAdjacentHTML("beforeend", flyout); + + // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout. + document + .querySelector("#flyout-search-form") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + }) +} + +if (themeLanguageSelector || themeVersionSelector) { + function onSelectorSwitch(event) { + const option = event.target.selectedIndex; + const item = event.target.options[option]; + window.location.href = item.dataset.url; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const versionSwitch = document.querySelector( + "div.switch-menus > div.version-switch", + ); + if (themeVersionSelector) { + let versions = config.versions.active; + if (config.versions.current.hidden || config.versions.current.type === "external") { + versions.unshift(config.versions.current); + } + const versionSelect = ` + + `; + + versionSwitch.innerHTML = versionSelect; + versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + + const languageSwitch = document.querySelector( + "div.switch-menus > div.language-switch", + ); + + if (themeLanguageSelector) { + if (config.projects.translations.length) { + // Add the current language to the options on the selector + let languages = config.projects.translations.concat( + config.projects.current, + ); + languages = languages.sort((a, b) => + a.language.name.localeCompare(b.language.name), + ); + + const languageSelect = ` + + `; + + languageSwitch.innerHTML = languageSelect; + languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + else { + languageSwitch.remove(); + } + } + }); +} + +document.addEventListener("readthedocs-addons-data-ready", function (event) { + // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. + document + .querySelector("[role='search'] input") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); +}); \ No newline at end of file diff --git a/branch/master/singlehtml/_static/language_data.js b/branch/master/singlehtml/_static/language_data.js new file mode 100644 index 00000000..367b8ed8 --- /dev/null +++ b/branch/master/singlehtml/_static/language_data.js @@ -0,0 +1,199 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/branch/master/singlehtml/_static/logo-hexagons-02-compact.svg.ico b/branch/master/singlehtml/_static/logo-hexagons-02-compact.svg.ico new file mode 100644 index 00000000..bafe8f98 Binary files /dev/null and b/branch/master/singlehtml/_static/logo-hexagons-02-compact.svg.ico differ diff --git a/branch/master/singlehtml/_static/minipres.js b/branch/master/singlehtml/_static/minipres.js new file mode 100644 index 00000000..ad11c871 --- /dev/null +++ b/branch/master/singlehtml/_static/minipres.js @@ -0,0 +1,223 @@ +// Add goTo method to elements +// http://stackoverflow.com/questions/4801655/how-to-go-to-a-specific-element-on-page +(function($) { + $.fn.goTo = function() { + $('html, body').animate({ + scrollTop: $(this).offset().top //+ 'px' + }, 'fast'); + return this; // for chaining... + } +})(jQuery); + +// NO good way to do this!. Copy a hack from here +// https://stackoverflow.com/questions/901115/how-can-i-get-query-string-values-in-javascript +// https://stackoverflow.com/a/2880929 +var urlParams; +(window.onpopstate = function () { + var match, + pl = /\+/g, // Regex for replacing addition symbol with a space + search = /([^&=]+)=?([^&]*)/g, + decode = function (s) { return decodeURIComponent(s.replace(pl, " ")); }, + query = window.location.search.substring(1); + urlParams = {}; + while (match = search.exec(query)) + urlParams[decode(match[1])] = decode(match[2]); +})(); + +// Select heading levels +var maxHeading = urlParams['h'] +if (maxHeading === undefined) maxHeading = 2 +var headingLevels = []; +for (h=2 ; h (sections.length-1) ) { + // if we would scroll past bottom, or above top, do nothing + return; + } + + console.log('xxxxxx'); + var targetSection = sections[targetPos]; + console.log(targetSection, typeof(targetSection)); + + // Return targetSection top and height + var secProperties = section_top_and_height(targetSection); + var top = secProperties['top']; + var height = secProperties['height'] + var win_height = window.innerHeight; + //console.info(top, height, win_height) + + var scroll_to = 0; + if (height >= win_height || height == 0) { + scroll_to = top; + } else { + scroll_to = top - (win_height-height)/3.; + } + //console.info(top, height, win_height, scroll_to) + + $('html, body').animate({ + scrollTop: scroll_to //+ 'px' + }, 'fast'); + +} + + +function minipres() { + /* Enable the minipres mode: + - call the hide() function + - set up the scrolling listener + */ + document.addEventListener('keydown', function (event) { + switch(event.which) { + case 37: // left + switch_slide(-1); + event.preventDefault(); + return false; + break; + //case 38: // up + case 39: // right + switch_slide(+1); + event.preventDefault(); + return false; + break; + //case 40: // down + default: + return; // exit this handler for other keys + } + }, true) + + hide() + + // Increase space between sections + //$("div .section").css('margin-bottom', '50%'); + $(sectionSelector).css('margin-top', '50%'); + + // Reduce size/color of other sections + if (hiddenSectionSelector.length > 0) { + var hideNodes = $(hiddenSectionSelector); + console.log(typeof hideNodes, hideNodes); + for (node in hideNodes) { + console.log("a", typeof node, node); + node = hideNodes[node]; // what's right way to iterate values? + console.log("b", typeof node, node); + if (node.parentNode && node.parentNode.className == "section") { + node = node.parentNode; + console.log("c", typeof node, node); + //node.css['transform'] = 'scale(.5)'; + //node.css['transform-origin'] = 'top center'; + $(node).css('color', 'lightgrey'); + //$(node).css('font-size', '20%'); + //$(node).css('visibility', 'collapse'); + //ntahousnatouhasno; + } + } + } +} + +function hide() { + /* Hide all non-essential elements on the page + */ + + // This is for sphinx_rst_theme and readthedocs + $(".wy-nav-side").remove(); + $(".wy-nav-content-wrap").css('margin-left', 0); + $('.rst-versions').remove(); // readthedocs version selector + + // Add other formats here. +} + + +var slideshow = minipres; + +if (window.location.search.match(/[?&](minipres|slideshow|pres)([=&]|$)/) ) { + //minipres() + window.addEventListener("load", minipres); +} else if (window.location.search.match(/[?&](plain)([=&]|$)/) ) { + window.addEventListener("load", hide); +} diff --git a/branch/master/singlehtml/_static/minus.png b/branch/master/singlehtml/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/branch/master/singlehtml/_static/minus.png differ diff --git a/branch/master/singlehtml/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css b/branch/master/singlehtml/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css new file mode 100644 index 00000000..33566310 --- /dev/null +++ b/branch/master/singlehtml/_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css @@ -0,0 +1,2342 @@ +/* Variables */ +:root { + --mystnb-source-bg-color: #f7f7f7; + --mystnb-stdout-bg-color: #fcfcfc; + --mystnb-stderr-bg-color: #fdd; + --mystnb-traceback-bg-color: #fcfcfc; + --mystnb-source-border-color: #ccc; + --mystnb-source-margin-color: green; + --mystnb-stdout-border-color: #f7f7f7; + --mystnb-stderr-border-color: #f7f7f7; + --mystnb-traceback-border-color: #ffd6d6; + --mystnb-hide-prompt-opacity: 70%; + --mystnb-source-border-radius: .4em; + --mystnb-source-border-width: 1px; +} + +/* Whole cell */ +div.container.cell { + padding-left: 0; + margin-bottom: 1em; +} + +/* Removing all background formatting so we can control at the div level */ +.cell_input div.highlight, +.cell_output pre, +.cell_input pre, +.cell_output .output { + border: none; + box-shadow: none; +} + +.cell_output .output pre, +.cell_input pre { + margin: 0px; +} + +/* Input cells */ +div.cell div.cell_input, +div.cell details.above-input>summary { + padding-left: 0em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + background-color: var(--mystnb-source-bg-color); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; + border-radius: var(--mystnb-source-border-radius); +} + +div.cell_input>div, +div.cell_output div.output>div.highlight { + margin: 0em !important; + border: none !important; +} + +/* All cell outputs */ +.cell_output { + padding-left: 1em; + padding-right: 0em; + margin-top: 1em; +} + +/* Text outputs from cells */ +.cell_output .output.text_plain, +.cell_output .output.traceback, +.cell_output .output.stream, +.cell_output .output.stderr { + margin-top: 1em; + margin-bottom: 0em; + box-shadow: none; +} + +.cell_output .output.text_plain, +.cell_output .output.stream { + background: var(--mystnb-stdout-bg-color); + border: 1px solid var(--mystnb-stdout-border-color); +} + +.cell_output .output.stderr { + background: var(--mystnb-stderr-bg-color); + border: 1px solid var(--mystnb-stderr-border-color); +} + +.cell_output .output.traceback { + background: var(--mystnb-traceback-bg-color); + border: 1px solid var(--mystnb-traceback-border-color); +} + +/* Collapsible cell content */ +div.cell details.above-input div.cell_input { + border-top-left-radius: 0; + border-top-right-radius: 0; + border-top: var(--mystnb-source-border-width) var(--mystnb-source-border-color) dashed; +} + +div.cell div.cell_input.above-output-prompt { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; +} + +div.cell details.above-input>summary { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; + border-bottom: var(--mystnb-source-border-width) var(--mystnb-source-border-color) dashed; + padding-left: 1em; + margin-bottom: 0; +} + +div.cell details.above-output>summary { + background-color: var(--mystnb-source-bg-color); + padding-left: 1em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + border-radius: var(--mystnb-source-border-radius); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; +} + +div.cell details.below-input>summary { + background-color: var(--mystnb-source-bg-color); + padding-left: 1em; + padding-right: 0em; + border: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; + border-top: none; + border-bottom-left-radius: var(--mystnb-source-border-radius); + border-bottom-right-radius: var(--mystnb-source-border-radius); + border-left-color: var(--mystnb-source-margin-color); + border-left-width: medium; +} + +div.cell details.hide>summary>span { + opacity: var(--mystnb-hide-prompt-opacity); +} + +div.cell details.hide[open]>summary>span.collapsed { + display: none; +} + +div.cell details.hide:not([open])>summary>span.expanded { + display: none; +} + +@keyframes collapsed-fade-in { + 0% { + opacity: 0; + } + + 100% { + opacity: 1; + } +} +div.cell details.hide[open]>summary~* { + -moz-animation: collapsed-fade-in 0.3s ease-in-out; + -webkit-animation: collapsed-fade-in 0.3s ease-in-out; + animation: collapsed-fade-in 0.3s ease-in-out; +} + +/* Math align to the left */ +.cell_output .MathJax_Display { + text-align: left !important; +} + +/* Pandas tables. Pulled from the Jupyter / nbsphinx CSS */ +div.cell_output table { + border: none; + border-collapse: collapse; + border-spacing: 0; + color: black; + font-size: 1em; + table-layout: fixed; +} + +div.cell_output thead { + border-bottom: 1px solid black; + vertical-align: bottom; +} + +div.cell_output tr, +div.cell_output th, +div.cell_output td { + text-align: right; + vertical-align: middle; + padding: 0.5em 0.5em; + line-height: normal; + white-space: normal; + max-width: none; + border: none; +} + +div.cell_output th { + font-weight: bold; +} + +div.cell_output tbody tr:nth-child(odd) { + background: #f5f5f5; +} + +div.cell_output tbody tr:hover { + background: rgba(66, 165, 245, 0.2); +} + +/** source code line numbers **/ +span.linenos { + opacity: 0.5; +} + +/* Inline text from `paste` operation */ + +span.pasted-text { + font-weight: bold; +} + +span.pasted-inline img { + max-height: 2em; +} + +tbody span.pasted-inline img { + max-height: none; +} + +/* Font colors for translated ANSI escape sequences +Color values are copied from Jupyter Notebook +https://github.com/jupyter/notebook/blob/52581f8eda9b319eb0390ac77fe5903c38f81e3e/notebook/static/notebook/less/ansicolors.less#L14-L21 +Background colors from +https://nbsphinx.readthedocs.io/en/latest/code-cells.html#ANSI-Colors +*/ +div.highlight .-Color-Bold { + font-weight: bold; +} + +div.highlight .-Color[class*=-Black] { + color: #3E424D +} + +div.highlight .-Color[class*=-Red] { + color: #E75C58 +} + +div.highlight .-Color[class*=-Green] { + color: #00A250 +} + +div.highlight .-Color[class*=-Yellow] { + color: #DDB62B +} + +div.highlight .-Color[class*=-Blue] { + color: #208FFB +} + +div.highlight .-Color[class*=-Magenta] { + color: #D160C4 +} + +div.highlight .-Color[class*=-Cyan] { + color: #60C6C8 +} + +div.highlight .-Color[class*=-White] { + color: #C5C1B4 +} + +div.highlight .-Color[class*=-BGBlack] { + background-color: #3E424D +} + +div.highlight .-Color[class*=-BGRed] { + background-color: #E75C58 +} + +div.highlight .-Color[class*=-BGGreen] { + background-color: #00A250 +} + +div.highlight .-Color[class*=-BGYellow] { + background-color: #DDB62B +} + +div.highlight .-Color[class*=-BGBlue] { + background-color: #208FFB +} + +div.highlight .-Color[class*=-BGMagenta] { + background-color: #D160C4 +} + +div.highlight .-Color[class*=-BGCyan] { + background-color: #60C6C8 +} + +div.highlight .-Color[class*=-BGWhite] { + background-color: #C5C1B4 +} + +/* Font colors for 8-bit ANSI */ + +div.highlight .-Color[class*=-C0] { + color: #000000 +} + +div.highlight .-Color[class*=-BGC0] { + background-color: #000000 +} + +div.highlight .-Color[class*=-C1] { + color: #800000 +} + +div.highlight .-Color[class*=-BGC1] { + background-color: #800000 +} + +div.highlight .-Color[class*=-C2] { + color: #008000 +} + +div.highlight .-Color[class*=-BGC2] { + background-color: #008000 +} + +div.highlight .-Color[class*=-C3] { + color: #808000 +} + +div.highlight .-Color[class*=-BGC3] { + background-color: #808000 +} + +div.highlight .-Color[class*=-C4] { + color: #000080 +} + +div.highlight .-Color[class*=-BGC4] { + background-color: #000080 +} + +div.highlight .-Color[class*=-C5] { + color: #800080 +} + +div.highlight .-Color[class*=-BGC5] { + background-color: #800080 +} + +div.highlight .-Color[class*=-C6] { + color: #008080 +} + +div.highlight .-Color[class*=-BGC6] { + background-color: #008080 +} + +div.highlight .-Color[class*=-C7] { + color: #C0C0C0 +} + +div.highlight .-Color[class*=-BGC7] { + background-color: #C0C0C0 +} + +div.highlight .-Color[class*=-C8] { + color: #808080 +} + +div.highlight .-Color[class*=-BGC8] { + background-color: #808080 +} + +div.highlight .-Color[class*=-C9] { + color: #FF0000 +} + +div.highlight .-Color[class*=-BGC9] { + background-color: #FF0000 +} + +div.highlight .-Color[class*=-C10] { + color: #00FF00 +} + +div.highlight .-Color[class*=-BGC10] { + background-color: #00FF00 +} + +div.highlight .-Color[class*=-C11] { + color: #FFFF00 +} + +div.highlight .-Color[class*=-BGC11] { + background-color: #FFFF00 +} + +div.highlight .-Color[class*=-C12] { + color: #0000FF +} + +div.highlight .-Color[class*=-BGC12] { + background-color: #0000FF +} + +div.highlight .-Color[class*=-C13] { + color: #FF00FF +} + +div.highlight .-Color[class*=-BGC13] { + background-color: #FF00FF +} + +div.highlight .-Color[class*=-C14] { + color: #00FFFF +} + +div.highlight .-Color[class*=-BGC14] { + background-color: #00FFFF +} + +div.highlight .-Color[class*=-C15] { + color: #FFFFFF +} + +div.highlight .-Color[class*=-BGC15] { + background-color: #FFFFFF +} + +div.highlight .-Color[class*=-C16] { + color: #000000 +} + +div.highlight .-Color[class*=-BGC16] { + background-color: #000000 +} + +div.highlight .-Color[class*=-C17] { + color: #00005F +} + +div.highlight .-Color[class*=-BGC17] { + background-color: #00005F +} + +div.highlight .-Color[class*=-C18] { + color: #000087 +} + +div.highlight .-Color[class*=-BGC18] { + background-color: #000087 +} + +div.highlight .-Color[class*=-C19] { + color: #0000AF +} + +div.highlight .-Color[class*=-BGC19] { + background-color: #0000AF +} + +div.highlight .-Color[class*=-C20] { + color: #0000D7 +} + +div.highlight .-Color[class*=-BGC20] { + background-color: #0000D7 +} + +div.highlight .-Color[class*=-C21] { + color: #0000FF +} + +div.highlight .-Color[class*=-BGC21] { + background-color: #0000FF +} + +div.highlight .-Color[class*=-C22] { + color: #005F00 +} + +div.highlight .-Color[class*=-BGC22] { + background-color: #005F00 +} + +div.highlight .-Color[class*=-C23] { + color: #005F5F +} + +div.highlight .-Color[class*=-BGC23] { + background-color: #005F5F +} + +div.highlight .-Color[class*=-C24] { + color: #005F87 +} + +div.highlight .-Color[class*=-BGC24] { + background-color: #005F87 +} + +div.highlight .-Color[class*=-C25] { + color: #005FAF +} + +div.highlight .-Color[class*=-BGC25] { + background-color: #005FAF +} + +div.highlight .-Color[class*=-C26] { + color: #005FD7 +} + +div.highlight .-Color[class*=-BGC26] { + background-color: #005FD7 +} + +div.highlight .-Color[class*=-C27] { + color: #005FFF +} + +div.highlight .-Color[class*=-BGC27] { + background-color: #005FFF +} + +div.highlight .-Color[class*=-C28] { + color: #008700 +} + +div.highlight .-Color[class*=-BGC28] { + background-color: #008700 +} + +div.highlight .-Color[class*=-C29] { + color: #00875F +} + +div.highlight .-Color[class*=-BGC29] { + background-color: #00875F +} + +div.highlight .-Color[class*=-C30] { + color: #008787 +} + +div.highlight .-Color[class*=-BGC30] { + background-color: #008787 +} + +div.highlight .-Color[class*=-C31] { + color: #0087AF +} + +div.highlight .-Color[class*=-BGC31] { + background-color: #0087AF +} + +div.highlight .-Color[class*=-C32] { + color: #0087D7 +} + +div.highlight .-Color[class*=-BGC32] { + background-color: #0087D7 +} + +div.highlight .-Color[class*=-C33] { + color: #0087FF +} + +div.highlight .-Color[class*=-BGC33] { + background-color: #0087FF +} + +div.highlight .-Color[class*=-C34] { + color: #00AF00 +} + +div.highlight .-Color[class*=-BGC34] { + background-color: #00AF00 +} + +div.highlight .-Color[class*=-C35] { + color: #00AF5F +} + +div.highlight .-Color[class*=-BGC35] { + background-color: #00AF5F +} + +div.highlight .-Color[class*=-C36] { + color: #00AF87 +} + +div.highlight .-Color[class*=-BGC36] { + background-color: #00AF87 +} + +div.highlight .-Color[class*=-C37] { + color: #00AFAF +} + +div.highlight .-Color[class*=-BGC37] { + background-color: #00AFAF +} + +div.highlight .-Color[class*=-C38] { + color: #00AFD7 +} + +div.highlight .-Color[class*=-BGC38] { + background-color: #00AFD7 +} + +div.highlight .-Color[class*=-C39] { + color: #00AFFF +} + +div.highlight .-Color[class*=-BGC39] { + background-color: #00AFFF +} + +div.highlight .-Color[class*=-C40] { + color: #00D700 +} + +div.highlight .-Color[class*=-BGC40] { + background-color: #00D700 +} + +div.highlight .-Color[class*=-C41] { + color: #00D75F +} + +div.highlight .-Color[class*=-BGC41] { + background-color: #00D75F +} + +div.highlight .-Color[class*=-C42] { + color: #00D787 +} + +div.highlight .-Color[class*=-BGC42] { + background-color: #00D787 +} + +div.highlight .-Color[class*=-C43] { + color: #00D7AF +} + +div.highlight .-Color[class*=-BGC43] { + background-color: #00D7AF +} + +div.highlight .-Color[class*=-C44] { + color: #00D7D7 +} + +div.highlight .-Color[class*=-BGC44] { + background-color: #00D7D7 +} + +div.highlight .-Color[class*=-C45] { + color: #00D7FF +} + +div.highlight .-Color[class*=-BGC45] { + background-color: #00D7FF +} + +div.highlight .-Color[class*=-C46] { + color: #00FF00 +} + +div.highlight .-Color[class*=-BGC46] { + background-color: #00FF00 +} + +div.highlight .-Color[class*=-C47] { + color: #00FF5F +} + +div.highlight .-Color[class*=-BGC47] { + background-color: #00FF5F +} + +div.highlight .-Color[class*=-C48] { + color: #00FF87 +} + +div.highlight .-Color[class*=-BGC48] { + background-color: #00FF87 +} + +div.highlight .-Color[class*=-C49] { + color: #00FFAF +} + +div.highlight .-Color[class*=-BGC49] { + background-color: #00FFAF +} + +div.highlight .-Color[class*=-C50] { + color: #00FFD7 +} + +div.highlight .-Color[class*=-BGC50] { + background-color: #00FFD7 +} + +div.highlight .-Color[class*=-C51] { + color: #00FFFF +} + +div.highlight .-Color[class*=-BGC51] { + background-color: #00FFFF +} + +div.highlight .-Color[class*=-C52] { + color: #5F0000 +} + +div.highlight .-Color[class*=-BGC52] { + background-color: #5F0000 +} + +div.highlight .-Color[class*=-C53] { + color: #5F005F +} + +div.highlight .-Color[class*=-BGC53] { + background-color: #5F005F +} + +div.highlight .-Color[class*=-C54] { + color: #5F0087 +} + +div.highlight .-Color[class*=-BGC54] { + background-color: #5F0087 +} + +div.highlight .-Color[class*=-C55] { + color: #5F00AF +} + +div.highlight .-Color[class*=-BGC55] { + background-color: #5F00AF +} + +div.highlight .-Color[class*=-C56] { + color: #5F00D7 +} + +div.highlight .-Color[class*=-BGC56] { + background-color: #5F00D7 +} + +div.highlight .-Color[class*=-C57] { + color: #5F00FF +} + +div.highlight .-Color[class*=-BGC57] { + background-color: #5F00FF +} + +div.highlight .-Color[class*=-C58] { + color: #5F5F00 +} + +div.highlight .-Color[class*=-BGC58] { + background-color: #5F5F00 +} + +div.highlight .-Color[class*=-C59] { + color: #5F5F5F +} + +div.highlight .-Color[class*=-BGC59] { + background-color: #5F5F5F +} + +div.highlight .-Color[class*=-C60] { + color: #5F5F87 +} + +div.highlight .-Color[class*=-BGC60] { + background-color: #5F5F87 +} + +div.highlight .-Color[class*=-C61] { + color: #5F5FAF +} + +div.highlight .-Color[class*=-BGC61] { + background-color: #5F5FAF +} + +div.highlight .-Color[class*=-C62] { + color: #5F5FD7 +} + +div.highlight .-Color[class*=-BGC62] { + background-color: #5F5FD7 +} + +div.highlight .-Color[class*=-C63] { + color: #5F5FFF +} + +div.highlight .-Color[class*=-BGC63] { + background-color: #5F5FFF +} + +div.highlight .-Color[class*=-C64] { + color: #5F8700 +} + +div.highlight .-Color[class*=-BGC64] { + background-color: #5F8700 +} + +div.highlight .-Color[class*=-C65] { + color: #5F875F +} + +div.highlight .-Color[class*=-BGC65] { + background-color: #5F875F +} + +div.highlight .-Color[class*=-C66] { + color: #5F8787 +} + +div.highlight .-Color[class*=-BGC66] { + background-color: #5F8787 +} + +div.highlight .-Color[class*=-C67] { + color: #5F87AF +} + +div.highlight .-Color[class*=-BGC67] { + background-color: #5F87AF +} + +div.highlight .-Color[class*=-C68] { + color: #5F87D7 +} + +div.highlight .-Color[class*=-BGC68] { + background-color: #5F87D7 +} + +div.highlight .-Color[class*=-C69] { + color: #5F87FF +} + +div.highlight .-Color[class*=-BGC69] { + background-color: #5F87FF +} + +div.highlight .-Color[class*=-C70] { + color: #5FAF00 +} + +div.highlight .-Color[class*=-BGC70] { + background-color: #5FAF00 +} + +div.highlight .-Color[class*=-C71] { + color: #5FAF5F +} + +div.highlight .-Color[class*=-BGC71] { + background-color: #5FAF5F +} + +div.highlight .-Color[class*=-C72] { + color: #5FAF87 +} + +div.highlight .-Color[class*=-BGC72] { + background-color: #5FAF87 +} + +div.highlight .-Color[class*=-C73] { + color: #5FAFAF +} + +div.highlight .-Color[class*=-BGC73] { + background-color: #5FAFAF +} + +div.highlight .-Color[class*=-C74] { + color: #5FAFD7 +} + +div.highlight .-Color[class*=-BGC74] { + background-color: #5FAFD7 +} + +div.highlight .-Color[class*=-C75] { + color: #5FAFFF +} + +div.highlight .-Color[class*=-BGC75] { + background-color: #5FAFFF +} + +div.highlight .-Color[class*=-C76] { + color: #5FD700 +} + +div.highlight .-Color[class*=-BGC76] { + background-color: #5FD700 +} + +div.highlight .-Color[class*=-C77] { + color: #5FD75F +} + +div.highlight .-Color[class*=-BGC77] { + background-color: #5FD75F +} + +div.highlight .-Color[class*=-C78] { + color: #5FD787 +} + +div.highlight .-Color[class*=-BGC78] { + background-color: #5FD787 +} + +div.highlight .-Color[class*=-C79] { + color: #5FD7AF +} + +div.highlight .-Color[class*=-BGC79] { + background-color: #5FD7AF +} + +div.highlight .-Color[class*=-C80] { + color: #5FD7D7 +} + +div.highlight .-Color[class*=-BGC80] { + background-color: #5FD7D7 +} + +div.highlight .-Color[class*=-C81] { + color: #5FD7FF +} + +div.highlight .-Color[class*=-BGC81] { + background-color: #5FD7FF +} + +div.highlight .-Color[class*=-C82] { + color: #5FFF00 +} + +div.highlight .-Color[class*=-BGC82] { + background-color: #5FFF00 +} + +div.highlight .-Color[class*=-C83] { + color: #5FFF5F +} + +div.highlight .-Color[class*=-BGC83] { + background-color: #5FFF5F +} + +div.highlight .-Color[class*=-C84] { + color: #5FFF87 +} + +div.highlight .-Color[class*=-BGC84] { + background-color: #5FFF87 +} + +div.highlight .-Color[class*=-C85] { + color: #5FFFAF +} + +div.highlight .-Color[class*=-BGC85] { + background-color: #5FFFAF +} + +div.highlight .-Color[class*=-C86] { + color: #5FFFD7 +} + +div.highlight .-Color[class*=-BGC86] { + background-color: #5FFFD7 +} + +div.highlight .-Color[class*=-C87] { + color: #5FFFFF +} + +div.highlight .-Color[class*=-BGC87] { + background-color: #5FFFFF +} + +div.highlight .-Color[class*=-C88] { + color: #870000 +} + +div.highlight .-Color[class*=-BGC88] { + background-color: #870000 +} + +div.highlight .-Color[class*=-C89] { + color: #87005F +} + +div.highlight .-Color[class*=-BGC89] { + background-color: #87005F +} + +div.highlight .-Color[class*=-C90] { + color: #870087 +} + +div.highlight .-Color[class*=-BGC90] { + background-color: #870087 +} + +div.highlight .-Color[class*=-C91] { + color: #8700AF +} + +div.highlight .-Color[class*=-BGC91] { + background-color: #8700AF +} + +div.highlight .-Color[class*=-C92] { + color: #8700D7 +} + +div.highlight .-Color[class*=-BGC92] { + background-color: #8700D7 +} + +div.highlight .-Color[class*=-C93] { + color: #8700FF +} + +div.highlight .-Color[class*=-BGC93] { + background-color: #8700FF +} + +div.highlight .-Color[class*=-C94] { + color: #875F00 +} + +div.highlight .-Color[class*=-BGC94] { + background-color: #875F00 +} + +div.highlight .-Color[class*=-C95] { + color: #875F5F +} + +div.highlight .-Color[class*=-BGC95] { + background-color: #875F5F +} + +div.highlight .-Color[class*=-C96] { + color: #875F87 +} + +div.highlight .-Color[class*=-BGC96] { + background-color: #875F87 +} + +div.highlight .-Color[class*=-C97] { + color: #875FAF +} + +div.highlight .-Color[class*=-BGC97] { + background-color: #875FAF +} + +div.highlight .-Color[class*=-C98] { + color: #875FD7 +} + +div.highlight .-Color[class*=-BGC98] { + background-color: #875FD7 +} + +div.highlight .-Color[class*=-C99] { + color: #875FFF +} + +div.highlight .-Color[class*=-BGC99] { + background-color: #875FFF +} + +div.highlight .-Color[class*=-C100] { + color: #878700 +} + +div.highlight .-Color[class*=-BGC100] { + background-color: #878700 +} + +div.highlight .-Color[class*=-C101] { + color: #87875F +} + +div.highlight .-Color[class*=-BGC101] { + background-color: #87875F +} + +div.highlight .-Color[class*=-C102] { + color: #878787 +} + +div.highlight .-Color[class*=-BGC102] { + background-color: #878787 +} + +div.highlight .-Color[class*=-C103] { + color: #8787AF +} + +div.highlight .-Color[class*=-BGC103] { + background-color: #8787AF +} + +div.highlight .-Color[class*=-C104] { + color: #8787D7 +} + +div.highlight .-Color[class*=-BGC104] { + background-color: #8787D7 +} + +div.highlight .-Color[class*=-C105] { + color: #8787FF +} + +div.highlight .-Color[class*=-BGC105] { + background-color: #8787FF +} + +div.highlight .-Color[class*=-C106] { + color: #87AF00 +} + +div.highlight .-Color[class*=-BGC106] { + background-color: #87AF00 +} + +div.highlight .-Color[class*=-C107] { + color: #87AF5F +} + +div.highlight .-Color[class*=-BGC107] { + background-color: #87AF5F +} + +div.highlight .-Color[class*=-C108] { + color: #87AF87 +} + +div.highlight .-Color[class*=-BGC108] { + background-color: #87AF87 +} + +div.highlight .-Color[class*=-C109] { + color: #87AFAF +} + +div.highlight .-Color[class*=-BGC109] { + background-color: #87AFAF +} + +div.highlight .-Color[class*=-C110] { + color: #87AFD7 +} + +div.highlight .-Color[class*=-BGC110] { + background-color: #87AFD7 +} + +div.highlight .-Color[class*=-C111] { + color: #87AFFF +} + +div.highlight .-Color[class*=-BGC111] { + background-color: #87AFFF +} + +div.highlight .-Color[class*=-C112] { + color: #87D700 +} + +div.highlight .-Color[class*=-BGC112] { + background-color: #87D700 +} + +div.highlight .-Color[class*=-C113] { + color: #87D75F +} + +div.highlight .-Color[class*=-BGC113] { + background-color: #87D75F +} + +div.highlight .-Color[class*=-C114] { + color: #87D787 +} + +div.highlight .-Color[class*=-BGC114] { + background-color: #87D787 +} + +div.highlight .-Color[class*=-C115] { + color: #87D7AF +} + +div.highlight .-Color[class*=-BGC115] { + background-color: #87D7AF +} + +div.highlight .-Color[class*=-C116] { + color: #87D7D7 +} + +div.highlight .-Color[class*=-BGC116] { + background-color: #87D7D7 +} + +div.highlight .-Color[class*=-C117] { + color: #87D7FF +} + +div.highlight .-Color[class*=-BGC117] { + background-color: #87D7FF +} + +div.highlight .-Color[class*=-C118] { + color: #87FF00 +} + +div.highlight .-Color[class*=-BGC118] { + background-color: #87FF00 +} + +div.highlight .-Color[class*=-C119] { + color: #87FF5F +} + +div.highlight .-Color[class*=-BGC119] { + background-color: #87FF5F +} + +div.highlight .-Color[class*=-C120] { + color: #87FF87 +} + +div.highlight .-Color[class*=-BGC120] { + background-color: #87FF87 +} + +div.highlight .-Color[class*=-C121] { + color: #87FFAF +} + +div.highlight .-Color[class*=-BGC121] { + background-color: #87FFAF +} + +div.highlight .-Color[class*=-C122] { + color: #87FFD7 +} + +div.highlight .-Color[class*=-BGC122] { + background-color: #87FFD7 +} + +div.highlight .-Color[class*=-C123] { + color: #87FFFF +} + +div.highlight .-Color[class*=-BGC123] { + background-color: #87FFFF +} + +div.highlight .-Color[class*=-C124] { + color: #AF0000 +} + +div.highlight .-Color[class*=-BGC124] { + background-color: #AF0000 +} + +div.highlight .-Color[class*=-C125] { + color: #AF005F +} + +div.highlight .-Color[class*=-BGC125] { + background-color: #AF005F +} + +div.highlight .-Color[class*=-C126] { + color: #AF0087 +} + +div.highlight .-Color[class*=-BGC126] { + background-color: #AF0087 +} + +div.highlight .-Color[class*=-C127] { + color: #AF00AF +} + +div.highlight .-Color[class*=-BGC127] { + background-color: #AF00AF +} + +div.highlight .-Color[class*=-C128] { + color: #AF00D7 +} + +div.highlight .-Color[class*=-BGC128] { + background-color: #AF00D7 +} + +div.highlight .-Color[class*=-C129] { + color: #AF00FF +} + +div.highlight .-Color[class*=-BGC129] { + background-color: #AF00FF +} + +div.highlight .-Color[class*=-C130] { + color: #AF5F00 +} + +div.highlight .-Color[class*=-BGC130] { + background-color: #AF5F00 +} + +div.highlight .-Color[class*=-C131] { + color: #AF5F5F +} + +div.highlight .-Color[class*=-BGC131] { + background-color: #AF5F5F +} + +div.highlight .-Color[class*=-C132] { + color: #AF5F87 +} + +div.highlight .-Color[class*=-BGC132] { + background-color: #AF5F87 +} + +div.highlight .-Color[class*=-C133] { + color: #AF5FAF +} + +div.highlight .-Color[class*=-BGC133] { + background-color: #AF5FAF +} + +div.highlight .-Color[class*=-C134] { + color: #AF5FD7 +} + +div.highlight .-Color[class*=-BGC134] { + background-color: #AF5FD7 +} + +div.highlight .-Color[class*=-C135] { + color: #AF5FFF +} + +div.highlight .-Color[class*=-BGC135] { + background-color: #AF5FFF +} + +div.highlight .-Color[class*=-C136] { + color: #AF8700 +} + +div.highlight .-Color[class*=-BGC136] { + background-color: #AF8700 +} + +div.highlight .-Color[class*=-C137] { + color: #AF875F +} + +div.highlight .-Color[class*=-BGC137] { + background-color: #AF875F +} + +div.highlight .-Color[class*=-C138] { + color: #AF8787 +} + +div.highlight .-Color[class*=-BGC138] { + background-color: #AF8787 +} + +div.highlight .-Color[class*=-C139] { + color: #AF87AF +} + +div.highlight .-Color[class*=-BGC139] { + background-color: #AF87AF +} + +div.highlight .-Color[class*=-C140] { + color: #AF87D7 +} + +div.highlight .-Color[class*=-BGC140] { + background-color: #AF87D7 +} + +div.highlight .-Color[class*=-C141] { + color: #AF87FF +} + +div.highlight .-Color[class*=-BGC141] { + background-color: #AF87FF +} + +div.highlight .-Color[class*=-C142] { + color: #AFAF00 +} + +div.highlight .-Color[class*=-BGC142] { + background-color: #AFAF00 +} + +div.highlight .-Color[class*=-C143] { + color: #AFAF5F +} + +div.highlight .-Color[class*=-BGC143] { + background-color: #AFAF5F +} + +div.highlight .-Color[class*=-C144] { + color: #AFAF87 +} + +div.highlight .-Color[class*=-BGC144] { + background-color: #AFAF87 +} + +div.highlight .-Color[class*=-C145] { + color: #AFAFAF +} + +div.highlight .-Color[class*=-BGC145] { + background-color: #AFAFAF +} + +div.highlight .-Color[class*=-C146] { + color: #AFAFD7 +} + +div.highlight .-Color[class*=-BGC146] { + background-color: #AFAFD7 +} + +div.highlight .-Color[class*=-C147] { + color: #AFAFFF +} + +div.highlight .-Color[class*=-BGC147] { + background-color: #AFAFFF +} + +div.highlight .-Color[class*=-C148] { + color: #AFD700 +} + +div.highlight .-Color[class*=-BGC148] { + background-color: #AFD700 +} + +div.highlight .-Color[class*=-C149] { + color: #AFD75F +} + +div.highlight .-Color[class*=-BGC149] { + background-color: #AFD75F +} + +div.highlight .-Color[class*=-C150] { + color: #AFD787 +} + +div.highlight .-Color[class*=-BGC150] { + background-color: #AFD787 +} + +div.highlight .-Color[class*=-C151] { + color: #AFD7AF +} + +div.highlight .-Color[class*=-BGC151] { + background-color: #AFD7AF +} + +div.highlight .-Color[class*=-C152] { + color: #AFD7D7 +} + +div.highlight .-Color[class*=-BGC152] { + background-color: #AFD7D7 +} + +div.highlight .-Color[class*=-C153] { + color: #AFD7FF +} + +div.highlight .-Color[class*=-BGC153] { + background-color: #AFD7FF +} + +div.highlight .-Color[class*=-C154] { + color: #AFFF00 +} + +div.highlight .-Color[class*=-BGC154] { + background-color: #AFFF00 +} + +div.highlight .-Color[class*=-C155] { + color: #AFFF5F +} + +div.highlight .-Color[class*=-BGC155] { + background-color: #AFFF5F +} + +div.highlight .-Color[class*=-C156] { + color: #AFFF87 +} + +div.highlight .-Color[class*=-BGC156] { + background-color: #AFFF87 +} + +div.highlight .-Color[class*=-C157] { + color: #AFFFAF +} + +div.highlight .-Color[class*=-BGC157] { + background-color: #AFFFAF +} + +div.highlight .-Color[class*=-C158] { + color: #AFFFD7 +} + +div.highlight .-Color[class*=-BGC158] { + background-color: #AFFFD7 +} + +div.highlight .-Color[class*=-C159] { + color: #AFFFFF +} + +div.highlight .-Color[class*=-BGC159] { + background-color: #AFFFFF +} + +div.highlight .-Color[class*=-C160] { + color: #D70000 +} + +div.highlight .-Color[class*=-BGC160] { + background-color: #D70000 +} + +div.highlight .-Color[class*=-C161] { + color: #D7005F +} + +div.highlight .-Color[class*=-BGC161] { + background-color: #D7005F +} + +div.highlight .-Color[class*=-C162] { + color: #D70087 +} + +div.highlight .-Color[class*=-BGC162] { + background-color: #D70087 +} + +div.highlight .-Color[class*=-C163] { + color: #D700AF +} + +div.highlight .-Color[class*=-BGC163] { + background-color: #D700AF +} + +div.highlight .-Color[class*=-C164] { + color: #D700D7 +} + +div.highlight .-Color[class*=-BGC164] { + background-color: #D700D7 +} + +div.highlight .-Color[class*=-C165] { + color: #D700FF +} + +div.highlight .-Color[class*=-BGC165] { + background-color: #D700FF +} + +div.highlight .-Color[class*=-C166] { + color: #D75F00 +} + +div.highlight .-Color[class*=-BGC166] { + background-color: #D75F00 +} + +div.highlight .-Color[class*=-C167] { + color: #D75F5F +} + +div.highlight .-Color[class*=-BGC167] { + background-color: #D75F5F +} + +div.highlight .-Color[class*=-C168] { + color: #D75F87 +} + +div.highlight .-Color[class*=-BGC168] { + background-color: #D75F87 +} + +div.highlight .-Color[class*=-C169] { + color: #D75FAF +} + +div.highlight .-Color[class*=-BGC169] { + background-color: #D75FAF +} + +div.highlight .-Color[class*=-C170] { + color: #D75FD7 +} + +div.highlight .-Color[class*=-BGC170] { + background-color: #D75FD7 +} + +div.highlight .-Color[class*=-C171] { + color: #D75FFF +} + +div.highlight .-Color[class*=-BGC171] { + background-color: #D75FFF +} + +div.highlight .-Color[class*=-C172] { + color: #D78700 +} + +div.highlight .-Color[class*=-BGC172] { + background-color: #D78700 +} + +div.highlight .-Color[class*=-C173] { + color: #D7875F +} + +div.highlight .-Color[class*=-BGC173] { + background-color: #D7875F +} + +div.highlight .-Color[class*=-C174] { + color: #D78787 +} + +div.highlight .-Color[class*=-BGC174] { + background-color: #D78787 +} + +div.highlight .-Color[class*=-C175] { + color: #D787AF +} + +div.highlight .-Color[class*=-BGC175] { + background-color: #D787AF +} + +div.highlight .-Color[class*=-C176] { + color: #D787D7 +} + +div.highlight .-Color[class*=-BGC176] { + background-color: #D787D7 +} + +div.highlight .-Color[class*=-C177] { + color: #D787FF +} + +div.highlight .-Color[class*=-BGC177] { + background-color: #D787FF +} + +div.highlight .-Color[class*=-C178] { + color: #D7AF00 +} + +div.highlight .-Color[class*=-BGC178] { + background-color: #D7AF00 +} + +div.highlight .-Color[class*=-C179] { + color: #D7AF5F +} + +div.highlight .-Color[class*=-BGC179] { + background-color: #D7AF5F +} + +div.highlight .-Color[class*=-C180] { + color: #D7AF87 +} + +div.highlight .-Color[class*=-BGC180] { + background-color: #D7AF87 +} + +div.highlight .-Color[class*=-C181] { + color: #D7AFAF +} + +div.highlight .-Color[class*=-BGC181] { + background-color: #D7AFAF +} + +div.highlight .-Color[class*=-C182] { + color: #D7AFD7 +} + +div.highlight .-Color[class*=-BGC182] { + background-color: #D7AFD7 +} + +div.highlight .-Color[class*=-C183] { + color: #D7AFFF +} + +div.highlight .-Color[class*=-BGC183] { + background-color: #D7AFFF +} + +div.highlight .-Color[class*=-C184] { + color: #D7D700 +} + +div.highlight .-Color[class*=-BGC184] { + background-color: #D7D700 +} + +div.highlight .-Color[class*=-C185] { + color: #D7D75F +} + +div.highlight .-Color[class*=-BGC185] { + background-color: #D7D75F +} + +div.highlight .-Color[class*=-C186] { + color: #D7D787 +} + +div.highlight .-Color[class*=-BGC186] { + background-color: #D7D787 +} + +div.highlight .-Color[class*=-C187] { + color: #D7D7AF +} + +div.highlight .-Color[class*=-BGC187] { + background-color: #D7D7AF +} + +div.highlight .-Color[class*=-C188] { + color: #D7D7D7 +} + +div.highlight .-Color[class*=-BGC188] { + background-color: #D7D7D7 +} + +div.highlight .-Color[class*=-C189] { + color: #D7D7FF +} + +div.highlight .-Color[class*=-BGC189] { + background-color: #D7D7FF +} + +div.highlight .-Color[class*=-C190] { + color: #D7FF00 +} + +div.highlight .-Color[class*=-BGC190] { + background-color: #D7FF00 +} + +div.highlight .-Color[class*=-C191] { + color: #D7FF5F +} + +div.highlight .-Color[class*=-BGC191] { + background-color: #D7FF5F +} + +div.highlight .-Color[class*=-C192] { + color: #D7FF87 +} + +div.highlight .-Color[class*=-BGC192] { + background-color: #D7FF87 +} + +div.highlight .-Color[class*=-C193] { + color: #D7FFAF +} + +div.highlight .-Color[class*=-BGC193] { + background-color: #D7FFAF +} + +div.highlight .-Color[class*=-C194] { + color: #D7FFD7 +} + +div.highlight .-Color[class*=-BGC194] { + background-color: #D7FFD7 +} + +div.highlight .-Color[class*=-C195] { + color: #D7FFFF +} + +div.highlight .-Color[class*=-BGC195] { + background-color: #D7FFFF +} + +div.highlight .-Color[class*=-C196] { + color: #FF0000 +} + +div.highlight .-Color[class*=-BGC196] { + background-color: #FF0000 +} + +div.highlight .-Color[class*=-C197] { + color: #FF005F +} + +div.highlight .-Color[class*=-BGC197] { + background-color: #FF005F +} + +div.highlight .-Color[class*=-C198] { + color: #FF0087 +} + +div.highlight .-Color[class*=-BGC198] { + background-color: #FF0087 +} + +div.highlight .-Color[class*=-C199] { + color: #FF00AF +} + +div.highlight .-Color[class*=-BGC199] { + background-color: #FF00AF +} + +div.highlight .-Color[class*=-C200] { + color: #FF00D7 +} + +div.highlight .-Color[class*=-BGC200] { + background-color: #FF00D7 +} + +div.highlight .-Color[class*=-C201] { + color: #FF00FF +} + +div.highlight .-Color[class*=-BGC201] { + background-color: #FF00FF +} + +div.highlight .-Color[class*=-C202] { + color: #FF5F00 +} + +div.highlight .-Color[class*=-BGC202] { + background-color: #FF5F00 +} + +div.highlight .-Color[class*=-C203] { + color: #FF5F5F +} + +div.highlight .-Color[class*=-BGC203] { + background-color: #FF5F5F +} + +div.highlight .-Color[class*=-C204] { + color: #FF5F87 +} + +div.highlight .-Color[class*=-BGC204] { + background-color: #FF5F87 +} + +div.highlight .-Color[class*=-C205] { + color: #FF5FAF +} + +div.highlight .-Color[class*=-BGC205] { + background-color: #FF5FAF +} + +div.highlight .-Color[class*=-C206] { + color: #FF5FD7 +} + +div.highlight .-Color[class*=-BGC206] { + background-color: #FF5FD7 +} + +div.highlight .-Color[class*=-C207] { + color: #FF5FFF +} + +div.highlight .-Color[class*=-BGC207] { + background-color: #FF5FFF +} + +div.highlight .-Color[class*=-C208] { + color: #FF8700 +} + +div.highlight .-Color[class*=-BGC208] { + background-color: #FF8700 +} + +div.highlight .-Color[class*=-C209] { + color: #FF875F +} + +div.highlight .-Color[class*=-BGC209] { + background-color: #FF875F +} + +div.highlight .-Color[class*=-C210] { + color: #FF8787 +} + +div.highlight .-Color[class*=-BGC210] { + background-color: #FF8787 +} + +div.highlight .-Color[class*=-C211] { + color: #FF87AF +} + +div.highlight .-Color[class*=-BGC211] { + background-color: #FF87AF +} + +div.highlight .-Color[class*=-C212] { + color: #FF87D7 +} + +div.highlight .-Color[class*=-BGC212] { + background-color: #FF87D7 +} + +div.highlight .-Color[class*=-C213] { + color: #FF87FF +} + +div.highlight .-Color[class*=-BGC213] { + background-color: #FF87FF +} + +div.highlight .-Color[class*=-C214] { + color: #FFAF00 +} + +div.highlight .-Color[class*=-BGC214] { + background-color: #FFAF00 +} + +div.highlight .-Color[class*=-C215] { + color: #FFAF5F +} + +div.highlight .-Color[class*=-BGC215] { + background-color: #FFAF5F +} + +div.highlight .-Color[class*=-C216] { + color: #FFAF87 +} + +div.highlight .-Color[class*=-BGC216] { + background-color: #FFAF87 +} + +div.highlight .-Color[class*=-C217] { + color: #FFAFAF +} + +div.highlight .-Color[class*=-BGC217] { + background-color: #FFAFAF +} + +div.highlight .-Color[class*=-C218] { + color: #FFAFD7 +} + +div.highlight .-Color[class*=-BGC218] { + background-color: #FFAFD7 +} + +div.highlight .-Color[class*=-C219] { + color: #FFAFFF +} + +div.highlight .-Color[class*=-BGC219] { + background-color: #FFAFFF +} + +div.highlight .-Color[class*=-C220] { + color: #FFD700 +} + +div.highlight .-Color[class*=-BGC220] { + background-color: #FFD700 +} + +div.highlight .-Color[class*=-C221] { + color: #FFD75F +} + +div.highlight .-Color[class*=-BGC221] { + background-color: #FFD75F +} + +div.highlight .-Color[class*=-C222] { + color: #FFD787 +} + +div.highlight .-Color[class*=-BGC222] { + background-color: #FFD787 +} + +div.highlight .-Color[class*=-C223] { + color: #FFD7AF +} + +div.highlight .-Color[class*=-BGC223] { + background-color: #FFD7AF +} + +div.highlight .-Color[class*=-C224] { + color: #FFD7D7 +} + +div.highlight .-Color[class*=-BGC224] { + background-color: #FFD7D7 +} + +div.highlight .-Color[class*=-C225] { + color: #FFD7FF +} + +div.highlight .-Color[class*=-BGC225] { + background-color: #FFD7FF +} + +div.highlight .-Color[class*=-C226] { + color: #FFFF00 +} + +div.highlight .-Color[class*=-BGC226] { + background-color: #FFFF00 +} + +div.highlight .-Color[class*=-C227] { + color: #FFFF5F +} + +div.highlight .-Color[class*=-BGC227] { + background-color: #FFFF5F +} + +div.highlight .-Color[class*=-C228] { + color: #FFFF87 +} + +div.highlight .-Color[class*=-BGC228] { + background-color: #FFFF87 +} + +div.highlight .-Color[class*=-C229] { + color: #FFFFAF +} + +div.highlight .-Color[class*=-BGC229] { + background-color: #FFFFAF +} + +div.highlight .-Color[class*=-C230] { + color: #FFFFD7 +} + +div.highlight .-Color[class*=-BGC230] { + background-color: #FFFFD7 +} + +div.highlight .-Color[class*=-C231] { + color: #FFFFFF +} + +div.highlight .-Color[class*=-BGC231] { + background-color: #FFFFFF +} + +div.highlight .-Color[class*=-C232] { + color: #080808 +} + +div.highlight .-Color[class*=-BGC232] { + background-color: #080808 +} + +div.highlight .-Color[class*=-C233] { + color: #121212 +} + +div.highlight .-Color[class*=-BGC233] { + background-color: #121212 +} + +div.highlight .-Color[class*=-C234] { + color: #1C1C1C +} + +div.highlight .-Color[class*=-BGC234] { + background-color: #1C1C1C +} + +div.highlight .-Color[class*=-C235] { + color: #262626 +} + +div.highlight .-Color[class*=-BGC235] { + background-color: #262626 +} + +div.highlight .-Color[class*=-C236] { + color: #303030 +} + +div.highlight .-Color[class*=-BGC236] { + background-color: #303030 +} + +div.highlight .-Color[class*=-C237] { + color: #3A3A3A +} + +div.highlight .-Color[class*=-BGC237] { + background-color: #3A3A3A +} + +div.highlight .-Color[class*=-C238] { + color: #444444 +} + +div.highlight .-Color[class*=-BGC238] { + background-color: #444444 +} + +div.highlight .-Color[class*=-C239] { + color: #4E4E4E +} + +div.highlight .-Color[class*=-BGC239] { + background-color: #4E4E4E +} + +div.highlight .-Color[class*=-C240] { + color: #585858 +} + +div.highlight .-Color[class*=-BGC240] { + background-color: #585858 +} + +div.highlight .-Color[class*=-C241] { + color: #626262 +} + +div.highlight .-Color[class*=-BGC241] { + background-color: #626262 +} + +div.highlight .-Color[class*=-C242] { + color: #6C6C6C +} + +div.highlight .-Color[class*=-BGC242] { + background-color: #6C6C6C +} + +div.highlight .-Color[class*=-C243] { + color: #767676 +} + +div.highlight .-Color[class*=-BGC243] { + background-color: #767676 +} + +div.highlight .-Color[class*=-C244] { + color: #808080 +} + +div.highlight .-Color[class*=-BGC244] { + background-color: #808080 +} + +div.highlight .-Color[class*=-C245] { + color: #8A8A8A +} + +div.highlight .-Color[class*=-BGC245] { + background-color: #8A8A8A +} + +div.highlight .-Color[class*=-C246] { + color: #949494 +} + +div.highlight .-Color[class*=-BGC246] { + background-color: #949494 +} + +div.highlight .-Color[class*=-C247] { + color: #9E9E9E +} + +div.highlight .-Color[class*=-BGC247] { + background-color: #9E9E9E +} + +div.highlight .-Color[class*=-C248] { + color: #A8A8A8 +} + +div.highlight .-Color[class*=-BGC248] { + background-color: #A8A8A8 +} + +div.highlight .-Color[class*=-C249] { + color: #B2B2B2 +} + +div.highlight .-Color[class*=-BGC249] { + background-color: #B2B2B2 +} + +div.highlight .-Color[class*=-C250] { + color: #BCBCBC +} + +div.highlight .-Color[class*=-BGC250] { + background-color: #BCBCBC +} + +div.highlight .-Color[class*=-C251] { + color: #C6C6C6 +} + +div.highlight .-Color[class*=-BGC251] { + background-color: #C6C6C6 +} + +div.highlight .-Color[class*=-C252] { + color: #D0D0D0 +} + +div.highlight .-Color[class*=-BGC252] { + background-color: #D0D0D0 +} + +div.highlight .-Color[class*=-C253] { + color: #DADADA +} + +div.highlight .-Color[class*=-BGC253] { + background-color: #DADADA +} + +div.highlight .-Color[class*=-C254] { + color: #E4E4E4 +} + +div.highlight .-Color[class*=-BGC254] { + background-color: #E4E4E4 +} + +div.highlight .-Color[class*=-C255] { + color: #EEEEEE +} + +div.highlight .-Color[class*=-BGC255] { + background-color: #EEEEEE +} diff --git a/branch/master/singlehtml/_static/play-solid.svg b/branch/master/singlehtml/_static/play-solid.svg new file mode 100644 index 00000000..bcd81f7a --- /dev/null +++ b/branch/master/singlehtml/_static/play-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/branch/master/singlehtml/_static/plus.png b/branch/master/singlehtml/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/branch/master/singlehtml/_static/plus.png differ diff --git a/branch/master/singlehtml/_static/pygments.css b/branch/master/singlehtml/_static/pygments.css new file mode 100644 index 00000000..84ab3030 --- /dev/null +++ b/branch/master/singlehtml/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #008000; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #9C6500 } /* Comment.Preproc */ +.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #E40000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #008400 } /* Generic.Inserted */ +.highlight .go { color: #717171 } /* Generic.Output */ +.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #008000 } /* Keyword.Pseudo */ +.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #B00040 } /* Keyword.Type */ +.highlight .m { color: #666666 } /* Literal.Number */ +.highlight .s { color: #BA2121 } /* Literal.String */ +.highlight .na { color: #687822 } /* Name.Attribute */ +.highlight .nb { color: #008000 } /* Name.Builtin */ +.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.highlight .no { color: #880000 } /* Name.Constant */ +.highlight .nd { color: #AA22FF } /* Name.Decorator */ +.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #0000FF } /* Name.Function */ +.highlight .nl { color: #767600 } /* Name.Label */ +.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #19177C } /* Name.Variable */ +.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #666666 } /* Literal.Number.Bin */ +.highlight .mf { color: #666666 } /* Literal.Number.Float */ +.highlight .mh { color: #666666 } /* Literal.Number.Hex */ +.highlight .mi { color: #666666 } /* Literal.Number.Integer */ +.highlight .mo { color: #666666 } /* Literal.Number.Oct */ +.highlight .sa { color: #BA2121 } /* Literal.String.Affix */ +.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */ +.highlight .sc { color: #BA2121 } /* Literal.String.Char */ +.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #BA2121 } /* Literal.String.Double */ +.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */ +.highlight .sx { color: #008000 } /* Literal.String.Other */ +.highlight .sr { color: #A45A77 } /* Literal.String.Regex */ +.highlight .s1 { color: #BA2121 } /* Literal.String.Single */ +.highlight .ss { color: #19177C } /* Literal.String.Symbol */ +.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #0000FF } /* Name.Function.Magic */ +.highlight .vc { color: #19177C } /* Name.Variable.Class */ +.highlight .vg { color: #19177C } /* Name.Variable.Global */ +.highlight .vi { color: #19177C } /* Name.Variable.Instance */ +.highlight .vm { color: #19177C } /* Name.Variable.Magic */ +.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/branch/master/singlehtml/_static/searchtools.js b/branch/master/singlehtml/_static/searchtools.js new file mode 100644 index 00000000..b08d58c9 --- /dev/null +++ b/branch/master/singlehtml/_static/searchtools.js @@ -0,0 +1,620 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + "Search finished, found ${resultCount} page(s) matching the search query." + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/branch/master/singlehtml/_static/sphinx-thebe.css b/branch/master/singlehtml/_static/sphinx-thebe.css new file mode 100644 index 00000000..1da27930 --- /dev/null +++ b/branch/master/singlehtml/_static/sphinx-thebe.css @@ -0,0 +1,129 @@ +/* Thebelab Buttons */ +.thebelab-button { + z-index: 999; + display: inline-block; + padding: 0.35em 1.2em; + margin: 0px 1px; + border-radius: 0.12em; + box-sizing: border-box; + text-decoration: none; + font-family: "Roboto", sans-serif; + font-weight: 300; + text-align: center; + transition: all 0.2s; + background-color: #dddddd; + border: 0.05em solid white; + color: #000000; +} + +.thebelab-button:hover { + border: 0.05em solid black; + background-color: #fcfcfc; +} + +.thebe-launch-button { + height: 2.2em; + font-size: 0.8em; + border: 1px black solid; +} + +/* Thebelab Cell */ +.thebelab-cell pre { + background: none; +} + +.thebelab-cell .thebelab-input { + padding-left: 1em; + margin-bottom: 0.5em; + margin-top: 0.5em; +} + +.thebelab-cell .jp-OutputArea { + margin-top: 0.5em; + margin-left: 1em; +} + +button.thebelab-button.thebelab-run-button { + margin-left: 1.5em; + margin-bottom: 0.5em; +} + +/* Loading button */ +button.thebe-launch-button div.spinner { + float: left; + margin-right: 1em; +} + +/* Remove the spinner when thebelab is ready */ +.thebe-launch-button.thebe-status-ready .spinner { + display: none; +} + +.thebe-launch-button span.status { + font-family: monospace; + font-weight: bold; +} + +.thebe-launch-button.thebe-status-ready span.status { + color: green; +} + +.spinner { + height: 2em; + text-align: center; + font-size: 0.7em; +} + +.spinner > div { + background-color: #f37726; + height: 100%; + width: 6px; + display: inline-block; + + -webkit-animation: sk-stretchdelay 1.2s infinite ease-in-out; + animation: sk-stretchdelay 1.2s infinite ease-in-out; +} + +.spinner .rect2 { + -webkit-animation-delay: -1.1s; + animation-delay: -1.1s; +} + +.spinner .rect3 { + -webkit-animation-delay: -1s; + animation-delay: -1s; +} + +.spinner .rect4 { + -webkit-animation-delay: -0.9s; + animation-delay: -0.9s; +} + +.spinner .rect5 { + -webkit-animation-delay: -0.8s; + animation-delay: -0.8s; +} + +@-webkit-keyframes sk-stretchdelay { + 0%, + 40%, + 100% { + -webkit-transform: scaleY(0.4); + } + 20% { + -webkit-transform: scaleY(1); + } +} + +@keyframes sk-stretchdelay { + 0%, + 40%, + 100% { + transform: scaleY(0.4); + -webkit-transform: scaleY(0.4); + } + 20% { + transform: scaleY(1); + -webkit-transform: scaleY(1); + } +} diff --git a/branch/master/singlehtml/_static/sphinx-thebe.js b/branch/master/singlehtml/_static/sphinx-thebe.js new file mode 100644 index 00000000..d92b1d3b --- /dev/null +++ b/branch/master/singlehtml/_static/sphinx-thebe.js @@ -0,0 +1,127 @@ +/** + * Add attributes to Thebe blocks to initialize thebe properly + */ +var configureThebe = () => { + // Load thebe config in case we want to update it as some point + console.log("[sphinx-thebe]: Loading thebe config..."); + thebe_config = document.querySelector("script[type=\"text/x-thebe-config\"]"); + + // If we already detect a Thebe cell, don't re-run + if (document.querySelectorAll("div.thebe-cell").length > 0) { + return; + } + + // Update thebe buttons with loading message + document.querySelectorAll(".thebe-launch-button").forEach((button) => { + button.innerHTML = ` + + `; + }); + + // Set thebe event hooks + var thebeStatus; + thebelab.on("status", function (evt, data) { + console.log("Status changed:", data.status, data.message); + + const button = document.querySelector(".thebe-launch-button "); + button.classList.replace( + `thebe-status-${thebeStatus}`, + `thebe-status-${data.status}` + ) + button.querySelector(".loading-text") + .innerHTML = ( + `Launching from mybinder.org: + ${data.status}` + ); + + // Now update our thebe status + thebeStatus = data.status; + + // Find any cells with an initialization tag and ask thebe to run them when ready + if (data.status === "ready") { + var thebeInitCells = document.querySelectorAll( + ".thebe-init, .tag_thebe-init" + ); + thebeInitCells.forEach((cell) => { + console.log("Initializing Thebe with cell: " + cell.id); + cell.querySelector(".thebelab-run-button").click(); + }); + } + }); +}; + +/** + * Update the page DOM to use Thebe elements + */ +var modifyDOMForThebe = () => { + // Find all code cells, replace with Thebe interactive code cells + const codeCells = document.querySelectorAll(thebe_selector); + codeCells.forEach((codeCell, index) => { + const codeCellId = (index) => `codecell${index}`; + codeCell.id = codeCellId(index); + codeCellText = codeCell.querySelector(thebe_selector_input); + codeCellOutput = codeCell.querySelector(thebe_selector_output); + + // Clean up the language to make it work w/ CodeMirror and add it to the cell + dataLanguage = detectLanguage(kernelName); + + // Re-arrange the cell and add metadata + if (codeCellText) { + codeCellText.setAttribute("data-language", dataLanguage); + codeCellText.setAttribute("data-executable", "true"); + + // If we had an output, insert it just after the `pre` cell + if (codeCellOutput) { + codeCellOutput.setAttribute("data-output", ""); + codeCellText.insertAdjacentElement('afterend', codeCellOutput); + } + } + + // Remove sphinx-copybutton blocks, which are common in Sphinx + codeCell.querySelectorAll("button.copybtn").forEach((el) => { + el.remove(); + }); + }); +}; + +var initThebe = () => { + // Load thebe dynamically if it's not already loaded + if (typeof thebelab === "undefined") { + console.log("[sphinx-thebe]: Loading thebe from CDN..."); + document.querySelector(".thebe-launch-button ").innerText = "Loading thebe from CDN..."; + + const script = document.createElement("script"); + script.src = `${THEBE_JS_URL}`; + document.head.appendChild(script); + + // Runs once the script has finished loading + script.addEventListener("load", () => { + console.log("[sphinx-thebe]: Finished loading thebe from CDN..."); + configureThebe(); + modifyDOMForThebe(); + thebelab.bootstrap(); + }); + } else { + console.log( + "[sphinx-thebe]: thebe already loaded, not loading from CDN..." + ); + configureThebe(); + modifyDOMForThebe(); + thebelab.bootstrap(); + } +}; + +// Helper function to munge the language name +var detectLanguage = (language) => { + if (language.indexOf("python") > -1) { + language = "python"; + } else if (language === "ir") { + language = "r"; + } + return language; +}; diff --git a/branch/master/singlehtml/_static/sphinx_highlight.js b/branch/master/singlehtml/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/branch/master/singlehtml/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/branch/master/singlehtml/_static/sphinx_lesson.css b/branch/master/singlehtml/_static/sphinx_lesson.css new file mode 100644 index 00000000..68cb32da --- /dev/null +++ b/branch/master/singlehtml/_static/sphinx_lesson.css @@ -0,0 +1,103 @@ +/* sphinx_lesson.css + * https://webaim.org/resources/contrastchecker/?fcolor=00000&bcolor=FCE762 + * */ +:root { + --sphinx-lesson-selection-bg-color: #fce762; + --sphinx-lesson-selection-fg-color: #000000; +} + +/* https://webaim.org/resources/contrastchecker/?fcolor=FFFFFF&bcolor=745315 + * when dark theme is selected the some themes use this attirbute + */ +html[data-theme='dark'], body[data-theme='dark'] { + --sphinx-lesson-selection-bg-color: #745315; + --sphinx-lesson-selection-fg-color: #ffffff; +} + +/* when browser/system theme is dark and no theme is selected */ +@media (prefers-color-scheme: dark) { + html[data-theme='auto'], body[data-theme='auto'] { + --sphinx-lesson-selection-bg-color: #745315; + --sphinx-lesson-selection-fg-color: #ffffff; + } +} + +body.wy-body-for-nav img.with-border { + border: 2px solid; +} + +.rst-content .admonition-no-content { + padding-bottom: 0px; +} + +.rst-content .demo > .admonition-title::before { + content: "\01F440"; /* Eyes */ } +.rst-content .type-along > .admonition-title::before { + content: "\02328\0FE0F"; /* Keyboard */ } +.rst-content .exercise > .admonition-title::before { + content: "\0270D\0FE0F"; /* Hand */ } +.rst-content .solution > .admonition-title::before { + content: "\02714\0FE0E"; /* Check mark */ } +.rst-content .homework > .admonition-title::before { + content: "\01F4DD"; /* Memo */ } +.rst-content .discussion > .admonition-title::before { + content: "\01F4AC"; /* Speech balloon */ } +.rst-content .questions > .admonition-title::before { + content: "\02753\0FE0E"; /* Question mark */ } +.rst-content .prerequisites > .admonition-title::before { + content: "\02699"; /* Gear */ } +.rst-content .seealso > .admonition-title::before { + content: "\027A1\0FE0E"; /* Question mark */ } + + +/* instructor-note */ +.rst-content .instructor-note { + background: #e7e7e7; +} +.rst-content .instructor-note > .admonition-title { + background: #6a6a6a; +} +.rst-content .instructor-note > .admonition-title::before { + content: ""; +} + + +/* sphinx_toggle_button, make the font white */ +.rst-content .toggle.admonition button.toggle-button { + color: white; +} + +/* sphinx-togglebutton, remove underflow when toggled to hidden mode */ +.rst-content .admonition.toggle-hidden { + padding-bottom: 0px; +} + +/* selection / highlight colour uses a yellow background and a black text */ +/*** Works on common browsers ***/ +::selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/*** Mozilla based browsers ***/ +::-moz-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/***For Other Browsers ***/ +::-o-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +::-ms-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} + +/*** For Webkit ***/ +::-webkit-selection { + background-color: var(--sphinx-lesson-selection-bg-color); + color: var(--sphinx-lesson-selection-fg-color); +} diff --git a/branch/master/singlehtml/_static/sphinx_rtd_theme_ext_color_contrast.css b/branch/master/singlehtml/_static/sphinx_rtd_theme_ext_color_contrast.css new file mode 100644 index 00000000..e68feb82 --- /dev/null +++ b/branch/master/singlehtml/_static/sphinx_rtd_theme_ext_color_contrast.css @@ -0,0 +1,47 @@ +/* The following are for web accessibility of sphinx_rtd_theme: they + * solve some of the most frequent contrast issues. Remove when this + * solved: + * https://github.com/readthedocs/sphinx_rtd_theme/issues/971 + */ +/* background: #fcfcfc, note boxes #E7F2FA */ +a { color: #2573A7; } /* original #2980B9, #1F5C84; */ +body { color: #242424; } /* original #404040, #383838 */ +.wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a { + color: #ffffff; +} /* original #fcfcfc */ +footer { color: #737373; } /* original gray=#808080*/ +footer span.commit code, footer span.commit .rst-content tt, .rst-content footer span.commit tt { + color: #737373; +} /* original gray=#808080*/ +.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal { + color: #AB2314; +} +/* Sidebar background */ +.wy-side-nav-search { background-color: #277CB4;} + +/* Same, but for pygments */ +.highlight .ch { color: #3E7A89; } /* #! line */ +.highlight .c1 { color: #3E7A89; } /* also comments */ +.highlight .nv { color: #AD3ECC; } /* variable */ +.highlight .gp { color: #B45608; } /* prompt character, $*/ +.highlight .si { color: #3975B1; } /* ${} variable text */ +.highlight .nc { color: #0C78A7; } + +/* Sphinx admonitions */ +/* warning */ +.wy-alert.wy-alert-warning .wy-alert-title, .rst-content .wy-alert-warning.note .wy-alert-title, .rst-content .attention .wy-alert-title, .rst-content .caution .wy-alert-title, .rst-content .wy-alert-warning.danger .wy-alert-title, .rst-content .wy-alert-warning.error .wy-alert-title, .rst-content .wy-alert-warning.hint .wy-alert-title, .rst-content .wy-alert-warning.important .wy-alert-title, .rst-content .wy-alert-warning.tip .wy-alert-title, .rst-content .warning .wy-alert-title, .rst-content .wy-alert-warning.seealso .wy-alert-title, .rst-content .admonition-todo .wy-alert-title, .rst-content .wy-alert-warning.admonition .wy-alert-title, .wy-alert.wy-alert-warning .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-warning .admonition-title, .rst-content .wy-alert-warning.note .admonition-title, .rst-content .attention .admonition-title, .rst-content .caution .admonition-title, .rst-content .wy-alert-warning.danger .admonition-title, .rst-content .wy-alert-warning.error .admonition-title, .rst-content .wy-alert-warning.hint .admonition-title, .rst-content .wy-alert-warning.important .admonition-title, .rst-content .wy-alert-warning.tip .admonition-title, .rst-content .warning .admonition-title, .rst-content .wy-alert-warning.seealso .admonition-title, .rst-content .admonition-todo .admonition-title, .rst-content .wy-alert-warning.admonition .admonition-title { + background: #B15E16; } +/* important */ +.wy-alert.wy-alert-success .wy-alert-title, .rst-content .wy-alert-success.note .wy-alert-title, .rst-content .wy-alert-success.attention .wy-alert-title, .rst-content .wy-alert-success.caution .wy-alert-title, .rst-content .wy-alert-success.danger .wy-alert-title, .rst-content .wy-alert-success.error .wy-alert-title, .rst-content .hint .wy-alert-title, .rst-content .important .wy-alert-title, .rst-content .tip .wy-alert-title, .rst-content .wy-alert-success.warning .wy-alert-title, .rst-content .wy-alert-success.seealso .wy-alert-title, .rst-content .wy-alert-success.admonition-todo .wy-alert-title, .rst-content .wy-alert-success.admonition .wy-alert-title, .wy-alert.wy-alert-success .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-success .admonition-title, .rst-content .wy-alert-success.note .admonition-title, .rst-content .wy-alert-success.attention .admonition-title, .rst-content .wy-alert-success.caution .admonition-title, .rst-content .wy-alert-success.danger .admonition-title, .rst-content .wy-alert-success.error .admonition-title, .rst-content .hint .admonition-title, .rst-content .important .admonition-title, .rst-content .tip .admonition-title, .rst-content .wy-alert-success.warning .admonition-title, .rst-content .wy-alert-success.seealso .admonition-title, .rst-content .wy-alert-success.admonition-todo .admonition-title, .rst-content .wy-alert-success.admonition .admonition-title { + background: #12826C; } +/* seealso, note, etc */ +.wy-alert.wy-alert-info .wy-alert-title, .rst-content .note .wy-alert-title, .rst-content .wy-alert-info.attention .wy-alert-title, .rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error .wy-alert-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content .wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .seealso .wy-alert-title, .rst-content .wy-alert-info.admonition-todo .wy-alert-title, .rst-content .wy-alert-info.admonition .wy-alert-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-info .admonition-title, .rst-content .note .admonition-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.caution .admonition-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content .wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.tip .admonition-title, .rst-content .wy-alert-info.warning .admonition-title, .rst-content .seealso .admonition-title, .rst-content .wy-alert-info.admonition-todo .admonition-title, .rst-content .wy-alert-info.admonition .admonition-title { + background: #277CB4; } +/* error, danger */ +.rst-content .danger .admonition-title, .rst-content .danger .wy-alert-title, .rst-content .error .admonition-title, .rst-content .error .wy-alert-title, .rst-content .wy-alert-danger.admonition-todo .admonition-title, .rst-content .wy-alert-danger.admonition-todo .wy-alert-title, .rst-content .wy-alert-danger.admonition .admonition-title, .rst-content .wy-alert-danger.admonition .wy-alert-title, .rst-content .wy-alert-danger.attention .admonition-title, .rst-content .wy-alert-danger.attention .wy-alert-title, .rst-content .wy-alert-danger.caution .admonition-title, .rst-content .wy-alert-danger.caution .wy-alert-title, .rst-content .wy-alert-danger.hint .admonition-title, .rst-content .wy-alert-danger.hint .wy-alert-title, .rst-content .wy-alert-danger.important .admonition-title, .rst-content .wy-alert-danger.important .wy-alert-title, .rst-content .wy-alert-danger.note .admonition-title, .rst-content .wy-alert-danger.note .wy-alert-title, .rst-content .wy-alert-danger.seealso .admonition-title, .rst-content .wy-alert-danger.seealso .wy-alert-title, .rst-content .wy-alert-danger.tip .admonition-title, .rst-content .wy-alert-danger.tip .wy-alert-title, .rst-content .wy-alert-danger.warning .admonition-title, .rst-content .wy-alert-danger.warning .wy-alert-title, .rst-content .wy-alert.wy-alert-danger .admonition-title, .wy-alert.wy-alert-danger .rst-content .admonition-title, .wy-alert.wy-alert-danger .wy-alert-title { + background: #e31704; +} + +/* Generic admonition titles */ +.wy-alert-title, .rst-content .admonition-title { + background: #277CB4; } diff --git a/branch/master/singlehtml/_static/tabs.css b/branch/master/singlehtml/_static/tabs.css new file mode 100644 index 00000000..957ba60d --- /dev/null +++ b/branch/master/singlehtml/_static/tabs.css @@ -0,0 +1,89 @@ +.sphinx-tabs { + margin-bottom: 1rem; +} + +[role="tablist"] { + border-bottom: 1px solid #a0b3bf; +} + +.sphinx-tabs-tab { + position: relative; + font-family: Lato,'Helvetica Neue',Arial,Helvetica,sans-serif; + color: #1D5C87; + line-height: 24px; + margin: 0; + font-size: 16px; + font-weight: 400; + background-color: rgba(255, 255, 255, 0); + border-radius: 5px 5px 0 0; + border: 0; + padding: 1rem 1.5rem; + margin-bottom: 0; +} + +.sphinx-tabs-tab[aria-selected="true"] { + font-weight: 700; + border: 1px solid #a0b3bf; + border-bottom: 1px solid white; + margin: -1px; + background-color: white; +} + +.sphinx-tabs-tab:focus { + z-index: 1; + outline-offset: 1px; +} + +.sphinx-tabs-panel { + position: relative; + padding: 1rem; + border: 1px solid #a0b3bf; + margin: 0px -1px -1px -1px; + border-radius: 0 0 5px 5px; + border-top: 0; + background: white; +} + +.sphinx-tabs-panel.code-tab { + padding: 0.4rem; +} + +.sphinx-tab img { + margin-bottom: 24 px; +} + +/* Dark theme preference styling */ + +@media (prefers-color-scheme: dark) { + body[data-theme="auto"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); + } + + body[data-theme="auto"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); + } + + body[data-theme="auto"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 1px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); + } +} + +/* Explicit dark theme styling */ + +body[data-theme="dark"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); +} + +body[data-theme="dark"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); +} + +body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 2px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); +} diff --git a/branch/master/singlehtml/_static/tabs.js b/branch/master/singlehtml/_static/tabs.js new file mode 100644 index 00000000..48dc303c --- /dev/null +++ b/branch/master/singlehtml/_static/tabs.js @@ -0,0 +1,145 @@ +try { + var session = window.sessionStorage || {}; +} catch (e) { + var session = {}; +} + +window.addEventListener("DOMContentLoaded", () => { + const allTabs = document.querySelectorAll('.sphinx-tabs-tab'); + const tabLists = document.querySelectorAll('[role="tablist"]'); + + allTabs.forEach(tab => { + tab.addEventListener("click", changeTabs); + }); + + tabLists.forEach(tabList => { + tabList.addEventListener("keydown", keyTabs); + }); + + // Restore group tab selection from session + const lastSelected = session.getItem('sphinx-tabs-last-selected'); + if (lastSelected != null) selectNamedTabs(lastSelected); +}); + +/** + * Key focus left and right between sibling elements using arrows + * @param {Node} e the element in focus when key was pressed + */ +function keyTabs(e) { + const tab = e.target; + let nextTab = null; + if (e.keyCode === 39 || e.keyCode === 37) { + tab.setAttribute("tabindex", -1); + // Move right + if (e.keyCode === 39) { + nextTab = tab.nextElementSibling; + if (nextTab === null) { + nextTab = tab.parentNode.firstElementChild; + } + // Move left + } else if (e.keyCode === 37) { + nextTab = tab.previousElementSibling; + if (nextTab === null) { + nextTab = tab.parentNode.lastElementChild; + } + } + } + + if (nextTab !== null) { + nextTab.setAttribute("tabindex", 0); + nextTab.focus(); + } +} + +/** + * Select or deselect clicked tab. If a group tab + * is selected, also select tab in other tabLists. + * @param {Node} e the element that was clicked + */ +function changeTabs(e) { + // Use this instead of the element that was clicked, in case it's a child + const notSelected = this.getAttribute("aria-selected") === "false"; + const positionBefore = this.parentNode.getBoundingClientRect().top; + const notClosable = !this.parentNode.classList.contains("closeable"); + + deselectTabList(this); + + if (notSelected || notClosable) { + selectTab(this); + const name = this.getAttribute("name"); + selectNamedTabs(name, this.id); + + if (this.classList.contains("group-tab")) { + // Persist during session + session.setItem('sphinx-tabs-last-selected', name); + } + } + + const positionAfter = this.parentNode.getBoundingClientRect().top; + const positionDelta = positionAfter - positionBefore; + // Scroll to offset content resizing + window.scrollTo(0, window.scrollY + positionDelta); +} + +/** + * Select tab and show associated panel. + * @param {Node} tab tab to select + */ +function selectTab(tab) { + tab.setAttribute("aria-selected", true); + + // Show the associated panel + document + .getElementById(tab.getAttribute("aria-controls")) + .removeAttribute("hidden"); +} + +/** + * Hide the panels associated with all tabs within the + * tablist containing this tab. + * @param {Node} tab a tab within the tablist to deselect + */ +function deselectTabList(tab) { + const parent = tab.parentNode; + const grandparent = parent.parentNode; + + Array.from(parent.children) + .forEach(t => t.setAttribute("aria-selected", false)); + + Array.from(grandparent.children) + .slice(1) // Skip tablist + .forEach(panel => panel.setAttribute("hidden", true)); +} + +/** + * Select grouped tabs with the same name, but no the tab + * with the given id. + * @param {Node} name name of grouped tab to be selected + * @param {Node} clickedId id of clicked tab + */ +function selectNamedTabs(name, clickedId=null) { + const groupedTabs = document.querySelectorAll(`.sphinx-tabs-tab[name="${name}"]`); + const tabLists = Array.from(groupedTabs).map(tab => tab.parentNode); + + tabLists + .forEach(tabList => { + // Don't want to change the tabList containing the clicked tab + const clickedTab = tabList.querySelector(`[id="${clickedId}"]`); + if (clickedTab === null ) { + // Select first tab with matching name + const tab = tabList.querySelector(`.sphinx-tabs-tab[name="${name}"]`); + deselectTabList(tab); + selectTab(tab); + } + }) +} + +if (typeof exports === 'undefined') { + exports = {}; +} + +exports.keyTabs = keyTabs; +exports.changeTabs = changeTabs; +exports.selectTab = selectTab; +exports.deselectTabList = deselectTabList; +exports.selectNamedTabs = selectNamedTabs; diff --git a/branch/master/singlehtml/_static/term_role_formatting.css b/branch/master/singlehtml/_static/term_role_formatting.css new file mode 100644 index 00000000..0b66095c --- /dev/null +++ b/branch/master/singlehtml/_static/term_role_formatting.css @@ -0,0 +1,4 @@ +/* Make terms bold */ +a.reference span.std-term { + font-weight: bold; +} diff --git a/branch/master/singlehtml/_static/togglebutton.css b/branch/master/singlehtml/_static/togglebutton.css new file mode 100644 index 00000000..54a67879 --- /dev/null +++ b/branch/master/singlehtml/_static/togglebutton.css @@ -0,0 +1,160 @@ +/** + * Admonition-based toggles + */ + +/* Visibility of the target */ +.admonition.toggle .admonition-title ~ * { + transition: opacity .3s, height .3s; +} + +/* Toggle buttons inside admonitions so we see the title */ +.admonition.toggle { + position: relative; +} + +/* Titles should cut off earlier to avoid overlapping w/ button */ +.admonition.toggle .admonition-title { + padding-right: 25%; + cursor: pointer; +} + +/* Hovering will cause a slight shift in color to make it feel interactive */ +.admonition.toggle .admonition-title:hover { + box-shadow: inset 0 0 0px 20px rgb(0 0 0 / 1%); +} + +/* Hovering will cause a slight shift in color to make it feel interactive */ +.admonition.toggle .admonition-title:active { + box-shadow: inset 0 0 0px 20px rgb(0 0 0 / 3%); +} + +/* Remove extra whitespace below the admonition title when hidden */ +.admonition.toggle-hidden { + padding-bottom: 0; +} + +.admonition.toggle-hidden .admonition-title { + margin-bottom: 0; +} + +/* hides all the content of a page until de-toggled */ +.admonition.toggle-hidden .admonition-title ~ * { + height: 0; + margin: 0; + opacity: 0; + visibility: hidden; +} + +/* General button style and position*/ +button.toggle-button { + /** + * Background and shape. By default there's no background + * but users can style as they wish + */ + background: none; + border: none; + outline: none; + + /* Positioning just inside the admonition title */ + position: absolute; + right: 0.5em; + padding: 0px; + border: none; + outline: none; +} + +/* Display the toggle hint on wide screens */ +@media (min-width: 768px) { + button.toggle-button.toggle-button-hidden:before { + content: attr(data-toggle-hint); /* This will be filled in by JS */ + font-size: .8em; + align-self: center; + } +} + +/* Icon behavior */ +.tb-icon { + transition: transform .2s ease-out; + height: 1.5em; + width: 1.5em; + stroke: currentColor; /* So that we inherit the color of other text */ +} + +/* The icon should point right when closed, down when open. */ +/* Open */ +.admonition.toggle button .tb-icon { + transform: rotate(90deg); +} + +/* Closed */ +.admonition.toggle button.toggle-button-hidden .tb-icon { + transform: rotate(0deg); +} + +/* With details toggles, we don't rotate the icon so it points right */ +details.toggle-details .tb-icon { + height: 1.4em; + width: 1.4em; + margin-top: 0.1em; /* To center the button vertically */ +} + + +/** + * Details-based toggles. + * In this case, we wrap elements with `.toggle` in a details block. + */ + +/* Details blocks */ +details.toggle-details { + margin: 1em 0; +} + + +details.toggle-details summary { + display: flex; + align-items: center; + cursor: pointer; + list-style: none; + border-radius: .2em; + border-left: 3px solid #1976d2; + background-color: rgb(204 204 204 / 10%); + padding: 0.2em 0.7em 0.3em 0.5em; /* Less padding on left because the SVG has left margin */ + font-size: 0.9em; +} + +details.toggle-details summary:hover { + background-color: rgb(204 204 204 / 20%); +} + +details.toggle-details summary:active { + background: rgb(204 204 204 / 28%); +} + +.toggle-details__summary-text { + margin-left: 0.2em; +} + +details.toggle-details[open] summary { + margin-bottom: .5em; +} + +details.toggle-details[open] summary .tb-icon { + transform: rotate(90deg); +} + +details.toggle-details[open] summary ~ * { + animation: toggle-fade-in .3s ease-out; +} + +@keyframes toggle-fade-in { + from {opacity: 0%;} + to {opacity: 100%;} +} + +/* Print rules - we hide all toggle button elements at print */ +@media print { + /* Always hide the summary so the button doesn't show up */ + details.toggle-details summary { + display: none; + } +} \ No newline at end of file diff --git a/branch/master/singlehtml/_static/togglebutton.js b/branch/master/singlehtml/_static/togglebutton.js new file mode 100644 index 00000000..215a7eef --- /dev/null +++ b/branch/master/singlehtml/_static/togglebutton.js @@ -0,0 +1,187 @@ +/** + * Add Toggle Buttons to elements + */ + +let toggleChevron = ` + + + +`; + +var initToggleItems = () => { + var itemsToToggle = document.querySelectorAll(togglebuttonSelector); + console.log(`[togglebutton]: Adding toggle buttons to ${itemsToToggle.length} items`) + // Add the button to each admonition and hook up a callback to toggle visibility + itemsToToggle.forEach((item, index) => { + if (item.classList.contains("admonition")) { + // If it's an admonition block, then we'll add a button inside + // Generate unique IDs for this item + var toggleID = `toggle-${index}`; + var buttonID = `button-${toggleID}`; + + item.setAttribute('id', toggleID); + if (!item.classList.contains("toggle")){ + item.classList.add("toggle"); + } + // This is the button that will be added to each item to trigger the toggle + var collapseButton = ` + `; + + title = item.querySelector(".admonition-title") + title.insertAdjacentHTML("beforeend", collapseButton); + thisButton = document.getElementById(buttonID); + + // Add click handlers for the button + admonition title (if admonition) + admonitionTitle = document.querySelector(`#${toggleID} > .admonition-title`) + if (admonitionTitle) { + // If an admonition, then make the whole title block clickable + admonitionTitle.addEventListener('click', toggleClickHandler); + admonitionTitle.dataset.target = toggleID + admonitionTitle.dataset.button = buttonID + } else { + // If not an admonition then we'll listen for the button click + thisButton.addEventListener('click', toggleClickHandler); + } + + // Now hide the item for this toggle button unless explicitly noted to show + if (!item.classList.contains("toggle-shown")) { + toggleHidden(thisButton); + } + } else { + // If not an admonition, wrap the block in a
block + // Define the structure of the details block and insert it as a sibling + var detailsBlock = ` +
+ + ${toggleChevron} + ${toggleHintShow} + +
`; + item.insertAdjacentHTML("beforebegin", detailsBlock); + + // Now move the toggle-able content inside of the details block + details = item.previousElementSibling + details.appendChild(item) + item.classList.add("toggle-details__container") + + // Set up a click trigger to change the text as needed + details.addEventListener('click', (click) => { + let parent = click.target.parentElement; + if (parent.tagName.toLowerCase() == "details") { + summary = parent.querySelector("summary"); + details = parent; + } else { + summary = parent; + details = parent.parentElement; + } + // Update the inner text for the proper hint + if (details.open) { + summary.querySelector("span.toggle-details__summary-text").innerText = toggleHintShow; + } else { + summary.querySelector("span.toggle-details__summary-text").innerText = toggleHintHide; + } + + }); + + // If we have a toggle-shown class, open details block should be open + if (item.classList.contains("toggle-shown")) { + details.click(); + } + } + }) +}; + +// This should simply add / remove the collapsed class and change the button text +var toggleHidden = (button) => { + target = button.dataset['target'] + var itemToToggle = document.getElementById(target); + if (itemToToggle.classList.contains("toggle-hidden")) { + itemToToggle.classList.remove("toggle-hidden"); + button.classList.remove("toggle-button-hidden"); + } else { + itemToToggle.classList.add("toggle-hidden"); + button.classList.add("toggle-button-hidden"); + } +} + +var toggleClickHandler = (click) => { + // Be cause the admonition title is clickable and extends to the whole admonition + // We only look for a click event on this title to trigger the toggle. + + if (click.target.classList.contains("admonition-title")) { + button = click.target.querySelector(".toggle-button"); + } else if (click.target.classList.contains("tb-icon")) { + // We've clicked the icon and need to search up one parent for the button + button = click.target.parentElement; + } else if (click.target.tagName == "polyline") { + // We've clicked the SVG elements inside the button, need to up 2 layers + button = click.target.parentElement.parentElement; + } else if (click.target.classList.contains("toggle-button")) { + // We've clicked the button itself and so don't need to do anything + button = click.target; + } else { + console.log(`[togglebutton]: Couldn't find button for ${click.target}`) + } + target = document.getElementById(button.dataset['button']); + toggleHidden(target); +} + +// If we want to blanket-add toggle classes to certain cells +var addToggleToSelector = () => { + const selector = ""; + if (selector.length > 0) { + document.querySelectorAll(selector).forEach((item) => { + item.classList.add("toggle"); + }) + } +} + +// Helper function to run when the DOM is finished +const sphinxToggleRunWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} +sphinxToggleRunWhenDOMLoaded(addToggleToSelector) +sphinxToggleRunWhenDOMLoaded(initToggleItems) + +/** Toggle details blocks to be open when printing */ +if (toggleOpenOnPrint == "true") { + window.addEventListener("beforeprint", () => { + // Open the details + document.querySelectorAll("details.toggle-details").forEach((el) => { + el.dataset["togglestatus"] = el.open; + el.open = true; + }); + + // Open the admonitions + document.querySelectorAll(".admonition.toggle.toggle-hidden").forEach((el) => { + console.log(el); + el.querySelector("button.toggle-button").click(); + el.dataset["toggle_after_print"] = "true"; + }); + }); + window.addEventListener("afterprint", () => { + // Re-close the details that were closed + document.querySelectorAll("details.toggle-details").forEach((el) => { + el.open = el.dataset["togglestatus"] == "true"; + delete el.dataset["togglestatus"]; + }); + + // Re-close the admonition toggle buttons + document.querySelectorAll(".admonition.toggle").forEach((el) => { + if (el.dataset["toggle_after_print"] == "true") { + el.querySelector("button.toggle-button").click(); + delete el.dataset["toggle_after_print"]; + } + }); + }); +} diff --git a/branch/master/singlehtml/index.html b/branch/master/singlehtml/index.html new file mode 100644 index 00000000..6b212388 --- /dev/null +++ b/branch/master/singlehtml/index.html @@ -0,0 +1,8639 @@ + + + + + + + + + + + + + + + Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python for Scientific Computing

+
+

Attending the course 5-7 November, 2024?

+

See the course page here +and watch at https://twitch.tv/coderefinery. +Whether you are or aren’t, the course material is below. Videos +will appear in this playlist (Last year’s videos: playlist).

+
+

Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, Matplotlib for visualization, and so on. In +addition, it talks about how python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write.

+

This course (like any course) can’t teach you Python… it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to.

+
+

Prerequisites

+ +

These are not prerequisites:

+
    +

  • Any external libraries, e.g. numpy

    • +

  • Knowing how to make scripts or use Jupyter

    • +
+
+
+

Videos and archived Q&A

+

Videos and material from past instances:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

(prereq)

Introduction to Python

30 min

Jupyter

60 min

NumPy or Advanced NumPy

60 min

Pandas

30 min

Xarray

60 min

Plotting with Matplotlib

60 min

Plotting with Vega-Altair

30 min

Working with Data

60 min

Scripts

40 min

Profiling

20 min

Productivity tools

30 min

Web APIs with Python

15 min

SciPy

30 min

Library ecosystem

45 min

Parallel programming

45 min

Dependency management

30 min

Binder

60 min

Packaging

+
+
+

Introduction to Python

+
+

Questions

+
    +

  • What are the basic blocks of Python language?

    • +

  • How are functions and classes defined in Python?

    • +
+
+
+

Objectives

+
    +

  • Get a very short introduction to Python types and syntax

    • +

  • Be able to follow the rest of the examples in the course, even if you don’t understand everything perfectly.

    • +
+

We expect everyone to be able to know the following basic material +to follow the course (though it is not everything you need to +know about Python).

+
+

If you are not familiar with Python, here is a very short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise.

+
+

See also

+

This page contains an overview of the basics of Python. You can +also refer to This Python overview from a different lesson +which is slightly more engaging.

+
+
+

Scalars

+

Scalar types, that is, single elements of various types:

+
i = 42       # integer
+i = 2**77    # Integers have arbitrary precision
+g = 3.14     # floating point number
+c = 2 - 3j   # Complex number
+b = True     # boolean
+s = "Hello!" # String (Unicode)
+q = b'Hello' # bytes (8-bit values)
+
+
+

Read more: int, float, complex, +bool, str, bytes.

+
+
+

Collections

+

Collections are data structures capable of storing multiple values.

+
l = [1, 2, 3]                      # list
+l[1]                               # lists are indexed by int
+l[1] = True                        # list elements can be any type
+d = {"Janne": 123, "Richard": 456} # dictionary
+d["Janne"]
+s = set(("apple", "cherry", "banana", "apple")) # Set of unique values
+s
+
+
+

Read more: list, tuple, dict, set.

+
+
+

Control structures

+

Python has the usual control structures, that is conditional +statements and loops. For example, the The if statement statement:

+
x = 2
+if x == 3:
+    print('x is 3')
+elif x == 2:
+    print('x is 2')
+else:
+    print('x is something else')
+
+
+

While loops loop until some condition is met:

+
x = 0
+while x < 42:
+    print('x is ', x)
+    x += 0.2
+
+
+

For loops loop over some collection of values:

+
xs = [1, 2, 3, 4]
+for x in xs:
+    print(x)
+
+
+

Often you want to loop over a sequence of integers, in that case the +range function is useful:

+
for x in range(9):
+    print(x)
+
+
+

Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the enumerate() +function:

+
xs = [1, 'hello', 'world']
+for ii, x in enumerate(xs):
+    print(ii, x)
+
+
+
+
+

Functions and classes

+

Python functions are defined by the Function definitions keyword. They take a +number of arguments, and return a number of return values.

+
def hello(name):
+    """Say hello to the person given by the argument"""
+    print('Hello', name)
+    return 'Hello ' + name
+
+hello("Anne")
+
+
+

Classes are defined by the Class definitions keyword:

+
class Hello:
+    def __init__(self, name):
+        self._name = name
+    def say(self):
+        print('Hello', self._name)
+
+h = Hello("Richard")
+h.say()
+
+
+
+
+

Python type system

+

Python is strongly and dynamically typed.

+

Strong here means, roughly, that it’s not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior).

+
x = 42
+type(x)
+x + "hello"
+
+
+

Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type:

+
x = 42
+x = "hello"
+
+
+

Jargon: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation.

+

??? (lesson here)

+
+

Keypoints

+
    +

  • Python offers a nice set of basic types as many other programming languages

    • +

  • Python is strongly typed and dynamically typed

    • +
+
+
+
+
+

Jupyter

+
+

Questions

+
    +

  • What is the purpose of a “Computational narrative”?

    • +

  • What role does Jupyter play in development?

    • +

  • When is Jupyter not a good tool?

    • +
+
+
+

Objectives

+

This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.

+
    +

  • Be able to use Jupyter to run examples for the rest of the course.

    • +

  • Be able to run Jupyter in a directory do your own work.

    • +

  • You won’t be a Jupyter expert after this, but should be able to do the rest of the course.

    • +
+
+
+

What is Jupyter?

+

Jupyter is a web-based interactive computing system. It is most well known for having the notebook file format and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a computational narrative.

+

Jupyter is good for data exploration and interactive work.

+

We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.

+
+
+

Getting started with Jupyter

+
    +

  • Start JupyterLab: there are different ways, depending on how you installed it. See the installation instructions. If JupyterLab isn’t working yet, you have some time to try to follow the installation instructions now.

    • +
+
+

This is the command line method we went though in our installation instructions.

+
+
$ source ~/miniforge3/bin/activate
+$ conda activate python-for-scicomp
+$ jupyter-lab
+
+
+
+
+

For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need.

+

Here, we see a tour of the JupyterLab interface:

+

Main UI tour

+
+
+

Exercises 1

+
+

Exercises: Jupyter-1

+

If you aren’t set up with JupyterLab yet or these things don’t work, use this time to see the installation instructions and ask us any questions you may have.

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are using Miniforge from the command line, you can navigate with cd to a directory of your choice.

      • +

    • If you are starting from the Anaconda Navigator, change to the directory you want to use.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+
+
+

Running code in Jupyter

+

A notebook is divided into cells. Each cell has some input, and when it is executed an output appears right below it.

+

There are different types of cells: primarily code cells and markdown cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving style to text - you can check out this reference. For example the previous sentence is:

+
Markdown is a lightweight way of giving *style* to `text` - you 
+can check out [this reference](https://commonmark.org/help/).
+
+
+

notebook UI

+

When using keyboard shortcuts, you can switch between edit mode and command mode with Enter and Esc.

+

You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:

+
    +

  • Ctrl-Enter: Run cell

    • +

  • Shift-Enter: Run cell and select cell below

    • +

  • Alt-Enter: Run cell and insert new cell below

    • +

  • a / b: insert new cell above/below

    • +

  • m / y: markdown cell / code cell

    • +

  • x: cut cell

    • +

  • c: copy cell

    • +

  • v: paste cell

    • +

  • d, d: delete cell

    • +
+

Now, let’s look at some code samples:

+
+
+
for i in range(3):
+    print(i)
+
+
+
+
+
0
+1
+2
+
+
+
+
+
+
+
print(sum(range(5)))
+
+
+
+
+
10
+
+
+
+
+

By convention, if the last thing in a cell is an object, that object gets printed:

+
+
+
sum(range(5))
+sum(range(10))
+
+
+
+
+
45
+
+
+
+
+

In addition to raw cells, there are magics, which exist outside of Python. They are a property of the runtime itself (in Python’s case, they come from IPython. For example, the following cell magic %%timeit will use the timeit module to time a cell by running it multiple times):

+
+
+
%%timeit
+for x in range(1000000):
+    x**2
+
+
+
+
+
54.1 ms ± 993 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
+
+
+
+
+

Another example is %%bash which will turn the cell into a shell script (This will only work on operating systems with the Bash shell installed - MacOS and Linux at least):

+
+
+
%%bash
+for x in $(seq 3) ; do
+    echo $x
+done
+
+
+
+
+
1
+2
+3
+
+
+
+
+
    +

  • A cell magic starts with %%, goes on the first line of a cell, and applies to the whole cell

    • +

  • A line magic starts with %, goes on any line, and applies to that line.

    • +
+
+
+

Exercises 2

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+ +
+
+

Why Jupyter?

+
    +

  • Being able to edit, check, re-edit quickly is great for prototyping and testing new ideas

    +
      +

    • Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.

      • +
    +
    • +

  • You can make a complete story - in one place. No more having code, figures, and description in different places.

    +
      +

    • Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.

      • +
    +
    • +

  • Notebook as an interactive publication itself - for example the discovery of gravitational waves data is released as a notebook.

    • +

  • Jupyter Notebooks display on Github - low-barrier way to share your analysis.

    • +

  • Teaching - great for getting difficult software distribution out of the way.

    • +
+
+
+

Why not Jupyter?

+

Jupyter is great for many things, but there are some problems if not used well:

+
    +

  • They don’t promote modularity, and once you get started in a +notebook it can be hard to migrate to modules.

    • +

  • They are difficult to test. There are things to run notebooks as +unit tests like nbval, but it’s not +perfect.

    • +

  • Notebooks can be version controlled +(nbdime helps with that), but +there are still limitations.

    • +

  • You can change code after you run it and run code out of order. +This can make debugging hard and results irreproducible if you +aren’t careful.

    • +

  • Notebooks aren’t named by default and tend to acquire a bunch of +unrelated stuff. Be careful with organization!

    • +

  • Once lots of code is in notebooks, it can be hard to change to +proper programs that can be scripted.

    • +
+

You can read more about these downsides https://scicomp.aalto.fi/scicomp/jupyter-pitfalls/.

+

But these downsides aren’t specific to Jupyter! They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.

+
+
+

Exercises 3

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Jupyter is powerful and can be used for interactive work

    • +

  • … but not the end solution when you need to scale up.

    • +
+
+
+
+
+

NumPy

+
+

Questions

+
    +

  • Why use NumPy instead of pure python?

    • +

  • How to use basic NumPy?

    • +

  • What is vectorization?

    • +
+
+
+

Objectives

+
    +

  • Understand the Numpy array object

    • +

  • Be able to use basic NumPy functionality

    • +

  • Understand enough of NumPy to seach for answers to the rest of your questions ;)

    • +
+

We expect most people to be able to do all the basic exercises +here. It is probably quite easy for many people; we have advanced +exercises at the end in that case.

+
+

So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible.

+
+

What is an array?

+

For example, consider [1, 2.5, 'asdf', False, [1.5, True]] - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately.

+

NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it.

+

An array is a ‘grid’ of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has:

+
    +

  • dtype - data type. Arrays always contain one type

    • +

  • shape - shape of the data, for example 3×2 or 3×2×500 or even +500 (one dimensional) or [] (zero dimensional).

    • +

  • data - raw data storage in memory. This can be passed to C or +Fortran code for efficient calculations.

    • +
+

To test the performance of pure Python vs NumPy we can write in our jupyter notebook:

+

Create one list and one ‘empty’ list, to store the result in

+
a = list(range(10000))
+b = [ 0 ] * 10000
+
+
+

In a new cell starting with %%timeit, loop through the list a and fill the second list b with a squared

+
%%timeit
+for i in range(len(a)):
+  b[i] = a[i]**2
+
+
+

That looks and feels quite fast. But let’s take a look at how NumPy performs for the same task.

+

So for the NumPy example, create one array and one ‘empty’ array to store the result in

+
import numpy as np
+a = np.arange(10000)
+b = np.zeros(10000)
+
+
+

In a new cell starting with %%timeit, fill b with a squared

+
%%timeit
+b = a ** 2
+
+
+

We see that compared to working with numpy arrays, working with traditional python lists is actually slow.

+
+
+

Creating arrays

+

There are different ways of creating arrays (numpy.array(), numpy.ndarray.shape, numpy.ndarray.size):

+
a = np.array([1,2,3])               # 1-dimensional array (rank 1)
+b = np.array([[1,2,3],[4,5,6]])     # 2-dimensional array (rank 2)
+
+b.shape                             # the shape (rows,columns)
+b.size                              # number of elements
+
+
+

In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (numpy.zeros(), numpy.ones(), numpy.full(), numpy.eye(), numpy.arange(), numpy.linspace()):

+
np.zeros((2, 3))             # 2x3 array with all elements 0
+np.ones((1,2))               # 1x2 array with all elements 1
+np.full((2,2),7)             # 2x2 array with all elements 7
+np.eye(2)                    # 2x2 identity matrix
+
+np.arange(10)                # Evenly spaced values in an interval
+np.linspace(0,9,10)          # same as above, see exercise
+
+c = np.ones((3,3))
+d = np.ones((3, 2), 'bool')  # 3x2 boolean array
+
+
+

Arrays can also be stored and read from a (.npy) file (numpy.save(), numpy.load()):

+
np.save('x.npy', a)           # save the array a to a .npy file
+x = np.load('x.npy')          # load an array from a .npy file and store it in variable x
+
+
+

In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (numpy.ndarray.dtype, numpy.ndarray.astype()):

+
d.dtype                    # datatype of the array
+d.astype('int')            # change datatype from boolean to integer
+
+
+

In the last example, .astype('int'), it will make a copy of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed.

+
+
+

Exercises 1

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+ +
+
+

Array maths and vectorization

+

Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do.

+

By default, basic arithmetic (+, -, *, /) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is “vectorized” +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop.

+

Note that unlike Matlab, where * means matrix multiplication, NumPy uses +* to perform element-by-element multiplication and uses the @ symbol to +perform matrix multiplication:

+
a = np.array([[1,2],[3,4]])
+b = np.array([[5,6],[7,8]])
+
+# Addition
+c = a + b
+d = np.add(a,b)
+
+# Matrix multiplication
+e = a @ b
+f = np.dot(a, b)
+
+
+

Other common mathematical operations include: - (numpy.subtract), * (numpy.multiply), / (numpy.divide), .T (numpy.transpose()), numpy.sqrt, numpy.sum(), numpy.mean(), …

+
+
+

Exercises 2

+
+

Exercises: Numpy-2

+ +
+ +
+
+

Indexing and Slicing

+
+

See also

+

Numpy basic indexing docs

+
+

NumPy has many ways to extract values out of arrays:

+
    +

  • You can select a single element

    • +

  • You can select rows or columns

    • +

  • You can select ranges where a condition is true.

    • +
+

Clever and efficient use of these operations is a key to NumPy’s +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C.

+
a = np.arange(16).reshape(4, 4)  # 4x4 matrix from 0 to 15
+a[0]                             # first row
+a[:,0]                           # first column
+a[1:3,1:3]                       # middle 2x2 array
+
+a[(0, 1), (1, 1)]                # second element of first and second row as array
+
+
+

Boolean indexing on above created array:

+
idx = (a > 0)      # creates boolean matrix of same size as a
+a[idx]             # array with matching values of above criterion
+
+a[a > 0]           # same as above in one line
+
+
+
+
+

Exercises 3

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+ +
+
+

Types of operations

+

There are different types of standard operations in NumPy:

+

ufuncs, “universal functions”: These are element-by-element +functions with standardized arguments:

+
    +

  • One, two, or three input arguments

    • +

  • For example, a + b is similar to np.add(a, b) but the ufunc +has more control.

    • +

  • out= output argument, store output in this array (rather than +make a new array) - saves copying data!

    • +

  • See the full reference

    • +

  • They also do broadcasting (ref). Can you add a 1-dimensional array of shape (3) +to an 2-dimensional array of shape (3, 2)? With broadcasting you +can!

    +
    a = np.array([[1, 2, 3],
+              [4, 5, 6]])
+b = np.array([10, 10, 10])
+a + b                       # array([[11, 12, 13],
+                            #        [14, 15, 16]])
+
    +
    +

    Broadcasting is smart and consistent about what it does, which I’m +not clever enough to explain quickly here: the manual page on +broadcasting. +The basic idea is that it expands dimensions of the smaller array so +that they are compatible in shape.

    +
    • +
+

Array methods do something to one array:

+
    +

  • Some of these are the same as ufuncs:

    +
    x = np.arange(12)
+x.shape = (3, 4)
+x                    #  array([[ 0,  1,  2,  3],
+                     #         [ 4,  5,  6,  7],
+                     #         [ 8,  9, 10, 11]])
+x.max()              #  11
+x.max(axis=0)        #  array([ 8,  9, 10, 11])
+x.max(axis=1)        #  array([ 3,  7, 11])
+
    +
    +
    • +
+

Other functions: there are countless other functions covering +linear algebra, scientific functions, etc.

+
+
+

Exercises 4

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+ +
+
+

Linear algebra and other advanced math

+

In general, you use arrays (n-dimensions), not matrixes +(specialized 2-dimensional) in NumPy.

+

Internally, NumPy doesn’t invent its own math routines: it relies on +BLAS +and LAPACK to do this kind +of math - the same as many other languages.

+
    +

  • Linear algebra in numpy

    • +

  • Many, many other array functions

    • +

  • Scipy has even +more functions

    • +

  • Many other libraries use NumPy arrays as the standard data +structure: they take data in this format, and return it similarly. +Thus, all the other packages you may want to use are compatible

    • +

  • If you need to write your own fast code in C, NumPy arrays can be +used to pass data. This is known as extending Python.

    • +
+
+
+

Additional exercises

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally.

    • +

  • Be aware of some NumPy specific peculiarities

    • +
+
+
+
+
+

Advanced NumPy

+
+

Questions

+
    +

  • How can NumPy be so fast?

    • +

  • Why are some things fast and some things slow?

    • +

  • How can I control whether NumPy makes a copy or operates in-place?

    • +
+
+
+

Objectives

+
    +

  • Understand why NumPy has so many specialized functions for specific operations

    • +

  • Understand the underlying machinery of the Numpy ndarray object

    • +

  • Understand when and why NumPy makes a copy of the data rather than a view

    • +
+

This is intended as a follow-up to the basic NumPy lesson. The intended +audience for this advanced lesson is those who have used NumPy before and +now want to learn how to get the most out of this amazing package.

+
+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +Guide to NumPy by +Travis E. Oliphant, its initial creator.

+
+

NumPy can be really fast

+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast.

+

How fast can NumPy be? Let’s race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:

+
#include <stdlib.h>
+#include <stdio.h>
+#define N_ELEMENTS 100000000
+int main(int argc, char** argv) {
+    double* a = (double*) malloc(sizeof(double) * N_ELEMENTS);
+    int i;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        a[i] = (double) rand() / RAND_MAX;
+    }
+    double sum = 0;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        sum += a[i];
+    }
+    printf("%f", sum);
+    return 0;
+}
+
+
+
+
+

Exercise 1

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lesson before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+ +
+
+

The libraries behind the curtain: MKL and BLAS

+

NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel’s Math Kernel Library (MKL), +which are in turn derived from a Fortran library called +Basic Linear Algebra Subprograms (BLAS). +BLAS for Fortran was published in 1979 +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +specialized CPU instructions for manipulating arrays. +In other words, they are fast.

+

One of the functions inside the BLAS library is a +function +to compute the “norm” of a vector, which is the same as computing its length, using the +Pythagorean theorem: +\(\sqrt(a[0]^2 + a[1]^2 + \ldots)\).

+

Let’s race the BLAS function versus a naive “manual” version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:

+
import numpy as np
+rng = np.random.default_rng(seed=0)
+a = rng.random(100_000_000)
+
+
+

We now implement the Pythagorean theorem using basic NumPy functionality and +use %%timeit to record how long it takes to execute:

+
%%timeit
+l = np.sqrt(np.sum(a ** 2))
+print(l)
+
+
+

And here is the version using the specialized BLAS function norm():

+
%%timeit
+l = np.linalg.norm(a)
+print(l)
+
+
+
+
+

NumPy tries to avoid copying data

+

Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy’s +numpy.ndarray datastructure works behind the scenes.

+
+

An example: matrix transpose

+

Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let’s see how long NumPy’s +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +rand() matrix:

+
import numpy as np
+a = np.random.rand(10_000, 20_000)
+print(f'Matrix `a` takes up {a.nbytes / 10**6} MB')
+
+
+

Let’s time the transpose() method:

+
%%timeit
+b = a.transpose()
+
+
+

It takes mere nanoseconds to transpose 1600 MB of data! How?

+
+
+

The ndarray exposed

+

The first thing you need to know about numpy.ndarray is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector.

+_images/01_memory_layout.svg +

NumPy is faking the second dimension behind the scenes! When we request the +element at say, [2, 3], NumPy converts this to the correct index in the +long 1D array [11].

+
+
    +

  • Converting [2, 3] → [11] is called “raveling”

    • +

  • The reverse, converting [11] → [2, 3] is called “unraveling”

    • +
+
+

The implications of this are many, so take let’s take some time to understand +it properly by writing our own ravel() function.

+
+
+
+

Exercise 2

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+ +
+
+

Strides

+

As seen in the exercise, to get to the next row, we have to skip over +n_cols indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of “strides”:

+
np.zeros((4, 8)).strides           # (64, 8)
+np.zeros((4, 5, 6, 7, 8)).strides  # (13440, 2688, 448, 64, 8)
+
+
+

The strides attribute contains for each dimension, the number of bytes (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes.

+

So now we know the mystery behind the speed of transpose(). NumPy can avoid +copying any data by just modifying the strides of the array:

+
import numpy as np
+
+a = np.random.rand(10_000, 20_000)
+b = a.transpose()
+
+print(a.strides)  # (160000, 8)
+print(b.strides)  # (8, 160000)
+
+
+
+

Another example: reshaping

+

Modifying the shape of an array through numpy.reshape() is also +accomplished without any copying of data by modifying the strides:

+
a = np.random.rand(20_000, 10_000)
+print(f'{a.strides=}')  # (80000, 8)
+b = a.reshape(40_000, 5_000)
+print(f'{b.strides=}')  # (40000, 8)
+c = a.reshape(20_000, 5_000, 2)
+print(f'{c.strides=}')  # (80000, 16, 8)
+
+
+
+
+
+

Exercises 3

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+ +
+
+

A fast thing + a fast thing = a fast thing?

+

If numpy.transpose() is fast, and numpy.reshape() is fast, then +doing them both must be fast too, right?:

+
# Create a large array
+a = np.random.rand(10_000, 20_000)
+
+
+

Measuring the time it takes to first transpose and then reshape:

+
%%timeit -n 1 -r 1
+a.T.reshape(40_000, 5_000)
+
+
+

In this case, the data actually had to be copied and it’s super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the strides:

+
a = np.array([[1, 2, 3], [4, 5, 6]])
+
+print('Original array:')
+print(a)
+
+print('\nTransposed:')
+print(a.T)
+
+print('\nTransposed and then reshaped:')
+print(a.T.reshape(2, 3))
+
+
+
+
+

Copy versus view

+

Whenever NumPy constructs a new array by modifying the strides instead of +copying data, we way it created a “view”. This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +numpy.ndarray object will have a reference to the original array in +its base attribute:

+
a = np.zeros((5, 5))
+print(a.base)  # None
+b = a[:2, :2]
+print(b.base.shape)  # (5, 5)
+
+
+
+

Warning

+

When you create a large array and select only a portion of it, the large +array will stay in memory if a view was created!

+
+

The new array b object has a pointer to the same memory buffer as the array +it has been derived from:

+
print(a.__array_interface__['data'])
+print(b.__array_interface__['data'])
+
+
+

Views are created by virtue of modifying the value of the shape attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:

+
b = a[1:3, 1:3]   # This view does not start at the beginning
+offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0]
+print('Offset:', offset, 'bytes')  # Offset: 48 bytes
+
+
+_images/02_views.svg +

Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:

+
b[0, 0] = 1.
+print(a)  # Original matrix was modified
+
+
+

Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:

+
c = a[[0, 2]]  # Select rows 0 and 2
+print(c.base)  # None. So not a view.
+
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • The best way to make your code more efficient is to learn more about the +NumPy API and use specialized functions whenever possible.

    • +

  • NumPy will avoid copying data whenever it can. Whether it can depends on +what kind of layout the data is currently in.

    • +
+
+
+
+
+

Pandas

+
+

Questions

+
    +

  • How do I learn a new Python package?

    • +

  • How can I use pandas dataframes in my research?

    • +
+
+
+

Objectives

+
    +

  • Learn simple and some more advanced usage of pandas dataframes

    • +

  • Get a feeling for when pandas is useful and know where to find more information

    • +

  • Understand enough of pandas to be able to read its documentation.

    • +
+
+

Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including:

+ +
+

A quick Pandas preview

+

Let’s get a flavor of what we can do with pandas (you won’t be able to follow everything yet). We will be working with an example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:

+
import pandas as pd
+
+
+

We can download the data from this GitHub repository +by visiting the page and saving it to disk, or by directly reading into +a DataFrame:

+
url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv"
+titanic = pd.read_csv(url, index_col='Name')
+
+
+

We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:

+
# print the first 5 lines of the dataframe
+titanic.head()
+
+
+
# print summary statistics for each column
+titanic.describe()
+
+
+

Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38% of passengers survived, etc.

+

Let’s say we’re interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn’t survive, and plot corresponding histograms of +the age distribution (pandas.DataFrame.groupby(), pandas.DataFrame.hist()):

+
print(titanic.groupby("Survived")["Age"].mean())
+
+
+
titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10),
+             layout=(2,1), zorder=2, sharex=True, rwidth=0.9);
+
+
+

Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let’s get back to basics.

+
+

Getting help

+

Series and DataFrames have a lot functionality, but +how can we find out what methods are available and how they work? One way is to visit +the API reference +and reading through the list. +Another way is to use the autocompletion feature in Jupyter and type e.g. +titanic["Age"]. in a notebook and then hit TAB twice - this should open +up a list menu of available methods and attributes.

+

Jupyter also offers quick access to help pages (docstrings) which can be +more efficient than searching the internet. Two ways exist:

+
    +

  • Write a function name followed by question mark and execute the cell, e.g. +write titanic.hist? and hit SHIFT + ENTER.

    • +

  • Write the function name and hit SHIFT + TAB.

    • +

  • Right click and select “Show contextual help”. This tab will +update with help for anything you click.

    • +
+
+
+
+

What’s in a dataframe?

+

As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +pandas.DataFrame +is composed of rows and columns:

+_images/01_table_dataframe.svg +

Each column of a dataframe is a pandas.Series object +- a dataframe is thus a collection of series:

+
# print some information about the columns
+titanic.info()
+
+
+

Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type int64 or of type object.

+

Let’s inspect one column of the Titanic passenger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):

+
titanic["Age"]
+titanic.Age          # same as above
+
+
+
type(titanic["Age"]) # a pandas Series object
+
+
+

The columns have names. Here’s how to get them (columns):

+
titanic.columns
+
+
+

However, the rows also have names! This is what Pandas calls the index:

+
titanic.index
+
+
+

We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and +values. We can refer to columns and rows either by their name +(loc, at) or by +their index (iloc, +iat):

+
titanic.loc['Lam, Mr. Ali',"Age"]          # select single value by row and column
+titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"]  # slice the dataframe by row and column *names*
+titanic.iloc[0:2,3:6]                      # same slice as above by row and column *numbers*
+
+titanic.at['Lam, Mr. Ali',"Age"] = 42      # set single value by row and column *name* (fast)
+titanic.at['Lam, Mr. Ali',"Age"]           # select single value by row and column *name* (fast)
+titanic.iat[0,5]                           # select same value by row and column *number* (fast)
+
+titanic["is_passenger"] = True             # set a whole column
+
+
+

Dataframes also support boolean indexing, just like we saw for numpy +arrays:

+
titanic[titanic["Age"] > 70]
+# ".str" creates a string object from a column
+titanic[titanic.index.str.contains("Margaret")]
+
+
+

What if your dataset has missing data? Pandas uses the value numpy.nan +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:

+
titanic.isna()                    # returns boolean mask of NaN values
+titanic.dropna()                  # drop missing values
+titanic.dropna(how="any")         # or how="all"
+titanic.dropna(subset=["Cabin"])  # only drop NaNs from one column
+titanic.fillna(0)                 # replace NaNs with zero
+titanic.fillna(method='ffill')    # forward-fill NaNs
+
+
+
+
+

Exercises 1

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+
+
+

Tidy data

+

The above analysis was rather straightforward thanks to the fact +that the dataset is tidy.

+_images/tidy_data.png +

In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data.

+

What would untidy data look like? Here’s an example from +some run time statistics from a 1500 m running event:

+
runners = pd.DataFrame([
+              {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240},
+              {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300},
+              {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360},
+          ])
+
+
+

What makes this data untidy is that the column names 400, 800, 1200, 1500 +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row.

+

To make untidy data tidy, a common operation is to “melt” it, +which is to convert it from wide form to a long form:

+
runners = pd.melt(runners, id_vars="Runner",
+              value_vars=[400, 800, 1200, 1500],
+              var_name="distance",
+              value_name="time"
+          )
+
+
+

In this form it’s easier to filter, group, join +and aggregate the data, and it’s also easier to model relationships +between variables.

+

The opposite of melting is to pivot data, which can be useful to +view data in different ways as we’ll see below.

+

For a detailed exposition of data tidying, have a look at +this article.

+
+
+

Working with dataframes

+

We saw above how we can read in data into a dataframe using the read_csv() function. +Pandas also understands multiple other formats, for example using read_excel, +read_hdf, read_json, etc. (and corresponding methods to write to file: +to_csv, to_excel, to_hdf, to_json, etc.)

+

But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +DataFrame docs):

+
import numpy as np
+dates = pd.date_range('20130101', periods=6)
+df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD'))
+df
+
+
+

or a dictionary (see same docs):

+
df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'],
+                   'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'],
+                   'C': np.array([3] * 8, dtype='int32'),
+                   'D': np.random.randn(8),
+                   'E': np.random.randn(8)})
+df
+
+
+

There are many ways to operate on dataframes. Let’s look at a +few examples in order to get a feeling of what’s possible +and what the use cases can be.

+

We can easily split and concatenate dataframes:

+
sub1, sub2, sub3 = df[:2], df[2:4], df[4:]
+pd.concat([sub1, sub2, sub3])
+
+
+

When pulling data from multiple dataframes, a powerful pandas.DataFrame.merge method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:

+
age = pd.DataFrame([
+    {"Runner": "Runner 4", "Age": 18},
+    {"Runner": "Runner 2", "Age": 21},
+    {"Runner": "Runner 1", "Age": 23},
+    {"Runner": "Runner 3", "Age": 19},
+])
+
+
+

We now want to use this table to annotate the original runners table from +before with their age. Note that the runners and age dataframes have a +different ordering to it, and age has an entry for Dave which is not +present in the runners table. We can let Pandas deal with all of it using +the merge method:

+
# Add the age for each runner
+runners.merge(age, on="Runner")
+
+
+

In fact, much of what can be done in SQL +is also possible with pandas.

+

groupby is a powerful method which splits a dataframe and aggregates data +in groups. To see what’s possible, let’s return to the Titanic dataset. Let’s +test the old saying “Women and children first”. We start by creating a new +column Child to indicate whether a passenger was a child or not, based on +the existing Age column. For this example, let’s assume that you are a +child when you are younger than 12 years:

+
titanic["Child"] = titanic["Age"] < 12
+
+
+

Now we can test the saying by grouping the data on Sex and then creating further sub-groups based on Child:

+
titanic.groupby(["Sex", "Child"])["Survived"].mean()
+
+
+

Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +std, min, +max, cumsum, +median, skew, +var etc.

+
+
+

Exercises 2

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+
+
+

Time series superpowers

+

An introduction of pandas wouldn’t be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv .

+

Unfortunately this API does not allow “non-browser requests”, so +pandas.read_csv will not work directly on it. Instead, we put a +local copy on Github which we can access (the original data is CC-0, +so we are allowed to do this). (Aside: if you do JupyterLab → +File → Open from URL → paste the URL above, it will open it in +JupyterLab and download a copy for your use.)

+

We can then load and explore the data:

+
nobel = pd.read_csv("https://github.com/AaltoSciComp/python-for-scicomp/raw/master/resources/data/laureate.csv")
+nobel.head()
+
+
+

This dataset has three columns for time, “born”/”died” and “year”. +These are represented as strings and integers, respectively, and +need to be converted to datetime format. pandas.to_datetime() +makes this easy:

+
# the errors='coerce' argument is needed because the dataset is a bit messy
+nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce')
+nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce')
+nobel["year"] = pd.to_datetime(nobel["year"], format="%Y")
+
+
+

Pandas knows a lot about dates (using .dt accessor):

+
print(nobel["born"].dt.day)
+print(nobel["born"].dt.year)
+print(nobel["born"].dt.weekday)
+
+
+

We can add a column containing the (approximate) lifespan in years rounded +to one decimal:

+
nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1)
+
+
+

and then plot a histogram of lifespans:

+
nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9)
+
+
+

Finally, let’s see one more example of an informative plot (boxplot()) +produced by a single line of code:

+
nobel.boxplot(column="lifespan", by="category")
+
+
+
+
+

Exercises 3

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries (you need to look at the +data and find how countries are written, and replace COUNTRY +with those strings):

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Beyond the basics

+

Larger DataFrame operations might be faster using eval() with string expressions, see:

+
import pandas as pd
+# Make some really big dataframes
+nrows, ncols = 100000, 100
+rng = np.random.RandomState(42)
+df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols))
+                      for i in range(4))
+
+
+

Adding dataframes the pythonic way yields:

+
%timeit df1 + df2 + df3 + df4
+# 80ms
+
+
+

And by using eval():

+
%timeit pd.eval('df1 + df2 + df3 + df4')
+# 40ms
+
+
+

We can assign function return lists as dataframe columns:

+
def fibo(n):
+    """Compute Fibonacci numbers. Here we skip the overhead from the
+    recursive function calls by using a list. """
+    if n < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif n < 2:
+        return n
+    memo = [0]*(n+1)
+    memo[0] = 0
+    memo[1] = 1
+    for i in range(2, n+1):
+        memo[i] = memo[i-1] + memo[i-2]
+    return memo
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = fibo(99)  # Assigns list to column
+
+
+

There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its API. You should try to get good at +searching the web for an example showing what you can do. And when +there is not, you can always +apply your own functions to the data using apply:

+
from functools import lru_cache
+
+@lru_cache
+def fib(x):
+    """Compute Fibonacci numbers. The @lru_cache remembers values we
+    computed before, which speeds up this function a lot."""
+    if x < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif x < 2:
+        return x
+    else:
+        return fib(x - 2) + fib(x - 1)
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = df['Generation'].apply(fib)
+
+
+

Note that the numpy precision for integers caps at int64 while python ints are unbounded – +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df[‘Number of Rabbits’][99] given by both functions above +is in fact <class ‘int’>.

+
+
+

Alternatives to Pandas

+

Polars

+

Polars is a DataFrame library designed to processing data with a fast lighting time. Polars is implemented in Rust Programming language and uses Apache Arrow as its memory format.

+

Dask

+

Dask is a Python package for parallel computing in Python and uses parallel data-frames for dealing with very large arrays.

+

Vaex

+

Vaex is a high performance Python library for lazy Out-of-Core DataFrames, to visualize and explore big tabular datasets.

+
+

Keypoints

+
    +

  • pandas dataframes are a good data structure for tabular data

    • +

  • Dataframes allow both simple and advanced analysis in very compact form

    • +
+
+
+
+
+

Xarray

+
+

Questions

+
    +

  • How shall we deal with real-world datasets that are usually more than just raw numbers?

    • +

  • What is the advantage of using labelled multidimensional arrays?

    • +

  • What does Xarray add to Numpy and Pandas to address these questions?

    • +
+
+
+

Objectives

+
    +

  • Learn how to apply operations over dimensions and select values by label

    • +

  • Understand Xarray’s DataArrays and Datasets

    • +

  • Learn how to easily plot data in Xarray

    • +

  • Learn how to turn your own data into an Xarray Dataset

    • +
+
+

We have already seen how Pandas simplifies working with tabular NumPy data by adding labels to columns and rows. In this lesson, we take a look at how xarray can be used to add the same functionality to multidimensional data. Let’s consider the following example:

+

Imagine we have a dataset representing temperature measurements across different heights, latitudes, and longitudes. We can store the temperature data as a 3D NumPy array where each axis corresponds to one of these dimensions:

+
import numpy as np
+# Create a 3D numpy array: height x latitude x longitude
+data = np.random.rand(10, 5, 5)  # 10 heights, 5 latitudes, 5 longitudes
+
+
+

Let’s assume now we want to take a look at a specific value in the dataset at a certain height, latitude, and longitude. We could do this by indexing the array with the corresponding indices:

+
# Get the temperature at height 3, latitude 2, longitude 4
+temperature = data[3, 2, 4]
+
+
+

OK, we got a value, but how do we know whether this value corresponds to the correct height, latitude and longitude? Are we sure that latitude was the second dimension in the dataset? Was it the second or third index that corresponds to the correct position? In pure NumPy, we are mostly left in the dark and need to manually keep track of these things.

+

Unfortunately, Pandas isn’t of much help either since it is not designed for data with more than 2 dimensions. Fortunately, some clever climate scientists have come up with a solution to this problem and created Xarray.

+
+

What is Xarray?

+

Xarray is a powerful Python library that introduces labelled multidimensional arrays. This means the axes have labels (=dimensions), each row/column has a label (coordinates), and labels can even have units of measurement. This makes it much easier to follow what the data in an array means and select specific portions of data.

+

We will first download a dataset similar to the example above to illustrate the advantages of Xarray. We will cover how to transform your own data into an Xarray Dataset later in this lecture.

+
+

Note

+

If you have set up your python-for-scicomp environment yesterday or earlier, you need to install the packages netcdf4 and pythia_datasets manually. You can do this by running the following command in your (JupyterLab) terminal:

+
conda install netcdf4 pythia-datasets -c conda-forge
+
+
+
+

Let us open a python shell and download a public dataset:

+
>>> from pythia_datasets import DATASETS
+>>> filepath = DATASETS.fetch('NARR_19930313_0000.nc')
+
+
+

We can now import xarray and open the dataset. Le’ts take a look at what it contains:

+
>>> import xarray as xr
+>>> ds = xr.open_dataset(filepath)
+>>> ds
+<xarray.Dataset> Size: 15MB
+Dimensions:                       (time1: 1, isobaric1: 29, y: 119, x: 268)
+Coordinates:
+  * time1                         (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1                     (isobaric1) float32 116B 100.0 125.0 ... 1e+03
+  * y                             (y) float32 476B -3.117e+03 ... 714.1
+  * x                             (x) float32 1kB -3.324e+03 ... 5.343e+03
+Data variables:
+    u-component_of_wind_isobaric  (time1, isobaric1, y, x) float32 4MB ...
+    LambertConformal_Projection   int32 4B ...
+    lat                           (y, x) float64 255kB ...
+    lon                           (y, x) float64 255kB ...
+    Geopotential_height_isobaric  (time1, isobaric1, y, x) float32 4MB ...
+    v-component_of_wind_isobaric  (time1, isobaric1, y, x) float32 4MB ...
+    Temperature_isobaric          (time1, isobaric1, y, x) float32 4MB ...
+Attributes:
+    Originating_or_generating_Center:     US National Weather Service, Nation...
+    Originating_or_generating_Subcenter:  North American Regional Reanalysis ...
+    GRIB_table_version:                   0,131
+    Generating_process_or_model:          North American Regional Reanalysis ...
+    Conventions:                          CF-1.6
+    history:                              Read using CDM IOSP GribCollection v3
+    featureType:                          GRID
+    History:                              Translated to CF-1.0 Conventions by...
+    geospatial_lat_min:                   10.753308882144761
+    geospatial_lat_max:                   46.8308828962289
+    geospatial_lon_min:                   -153.88242040519995
+    geospatial_lon_max:                   -42.666108129242815
+
+
+

That was a lot of information at once, but let’s break it down.

+
+
    +

  • Close to the top of the output we see the Dimensions of the dataset: time1, isobaric1, y, and x.

    • +

  • Below the dimensions, we see the Coordinates of the dataset. These are for each dimension the labels for each value along that dimension. For example, we have a timestamp of each value along the first dimension (time1).

    • +

  • The Data variables are the actual data stored in the dataset. We see that the dataset contains a bunch of arrays, most of which are 4-dimensional, where each dimension corresponds to one of the Dimensions described above. There are also some 2-dimensional arrays that only have some of the Dimensions described above.

    • +

  • At the bottom, we see the Attributes of the dataset. This is a dictionary that stores metadata about the dataset.

    • +
+
+

The following image shows the structure of this particular Xarray Dataset:

+
+
_images/xarray_dataset_image.png +
+
+
+

Accessing and manipulating data in Xarray

+

An xarray Dataset typically consists of multiple DataArrays. Our example dataset has 7 of them (u-component_of_wind_isobaric, LambertConformal_Projection, lat, lon, Geopotential_height_isobaric, v-component_of_wind_isobaric, Temperature_isobaric). +We can select a single DataArray from the dataset using a dictionary-like syntax:

+
>>> temperature_data = ds['Temperature_isobaric']
+>>> temperature_data
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, isobaric1: 29, y: 119,
+                                          x: 268)> Size: 4MB
+[924868 values with dtype=float32]
+Coordinates:
+  * time1      (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1  (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03
+  * y          (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+  * x          (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03
+Attributes:
+    long_name:           Temperature @ Isobaric surface
+    units:               K
+    description:         Temperature
+    grid_mapping:        LambertConformal_Projection
+    Grib_Variable_Id:    VAR_7-15-131-11_L100
+    Grib1_Center:        7
+    Grib1_Subcenter:     15
+    Grib1_TableVersion:  131
+    Grib1_Parameter:     11
+    Grib1_Level_Type:    100
+    Grib1_Level_Desc:    Isobaric surface
+
+
+

Xarray uses Numpy(-like) arrays under the hood, we can always access the underlying Numpy array using the .values attribute:

+
>>> temperature_numpy = ds['Temperature_isobaric'].values
+>>> temperature_numpy
+array([[[[201.88957, 202.2177 , 202.49895, ..., 195.10832, 195.23332,
+          195.37395],
+         [201.68645, 202.0302 , 202.3427 , ..., 195.24895, 195.38957,
+          195.51457],
+         [201.5302 , 201.87395, 202.20207, ..., 195.37395, 195.51457,
+          195.63957],
+         ...,
+         [276.735  , 276.70374, 276.6881 , ..., 289.235  , 289.1725 ,
+          289.07874],
+         [276.86   , 276.84436, 276.78186, ..., 289.1881 , 289.11   ,
+          289.01624],
+         [277.01624, 276.82874, 276.82874, ..., 289.14124, 289.0475 ,
+          288.96936]]]], dtype=float32)
+
+
+

Xarray allows you to select data using the .sel() method, which uses the labels of the dimensions to extract data:

+
>>> ds['Temperature_isobaric'].sel(x='-3292.0078')
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, isobaric1: 29, y: 119)> Size: 14kB
+array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895],
+        [202.58566, 202.58566, ..., 219.16379, 219.28879],
+        ...,
+        [292.1622 , 292.14658, ..., 275.05283, 275.11533],
+        [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32)
+Coordinates:
+  * time1      (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1  (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03
+  * y          (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+    x          float32 4B -3.292e+03
+Attributes:
+    long_name:           Temperature @ Isobaric surface
+    units:               K
+    description:         Temperature
+    grid_mapping:        LambertConformal_Projection
+    Grib_Variable_Id:    VAR_7-15-131-11_L100
+    Grib1_Center:        7
+    Grib1_Subcenter:     15
+    Grib1_TableVersion:  131
+    Grib1_Parameter:     11
+    Grib1_Level_Type:    100
+    Grib1_Level_Desc:    Isobaric surface
+
+
+

We can still access the same data by index using the .isel() method:

+
>>> ds['Temperature_isobaric'].isel(x=1)
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, isobaric1: 29, y: 119)> Size: 14kB
+array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895],
+        [202.58566, 202.58566, ..., 219.16379, 219.28879],
+        ...,
+        [292.1622 , 292.14658, ..., 275.05283, 275.11533],
+        [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32)
+Coordinates:
+  * time1      (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1  (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03
+  * y          (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+    x          float32 4B -3.292e+03
+Attributes:
+    long_name:           Temperature @ Isobaric surface
+    units:               K
+    description:         Temperature
+    grid_mapping:        LambertConformal_Projection
+    Grib_Variable_Id:    VAR_7-15-131-11_L100
+    Grib1_Center:        7
+    Grib1_Subcenter:     15
+    Grib1_TableVersion:  131
+    Grib1_Parameter:     11
+    Grib1_Level_Type:    100
+    Grib1_Level_Desc:    Isobaric surface
+
+
+

A DataArray provides a lot of the functionality we expect from Numpy arrays, such as sum(), mean(), median(), min(), and max() that we can use these methods to aggregate data over one or multiple dimensions:

+
>>> # Calculate the mean over the 'isobaric1' dimension
+>>> ds['Temperature_isobaric'].mean(dim='isobaric1')
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, y: 119, x: 268)> Size: 128kB
+array([[[259.88446, 259.90222, 259.91678, ..., 262.61667, 262.6285 ,
+         262.65167],
+        [259.74866, 259.76752, 259.78638, ..., 262.5757 , 262.58218,
+         262.57516],
+        [259.6156 , 259.63498, 259.65115, ..., 262.52075, 262.51215,
+         262.4976 ],
+        ...,
+        [249.8796 , 249.83649, 249.79501, ..., 254.43617, 254.49059,
+         254.54985],
+        [249.8505 , 249.80202, 249.75244, ..., 254.37044, 254.42378,
+         254.47711],
+        [249.82195, 249.75998, 249.71204, ..., 254.30956, 254.35805,
+         254.41139]]], dtype=float32)
+Coordinates:
+  * time1    (time1) datetime64[ns] 8B 1993-03-13
+  * y        (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+  * x        (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03
+
+
+

Let’s take a look at a concrete example and compare it to NumPy. We will calculate the max temperature over the ‘isobaric1’ dimension at a specific value for x:

+
>>> # Xarray
+>>> ds['Temperature_isobaric'].sel(x='-3259.5447').max(dim='isobaric1')
+array([[294.11   , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 ,
+        ...,
+        276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]],
+      dtype=float32)
+
+
+

In comparison, if we were to use plain Numpy, this would be:

+
>>> # NumPy
+>>> np.max(temperature_numpy[:, :, :, 2 ], axis = 1)
+array([[294.11   , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 ,
+        ...,
+        276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]],
+      dtype=float32)
+
+
+

As you can see, the Xarray code is much more readable and we didn’t need to keep track of the right indices and order of the dimensions.

+
+
+

Plotting data in Xarray

+

Like Pandas, Xarray comes with basic plotting capabilities. We can easily plot data in 1D and 2D using the .plot() method. Xarray uses a widely used plotting library called matplotlib for this. When calling the .plot() method, Xarray checks the dimensionality of the data and plots it accordingly. Let’s import matplotlib and plot the data:

+
>>> import matplotlib.pyplot as plt
+
+>>> ds['Temperature_isobaric'].isel(x=2).plot()
+>>> plt.show()
+
+
+

For a 2D DataArray the plot would resemble this example:

+
+
_images/xarray_2d_plot.png +
+

Note, that we didn’t specify the axes labels, Xarray automatically used the coordinates of the DataArray for the plot. This plot might not be one you include directly in a paper, but it is a great way to quickly visualize your data.

+

Let’s have a look at a dataslice of 1D data:

+
>>> ds['Temperature_isobaric'].isel(x=2, y=5).plot()
+>>> plt.show()
+
+
+

The resulting plot detects the dimentionality of the data and plots it accordingly:

+
+
_images/xarray_1d_plot.png +
+

If the data has more than two dimensions, Xarray will plot a histogram of the data:

+
>>> ds['Temperature_isobaric'].plot()
+>>> plt.show()
+
+
+

The resulting plot would look like this:

+
+
_images/xarray_hist.png +
+

We can modify the plots by passing additional arguments to the .plot() method. Since we haven’t discussed the plotting library matplotlib in this course, we will not go into further detail here. You can find more information in the Xarray documentation.

+
+
+

Exercises 1

+
+

Exercises: Xarray-1

+

Download the NARR_19930313_0000.nc dataset have a look at all Data variables. Calculate the geopotential height at x=5148.3726 averaged over y and return the median value. You can use the .plot() method to check on the way whether you use the correct dimensions and indices.

+
+ +
+
+

Creating your own Xarray Dataset

+

Creating your own Xarray Dataset is quite simple. We can create a Dataset from scratch using basic Python data structures. Let’s create a simple weather dataset with pressure and humidity data with the following script:

+
import xarray as xr
+import numpy as np
+
+# Define coordinates using basic Python lists
+time = ['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05']
+location = ['Location1', 'Location2', 'Location3']
+
+# Define data variables as numpy arrays
+pressure_data = np.random.rand(5, 3) * 1000  # Random pressure data in hPa
+humidity_data = np.random.rand(5, 3) * 100  # Random humidity data
+
+# Put everything together to create the Dataset
+ds = xr.Dataset(
+    data_vars = {
+        "pressure": (["time", "location"], pressure_data),
+        "humidity": (["time", "location"], humidity_data)
+    },
+    coords={
+        "time": time,
+        "location": location
+    },
+    attrs={
+        "description": "Weather data",
+        "creation_date": "2023-01-01",
+        "author": "Data Scientist"
+    }
+)
+
+
+
+
+

Converting Xarray objects to NumPy, Pandas and NetCDF

+

Another handy feature of Xarray is the simple conversion between Xarray objects, NumPy arrays, Pandas DataFrames and even NetCDF files.

+

To convert an xarray DataArray to a NumPy array, you can use the .values attribute or the .to_numpy() method:

+
# Convert the 'pressure' DataArray to a NumPy array
+pressure_numpy = ds['pressure'].values
+# or
+pressure_numpy = ds['pressure'].to_numpy()
+
+
+

To convert the entire Dataset or individual DataArrays to pandas DataFrames, use the .to_dataframe() method:

+
# Convert the entire Dataset to a DataFrame
+df = ds.to_dataframe()
+# Convert a single DataArray to DataFrame
+pressure_df = ds['pressure'].to_dataframe()
+
+
+

To save the dataset as a NetCDF file, use the .to_netcdf() method:

+
# Save the Dataset as a NetCDF file
+ds.to_netcdf('weather_data.nc')
+
+
+
+
+

Exercises 2

+
+

Exercises: Xarray-2

+

Let’s change from climate science to finance for this example. Put the stock prices and trading volumes of three companies over ten days in one dataset. Create an Xarray Dataset that uses time and company as dimensions and contains two DataArrays: stock_price and trading_volume. You can choose the values for the stock prices and trading volumes yourself. As a last thing, add the currency of the stock prices as an attribute to the Dataset.

+
+ +
+
+

Advanced Topics

+

We have barely scratched the surface of all the features Xarray has to offer. Hopefully this quick introduction has shown you whether Xarray is the right tool for your data analysis needs. If you are interested in learning more about Xarray, here are some topics for further reading:

+
    +

  • Xarray integrates with Dask to support parallel computations and streaming computation on datasets that don’t fit into memory. If you work with datasets that are too large for your memory, have a read of the chapter Parallel computing with Dask in the Xarray documentation.

    • +

  • If you want to accelerate Xarray operations with your GPU, have a look at CuPy-Xarray.

    • +

  • Xarray can be combined with pint, a Python library that adds support for physical quantities to NumPy arrays. This blog post provides a good introduction to the topic.

    • +

  • You can extend Xarray with your own methods using the register_dataset_accessor() method. This is a powerful feature that allows you to add custom methods to your own Xarray Datasets.

    • +
+
+
+
+

Plotting with Matplotlib

+
+

Questions

+
    +

  • What happens if you can’t automatically produce plots?

    • +

  • When to use Matplotlib for data visualization?

    • +

  • When to prefer other libraries?

    • +
+
+
+

Objectives

+
    +

  • Be able to create simple plots with Matplotlib and tweak them

    • +

  • Know about object-oriented vs pyplot interfaces of Matplotlib

    • +

  • Be able to adapt gallery examples

    • +

  • Know how to look for help

    • +

  • Know that other tools exist

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • Try to minimize manual post-processing. This could bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    + +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative.

    • +
+
+
+

Why are we starting with Matplotlib?

+
    +

  • Matplotlib is perhaps the most popular Python plotting library.

    • +

  • Many libraries build on top of Matplotlib (example: Seaborn).

    • +

  • MATLAB users will feel familiar.

    • +

  • Even if you choose to use another library (see above list), chances are high +that you need to adapt a Matplotlib plot of somebody else.

    • +

  • Libraries that are built on top of Matplotlib may need knowledge of Matplotlib +for custom adjustments.

    • +
+

However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code.

+

Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences.

+
+
+

Getting started with Matplotlib

+

We can start in a Jupyter Notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK.

+

Let us create our first plot using +subplots(), +scatter, and some other methods on the +Axes object:

+
import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
+# uncomment the next line if you would like to save the figure to disk
+# fig.savefig("my-first-plot.png")
+
+
+
+Result of our first plot + +
+

This is the result of our first plot.

+
+
+

When running a Matplotlib script on a remote server without a +“display” (e.g. compute cluster), you may need to add the +matplotlib.use call:

+
import matplotlib.pyplot as plt
+matplotlib.use("Agg")
+
+# ... rest of the script
+
+
+
+
+

Exercise: Matplotlib

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y * 2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset. +You can also consult this great +quick start guide.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +

  • Experiment also by using named colors (e.g. “red”) instead of the hex-codes.

    • +
+
+ + +
+
+
+

Matplotlib has two different interfaces

+

When plotting with Matplotlib, it is useful to know and understand that +there are two approaches even though the reasons of this dual approach is +outside the scope of this lesson.

+
    +

  • The more modern option is an object-oriented interface or explicit interface (the +fig and ax objects +can be configured separately and passed around to functions):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
    +
    +
    • +

  • The more traditional option mimics MATLAB plotting and uses the +pyplot interface or implicit interface (plt carries +the global settings):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+plt.scatter(x=data_x, y=data_y, c="#E69F00")
+
+plt.xlabel("we should label the x axis")
+plt.ylabel("we should label the y axis")
+plt.title("some title")
+
    +
    +
    • +
+

When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, we +recommend to learn and use the object oriented interface.

+
+

Why do we emphasize this?

+

One day you may want to write functions which wrap +around Matplotlib function calls and then you can send Figure and Axes +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions.

+

When using the pyplot interface, settings are modified for the entire +matplotlib.pyplot package. The latter is acceptable for simple scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls.

+
+
+
+
+

Styling and customizing plots

+
    +

  • Before you customize plots “manually” using a graphical program, please +consider how this affects reproducibility.

    • +

  • Try to minimize manual post-processing. This might bite you when you +need to regenerate 50 figures one day before submission deadline or +regenerate a set of figures after the person who created them left the group.

    • +

  • Matplotlib and also all the other libraries allow to customize almost every aspect of a plot.

    • +

  • It is useful to study Matplotlib parts of a figure +so that we know what to search for to customize things.

    • +

  • Matplotlib cheatsheets: https://github.com/matplotlib/cheatsheets

    • +

  • You can also select among pre-defined themes/ +style +sheets +with use, for instance:

    +
    plt.style.use('ggplot')
+
    +
    +
    • +
+
+
+

Exercises: Styling and customization

+

Here are 3 exercises where we try to adapt existing scripts to either tweak +how the plot looks (exercises 1 and 2) or to modify the input data (example 3).

+

This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice:

+
    +

  • Select an example that is close to what you have in mind

    • +

  • Being able to adapt it to your needs

    • +

  • Being able to search for help

    • +

  • Being able to understand help request answers (not easy)

    • +
+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = (
+    "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+)
+gapminder_data = pd.read_csv(url).query("year == 2007")
+
+gapminder_data
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP per capita (PPP dollars)")
+ax.set_ylabel("Life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+ +
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+ +
+
+

Discussion

+

After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on.

+
+
+
+
+

Matplotlib and pandas DataFrames

+

In the above exercises we have sent individual columns of the gapminder_data DataFrame +into ax.scatter() like this:

+
fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+
+

It is possible to do this instead and let Matplotlib “unpack” the columns:

+
fig, ax = plt.subplots()
+
+ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data)
+
+
+

Other input types are possible. See Types of inputs to plotting +functions.

+
+
+

Keypoints

+
    +

  • Minimize manual post-processing, script everything.

    • +

  • Browse a number of example galleries to help you choose the library +that fits best your work/style.

    • +

  • Figures for presentation slides and figures for manuscripts have +different requirements.

    • +

  • Think about color-vision deficiencies when choosing colors. Use +existing solutions for this problem.

    • +
+
+
+
+
+

Plotting with Vega-Altair

+
+

Objectives

+
    +

  • Be able to create simple plots with Vega-Altair and tweak them

    • +

  • Know how to look for help

    • +

  • Reading data with Pandas from disk or a web resource

    • +

  • Know how to tweak example plots from a gallery for your own purpose

    • +

  • We will build up +this notebook +(spoiler alert!)

    • +
+
+
+

Instructor note

+
    +

  • 10 min: Introduction

    • +

  • 10 min: Type-along (creating a first plot)

    • +

  • 20 min: Exercise (using visual channels)

    • +

  • 20 min: Exercise (adapting a gallery example and customizing)

    • +

  • 10 min: Key points, discussion, and Q&A

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • Try to minimize manual post-processing. This could bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    +
      +

    • Vega-Altair: +declarative visualization, statistics built in

      • +

    • Matplotlib: +probably the most standard and most widely used

      • +

    • Seaborn: +high-level interface to Matplotlib, statistical functions built in

      • +

    • Plotly: +interactive graphs

      • +

    • Bokeh: +also here good for interactivity

      • +

    • plotnine: +implementation of a grammar of graphics in Python, it is based on ggplot2

      • +

    • ggplot: +R users will be more at home

      • +

    • PyNGL: +used in the weather forecast community

      • +

    • K3D: +Jupyter Notebook extension for 3D visualization

      • +

    • …

      • +
    +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative (e.g. Vega-Altair).

    • +
+
+
+

Why are we starting with Vega-Altair?

+
    +

  • Concise and powerful

    • +

  • “Simple, friendly and consistent API” allows us to focus on the data +visualization part and get started without too much Python knowledge

    • +

  • The way it combines visual channels with data columns can feel intuitive

    • +

  • Interfaces very nicely with Pandas (earlier episode)

    • +

  • Easy to change figures

    • +

  • Good documentation

    • +

  • Open source

    • +

  • Makes it easy to save figures in a number of formats (svg, png, html)

    • +

  • Easy to save interactive visualizations to be used in websites

    • +
+
+
+

Example data: Weather data from two Norwegian cities

+

We will experiment with some example weather data obtained from Norsk +KlimaServiceSenter, Meteorologisk +institutt (MET) (CC BY 4.0). The data is in CSV format (comma-separated +values) and contains daily and monthly weather data for two cities in Norway: +Oslo and Tromsø. You can browse the data +here in the lesson repository.

+

We will use the Pandas library to read the data into a dataframe. We have learned about Pandas in an earlier episode.

+

Pandas can read from and write to a large set of formats +(overview of input/output functions and formats). +We will load a CSV file directly from the web. Instead of using a web URL we +could use a local file name instead.

+

Pandas dataframes are a great data structure for tabular data and tabular +data turns out to be a great input format for data visualization libraries. +Vega-Altair understands Pandas dataframes and can plot them directly.

+
+
+

Reading data into a dataframe

+

We can try this together in a notebook: +Using Pandas we can merge, join, concatenate, and compare +dataframes, see https://pandas.pydata.org/pandas-docs/stable/user_guide/merging.html.

+

Let us try to concatenate two dataframes: one for Tromsø weather data (we +will now load monthly values) and one for Oslo:

+
import pandas as pd
+
+url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/"
+
+data_tromso = pd.read_csv(url_prefix + "tromso-monthly.csv")
+data_oslo = pd.read_csv(url_prefix + "oslo-monthly.csv")
+
+data_monthly = pd.concat([data_tromso, data_oslo], axis=0)
+
+# let us print the combined result
+data_monthly
+
+
+

Before plotting the data, there is a problem which we may not see yet: Dates +are not in a standard date format (YYYY-MM-DD). We can fix this:

+
# replace mm.yyyy to date format
+data_monthly["date"] = pd.to_datetime(list(data_monthly["date"]), format="%m.%Y")
+
+
+

With Pandas it is possible to do a lot more (adjusting missing values, fixing +inconsistencies, changing format).

+
+
+

Plotting the data

+

Now let’s plot the data. We will start with a plot that is not optimal and +then we will explore and improve a bit as we go:

+
import altair as alt
+
+alt.Chart(data_monthly).mark_bar().encode(
+    x="date",
+    y="precipitation",
+    color="name",
+)
+
+
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year.

+
+
+
+

Let us pause and explain the code

+
    +

  • alt is a short-hand for altair which we imported on top of the notebook

    • +

  • Chart() is a function defined inside altair which takes the data as argument

    • +

  • mark_bar() is a function that produces bar charts

    • +

  • encode() is a function which encodes data columns to visual channels

    • +
+

Observe how we connect (encode) visual channels to data columns:

+
    +

  • x-coordinate with “date”

    • +

  • y-coordinate with “precipitation”

    • +

  • color with “name” (name of weather station; city)

    • +
+
+

We can improve the plot by giving Vega-Altair a bit more information that the +x-axis is temporal (T) and that we would like to see the year and +month (yearmonth):

+
alt.Chart(data_monthly).mark_bar().encode(
+    x="yearmonth(date):T",
+    y="precipitation",
+    color="name",
+)
+
+
+

Apart from T (temporal), there are other +encoding data types:

+
    +

  • Q (quantitative)

    • +

  • O (ordinal)

    • +

  • N (nominal)

    • +

  • T (temporal)

    • +

  • G (geojson)

    • +
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year.

+
+
+

Let us improve the plot with another one-line change:

+
alt.Chart(data).mark_bar().encode(
+    x="yearmonth(date):T",
+    y="precipitation",
+    color="name",
+    column="name",
+)
+
+
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side.

+
+
+

With another one-line change we can make the bar chart stacked:

+
alt.Chart(data_monthly).mark_bar().encode(
+    x="yearmonth(date):T",
+    y="precipitation",
+    color="name",
+    xOffset="name",
+)
+
+
+
+Monthly precipitation for the cities Oslo and Tromsø over the course of a year with with both cities plotted side by side. +
+

Monthly precipitation for the cities Oslo and Tromsø over the course of a year +plotted as stacked bar chart.

+
+
+

This is not publication-quality yet but a really good start!

+

Let us try one more example where we can nicely see how Vega-Altair +is able to map visual channels to data columns:

+
alt.Chart(data_monthly).mark_area(opacity=0.5).encode(
+    x="yearmonth(date):T",
+    y="max temperature",
+    y2="min temperature",
+    color="name",
+)
+
+
+
+Monthly temperature ranges for two cities in Norway. +
+

Monthly temperature ranges for two cities in Norway.

+
+
+
+

What other marks and other visual channels exist?

+ +
+
+
+

Exercise: Using visual channels to re-arrange plots

+
+

Plotting-1: Using visual channels to re-arrange plots

+
    +

  1. Try to reproduce the above plots if they are not already in your notebook.

    2. +

  2. Above we have plotted the monthly precipitation for two cities side by side +using a stacked plot. Try to arrive at the following plot where months are +along the y-axis and the precipitation amount is along the x-axis:

    +
    +_images/precipitation-stacked-y.svg +
    +
    3. +

  3. Ask the Internet or AI how to change the axis title from “precipitation” +to “Precipitation (mm)”.

    4. +

  4. Modify the temperature range plot to show the temperature ranges for the +two cities side by side like this:

    +
    +_images/temperature-ranges-side.svg +
    +
    5. +
+ +
+
+
+

More fun with visual channels

+

Now we will try to plot the daily data and look at snow depths. We first +read and concatenate two datasets:

+
url_prefix = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/plotting/"
+
+data_tromso = pd.read_csv(url_prefix + "tromso-daily.csv")
+data_oslo = pd.read_csv(url_prefix + "oslo-daily.csv")
+
+data_daily = pd.concat([data_tromso, data_oslo], axis=0)
+
+
+

We adjust the data a bit:

+
# replace dd.mm.yyyy to date format
+data_daily["date"] = pd.to_datetime(list(data_daily["date"]), format="%d.%m.%Y")
+
+# we are here only interested in the range december to may
+data_daily = data_daily[
+    (data_daily["date"] > "2022-12-01") & (data_daily["date"] < "2023-05-01")
+]
+
+
+

Now we can plot the snow depths for the months December to May for the two +cities:

+
alt.Chart(data_daily).mark_bar().encode(
+    x="date",
+    y="snow depth",
+    column="name",
+)
+
+
+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway.

+
+
+

What happens if we try to color the plot by the “max temperature” values?

+
alt.Chart(data_daily).mark_bar().encode(
+    x="date",
+    y="snow depth",
+    color="max temperature",
+    column="name",
+)
+
+
+

The result looks neat:

+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature.

+
+
+

We can change the color scheme (available color schemes):

+
alt.Chart(data_daily).mark_bar().encode(
+    x="date",
+    y="snow depth",
+    color=alt.Color("max temperature").scale(scheme="plasma"),
+    column="name",
+)
+
+
+

With the following result:

+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth.

+
+
+

Let’s try one more change to show that we can experiment with different +plot types by changing mark_bar() to something else, in this case mark_circle():

+
alt.Chart(data_daily).mark_circle().encode(
+    x="date",
+    y="snow depth",
+    color=alt.Color("max temperature").scale(scheme="plasma"),
+    column="name",
+)
+
+
+
+Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth. +
+

Snow depth (in cm) for the months December 2022 to May 2023 for two cities in Norway. Colored by daily max temperature. Warmer days are often followed by reduced snow depth.

+
+
+
+
+

Themes

+

In Vega-Altair you can change the theme and +select from a long list of themes. On +top of your notebook try to add:

+
alt.themes.enable('dark')
+
+
+

Then re-run all cells. Later you can try some other themes such as:

+
    +

  • fivethirtyeight

    • +

  • latimes

    • +

  • urbaninstitute

    • +
+

You can even define your own themes!

+
+ +
+
+

Working with Data

+
+

Questions

+
    +

  • How do you store your data right now?

    • +

  • Are you doing data cleaning / preprocessing every time you load the data?

    • +
+
+
+

Objectives

+
    +

  • Learn benefits/drawbacks of common data formats.

    • +

  • Learn how you can read and write data in a variety of formats.

    • +
+
+
+https://imgs.xkcd.com/comics/norm_normal_file_format.png +
+

Source: xkcd #2116

+
+
+
+

What is a data format?

+

Data format can mean two different things

+
    +

  1. data structure or how +you’re storing the data in memory while you’re working on it;

    2. +

  2. file format or the way you’re +storing the data in the disk.

    3. +
+

Let’s consider this randomly generated DataFrame with various columns:

+
import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
+dataset.info()
+
+
+

This DataFrame is structured in the tidy data format. +In tidy data we have multiple columns of data that are collected in a Pandas +DataFrame, where each column represents a value of a specific type.

+_images/tidy_data.png +

Let’s consider another example:

+
n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+np.info(data_array)
+
+
+

Here we have a different data structure: we have a two-dimensional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block +instead of individual columns. This also means that the whole array must have one +data type.

+
+https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png +
+

Source: Elegant Scipy

+
+
+

Now the question is: Can the data be saved to the disk without changing the +data format?

+

For this we need a file format that can easily store our data structure.

+
+

Data type vs. data structure vs. file format

+
    +

  • Data type: Type of a single piece of data (integer, string, +float, …).

    • +

  • Data structure: How the data is organized in memory (individual +columns, 2D-array, nested dictionaries, …).

    • +

  • File format: How the data is organized when it is saved to the disk +(columns of strings, block of binary data, …).

    • +
+

For example, a black and white image stored as a .png-file (file format) +might be stored in memory as an NxM array (data structure) of integers +(data type) with each entry representing the color value of the pixel.

+
+
+
+

What to look for in a file format?

+

When deciding which file format you should use for your program, you should +remember the following:

+

There is no file format that is good for every use case.

+

and

+

It is very likely, that a good format already exists for your use case.

+

There are, indeed, various standard file formats for various use cases:

+
+https://imgs.xkcd.com/comics/standards.png +
+

Source: xkcd #927.

+
+
+

Usually, you’ll want to consider the following things when choosing a file +format:

+
    +

  1. Is the file format good for my data structure (is it fast/space +efficient/easy to use)?

    2. +

  2. Is everybody else / leading authorities in my field recommending a certain +format?

    3. +

  3. Do I need a human-readable format or is it enough to work on it using code?

    4. +

  4. Do I want to archive / share the data or do I just want to store it while +I’m working?

    5. +
+

Pandas supports +many file formats +for tidy data and Numpy supports +some file formats +for array data. However, there are many other file formats that can be used +through other libraries.

+

Table below describes some data formats:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
Name:
+
+
+
Human
+
readable:
+
+
+
Space
+
efficiency:
+
+
+
Arbitrary
+
data:
+
+
+
Tidy
+
data:
+
+
+
Array
+
data:
+
+
+
Long term
+
storage/sharing:
+
+

Pickle

❌

🟨

✅

🟨

🟨

❌

CSV

✅

❌

❌

✅

🟨

✅

Feather

❌

✅

❌

✅

❌

❌

Parquet

❌

✅

🟨

✅

🟨

✅

npy

❌

🟨

❌

❌

✅

❌

HDF5

❌

✅

❌

❌

✅

✅

NetCDF4

❌

✅

❌

❌

✅

✅

JSON

✅

❌

🟨

❌

❌

✅

Excel

❌

❌

❌

🟨

❌

🟨

Graph formats

🟨

🟨

❌

❌

❌

✅

+
+

Important

+
    +

  • ✅ : Good

    • +

  • 🟨 : Ok / depends on a case

    • +

  • ❌ : Bad

    • +
+
+

A more in-depth analysis of the file formats mentioned above, can be found +here.

+
+
+

Pros and cons

+

Let’s have a general look at pros and cons of some types of file formats

+
+

Binary File formats

+
+
Good things
+
    +

  • Can represent floating point numbers with full precision.

    • +

  • Can potentially save lots of space, especially, when storing numbers.

    • +

  • Data reading and writing is usually much faster than loading from text files, +since the format contains information about the data structure, and thus +memory allocation can be done more efficiently.

    • +

  • More explicit specification for storing multiple data sets and metadata in +the same file.

    • +

  • Many binary formats allow for partial loading of the data. +This makes it possible to work with datasets that are larger than your +computer’s memory.

    • +
+
+
+
Bad things
+
    +

  • Commonly requires the use of a specific library to read and write the data.

    • +

  • Library specific formats can be version dependent.

    • +

  • Not human readable.

    • +

  • Sharing can be more difficult (requires some expertise to be able to +read the data).

    • +

  • Might require more documentation efforts.

    • +
+
+
+
+

Textual formats

+
+
Good things
+
    +

  • Human readable.

    • +

  • Easy to check for (structural) errors.

    • +

  • Supported by many tool out of the box.

    • +

  • Easily shared.

    • +
+
+
+
Bad things
+
    +

  • Can be slow to read and write.

    • +

  • High potential to increase required disk space substantially (e.g. when +storing floating point numbers as text).

    • +

  • Prone to losing precision when storing floating point numbers.

    • +

  • Multi-dimensional data can be hard to represent.

    • +

  • While the data format might be specified, the data structure might not be +clear when starting to read the data.

    • +
+
+
+
+

Further considerations

+
    +

  • The closer your stored data is to the code, the more likely it depends on the +environment you are working in. If you pickle, e.g. a generated model, +you can only be sure that the model will work as intended if you load it in +an environment that has the same versions of all libraries the model depends +on.

    • +
+
+
+
+

Exercise

+
+

Exercise

+

You have a model that you have been training for a while. +Lets assume it’s a relatively simple neural network (consisting of a +network structure and it’s associated weights).

+

Let’s consider 2 scenarios

+

A: You have a different project, that is supposed to take this model, and +do some processing with it to determine it’s efficiency after different +times of training.

+

B: You want to publish the model and make it available to others.

+

What are good options to store the model in each of these scenarios?

+
+ +
+
+

Case study: Converting untidy data to tidy data

+

Many data analysis tools (like Pandas) are designed to work with tidy data, +but some data is not in a suitable format. What we have seen often in the +past is people then not using the powerful tools, but write complicated +scripts that extract individual pieces from the data each time they need +to do a calculation.

+

As an example, let’s see how we can use country data from an example REST API +endpoint (for more information on how to work with web APIs, see +this page). Let’s get the data with the following piece +of code:

+
import json
+import requests
+
+url = 'https://api.sampleapis.com/countries/countries'
+
+response = requests.get(url)
+
+countries_json = json.loads(response.content)
+
+
+

Let’s try to find the country with the largest population.

+

An example of a “questionable” way of solving this problem would be something +like the following piece of code that is written in pure Python:

+
max_population = 0
+top_population_country = ''
+
+for country in countries_json:
+    if country.get('population', 0) > max_population:
+        top_population_country = country['name']
+        max_population = country.get('population', 0)
+
+print(top_population_country)
+
+
+

This is a very natural way of writing a solution for the problem, but it has +major caveats:

+
    +

  1. We throw all of the other data out so we cannot answer any +follow up questions.

    2. +

  2. For bigger data, this would be very slow and ineffective.

    3. +

  3. We have to write lots of code to do a simple thing.

    4. +
+

Another typical solution would be something like the following code, +which picks some of the data and creates a Pandas dataframe out of it:

+
import pandas as pd
+
+countries_list = []
+
+for country in countries_json:
+    countries_list.append([country['name'], country.get('population',0)])
+
+countries_df = pd.DataFrame(countries_list, columns=['name', 'population'])
+
+print(countries_df.nlargest(1, 'population')['name'].values[0])
+
+
+

This solution has many of the same problems as the previous one, but now we can +use Pandas to do follow up analysis.

+

Better solution would be to use Pandas’ +pandas.DataFrame.from_dict +or pandas.json_normalize +to read the full data in:

+
countries_df = pd.DataFrame.from_dict(countries_json)
+print(countries_df.nlargest(1, 'population')['name'].values[0])
+
+countries_df = pd.json_normalize(countries_json)
+print(countries_df.nlargest(1, 'population')['name'].values[0])
+
+
+
+

Key points

+
    +

  • Convert your data to a format where it is easy to do analysis on it.

    • +

  • Check the tools you’re using if they have an existing feature that can help +you read the data in.

    • +
+
+
+
+

Things to remember

+
    +

  1. There is no file format that is good for every use case.

    2. +

  2. Usually, your research question determines which libraries you want to use +to solve it. Similarly, the data format you have determines file format you +want to use.

    3. +

  3. However, if you’re using a previously existing framework or tools or you +work in a specific field, you should prioritize using the formats that are +used in said framework/tools/field.

    4. +

  4. When you’re starting your project, it’s a good idea to take your initial +data, clean it, and store the results in a good binary format that works as +a starting point for your future analysis. If you’ve written the cleaning +procedure as a script, you can always reproduce it.

    5. +

  5. Throughout your work, you should use code to turn important data to +a human-readable format (e.g. plots, averages, +pandas.DataFrame.head()), not to keep your full data in a +human-readable format.

    6. +

  6. Once you’ve finished, you should store the data in a format that can be +easily shared to other people.

    7. +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pandas can read and write a variety of data formats.

    • +

  • There are many good, standard formats, and you don’t need to create your own.

    • +

  • There are plenty of other libraries dedicated to various formats.

    • +
+
+
+
+
+

Scripts

+
+

Questions

+
    +

  • Why are command line programs useful, compared to Jupyter +notebooks and similar?

    • +

  • How to create a Python script?

    • +

  • How to generalize a Python script?

    • +
+
+
+

Objectives

+
    +

  • Learn how to streamline your Python notebooks by creating repeatable Python scripts

    • +

  • Learn how to import other Python files

    • +

  • Learn to parse command line arguments in Python

    • +
+
+
+

Why scripts?

+

So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work.

+

But after several weeks of hard work with Python, you may end up:

+
    +

  • either with 10 different notebooks (so that you can run them concurrently)

    • +

  • or with a very long notebook which is becoming hardly readable!

    • +
+

Let’s imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks?

+

In this episode, we will learn how to automate your work using Python scripts so that

+
    +

  • you do not need to manually configure your notebooks to be able to run with different parameters

    • +

  • can easily run you work via other tools, such as on computing clusters.

    • +
+
+
+

From Jupyter notebooks to Python scripts

+
+
+

Save as Python script

+

Jupyter notebooks can be parameterized for instance using papermill. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See CodeRefinery’s lesson on Modular code development.

+

You need to convert the notebook to a Python file. +Check the JupyterLab documentation for more information. +You can get a command line by (File → New Launcher → Terminal - if you +go through New Launcher, your command line will be in the directory +you are currently browsing), you can convert files in the terminal by running:

+
$ jupyter nbconvert --to script your_notebook_name.ipynb
+
+
+

If nbconvert doesn’t work, within JupyterLab, you can export any +Jupyter notebook to a Python +script, but this downloads it to your own computer and then you need +to copy it to a place you are working (maybe upload it back to +JupyterLab?):

+
+JupyterLab screenshot as described in caption. + +
+

Select File (top menu bar) → Export Notebook as → Export notebook to Executable Script.

+
+
+
+
+

Exercises 1

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Hint: Copy the URL above (right-click) and in JupyterLab, use +File → Open from URL → Paste the URL. It will both download it to +the directory JupyterLab is in and open it for you.

    +
    2. +

  2. Open a terminal in Jupyter: File → New Launcher, then click +“Terminal” there. (if you do it this way, it will be in the right +directory. File → New → Terminal might not be.)

    3. +

  3. Convert the Jupyter script to a Python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+
+
+

Command line arguments with sys.argv

+

We now have a Python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +What we need is to allow the code to do something different based on something outside the code itself: in this case, to +plot information for different time ranges. This can be achieved by +using Pythons sys package, which provides access to arguments given to the Python interpreter at +startup in the sys.argv list. The first (i.e. sys.argv[0] entry of this array is the script that is running, +and any further argument (separated by space) is appended to this list, like such:

+
$ python my_script.py A B
+$ # sys.argv[1] is 'A'
+$ # sys.argv[2] is 'B'
+
+
+

Lets see how it works: We modify the weather_observations.py script such that we allow start +and end times as well as the output file to be passed in as arguments +to the function. Open it (find the .py file from the JupyterLab +file browser) and make these edits:

+
import sys
+import pandas as pd
+
+# define the start and end time for the plot
+start_date = pd.to_datetime(sys.argv[1], dayfirst=True)
+end_date = pd.to_datetime(sys.argv[2], dayfirst=True)
+...
+
+# select the data
+weather = weather[weather['Local time'].between(start_date,end_date)]
+...
+
+# save the figure
+output_file_name = sys.argv[3]
+fig.savefig(output_file_name)
+
+
+

We can try it out (see the file spring_in_tapiola.png made in the +file browser):

+
$ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png
+
+
+
+

Discussion

+
    +

  • Does it work?

    • +

  • Why is this better than modifying the script every time I want it to +plot data for a different period?

    • +

  • What problems do you expect when using this approach (using sys.argv)?

    • +
+
+

This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time:

+
    +

  • argparse: +built-in to Python, this is the one that we will show below.

    • +

  • doctopt: you write the help text and this generates a parser for you.

    • +

  • click: another nice +library for command line interfaces - very easy to use.

    • +
+
+
+

Parsing command line arguments with argparse

+

Argparse not only gives you descriptive command line arguments, it also automatically +generates a --help option for you. To use argparse you first set up a parser +by calling parser = argparse.ArgumentParser() and then you add arguments using +parser.add_argument(args). There are two different types of arguments:

+
    +

  • Positional arguments

    • +

  • Optional arguments

    • +
+

Positional arguments are detected by their order, while optional arguments need to be +given with their respective flags ( like --name or -n). +The following example would parse a positional argument Name of type string +and an optional argument date of type string which defaults to 01/01/2000.

+
import argparse
+
+parser = argparse.ArgumentParser()
+# One positional and one optional argument
+parser.add_argument('name', type=str, metavar="N",
+                    help="The name of the subject")
+parser.add_argument('-d', '--date', type=string, default="01/01/2000",
+                    help="Birth date of the subject")
+
+args = parser.parse_args()
+
+print(args.name + " was born on " + args.date)
+
+
+

If this code was in birthday.py and we would call python birthday.py --help it +would show the following message:

+
$ python birthday.py --help
+usage: birthday.py [-h] [-d DATE] N
+
+positional arguments:
+  N                     The name of the subject
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d DATE, --date DATE  Birth date of the subject
+
+
+
+
+

Exercises 2

+
+

Scripts-2

+
    +

  1. Take the Python script (weather_observations.py) we have written in the preceding exercise and use +argparse to specify the input (URL) and output files and allow the start and end dates to be set.

    +
      +

    • Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on.

      • +

    • Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output.

      • +

    • Hint: The start and end dates should be optional parameters with the defaults as they are in the current script.

      • +
    +
    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). +Also try using this data for Cairo: https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv

    3. +
+
+ +
+

Discussion

+

What was the point of doing this?

+

Now you can do this:

+
$ python weather_observations.py --help
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png
+$ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png
+$ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv temperature_cairo.png
+
+
+
    +

  • We can now process different input files without changing the script.

    • +

  • We can select multiple time ranges without modifying the script.

    • +

  • We can easily save these commands to know what we did.

    • +

  • This way we can also loop over file patterns (using shell loops or similar) or use +the script in a workflow management system and process many files in parallel.

    • +

  • By changing from sys.argv to argparse we made the script more robust against +user input errors and also got a help text (accessible via --help).

    • +
+
+
+
+

Load larger option lists using config files

+

In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line:

+
$ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021
+
+
+

This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple Parameter = Value +format, and parse it yourself, or you can use e.g. the JSON or YAML formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won’t go into the details of the formats, and will only give +a short example using YAML here.

+

The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (yaml) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the json package).

+

The Python module optionsparser.py provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values.

+

In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation …), set the labels and titles explicitly etc.

+

In the YAML format, names and values are separated by :. Our above example would therefore translate to the following YAML file:

+
input:        https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv
+output:       rain_in_cairo.png
+xlabel:       Days in June
+ylabel:       Rainfall in mm
+title:        Rainfall in Cairo
+data_column:  RRR
+start:        01/06/2021
+end:          30/06/2021
+
+
+
+
+

Exercises 3 (optional)

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+ +

What did this config file parser get us? Now, we have separated the +code from the configuration. We could save all the configuration in +version control - separately and have one script that runs them. If +done right, our work could be much more reproducible and +understandable.

+
+

Further reading

+ +
+
+
+
+

Profiling

+
+

Objectives

+
    +

  • Understand when improving code performance is worth the time and effort.

    • +

  • Knowing how to find performance bottlenecks in Python code.

    • +

  • Try scalene as one of many tools to profile Python code.

    • +
+
+
+

Instructor note

+
    +

  • Discussion: 20 min

    • +

  • Exercise: 20 min

    • +
+
+
+

Should we even optimize the code?

+

Classic quote to keep in mind: “Premature optimization is the root of all evil.” [Donald Knuth]

+
+

Discussion

+

It is important to ask ourselves whether it is worth it.

+
    +

  • Is it worth spending e.g. 2 days to make a program run 20% faster?

    • +

  • Is it worth optimizing the code so that it spends 90% less memory?

    • +
+

Depends. What does it depend on?

+
+
+
+

Measure instead of guessing

+

Before doing code surgery to optimize the run time or lower the memory usage, +we should measure where the bottlenecks are. This is called profiling.

+

Analogy: Medical doctors don’t start surgery based on guessing. They first measure +(X-ray, MRI, …) to know precisely where the problem is.

+

Not only programming beginners can otherwise guess wrong, but also experienced +programmers can be surprised by the results of profiling.

+
+
+

One of the simplest tools is to insert timers

+

Below we will list some tools that can be used to profile Python code. +But even without these tools you can find time-consuming parts of your code +by inserting timers:

+
import time
+
+
+# ...
+# code before the function
+
+
+start = time.time()
+result = some_function()
+print(f"some_function took {time.time() - start} seconds")
+
+
+# code after the function
+# ...
+
+
+
+
+

Many tools exist

+

The list below here is probably not complete, but it gives an overview of the +different tools available for profiling Python code.

+

CPU profilers:

+ +

Memory profilers:

+ +

Both CPU and memory:

+ +

In the exercise below, we will use Scalene to profile a Python program. Scalene +is a sampling profiler that can profile CPU, memory, and GPU usage of Python.

+
+
+

Tracing profilers vs. sampling profilers

+

Tracing profilers record every function call and event in the program, +logging the exact sequence and duration of events.

+
    +

  • Pros:

    +
      +

    • Provides detailed information on the program’s execution.

      • +

    • Deterministic: Captures exact call sequences and timings.

      • +
    +
    • +

  • Cons:

    +
      +

    • Higher overhead, slowing down the program.

      • +

    • Can generate larger amount of data.

      • +
    +
    • +
+

Sampling profilers periodically samples the program’s state (where it is +and how much memory is used), providing a statistical view of where time is +spent.

+
    +

  • Pros:

    +
      +

    • Lower overhead, as it doesn’t track every event.

      • +

    • Scales better with larger programs.

      • +
    +
    • +

  • Cons:

    +
      +

    • Less precise, potentially missing infrequent or short calls.

      • +

    • Provides an approximation rather than exact timing.

      • +
    +
    • +
+
+

Analogy: Imagine we want to optimize the London Underground (subway) system

+

We wish to detect bottlenecks in the system to improve the service and for this we have +asked few passengers to help us by tracking their journey.

+
    +

  • Tracing: We follow every train and passenger, recording every stop +and delay. When passengers enter and exit the train, we record the exact time +and location.

    • +

  • Sampling: Every 5 minutes the phone notifies the passenger to note +down their current location. We then use this information to estimate +the most crowded stations and trains.

    • +
+
+
+
+

Choosing the right system size

+

Sometimes we can configure the system size (for instance the time step in a simulation +or the number of time steps or the matrix dimensions) to make the program finish sooner.

+

For profiling, we should choose a system size that is representative of the real-world +use case. If we profile a program with a small input size, we might not see the same +bottlenecks as when running the program with a larger input size.

+

Often, when we scale up the system size, or scale the number of processors, new bottlenecks +might appear which we didn’t see before. This brings us back to: “measure instead of guessing”.

+
+
+

Exercises

+
+

Exercise: Practicing profiling

+

In this exercise we will use the Scalene profiler to find out where most of the time is spent +and most of the memory is used in a given code example.

+

Please try to go through the exercise in the following steps:

+
    +

  1. Make sure scalene is installed in your environment (if you have followed +this course from the start and installed the recommended software +environment, then it is).

    2. +

  2. Download Leo Tolstoy’s “War and Peace” from the following link (the text is +provided by Project Gutenberg): +https://www.gutenberg.org/cache/epub/2600/pg2600.txt +(right-click and “save as” to download the file and save it as “book.txt”).

    3. +

  3. Before you run the profiler, try to predict in which function the code +will spend most of the time and in which function it will use most of the +memory.

    4. +

  4. Run the scalene profiler on the following code example and browse the +generated HTML report to find out where most of the time is spent and where +most of the memory is used:

    +
    $ scalene example.py
+
    +
    +

    Alternatively you can do this (and then open the generated file in a browser):

    +
    $ scalene example.py --html > profile.html
+
    +
    +

    You can find an example of the generated HTML report in the solution below.

    +
    5. +

  5. Does the result match your prediction? Can you explain the results?

    6. +
+
"""
+The code below reads a text file and counts the number of unique words in it
+(case-insensitive).
+"""
+import re
+
+
+def count_unique_words1(file_path: str) -> int:
+    with open(file_path, "r", encoding="utf-8") as file:
+        text = file.read()
+    words = re.findall(r"\b\w+\b", text.lower())
+    return len(set(words))
+
+
+def count_unique_words2(file_path: str) -> int:
+    unique_words = []
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower())
+            for word in words:
+                if word not in unique_words:
+                    unique_words.append(word)
+    return len(unique_words)
+
+
+def count_unique_words3(file_path: str) -> int:
+    unique_words = set()
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower())
+            for word in words:
+                unique_words.add(word)
+    return len(unique_words)
+
+
+def main():
+    # book.txt is downloaded from https://www.gutenberg.org/cache/epub/2600/pg2600.txt
+    _result = count_unique_words1("book.txt")
+    _result = count_unique_words2("book.txt")
+    _result = count_unique_words3("book.txt")
+
+
+if __name__ == "__main__":
+    main()
+
+
+ +
+
+
+

Additional resources

+ +
+
+
+

Productivity tools

+
+

Objectives

+
    +

  • Know about tools that can help you spot code problems and help you following +a consistent code style without you having to do it manually.

    • +

  • Get an overview of AI-based tools and how they can help you +writing code.

    • +
+
+
+

Instructor note

+
    +

  • Demo/discussion: 20 min

    • +
+
+
+

Linters and formatters

+

Linter: Tool that analyzes source code to detect potential errors, unused +imports, unused variables, code style violations, and to improve readability.

+ +

Formatter: Tool that automatically formats your code to a consistent style, +for instance following PEP 8.

+ +

In this course we will focus on Ruff since it +can do both checking and formatting and you don’t have to switch between +multiple tools.

+
+

Linters and formatters can be configured to your liking

+

These tools typically have good defaults. But if you don’t like the defaults, +you can configure what they should ignore or how they should format or not format.

+
+
+
+

Examples

+

This code example (which we possibly recognize from the previous section about +Profiling and Tracing) +has few problems (highlighted):

+
import re
+import requests
+
+
+def count_unique_words(file_path: str) -> int:
+    unique_words = set()
+    forgotten_variable = 13
+    with open(file_path, "r", encoding="utf-8") as file:
+        for line in file:
+            words = re.findall(r"\b\w+\b", line.lower()))
+            for word in words:
+                unique_words.add(word)
+    return len(unique_words)
+
+
+

Please try whether you can locate these problems using Ruff:

+
$ ruff check
+
+
+

Next, let us try to auto-format a code example which is badly formatted and also difficult +to read:

+
+
import re
+def  count_unique_words (file_path : str)->int:
+  unique_words=set()
+  with open(file_path,"r",encoding="utf-8") as file:
+    for line in file:
+      words=re.findall(r"\b\w+\b",line.lower())
+      for word in words:
+        unique_words.add(word)
+  return len(   unique_words   )
+
+
+
+
+
+

Type checking

+

A (static) type checker is a tool that checks whether the types of variables in your +code match the types that you have specified.

+ +
+
+

Integration with editors

+

Many/most of the above tools can be integrated with your editor. For instance, +you can configure your editor to automatically format your code when you save +the file. However, this only makes sense when all team members agree to follow +the same style, otherwise saving and possibly committing changes to version +control will show up changes to code written by others which you possibly +didn’t intend to make.

+
+
+

Integration with Jupyter notebooks

+

It is possible to automatically format your code in Jupyter notebooks! +For this to work you need +the following three dependencies installed:

+
    +

  • jupyterlab-code-formatter

    • +

  • black

    • +

  • isort

    • +
+

More information and a screen-cast of how this works can be found at +https://jupyterlab-code-formatter.readthedocs.io/.

+
+
+

Integration with version control

+

If you use version control and like to have your code checked or formatted +before you commit the change, you can use tools like pre-commit.

+
+
+

AI-assisted coding

+

We can use AI as an assistant/apprentice:

+
    +

  • Code completion

    • +

  • Write a test based on an implementation

    • +

  • Write an implementation based on a test

    • +
+

Or we can use AI as a mentor:

+
    +

  • Explain a concept

    • +

  • Improve code

    • +

  • Show a different (possibly better) way of implementing the same thing

    • +
+
+Screenshot of ChatGPT + +
+

Example for using a chat-based AI tool.

+
+
+
+Screen-cast of working with GitHub Copilot + +
+

Example for using AI to complete code in an editor.

+
+
+
+

AI tools open up a box of questions

+
    +

  • Legal

    • +

  • Ethical

    • +

  • Privacy

    • +

  • Lock-in/ monopolies

    • +

  • Lack of diversity

    • +

  • Will we still need to learn programming?

    • +

  • How will it affect learning and teaching programming?

    • +
+
+
+
+
+

SciPy

+
+

Questions

+
    +

  • When you need more advanced mathematical functions, where do you +look?

    • +
+
+
+

Objectives

+
    +

  • Understand that SciPy exists and what kinds of things it has.

    • +

  • Understand the importance of using external libraries and how to +use them.

    • +

  • Understand the purpose of wrapping existing C/Fortran code.

    • +

  • Non-objective: know details of everything (or anything) in SciPy.

    • +
+
+
+

See also

+ +
+

SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms.

+
+

What’s in SciPy?

+

Briefly, it contains functionality for

+
    +

  • Special functions (Bessel, Gamma, etc.)

    • +

  • Numerical integration

    • +

  • Optimization

    • +

  • Interpolation

    • +

  • Fast Fourier Transform (FFT)

    • +

  • Signal processing

    • +

  • Linear algebra (more complete than in NumPy)

    • +

  • Sparse matrices

    • +

  • Statistics

    • +

  • More I/O routine, e.g. Matrix Market format for sparse matrices, +MATLAB files (.mat), etc.

    • +
+

Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages.

+

Most functions are documented ridiculously well from a scientific +standpoint: you aren’t just using some unknown function, but have a +full scientific description and citation to the method and +implementation.

+
+
+

Exercises: use SciPy

+

These exercises do not exist because you might need these +functions someday. They are because you will need to read +documentation and understand documentation of an an external library +eventually.

+
+

1: Numerical integration

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+ +
+
+

2: Sparse matrices

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+ +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • When you need advance math or scientific functions, let’s just +admit it: you do a web search first.

    • +

  • But when you see something in SciPy come up, you know your +solutions are in good hands.

    • +
+
+
+
+
+

Library ecosystem

+
+

Questions

+
    +

  • What happens when you need some method beyond what we discuss in this course, what is available?

    • +

  • How do you decide what to build on for your work?

    • +
+
+
+

Objectives

+
    +

  • Know of some other available packages, but don’t necessarily know +how to use them.

    • +

  • Be able to evaluate what you should reuse and what you should +develop yourself.

    • +
+
+

You can’t do everything yourself. In fact, once we heard a quote such +as this:

+
+

When you are a student, you are expected to do everything +yourself, and that is how you are evaluated. When you become a +researcher, you have to be able to reuse what others have done. +We don’t have much practice in doing this. +– A student

+
+

In this lesson, we’ll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types:

+
    +

  • Well-maintained libraries that are used by many others.

    • +

  • A wide variety of public code that might work but isn’t necessarily +well-maintained (for example, code from articles).

    • +
+

We’ll start with the first then go to the second.

+
+

Glossary

+
+
Library

A collection of code used by a program.

+
+
Package

A library that has been made easily installable and reusable. +Often published on public repositories such as the Python Package +Index

+
+
Dependency

A requirement of another program, not included in that program.

+
+
+
+
+

The Python/SciPy ecosystem

+

This section is nothing more than a tour of what exists in Python. +You aren’t expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work.

+

The “core” packages could be considered. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy):

+
    +

  • Python

    • +

  • Numpy - arrays, everything builds on this

    • +

  • Scipy - scientific functions (not necessarily a lot builds on this)

    • +

  • matplotlib - plotting, many other plotting tools build on this

    • +

  • pandas - data structures

    • +

  • IPython / Jupyter: interactive work

    • +
+
+

Core numerics libraries

+
    +

  • numpy - arrays and array math.

    • +

  • scipy - software +for math, science, and engineering.

    • +
+
+
+

Plotting

+
    +

  • matplotlib - base plotting package, +somewhat low level but almost everything builds on it.

    • +

  • seaborn - higher level plotting +interface; statistical graphics.

    • +

  • mayavi - 3D plotting

    • +

  • PIL - image manipulation. The +original PIL is no longer maintained, the new “Pillow” is a drop-in +replacement.

    • +
+
+
+

Data analysis and other important core packages

+ +
+
+

Interactive computing and human interface

+
    +

  • Interactive computing

    +
      +

    • IPython - nicer interactive interpreter

      • +

    • Jupyter (notebook, lab, hub, …) - +web-based interface to IPython and other languages

      • +
    +
    • +

  • Testing

    +
      +

    • pytest - automated testing interface

      • +
    +
    • +

  • Documentation

    +
      +

    • Sphinx - documentation generator +(also used for this lesson…)

      • +
    +
    • +

  • Development environments

    +
      +

    • Spyder - interactive Python +development environment.

      • +
    +
    • +

  • Binder - load any git repository in +Jupyter automatically, good for reproducible research

    • +
+
+
+

Speeding up code and parallelism

+
    +

  • PyMPI - Message +Passing Interface (MPI) in Python for parallelizing jobs.

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • numba - just in time compiling of +functions for speed-up

    • +

  • PyPy - Python written in Python so that +it can internally optimize more.

    • +

  • Dask - distributed array data structure for +distributed computation

    • +

  • Joblib - easy embarrassingly +parallel computing

    • +

  • IPyParallel - easy +parallel task engine

    • +

  • numexpr - Fast evaluation of +array expressions by automatically compiling the arithmetic.

    • +
+
+
+

Machine learning

+

If you need some machine learning, you probably already know what you +need and this list is short and irrelevant.

+ +
+
+
+

Connecting Python to other languages

+

As we discussed with Scipy, very many of the above packages aren’t +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things:

+
    +

  • Extending Python by writing your own modules in C.

    +
      +

    • It’s actually common to first have (or write) an analysis package +in C or C++, then make the Python interface. Then it can be +supported by other languages, too.

      • +

    • Or one starts an analysis package in Python, and slowly moves bits +of it to C over time as there is need.

      • +
    +
    • +

  • Embedding Python, where you have another primary application +that uses Python under the hood as an internal scripting language.

    • +
+

These features aren’t exactly unique to Python, but Python does +support them very well. Read more: Extending and embedding Python.

+
+

Tools for interfacing with other languages

+

These days, one rarely directly extends the Python interpreter, but uses

+
    +

  • cffi and ctypes - interface to C +and compatible libraries

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • f2py - interface to Fortran +code

    • +

  • swig - connect to a variety of programming languages.

    • +

  • Boost.python - Another Python/C++ interface

    • +

  • TODO: Julia modules for Python?

    • +
+
+
+
+

Evaluating Python packages for reuse

+

Above, we talked about well-maintained mainstream packages. Do you +trust random code you find online (for example included in a paper)?

+

Especially consider scientific results, which have to be correct. +Still, you also can’t build everything yourself, so you have to +carefully evaluate the situation.

+

Below are some things to consider:

+
    +

  • Are there releases? Have they been going on for a while?

    • +

  • Are releases installable without copy-paste?

    • +

  • Are dependencies handled well?

    • +

  • Does the code randomly change, so that it no longer works with your +code. Is this relevant?

    • +

  • Is there good documentation, that not just tells how to use it but +how it works?

    • +

  • Is there automated testing? What’s your evaluation of the risk of +undetectable scientific errors?

    • +

  • Is there a community, or is it one person? Is it backed by some +organization? Does it have a permanent home?

    • +

  • Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) +where a community could form?

    • +

  • Do others post issues and make contributions? Are these issues +dealt with in a timely manner? Can you search past bug reports?

    • +

  • Is the software citeable?

    • +
+
+
+

Is your work reuseable?

+

Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a CodeRefinery workshop will make +sure you have the tools to produce high-quality, reusable code.

+
+
+

What’s next?

+
    +

  • The CodeRefinery workshop mentioned +above will prepare you for others to reuse your code and for you to +contribute to other code.

    • +

  • The upcoming Dependency management lesson will teach you how to +record and manage dependencies so that anyone can seamlessly reuse +your code.

    • +
+
+
+

Exercises

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+ +
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • Almost everything you need can already be found, except your +incremental work.

    • +

  • When do you build on that other work, and when do you create +things yourself?

    • +
+
+
+
+
+

Dependency management

+
+

Questions

+
    +

  • Do you expect your code to work in one year? Five? What if it +uses numpy or tensorflow or random-github-package ?

    • +

  • How can my collaborators easily install my code with all the necessary dependencies?

    • +

  • How can I make it easy for my others (and me in future) to reproduce my results?

    • +

  • How can I work on two (or more) projects with different and conflicting dependencies?

    • +
+
+
+

Objectives

+
    +

  • Learn how to record dependencies

    • +

  • Be able to communicate the dependencies as part of a report/thesis/publication

    • +

  • Learn how to use isolated environments for different projects

    • +

  • Simplify the use and reuse of scripts and projects

    • +
+
+
+

How do you track dependencies of your project?

+
    +

  • Dependency: Reliance on a external component. In this case, a +separately installed software package such as numpy.

    • +
+
+
+

Exercise 1

+
+

Dependencies-1: Discuss dependency management (5 min)

+

Please discuss and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+
+
+

PyPI (The Python Package Index) and conda ecosystem

+

PyPI (The Python Package Index) and conda are popular packaging/dependency +management tools:

+
    +

  • When you run pip install you typically install from PyPI, but you can also pip install from a GitHub +repository and similar.

    • +

  • When you run conda install you typically install from Anaconda Cloud where there are conda channels maintained +by Anaconda Inc. and by various communities.

    • +
+

Why are there two ecosystems?

+
+

PyPI

+
    +

  • Installation tool: pip

    • +

  • Summary: PyPI is traditionally used for Python-only packages or +for Python interfaces to external libraries. There are also packages +that have bundled external libraries (such as numpy).

    • +

  • Amount of packages: Huge number. Old versions are supported for +a long time.

    • +

  • How libraries are handled: If your code depends on external +libraries or tools, these things need to be either included in the +pip-package or provided via some other installation system (like +operating system installer or manual installation).

    • +
  • +
    Pros:
      +

    • Easy to use

      • +

    • Package creation is easy

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Installing packages that need external libraries can be complicated

      • +
    +
    +
    +
    • +
+
+
+

Conda

+
    +

  • Installation tool: conda or mamba

    • +

  • Summary: Conda aims to be a more general package distribution tool +and it tries to provide not only the Python packages, but also libraries +and tools needed by the Python packages. Most scientific software written +in Python uses external libraries to speed up calculations and installing +these libraries can often become complicated without conda.

    • +

  • Amount of packages: Curated list of packages in defaults-channel, huge +number in community managed channels. Other packages can be installed via pip.

    • +

  • How libraries are handled: Required libraries are installed as separate +conda packages.

    • +
  • +
    Pros:
      +

    • Quite easy to use

      • +

    • Easier to manage packages that need external libraries

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Package creation is harder

      • +
    +
    +
    +
    • +
+
+
+
+

Conda ecosystem explained

+
+

Warning

+

Anaconda has recently changed its licensing terms, which affects its +use in a professional setting. This caused uproar among academia +and Anaconda modified their position in +this article.

+

Main points of the article are:

+
    +

  • conda (installation tool) and community channels (e.g. conda-forge) +are free to use.

    • +

  • Anaconda repository and Anaconda’s channels in the community repository +are free for universities and companies with fewer than 200 employees. +Non-university research institutions and national laboratories need +licenses.

    • +

  • Miniconda is free, when it does not download Anaconda’s packages.

    • +

  • Miniforge is not related to Anaconda, so it is free.

    • +
+

For ease of use on sharing environment files, we recommend using +Miniforge to create the environments and using conda-forge as the main +channel that provides software.

+
+
    +

  • Package repositories:

    + +
    • +

  • Major package channels:

    +
      +

    • Anaconda’s proprietary channels: main, r, msys2 and anaconda. +These are sometimes called defaults.

      • +

    • conda-forge is the largest open source +community channel. It has over 27,000 packages that include open-source +versions of packages in Anaconda’s channels.

      • +
    +
    • +

  • Package distributions and installers:

    +
      +

    • Anaconda is a distribution of conda packages +made by Anaconda Inc.. When using Anaconda remember to check that your +situation abides with their licensing terms.

      • +

    • Miniconda is a minimal installer +maintained by Anaconda Inc. that has conda and uses Anaconda’s channels +by default. Check licensing terms when using these packages.

      • +

    • Miniforge is an open-source +Miniconda replacement that uses conda-forge as the default channel. +Contains mamba as well.

      • +

    • micromamba +is a tiny stand-alone version of the mamba package manager written in C++. +It can be used to create and manage environments without installing +base-environment and Python. It is very useful if you want to automate +environment creation or want a more lightweight tool.

      • +
    +
    • +

  • Package managers:

    +
      +

    • conda is a package and environment management system +used by Anaconda. It is an open source project maintained by Anaconda Inc..

      • +

    • mamba is a drop in +replacement for conda. It used be much faster than conda due to better +dependency solver but nowadays conda +also uses the same solver. +It still has some UI improvements.

      • +
    +
    • +
+
+
+

Exercise 2

+
+

Dependencies-2: Package language detective (5 min)

+

Think about the following sentences:

+
    +

  1. Yes, you can install my package with pip from GitHub.

    2. +

  2. I forgot to specify my channels, so my packages came from the defaults.

    3. +

  3. I have a Miniforge installation and I use mamba to create my environments.

    4. +
+

What hidden information is given in these sentences?

+ +
+
+
+

Python environments

+

An environment is a basically a folder that contains a Python +interpreter and other Python packages in a folder structure similar +to the operating system’s folder structure.

+

These environments can be created by the +venv-module in base +Python, by a pip package called +virtualenv +or by conda/mamba.

+

Using these environments is highly recommended because they solve the +following problems:

+
    +

  • Installing environments won’t modify system packages.

    • +

  • You can install specific versions of packages into them.

    • +

  • You can create an environment for each project and you won’t encounter any +problems if different projects require different versions of packages.

    • +

  • If you make some mistake and install something you did not want or need, you +can remove the environment and create a new one.

    • +

  • Others can replicate your environment by reusing the same specification +that you used to create the environment.

    • +
+
+
+

Creating Python environments

+
+

Record channels and packages you need to a file called +environment.yml:

+
name: my-environment
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - numpy
+  - matplotlib
+  - pandas
+
+
+

The name describes the name of the environment, +channels-list tells which channels should be search for packages +(channel priority goes from top to bottom) and dependencies-list +contains all packages that are needed.

+

Using this file you can now create an environment with:

+
$ conda env create --file environment.yml
+
+
+
+

You can also use mamba

+

If you have mamba installed, you can replace conda +with mamba in each command.

+
+

You can then activate the environment with:

+
$ conda activate my-environment
+
+
+
+

conda activate versus source activate

+

conda activate will only work if you have run conda init +in the past. Running conda init will make loading environments +easier as you will always have a conda environment loaded.

+

However, this can also cause problems as programs in the +main environment will be constantly loaded and they might be used +even when they’re not supposed to be used. A common example is +not having pip installed in a conda environment which results +pip from main environment to be used instead.

+
+

You can then check e.g. installed versions of Python and numpy:

+
$ python -c 'import sys; import numpy; print(f"Python version: {sys.version}\nNumPy version: {numpy.__version__}")'
+Python version: 3.13.0 | packaged by conda-forge | (main, Oct  8 2024, 20:04:32) [GCC 13.3.0]
+NumPy version: 2.1.2
+
+
+

To deactivate the environment, you can run:

+
$ conda deactivate
+
+
+
+
+

Creating environments without environment.yml/requirements.txt

+

It is possible to create environments with manual commands, but this +is highly discouraged for continuous use.

+

Firstly, replicating the environment becomes much harder.

+

Secondly, running package installation commands manually in an +environment can result in unexpected behaviour such as:

+
    +

  • Package manager might remove an already installed packages or update them.

    • +

  • Package manager might not find a package that works with already +installed packages.

    • +
+

The reason for this behavior is that package managers does not know what +commands you ran in the past. It only knows the state of your environment +and what you’re currently telling it to install.

+

These kinds of problems can be mitigated by recording dependencies in an +environment.yml or requirements.txt and using the relevant +package manager to update / recreate the environment.

+
+
+
+

Exercise 3

+
+

Dependencies-3: Create a Python environment (15 min)

+

Use conda or venv to create the environment presented in the +example.

+
+
+
+

Adding more packages to existing environments

+

Quite often when you’re creating a new environment you might forget +to add all relevant packages to environment.yml or +requirements.txt.

+

In these cases the best practice is to add missing packages to +environment.yml or requirements.txt and to update the environment.

+
+

Add new packages that you want to install to +dependencies in +environment.yml.

+

Afterwards, run

+
$ conda env update --file environment.yml
+
+
+

to update the environment.

+
+

Sometimes the new packages are incompatible with the ones already +in the environment. Maybe they have different dependencies that are +not satisfied with the current versions, maybe the package you’re installing +is incompatible with the ones installed. In these cases the safest approach +is to re-create the environment. This will let the dependency solvers +to start from clean slate and with a full picture of what packages +need to be installed.

+
+
+

Pinning package versions

+

Sometimes your code will only work with a certain range of dependencies. +Maybe you use a function or a class that was introduced in a later version +or a newer version has modified its API.

+

In these situations, you’ll want to pin the package versions.

+

For example, there is usually a delay between doing research and that +research being published. During this time packages used in the research +might update and reviewers or interested researchers might not be able +to replicate your results or run your code if new versions are not +compatible.

+
+

When pinning versions in environment.yml one can use a +variety of comparison operators:

+
name: my-environment
+channels:
+  - conda-forge
+dependencies:
+  # Use python 3.11
+  - python=3.11
+  # numpy that is bigger or equal than version 1, but less than version 2
+  - numpy>=1,<2
+  # matplotlib greater than 3.8.2
+  - matplotlib>3.8.2
+  # pandas that is compatible with 2.1
+  - pandas~=2.1
+
+
+
+

For more information on all possible specifications, see +this page +from Python’s packaging guide.

+

See also: https://coderefinery.github.io/reproducible-research/dependencies/

+
+

To pin or not to pin? That is the question.

+

Pinning versions means that you pin the environment to +that instance in time when these specific versions of the +dependencies were being used.

+

This can be good for single-use applications, like replicating a research +paper, but it is usually bad for the long-term maintainability of the software.

+

Pinning to major versions or to compatible versions is usually the best +practice as that allows your software to co-exist with other packages even +when they are updated.

+

Remember that at some point in time you will face a situation where +newer versions of the dependencies are no longer compatible with your +software. At this point you’ll have to update your software to use the newer +versions or to lock it into a place in time.

+
+
+
+

Exporting package versions from an existing environment

+

Sometimes you want to create a file that contains the exact versions +of packages in the environment. This is often called exporting or +freezing and environment.

+

Doing this will create a file that does describe the installed +packages, but it won’t tell which packages are the most important +ones and which ones are just dependencies for those packages.

+

Using manually created environment.yml or requirements.txt +are in most cases better than automatically created ones because they +shows which packages are the important packages needed by the software.

+
+

Once you have activated the environment, you can run

+
$ conda env export > environment.yml
+
+
+

If package build versions are not relevant for the use case, +one can also run

+
$ conda env export --no-builds > environment.yml
+
+
+

which leaves out the package build versions.

+

Alternatively one can also run

+
$ conda env export --from-history > environment.yml
+
+
+

which creates the environment.yml-file based on +what packages were asked to be installed.

+
+

conda-lock

+

For even more reproducibility, you should try out +conda-lock. +It turns your environment.yml into a conda.lock +that has all information needed to exactly create +the same environment. You can use conda.lock-files +in same way as environment.yml when you create +an environment:

+
$ conda env create --file conda.lock
+
+
+
+
+
+
+

Exercise 4

+
+

Dependencies-4: Export an environment (15 min)

+

Export the environment you previously created.

+
+
+
+

Additional tips and tricks

+
+
+

conda supports installing an environment from requirements.txt.

+
$ conda env create --name my-environment --channel conda-forge --file requirements.txt
+
+
+

To create an environment.yml from this environment that mimics +the requirements.txt, activate it and run

+
+
$ conda env export --from-history > environment.yml
+
+
+
+
+
+

How to communicate the dependencies as part of a report/thesis/publication

+

Each notebook or script or project which depends on libraries should come with +either a requirements.txt or a environment.yml, unless you are creating +and distributing this project as Python package (see next section).

+
    +

  • Attach a requirements.txt or a environment.yml to your thesis.

    • +

  • Even better: put requirements.txt or a environment.yml in your Git repository along your code.

    • +

  • Even better: also binderize your analysis pipeline (more about that in a later session).

    • +
+
+
+

Version pinning for package creators

+

We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in pyproject.toml (or setup.py) +(PyPI) or meta.yaml (conda).

+

These dependencies will then be used by either other libraries (who in turn +write their own setup.py or pyproject.toml or meta.yaml) or by +people directly (filling out requirements.txt or a environment.yml).

+

Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from setup.py):

+
# ...
+install_requires=[
+   'numpy==1.19.2',
+   'matplotlib==3.3.2'
+   'pandas==1.1.2'
+   'scipy==1.5.2'
+]
+# ...
+
+
+

or you can define a range or keep them undefined like here (example taken from +setup.py):

+
# ...
+install_requires=[
+   'numpy',
+   'matplotlib'
+   'pandas'
+   'scipy'
+]
+# ...
+
+
+

Should we pin the versions here or not?

+
    +

  • Pinning versions here would be good for reproducibility.

    • +

  • However pinning versions may make it difficult for this library to be used in a project alongside other +libraries with conflicting version dependencies.

    • +

  • Therefore as library creator make the version requirements as wide as possible.

    +
      +

    • Set minimum version when you know of a reason: >=2.1

      • +

    • Sometimes set maximum version to next major version (<4) (when +you currently use 3.x.y) when you expect issues with next +major version.

      • +
    +
    • +

  • As the “end consumer” of libraries, define your dependencies as narrowly as possible.

    • +
+
+
+

See also

+

Other tools for dependency management:

+
    +

  • Poetry: dependency management and packaging

    • +

  • Pipenv: dependency management, alternative to Poetry

    • +

  • pyenv: if you need different Python versions for different projects

    • +

  • micropipenv: lightweight tool to “rule them all”

    • +

  • mamba: a drop in replacement for +conda that does installations faster.

    • +

  • miniforge: Miniconda alternative with +conda-forge as the default channel and optionally mamba as the default installer.

    • +

  • micromamba: +tiny version of Mamba as a static C++ executable. Does not need base environment or +Python for installing an environment.

    • +

  • pixi: a package management tool which builds upon the foundation of the conda ecosystem.

    • +
+

Other resources:

+ +
+

Keypoints

+
    +

  • If somebody asks you what dependencies your code has, you should be able to answer this question with a file.

    • +

  • Install dependencies by first recording them in requirements.txt or +environment.yml and install using these files, then you have a trace.

    • +

  • Use isolated environments and avoid installing packages system-wide.

    • +
+
+
+
+
+

Binder

+
+

Questions

+
    +

  • Why sharing code alone may not be sufficient.

    • +

  • How to share a computational environment?

    • +

  • What is Binder?

    • +

  • How to binderize my Python repository?

    • +

  • How to publish my Python repository?

    • +
+
+
+

Objectives

+
    +

  • Learn about reproducible computational environments.

    • +

  • Learn to create and share custom computing environments with Binder.

    • +

  • Learn to get a DOI from Zenodo for a repository.

    • +
+
+
+

Why is it sometimes not enough to share your code?

+_images/python_unmasked.jpg +
+

Exercise 1

+
+

Binder-1: Discuss better strategies than only code sharing (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+
+
+
+

Sharing a computing environment with Binder

+

Binder allows you to create +custom computing environments that can be shared and used by many remote users. +It uses repo2docker to +create a container image (docker image) of a +project using information contained in included configuration files.

+

Repo2docker is a standalone package that you can install locally on your laptop +but an online Binder service is freely available. +This is what we will be using in the tutorial.

+

The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder.

+https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png +

Credit: Juliette Taka, Logilab and the OpenDreamKit project (2017)

+
+

Binder exercise/demo

+

In an earlier episode (Data visualization with Matplotlib) we have created this notebook:

+
import pandas as pd
+import matplotlib.pyplot as plt
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+data_2007 = data[data["year"] == 2007]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xscale("log")
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
+
+

We will now first share it via GitHub “statically”, +then using Binder.

+
+

Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this. This exercise (and all following) +requires git/GitHub knowledge and accounts, which wasn’t a +prerequisite of this course. Thus, this is a demo (and might even +be too fast for you to type-along). Watch the video if you +are reading this later on:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+
+
+
+

How can I get a DOI from Zenodo?

+

Zenodo is a general purpose open-access +repository built and operated by CERN and OpenAIRE that allows researchers to archive and get a +Digital Object Identifier (DOI) to data that they +share.

+ +
+ +
+
+

Parallel programming

+
+

Questions

+
    +

  • When you need more than one processor, what do you do?

    • +

  • How can we use more than one processor/core in Python?

    • +
+
+
+

Objectives

+
    +

  • Understand the major strategies of parallelizing code

    • +

  • Understand mechanics of the multiprocessing package

    • +

  • Know when to use more advanced packages or approaches

    • +
+
+
+

Modes of parallelism

+

You realize you do have more computation to do than you can on one processor? +What do you do?

+
    +

  1. Profile your code, identify the actual slow spots.

    2. +

  2. Can you improve your code in those areas? Use an existing library?

    3. +

  3. Are there are any low-effort optimizations that you can make?

    4. +

  4. Consider using numba or +cython to accelerate key functions.

    5. +

  5. Think about parallelizing.

    6. +
+

Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers).

+

Parallel computing is when many different tasks are carried out +simultaneously. There are three main models:

+
    +

  • Embarrassingly parallel: the code does not need to +synchronize/communicate with other instances, and you can run +multiple instances of the code separately, and combine the results +later. If you can do this, great! (array jobs, task queues, +workflow management tools)

    • +

  • Multithreading: Parallel threads need to communicate and do so via +the same memory (variables, state, etc). (OpenMP, threading)

    • +

  • Multiprocessing, message passing: Different processes manage +their own memory segments. They share data by communicating (passing +messages) as needed. (multiprocessing, MPI).

    • +
+
+

Warning

+

Parallel programming is not magic, but many things can go wrong and +you can get unexpected results or difficult to debug problems. +Parallel programming is a fascinating world to get involved in, but +make sure you invest enough time to do it well.

+

See the video by Raymond Hettinger (“See Also” at bottom +of page) for an entertaining take on this.

+
+
+
+

Multithreading and the GIL

+

The designers of the Python language made the choice +that only one thread in a process can run actual Python code +by using the so-called global interpreter lock (GIL). +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. But it’s not all bad!:

+
    +

  • External libraries (NumPy, SciPy, Pandas, etc), written in C or other +languages, can release the lock and run multi-threaded.

    • +

  • Most input/output releases the GIL, and input/output is slow. The +threading library can be used to multithread I/O.

    • +

  • Python libraries like multiprocessing and mpi4py run multiple +Python processes and this circumvents the GIL.

    • +
+

Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix:

+
import numpy as np
+import time
+
+A = np.random.random((4000,4000))
+A = A * A.T
+time_start = time.time()
+np.linalg.inv(A)
+time_end = time.time()
+print("time spent for inverting A is", round(time_end - time_start,2), 's')
+
+
+

If we run this in a Jupyter notebook or through a Python script, it +will automatically use multithreading through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either export OMP_NUM_THREADS=1 or export MKL_NUM_THREADS=1, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime.

+
+

See also

+ +
+
+
+

multiprocessing

+

As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +multiprocessing module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock.

+

To show an example, +the split-apply-combine +or map-reduce paradigm is +quite useful for many scientific workflows. Consider you have this:

+
def square(x):
+    return x*x
+
+
+

You can apply the function to every element in a list using the +map() function:

+
>>> list(map(square, [1, 2, 3, 4, 5, 6]))
+[1, 4, 9, 16, 25, 36]
+
+
+

The multiprocessing.pool.Pool class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list:

+
>>> from multiprocessing import Pool
+>>> with Pool() as pool:
+...     pool.map(square, [1, 2, 3, 4, 5, 6])
+[1, 4, 9, 16, 25, 36]
+
+
+
+

Warning

+

Running the above example interactively in a Jupyter notebook +or through an Python/IPython terminal may or may not work on your +computer! This is a feature and not a bug, as covered in the +documentation.

+

Fortunately, there is a fork of multiprocesssing called +multiprocess which does +work in interactive environments. All we have to do is install it +by pip install multiprocess and change the import statement: +from multiprocess import Pool.

+
+
+
+

Exercises, multiprocessing

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+
+
+

MPI

+

The message passing interface (MPI) approach to parallelization +is that:

+
    +

  • Tasks (cores) have a rank and are numbered 0, 1, 2, 3, …

    • +

  • Each task (core) manages its own memory

    • +

  • Tasks communicate and share data by sending messages

    • +

  • Many higher-level functions exist to distribute information to other tasks +and gather information from other tasks

    • +

  • All tasks typically run the entire code and we have to be careful to avoid +that all tasks do the same thing

    • +
+

Introductory MPI lessons where Python is included:

+ +

These blog posts are good for gentle MPI/mpi4py introduction:

+ +

Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together.

+

Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work:

+
import random
+import time
+from mpi4py import MPI
+
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x ** 2 + y ** 2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+comm = MPI.COMM_WORLD
+size = comm.Get_size()
+rank = comm.Get_rank()
+
+n = 10 ** 7
+
+if size > 1:
+    n_task = int(n / size)
+else:
+    n_task = n
+
+t0 = time.perf_counter()
+_, n_inside_circle = sample(n_task)
+t = time.perf_counter() - t0
+
+print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+n_inside_circle = comm.gather(n_inside_circle, root=0)
+print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+
+if rank == 0:
+    pi_estimate = 4.0 * sum(n_inside_circle) / n
+    print(
+        f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds"
+    )
+
+
+
+
+

Exercises, MPI

+
+

Parallel-3, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+
+
+

Coupling to other languages

+

As mentioned further up in “Multithreading and the GIL”, Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP “directly”.

+

However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don’t +need parallelism, but need to make an optimized algorithm for a small part of the code.

+

Two strategies are common:

+
    +

  • Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization:

    +
    +
      +

    • C: use the cffi package (C foreign function interface). ctypes is a similar but slightly more primitive module that is in the standard library.

      • +

    • C++: use pybind11

      • +

    • Fortran: create a C interface using iso_c_binding and then couple the C layer to Python +using cffi

      • +

    • Rust: use PyO3

      • +
    +
    +
    • +

  • Let compiled languages do the shared-memory parallelization part (as in above +point) and let Python do the MPI work and distribute tasks across nodes using +an mpi4py layer.

    • +
+

Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course.

+

Before you take this route, profile the application first to be sure where +the bottleneck is.

+

Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason.

+
+
+

Dask and task queues

+

There are other strategies that go completely beyond the manual +parallelization methods above. We won’t go into much detail.

+
+

Dask

+

Dask is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs.

+

Dask is very popular for data analysis and is used by a number of high-level Python libraries:

+
    +

  • Dask arrays scale NumPy (see also xarray

    • +

  • Dask dataframes scale Pandas workflows

    • +

  • Dask-ML scales Scikit-Learn

    • +
+

Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block.

+
+

Example from dask.org

+
# Arrays implement the Numpy API
+import dask.array as da
+x = da.random.random(size=(10000, 10000),
+                     chunks=(1000, 1000))
+x + x.T - x.mean(axis=0)
+# It runs using multiple threads on your machine.
+# It could also be distributed to multiple machines
+
+
+
+
+
+
+

Exercises, Dask

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+

Task queues

+

A task queue has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for embarrassingly parallel jobs.

+

There are different descriptions of task queues in Python. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant.

+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pure Python is not very good for highly parallel code.

    • +

  • Luckily it interfaces to many things which are good, and give +you the full control you need.

    • +

  • Combining vectorized functions (NumPy, Scipy, pandas, etc.) with +the parallel strategies listed here will get you very far.

    • +

  • Another popular framework similar to multiprocessing is +joblib.

    • +
+
+
+
+
+

Packaging

+
+

Questions

+
    +

  • How to organize Python projects larger than one script?

    • +

  • What is a good file and folder structure for Python projects?

    • +

  • How can you make your Python functions most usable by your collaborators?

    • +

  • How to prepare your code to make a Python package?

    • +

  • How to publish your Python package?

    • +
+
+
+

Objectives

+
    +

  • Learn to identify the components of a Python package

    • +

  • Learn to create a Python package

    • +

  • Learn to publish a Python package

    • +
+
+
+

Organizing Python projects

+

Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file.

+

In the Scripts episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further.

+

Recommendations:

+ +

To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: scipy.

+

These are the 3 files:

+
+
adding.py
+
def add(x, y):
+    return x + y
+
+
+
+
+
subtracting.py
+
def subtract(x, y):
+    return x - y
+
+
+
+
+
integrating.py
+
from scipy import integrate
+
+
+def integral(function, lower_limit, upper_limit):
+    return integrate.quad(function, lower_limit, upper_limit)
+
+
+
+

We will add a fourth file:

+
+
__init__.py
+
"""
+Example calculator package.
+"""
+
+from .adding import add
+from .subtracting import subtract
+from .integrating import integral
+
+__version__ = "0.1.0"
+
+
+
+

This __init__.py file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using relative imports +(with the dot).

+

This is how we will arrange the files in the project folder/repository:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+└── README.md
+
+
+

Now we are ready to test the package. For this we need to be in the “root” +folder, what we have called the project-folder. We also need to have +scipy available in our environment:

+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+

The package is not yet pip-installable, though. We will make this possible in +the next section.

+
+
+

Testing a local pip install

+

To make our example package pip-installable we need to add one more file:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+├── README.md
+└── pyproject.toml
+
+
+

This is how pyproject.toml looks:

+
+
pyproject.toml
+
[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "calculator-myname"
+description = "A small example package"
+version = "0.1.0"
+readme = "README.md"
+authors = [
+    { name = "Firstname Lastname", email = "firstname.lastname@example.org" }
+]
+dependencies = [
+    "scipy"
+]
+
+
+
+

Note how our package requires scipy and we decided to not pin the version +here (see Version pinning for package creators).

+

Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see PyPI (The Python Package Index) and conda ecosystem)

+
+
+

Exercises 1

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Sharing packages via PyPI

+

Once we are able to pip-install the example package locally, we are ready for +upload.

+

We exercise by uploading to test-PyPI, not the +real PyPI, so that if we mess things up, nothing bad +happens.

+

We need two more things:

+
    +

  • We will do this using Twine so you need +to pip install that, too.

    • +

  • You need an account on test-PyPI.

    • +
+

Let’s try it out. First we create the distribution package:

+
$ python3 -m build
+
+
+

We need twine:

+
$ pip install twine
+
+
+

And use twine to upload the distribution files to test-PyPI:

+
$ twine upload -r testpypi dist/*
+
+Uploading distributions to https://test.pypi.org/legacy/
+Enter your username:
+Enter your password:
+
+
+

Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt “myname”):

+
$ pip install -i https://test.pypi.org/simple/ calculator-myname
+
+
+
+
+

Tools that simplify sharing via PyPI

+

The solution that we have used to create the example package (using +setuptools and twine) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using pyproject.toml as more general +alternative to the previous setup.py.

+

There are at least two tools which try to make the packaging and PyPI interaction easier:

+ +
+
+

Building a conda package and share it

+
+

Demo

+

Most people will watch and observe this, due to speed which we will +move.

+
+
+

Prerequisites

+

To create a conda package, conda-build package is required. You may install it with Anaconda Navigator or from the command line:

+
$ conda install conda-build
+
+
+
+

The simplest way for creating a conda package for your python script is to +first publish it in PyPI following the steps explained +above.

+
+

Building a python package with conda skeleton pypi

+

Once build, the conda package can be installed locally. For this example, we +will use runtest. runtest is a numerically tolerant end-to-end test +library for research software.

+
    +

  1. Create pypi skeleton:

    +
    $ conda skeleton pypi runtest
+
    +
    +

    The command above will create a new folder called runtest containing a file meta.yaml, the conda recipe for runtest.

    +
    2. +

  2. Edit meta.yaml and update requirements:

    +
    requirements:
+  host:
+    - pip
+    - python
+    - flit
+  run:
+    - python
+    - flit
+
    +
    +

    In the requirements above, we specified what is required for the host and for running the package.

    +
    +

    Remark

    +

    For pure python recipes, this is all you need for building a python package with conda. +If your package needs to be built (for instance compilation), you would need additional files e.g. build.sh (to build on Linux/Mac-OSX) and bld.bat (to build on Windows systems). You can also add test scripts for testing your package. See documentation

    +
    +
    3. +

  3. Build your package with conda

    +

    Your package is now ready to be build with conda:

    +
    $ conda-build runtest
+
    +
    +
    +

    Conda package location

    +

    Look at the messages produced while building. The location of the local conda package is given (search for anaconda upload):

    +
    ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2
+
    +
    +

    The prefix ~/anaconda3/ may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder win-64 differs too (for instance linux-64 on Linux machines).

    +

    The conda package we have created is specific to your platform (here win-64). It can be converted to other platforms using conda convert.

    +
    +
    4. +

  4. Check within new environment

    +

    It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments.

    +
    $ conda create -n local-runtest --use-local runtest
+
    +
    +

    We can then check runtest has been successfully installed in local-runtest conda environment. Open a new Terminal with local-runtest environment (either from the command line:

    +
    $ conda activate local-runtest
+
    +
    +

    or via Anaconda Navigator (Open Terminal), import runtest and +check its version:

    +
    import runtest
+print(runtest.__version__)
+
    +
    +
    5. +
+
+

Building a conda package from scratch

+

It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the conda-build documentation for more information.

+
+

To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a conda channel (see below).

+
+
+

Publishing a python package

+
    +

  • Upload your package to Anaconda.org: see instructions here. +Please note that you will have to create an account on Anaconda.

    • +

  • Upload your package to conda-forge: +conda-forge is a conda channel: it contains community-led collection of +recipes, build infrastructure and distributions for the conda package +manager. Anyone can public conda packages to conda-forge if certain +guidelines are respected.

    • +

  • Upload your package to bioconda: bioconda is +a very popular channel for the conda package manager specializing in +bioinformatics software. As for conda-forge, you need to follow their +guidelines when +building conda recipes.

    • +
+

You can also create your own conda channel +for publishing your packages.

+
+

Keypoints

+
    +

  • It is worth it to organize your code for publishing, even if only +you are using it.

    • +

  • PyPI is a place for Python packages

    • +

  • conda is similar but is not limited to Python

    • +
+
+
+
+
+
+

Web APIs with Python

+
+

Questions

+
    +

  • Have you ever needed to get some data from somewhere else on the web?

    • +
+
+
+

Objectives

+
    +

  • Understand a web server and API and why might you need to talk to one.

    • +

  • Basics of the requests Python library

    • +

  • Some lightweight recommendations on saving data when you get to more serious data download.

    • +
+
+
+

Requests

+

Requests is a Python library that makes requests to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.

+

First, let’s take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: https://requests.readthedocs.io/en/latest/

+
+
+
# Embed the requests homepage
+from IPython.display import IFrame
+requests_documentation_url = "https://requests.readthedocs.io/en/latest/"
+IFrame(requests_documentation_url, '100%', '30%')
+
+
+
+
+
+
+

Retrieve data from API

+

An API (Application Programming Interface) is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the request-response cycle.

+

We can find a list of some free APIs (available without authentication) at https://apipheny.io/free-api/#apis-without-key . These APIs can be used for developing and testing our code.

+

Let’s make a request to the Cat Fact API. If we go to https://catfact.ninja/, it gives us the definitions:

+
    +

  • GET /fact is the API endpoint.

    • +

  • GET is the type of request we make and

    • +

  • /fact is the path.

    • +
+

You can even test this in your web browser: https://catfact.ninja/fact

+

Using the Requests library, we do this with get().

+
+
+
# Import
+import requests
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make a request
+response = requests.get(url)
+
+
+
+
+

The requests.Response object tells us what the server said. We can access the response content using content.

+
+
+
response_content = response.content
+
+# Display
+display(response_content)
+
+
+
+
+

The response content is in the JSON format and Requests gives us the json() method that decodes it and returns the corresponding data as Python objects. This is equivalent to json.load().

+
+
+
response_json = response.json()
+
+# Display
+display(response_json)
+
+
+
+
+

(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)

+
+
+

API which requires parameters

+

Let’s then examine another API which accepts parameters to specify the information request. In particular, we will request a list of Finnish universities from http://universities.hipolabs.com using the /search end point and a parameter country with value Finland, like this: +http://universities.hipolabs.com/search?country=Finland .

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search?country=Finland'
+
+# Make a request
+response = requests.get(url)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+

URLs containing parameters can always be constructed manually using the & character and then listing the parameter (key, value) pairs as above.

+

However, Requests allows us to provide the parameters as a dictionary of strings, using the params keyword argument to get(). This is easier to read and less error-prone.

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search'
+
+# Make the parameter dictionary
+parameters = {'country' : 'Finland'}
+
+# Get response
+response = requests.get(url, params=parameters)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+
+
+

Exercises 1

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+
+
+
# Import module
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Send the request using the get() function
+response = requests.get(url)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+
+
+
+
+

Next, let’s try to narrow down the suggestions by adding some parameters

+
    +

  • type

    • +

  • participants

    • +
+

All possible parameter values are presented at the bottom of the bored documentation page. Relevant parts in the Requests documentation

+
+
+
# Define some parameters
+params = {
+    'type' : 'education',
+    'participants' : 1,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display("Response")
+display(response.json())
+
+
+
+
+

Let’s narrow the request further with more parameters

+
    +

  • price range

    • +

  • accessibility range

    • +
+

(All possible parameter values are again presented at the bottom of the document page.)

+
+
+
# Define some parameters
+params = {
+    'type' : 'social',
+    'participants' : 2,
+    'minprice' : 0,
+    'maxprice' : 1000,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+display("")
+
+
+
+
+
+
+

Exercises 2

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+
+
+
# Import modules
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Make the request using the get() function
+response = requests.get(url)
+
+
+
+
+

We can access the headers of the original request

+
+
+
display("Request headers")
+display(dict(response.request.headers))
+
+
+
+
+

We can also access the headers of the response

+
+
+
display("Response headers")
+display(dict(response.headers))
+
+
+
+
+

In many cases, the default headers

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive'}
+
+
+

added automatically by Requests are sufficient. However, similarly to parameters, we can pass custom headers to the get function as an argument.

+

This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive',
+ 'example-user-id' : 'example-password'}
+
+
+

For examples of APIs using this type of authentication, see

+ +

For more on authentication, see also Requests documentation.

+
+
+

Exercises 3

+ +
+
+
# Import module
+import requests
+
+# Define webpage to scrape
+url = "http://www.example.com/"
+
+# Make a request for the URL
+response = requests.get(url)
+
+# Examine the response
+display(response.content)
+
+
+
+
+
+
+
# Looks like HTML :) Let's access it using the text attribute
+html = response.text
+
+print(html)
+
+
+
+
+
+
+
# Import beautiful soup module
+from bs4 import BeautifulSoup
+
+# Create soup
+soup = BeautifulSoup(html, 'html.parser')
+
+
+
+
+
+
+
# Extract page title from the HTML
+print(f"Found title: {soup.title.text}")
+
+
+
+
+
+
+
# Extract links (hrefs) from the HTML
+for link in soup.find_all('a'):
+    print(f"Found link: {link.get('href')}")
+
+
+
+
+
+
+
# Extract all text from the HTML
+print(f"Found text: {soup.get_text()}")    
+
+
+
+
+
+
+

After exercises: Saving retrieved data to disk

+

Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudinal study.

+

To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don’t, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).

+

For example, let’s retrieve three cat facts and save them to a JSONLINES file using the jsonlines library.

+
+
+
# Import
+import requests
+import jsonlines
+import time
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make three requests in loop and make a list of response JSON objects
+for i in range(3):
+
+    # Logging
+    print(f"Make request {i}")
+
+    # Make a request
+    response = requests.get(url)
+    
+    # Decode to JSON
+    response_json = response.json()
+                
+    # Open a jsonlines writer in 'append' mode 
+    with jsonlines.open('catfacts.jsonl', mode='a') as writer:
+
+        # Write
+        writer.write(response_json)
+        
+    # Sleep for one second between requests
+    time.sleep(1)
+
+
+
+
+

We can then read the objects from the disk using the same library.

+
+
+
# Open a jsonlines reader
+with jsonlines.open('catfacts.jsonl', mode='r') as reader:
+    
+    # Read and display
+    for obj in reader:
+        display(obj)
+
+
+
+
+
+
+

Wrap-up

+
+

Keypoints

+
    +

  • Requests is a common tool

    • +

  • Web APIs may often require some trial and error, but actually getting data is usually not that difficult

    • +

  • Storing all the data and processing it well can be a much larger issue.

    • +
+
+
+
+
+
+
+

Software installation

+

This course is interactive and demonstrates many different tools. +Thus, even beyond Python, extra software (Python libraries) needs to +be installed. This page contains the instructions.

+

Once the course starts, we don’t have time to stop for installing +software.

+

Please make sure before the course that you have all the required +software installed or some other way access to it. For example, the +workshop could be done with a remote Jupyter server, as long as you +can use the terminal from the Jupyter (you need to be able to access +the command line for some lessons).

+
+

Do you need help?

+

Participants from a partner institution are invited to install help +sessions. (Hint: ask your institution to become a partner if it +isn’t already!)

+

Otherwise, if you need installation help, show this page to someone +around you and they can probably help. These are relatively +standard tools.

+

Don’t be afraid to ask for help. Installing scientific software is +harder than it should be and it helps to have someone guide you +through it.

+
+
+

Python

+

We expect you to have a working Python installation with some common +libraries. We currently recommend Miniforge, which includes the base and +packages through a different, freely usable channel. You can +explore the options in the tabs below.

+
+

Python, conda, anaconda, miniforge, etc?

+

Unfortunately there’s a lot of jargon. We’ll go over this in the +course but here is a crash course:

+
    +

  • Python is a programming language very commonly used in +science, it’s the topic of this course.

    • +

  • Conda is a package manager: it allows distributing and +installing packages, and is designed for complex scientific +code.

    • +

  • Mamba is a re-implementation of Conda to be much faster with +resolving dependencies and installing things.

    • +

  • An Environment is a self-contained collections of packages +which can be installed separately from others. They are used so +each project can install what it needs without affecting others.

    • +

  • Anaconda is a commercial distribution of Python+Conda+many +packages that all work together. It used to be freely usable for +research, but since ~2023-2024 it’s more limited. Thus, we don’t +recommend it (even though it has a nice graphical user interface).

    • +

  • conda-forge is another channel of distributing packages that +is maintained by the community, and thus can be used by anyone. +(Anaconda’s parent company also hosts conda-forge packages)

    • +

  • miniforge is a distribution of conda pre-configured for +conda-forge. It operates via the command line.

    • +

  • miniconda is a distribution of conda pre-configured to use +the Anaconda channels.

    • +
+
+
+

This is our recommended method - it can be used for any purpose +and makes a strong base for the future.

+

Follow the instructions on the miniforge web page. This installs +the base, and from here other packages can be installed.

+

Miniforge uses the command line - this gives you the most power +but can feel unfamiliar. See the command line crash course for an intro.

+
+
+
+

Starting Python

+

You need to Python in a way that activates conda/mamba.

+
+
+

Linux/MacOS: Each time you start a new command line terminal, +you can activate Miniforge by running. This is needed so that +Miniforge is usable wherever you need, but doesn’t affect any +other software on your computer (this is not needed if you +choose “Do you wish to update your shell profile to +automatically initialize conda?”, but then it will always be +active):

+
$ source ~/miniforge3/bin/activate
+
+
+
+
+
+
+

Python for SciComp software environment

+

Once Python and conda/mamba are installed, you can use it to install +an environment. An environment is a self-contained set of extra +libraries - different projects can use different environments to not +interfere with each other. This environment will have all of the +software needed for this particular course.

+
+

This environment file +contains all packages needed for the course, and can be +installed with. The following command will install an +environment named python-for-scicomp (there may be lots of +warning messages: this is OK if it still goes through):

+
+
$ mamba env create -n python-for-scicomp -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml
+
+
+
+

Each time you start a new command line, you need to activate +miniforge and this environment:

+
+
$ source ~/miniforge3/bin/activate
+$ conda activate python-for-scicomp
+
+
+
+
+
+
+

JupyterLab

+

We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need).

+
+

JupyterLab was instaled in the previous step. To run it, first, +start the Miniforge command line interface. Remember, you may +need to activate Miniforge and the environment first.

+
+
$ source ~/miniforge3/bin/activate
+$ conda activate python-for-scicomp
+$ jupyter-lab
+
+
+
+
+
+
+

Verification of Python and JupyterLab

+
+

Watch the video

+

See this verification in video form - if you can do this, you are +ready to go for day one. Your exact steps may be a bit different.

+

Remember that you need to activate the environment first - see the +step above.

+
+
+

You can start JupyterLab from the command line:

+
$ jupyter-lab
+(... Jupyter starts in a web browser)
+
+
+
+

Verify that you can start a Jupyter notebook. We will learn how to +do this in day 1, but you can try running print("Hello, world!") +if you want.

+
+_images/jupyterlab-notebook.png +
+

Starting a Jupyter Notebook from JupyterLab.

+
+
+
+
+

Text editor

+

For one portion of the course, you will need a text editor. If you +don’t know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.

+
+

Other editors

+

Because we need to be simple in our teaching, we only teach the +most basic editors. We encourage you to try out more advanced ones +yourself.

+

For other editors, see the CodeRefinery instructions. You don’t +exactly need a terminal editor - the graphical ones, such as VSCode or +whatever you use now, will work as well.

+
+
+
+

Command line

+

You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed. If you want to +test in advance:

+
    +

  • You can start it from JupyterLab (recommended):

    +
    +_images/jupyterlab-terminal.png + +
    +

    From the JupyterLab launcher, select “Terminal”.

    +
    +
    +
    • +
+
+

Other ways to access the command line

+
    +

  • From the Anaconda Navigator:

    +
    +_images/anaconda-prompt.png +
    +

    From the Anaconda Navigator, you can select “environments” on the +left, then click on one, then the arrow, then “Open terminal”.

    +
    +
    +
    • +

  • From your operating system’s terminal applications, if you activate +Anaconda.

    • +
+
+
+

Verification of the command line

+

To verify command line usage, type the following commands (without the +$), and you should see the corresponding output that lists the +Python version:

+
$ python3 -V
+Python 3.8.3
+
+## Or python... if it's installed as that
+$ python -V
+Python 3.8.3
+
+
+

Any recent version of Python 3 should work for the course (for example +3.8 or higher).

+
+
+
+

Zoom

+

If this is an online workshop, it might use Zoom. You can see +CodeRefinery instructions for it.

+
+
+

Need help?

+

If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up!

+
+
+

See also

+ +
+
+
+

Quick reference

+ +
+
+

List of exercises

+
+

Full list

+

This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests.

+
+
+
+

Instructor’s guide

+
+

Learner personas

+

A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

+

A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

+

B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

+

Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren’t familiar.

+

Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter

+
+
+

About each section

+

In general, “Python for Scientific Computing could be a multi-year +course. We can’t even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path.

+
    +

  • Python intro: We can’t really replace a Python tutorial, but +here we try to outline some of the main points. We don’t go over +this in the course.

    • +

  • Jupyter: Jupyter is somewhat useful, but the main reason we go +over it is that it provides a convenient user interface for the +other programming lessons (it’s easier to spend a bit of time with +Jupyter than expect people to be able to use some +editor/IDE/shell/etc). So, we do start from the beginning, so that +people can do the other lessons, but also try to teach some advanced +tips and tricks.

    • +

  • Numpy: The basic of much of the rest of scipy, so we need to +cover it. We try to get the main principles out, but if someone +already knows it this can be a bit boring. We try to make sure +everyone comes out with an appreciation for vectorization and +broadcasting.

    • +

  • Pandas: A lot of similar goals to the Numpy section, especially +the concepts behind Dataframes that one needs to know in order to +read other documentation.

    • +

  • Visualization: Matplotlib is getting a bit old, but is still the +backbone of other plotting packages. We try to get forth the ideas +of the matplotlib API that can be seen in other packages and the +importance of scripted plots.

    • +

  • Data formats: Input/output/storage is a common task, and can +easily either be a bottleneck or a huge mess. This lessons tries to +show some best practices with data formats and, as usual, get the +idea to not “do it yourself”. Pandas is used as a common framework, +but we should point out there are plenty of other options.

    • +

  • Scripts: The most important lesson here is to break out of +Jupyter/run buttons of editors. If you can’t make actual programs +with an actual interface, you can’t scale up.

    +
      +

    • This is the first lesson to introduce the command line. We +recommend being as simple as possible: at least demonstrate the +JupyterLab terminal and discuss the bigger picture behind what it +means and why.

      • +

    • This is also the first lesson to use non-Jupyter code editor. We +recommend again being simple: use the JupyterLab code editor to +start off, and carefully explain what is going on.

      • +
    +
    • +

  • Scipy: We don’t cover much here (this is super short), but the +point is scipy exists and the concept of wrapping existing C/fortran +libraries and so on.

    • +

  • Library ecosystem: This was an overview of the types of packages +available in the “scipy ecosystem”, which is a large and ill-defined +thing. But there is another point: choosing what to use. Do you +trust a half-done thing published on someone’s personal webpage? If +it’s on Github? How do you make your code more reusable? When +coming from academic courses, you get a “build it yourself” idea, +which isn’t sustainable in research.

    • +

  • Parallel programming:

    • +

  • Dependencies: The main point here is environments, another thing +you often don’t learn in courses.

    +
      +

    • There is a lot of material here. Consider what you will demo, +what will be done as exercises, and what is advanced/optional. +However, it is the fourth-day lesson that is most interactive, so +it is OK if it take a while to go through everything.

      • +

    • If someone else installs Anaconda for a user (e.g. admin-managed +laptop), the conda environment creations (with --name, +possibly with --prefix too?) may not work. Be prepared for +this and mention it. You don’t need to solve the problem but +acknowledge that the lesson becomes a demo. The virtualenv part +should hopefully work for them.

      • +
    +
    • +

  • Binder: Binder exists and can help make code +reproducible/reusable by others.

    • +

  • Packaging: How to make your code reusable by others. By the +time we get here, people are tired and the topics get involved. We +more explicitly say “you might want to watch and take this as a +demo”.

    • +
+
+
+
+

In depth analysis of some selected file formats

+

Here is a selection of file formats that are commonly used in data science. They are somewhat ordered by their intended use.

+
+

Storing arbitrary Python objects

+
+

Pickle

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: None (pickle-module is included with Python).

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: 🟨

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ❌! See warning below.

    • +

  • Best use cases: Saving Python objects for debugging.

    • +
+
+
+

Warning

+

Loading pickles that you have not created is +risky as they can contain arbitrary executable code.

+

Do not unpickle objects from sources that you do not trust!

+
+

Pickle is Python’s own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:

+
import pickle
+
+with open('data_array.pickle', 'wb') as f:
+    pickle.dump(data_array, f)
+
+with open('data_array.pickle', 'rb') as f:
+    data_array_pickle = pickle.load(f)
+
+
+
+
+
+

Exercise 1

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+ +
+
+

Storing tidy data

+
+

CSV (comma-separated values)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: numpy, pandas

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data. Small data. Data that needs to be human-readable.

    • +
+
+

CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you’re working with big data.

+

Pandas has a very nice interface for writing and reading CSV files with to_csv- and read_csv-functions:

+
dataset.to_csv('dataset.csv', index=False)
+
+dataset_csv = pd.read_csv('dataset.csv')
+
+
+

Numpy has routines for saving and loading arrays as CSV files as well:

+
np.savetxt('data_array.csv', data_array)
+
+data_array_csv = np.loadtxt('data_array.csv')
+
+
+
+

Storing data in CSVs can reduce data precision

+
+

When working with floating point numbers you should be careful to save the data with enough decimal places so that you won’t lose precision.

+

For example, double-precision floating point numbers have ~16 decimal places of precision, but if you use normal Python to write these numbers, you can easily lose some of that precision. +Let’s consider the following example:

+
import numpy as np
+test_number = np.sqrt(2)
+# Write the number in a file
+test_file = open('sqrt2.csv', 'w')
+test_file.write('%f' % test_number)
+test_file.close()
+# Read the number from a file
+test_file = open('sqrt2.csv', 'r')
+test_number2 = np.float64(test_file.readline())
+test_file.close()
+# Calculate the distance between these numbers
+print(np.abs(test_number - test_number2))
+
+
+

CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. +We can check whether our written data matches the generated data:

+
dataset.compare(dataset_csv)
+
+np.all(data_array == data_array_csv)
+
+
+

In our case some rows of dataset_csv loaded from CSV do not match the original dataset as the last decimal can sometimes be rounded due to complex technical reasons.

+

Storage of these high-precision CSV files is usually very inefficient storage-wise.

+

Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems.

+
+
+
+
+

Feather

+
+

Requires additional packages

+
+

Using Feather requires pyarrow-package to be installed.

+

You can try installing pyarrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Temporary storage of tidy data.

    • +
+
+

Feather is a file format for storing data frames quickly. +There are libraries for Python, R and Julia.

+

We can work with Feather files with to_feather- and read_feather-functions:

+
dataset.to_feather('dataset.feather')
+dataset_feather = pd.read_feather('dataset.feather')
+
+
+

Feather is not a good format for storing array data, so we won’t present an example of that here.

+
+
+

Parquet

+
+

Requires additional packages

+
+

Using Parquet requires pyarrow-package to be installed.

+

You can try installing PyArrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in tidy data format. Archival of said data.

    • +
+
+

Parquet is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.).

+

We can work with Parquet files with to_parquet- and read_parquet-functions:

+
dataset.to_parquet('dataset.parquet')
+dataset_parquet = pd.read_parquet('dataset.parquet')
+
+
+

Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won’t do that here.

+
+
+
+

Exercise 2

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+ +
+
+

Storing array data

+
+

npy (numpy array format)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Saving numpy arrays temporarily.

    • +
+
+

If you want to temporarily store numpy arrays, you can use the numpy.save()- and numpy.load()-functions:

+
np.save('data_array.npy', data_array)
+data_array_npy = np.load('data_array.npy')
+
+
+

There also exists numpy.savez()-function for storing multiple datasets in a single file:

+
np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array)
+data_arrays = np.load('data_arrays.npz')
+data_arrays['data_array0']
+
+
+

For big arrays it’s good idea to check other binary formats such as HDF5 or NetCDF4.

+

np.save- and np.savez-functions work with +sparse matrices, +but one can also use dedicated +scipy.sparse.save_npz- and +scipy.sparse.load_npz-functions. +Storing sparse matrices using these functions can give huge storage savings.

+
+
+

HDF5 (Hierarchical Data Format version 5)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy, pandas, PyTables, h5py

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format.

    • +
+
+

HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences.

+

Pandas allows you to store tables as HDF5 with PyTables, which uses HDF5 to write the files. +You can create a HDF5 file with to_hdf- and read_parquet-functions:

+
dataset.to_hdf('dataset.h5', key='dataset', mode='w')
+dataset_hdf5 = pd.read_hdf('dataset.h5')
+
+
+

For writing data that is not a table, you can use the excellent h5py-package:

+
import h5py
+
+# Writing:
+
+# Open HDF5 file
+h5_file = h5py.File('data_array.h5', 'w')
+# Write dataset
+h5_file.create_dataset('data_array', data=data_array)
+# Close file and write data to disk. Important!
+h5_file.close()
+
+# Reading:
+
+# Open HDF5 file again
+h5_file = h5py.File('data_array.h5', 'r')
+# Read the full dataset
+data_array_h5 = h5_file['data_array'][()]
+# Close file
+h5_file.close()
+
+
+
+
+

NetCDF4 (Network Common Data Form version 4)

+
+

Requires additional packages

+
+

Using NetCDF4 requires netCDF4- or h5netcdf-package to be installed. +h5netcdf is often mentioned as being faster to the official netCDF4-package, so we’ll be using it in the example.

+

A great NetCDF4 interface is provided by a xarray-package.

+

You can try installing these packages with

+
!pip install h5netcdf xarray
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, netCDF4/h5netcdf, xarray

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets.

    • +
+
+

NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs.

+

NetCDF4 is a common format for storing large data from big simulations in physical sciences.

+

Using interface provided by xarray:

+
# Write tidy data as NetCDF4
+dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf')
+# Read tidy data from NetCDF4
+import xarray as xr
+dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf')
+dataset_netcdf4 = dataset_xarray.to_pandas()
+dataset_xarray.close()
+
+
+

Working with array data is easy as well:

+
# Write array data as NetCDF4
+xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf')
+# Read array data from NetCDF4
+data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf')
+data_array_netcdf4 = data_array_xarray.to_numpy()
+data_array_xarray.close()
+
+
+

The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (x, y, z) or timestamps (t) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis.

+
+
+
+

Exercise 3

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+ +
+
+

Other file formats

+
+

JSON (JavaScript Object Notation)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: None (json-module is included with Python).

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Saving nested/relational data, storing web requests.

    • +
+
+

JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.).

+

You rarely want to keep your data in this format, unless you’re working with +nested data with multiple layers or lots of interconnections.

+

Similarly to other popular files, Pandas can write and read json files with to_json()- and read_json()-functions:

+
dataset.to_json('dataset.json')
+dataset_json = pd.read_json('dataset.json')
+
+
+
+
+

Excel

+
+

Requires additional packages

+

Using Excel files with Pandas requires openpyxl-package to be installed.

+
+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: openpyxl

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: 🟨

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data in many fields. Quick data analysis.

    • +
+
+

Excel is very popular in social sciences and economics. +However, it is not a good format for data science.

+

See Pandas’ documentation on working with Excel files.

+
+
+

Graph formats (adjency lists, gt, GraphML etc.)

+
+

Key features

+
    +

  • Type: Many different formats

    • +

  • Packages needed: Depends on a format.

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: 🟨

    • +

  • Best use cases: Saving graphs or data that can be represented as a graph.

    • +
+
+

There are plenty of data formats for storing graphs. +We won’t list them here as optimal data format depends heavily on the graph structure.

+

One can use functions in libraries such as +networkx, +graph-tool, +igraph +to read and write graphs.

+
+
+
+
+
+

Who is the course for?

+

The course is targeted towards these learner personas:

+
    +

  • A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able +to do their research more efficiently and make sure that they are +using the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

    • +

  • A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

    • +

  • B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves: they want to know how to reuse tools +that already exist.

    • +
+
+
+

Motivation

+
+

Why Python

+

Python has become popular, largely due to good reasons. It’s very easy +to get started, there’s lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities.

+
+
+

Why not Python for Scientific Computing

+

While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools.

+
    +

  • Implementing performance-critical kernels. Python is a very +slow language, which often doesn’t matter if you can offload the +heavy lifting to fast compiled code, e.g. by using Numpy array +operations. But if what you’re trying to do isn’t vectorizable +then you’re out of luck. An alternative to Python, albeit much less +mature and with a smaller ecosystem, but which provides very fast +generated code, is Julia.

    • +

  • Creating libraries that can be called from other languages. In this +case you’ll often want to create a library with a C interface, which +can then be called from most languages. Suitable languages for this +sort of task, depending on what you are doing, could be Rust, C, +C++, or Fortran.

    • +

  • You really like static typing, or functional programming +approaches. Haskell might be what you’re looking for.

    • +
+
+
+

Python 2 vs Python 3

+

Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard.

+

At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2.

+
+
+
+

Credits

+

This course was originally designed by Janne Blomqvist.

+

In 2020 it was completely redesigned by a team of the following:

+
    +

  • Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, …

    • +

  • Editor:

    • +

  • Testers and advisors: Enrico Glerean

    • +
+

We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

+
+
+

See also

+ +
+
+ + + + +
+
+
+ +
+ +
+

© Copyright 2020-2024, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/singlehtml/objects.inv b/branch/master/singlehtml/objects.inv new file mode 100644 index 00000000..a013cb8a Binary files /dev/null and b/branch/master/singlehtml/objects.inv differ diff --git a/branch/master/web-apis/index.html b/branch/master/web-apis/index.html new file mode 100644 index 00000000..4c4cede7 --- /dev/null +++ b/branch/master/web-apis/index.html @@ -0,0 +1,611 @@ + + + + + + + + + + + + + + + Web APIs with Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Web APIs with Python

+
+

Questions

+
    +

  • Have you ever needed to get some data from somewhere else on the web?

    • +
+
+
+

Objectives

+
    +

  • Understand a web server and API and why might you need to talk to one.

    • +

  • Basics of the requests Python library

    • +

  • Some lightweight recommendations on saving data when you get to more serious data download.

    • +
+
+
+

Requests

+

Requests is a Python library that makes requests to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.

+

First, let’s take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: https://requests.readthedocs.io/en/latest/

+
+
+
# Embed the requests homepage
+from IPython.display import IFrame
+requests_documentation_url = "https://requests.readthedocs.io/en/latest/"
+IFrame(requests_documentation_url, '100%', '30%')
+
+
+
+
+
+
+

Retrieve data from API

+

An API (Application Programming Interface) is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the request-response cycle.

+

We can find a list of some free APIs (available without authentication) at https://apipheny.io/free-api/#apis-without-key . These APIs can be used for developing and testing our code.

+

Let’s make a request to the Cat Fact API. If we go to https://catfact.ninja/, it gives us the definitions:

+
    +

  • GET /fact is the API endpoint.

    • +

  • GET is the type of request we make and

    • +

  • /fact is the path.

    • +
+

You can even test this in your web browser: https://catfact.ninja/fact

+

Using the Requests library, we do this with get().

+
+
+
# Import
+import requests
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make a request
+response = requests.get(url)
+
+
+
+
+

The requests.Response object tells us what the server said. We can access the response content using content.

+
+
+
response_content = response.content
+
+# Display
+display(response_content)
+
+
+
+
+

The response content is in the JSON format and Requests gives us the json() method that decodes it and returns the corresponding data as Python objects. This is equivalent to json.load().

+
+
+
response_json = response.json()
+
+# Display
+display(response_json)
+
+
+
+
+

(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)

+
+
+

API which requires parameters

+

Let’s then examine another API which accepts parameters to specify the information request. In particular, we will request a list of Finnish universities from http://universities.hipolabs.com using the /search end point and a parameter country with value Finland, like this: +http://universities.hipolabs.com/search?country=Finland .

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search?country=Finland'
+
+# Make a request
+response = requests.get(url)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+

URLs containing parameters can always be constructed manually using the & character and then listing the parameter (key, value) pairs as above.

+

However, Requests allows us to provide the parameters as a dictionary of strings, using the params keyword argument to get(). This is easier to read and less error-prone.

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search'
+
+# Make the parameter dictionary
+parameters = {'country' : 'Finland'}
+
+# Get response
+response = requests.get(url, params=parameters)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+
+
+

Exercises 1

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+
+
+
# Import module
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Send the request using the get() function
+response = requests.get(url)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+
+
+
+
+

Next, let’s try to narrow down the suggestions by adding some parameters

+
    +

  • type

    • +

  • participants

    • +
+

All possible parameter values are presented at the bottom of the bored documentation page. Relevant parts in the Requests documentation

+
+
+
# Define some parameters
+params = {
+    'type' : 'education',
+    'participants' : 1,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display("Response")
+display(response.json())
+
+
+
+
+

Let’s narrow the request further with more parameters

+
    +

  • price range

    • +

  • accessibility range

    • +
+

(All possible parameter values are again presented at the bottom of the document page.)

+
+
+
# Define some parameters
+params = {
+    'type' : 'social',
+    'participants' : 2,
+    'minprice' : 0,
+    'maxprice' : 1000,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+display("")
+
+
+
+
+
+
+

Exercises 2

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+
+
+
# Import modules
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Make the request using the get() function
+response = requests.get(url)
+
+
+
+
+

We can access the headers of the original request

+
+
+
display("Request headers")
+display(dict(response.request.headers))
+
+
+
+
+

We can also access the headers of the response

+
+
+
display("Response headers")
+display(dict(response.headers))
+
+
+
+
+

In many cases, the default headers

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive'}
+
+
+

added automatically by Requests are sufficient. However, similarly to parameters, we can pass custom headers to the get function as an argument.

+

This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive',
+ 'example-user-id' : 'example-password'}
+
+
+

For examples of APIs using this type of authentication, see

+ +

For more on authentication, see also Requests documentation.

+
+
+

Exercises 3

+ +
+
+
# Import module
+import requests
+
+# Define webpage to scrape
+url = "http://www.example.com/"
+
+# Make a request for the URL
+response = requests.get(url)
+
+# Examine the response
+display(response.content)
+
+
+
+
+
+
+
# Looks like HTML :) Let's access it using the text attribute
+html = response.text
+
+print(html)
+
+
+
+
+
+
+
# Import beautiful soup module
+from bs4 import BeautifulSoup
+
+# Create soup
+soup = BeautifulSoup(html, 'html.parser')
+
+
+
+
+
+
+
# Extract page title from the HTML
+print(f"Found title: {soup.title.text}")
+
+
+
+
+
+
+
# Extract links (hrefs) from the HTML
+for link in soup.find_all('a'):
+    print(f"Found link: {link.get('href')}")
+
+
+
+
+
+
+
# Extract all text from the HTML
+print(f"Found text: {soup.get_text()}")    
+
+
+
+
+
+
+

After exercises: Saving retrieved data to disk

+

Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudinal study.

+

To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don’t, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).

+

For example, let’s retrieve three cat facts and save them to a JSONLINES file using the jsonlines library.

+
+
+
# Import
+import requests
+import jsonlines
+import time
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make three requests in loop and make a list of response JSON objects
+for i in range(3):
+
+    # Logging
+    print(f"Make request {i}")
+
+    # Make a request
+    response = requests.get(url)
+    
+    # Decode to JSON
+    response_json = response.json()
+                
+    # Open a jsonlines writer in 'append' mode 
+    with jsonlines.open('catfacts.jsonl', mode='a') as writer:
+
+        # Write
+        writer.write(response_json)
+        
+    # Sleep for one second between requests
+    time.sleep(1)
+
+
+
+
+

We can then read the objects from the disk using the same library.

+
+
+
# Open a jsonlines reader
+with jsonlines.open('catfacts.jsonl', mode='r') as reader:
+    
+    # Read and display
+    for obj in reader:
+        display(obj)
+
+
+
+
+
+
+

Wrap-up

+
+

Keypoints

+
    +

  • Requests is a common tool

    • +

  • Web APIs may often require some trial and error, but actually getting data is usually not that difficult

    • +

  • Storing all the data and processing it well can be a much larger issue.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/work-with-data/index.html b/branch/master/work-with-data/index.html new file mode 100644 index 00000000..ef9b45f6 --- /dev/null +++ b/branch/master/work-with-data/index.html @@ -0,0 +1,674 @@ + + + + + + + + + + + + + + + Working with Data — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Working with Data

+
+

Questions

+
    +

  • How do you store your data right now?

    • +

  • Are you doing data cleaning / preprocessing every time you load the data?

    • +
+
+
+

Objectives

+
    +

  • Learn benefits/drawbacks of common data formats.

    • +

  • Learn how you can read and write data in a variety of formats.

    • +
+
+
+https://imgs.xkcd.com/comics/norm_normal_file_format.png +
+

Source: xkcd #2116

+
+
+
+

What is a data format?

+

Data format can mean two different things

+
    +

  1. data structure or how +you’re storing the data in memory while you’re working on it;

    2. +

  2. file format or the way you’re +storing the data in the disk.

    3. +
+

Let’s consider this randomly generated DataFrame with various columns:

+
import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
+dataset.info()
+
+
+

This DataFrame is structured in the tidy data format. +In tidy data we have multiple columns of data that are collected in a Pandas +DataFrame, where each column represents a value of a specific type.

+../_images/tidy_data.png +

Let’s consider another example:

+
n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+np.info(data_array)
+
+
+

Here we have a different data structure: we have a two-dimensional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block +instead of individual columns. This also means that the whole array must have one +data type.

+
+https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png +
+

Source: Elegant Scipy

+
+
+

Now the question is: Can the data be saved to the disk without changing the +data format?

+

For this we need a file format that can easily store our data structure.

+
+

Data type vs. data structure vs. file format

+
    +

  • Data type: Type of a single piece of data (integer, string, +float, …).

    • +

  • Data structure: How the data is organized in memory (individual +columns, 2D-array, nested dictionaries, …).

    • +

  • File format: How the data is organized when it is saved to the disk +(columns of strings, block of binary data, …).

    • +
+

For example, a black and white image stored as a .png-file (file format) +might be stored in memory as an NxM array (data structure) of integers +(data type) with each entry representing the color value of the pixel.

+
+
+
+

What to look for in a file format?

+

When deciding which file format you should use for your program, you should +remember the following:

+

There is no file format that is good for every use case.

+

and

+

It is very likely, that a good format already exists for your use case.

+

There are, indeed, various standard file formats for various use cases:

+
+https://imgs.xkcd.com/comics/standards.png +
+

Source: xkcd #927.

+
+
+

Usually, you’ll want to consider the following things when choosing a file +format:

+
    +

  1. Is the file format good for my data structure (is it fast/space +efficient/easy to use)?

    2. +

  2. Is everybody else / leading authorities in my field recommending a certain +format?

    3. +

  3. Do I need a human-readable format or is it enough to work on it using code?

    4. +

  4. Do I want to archive / share the data or do I just want to store it while +I’m working?

    5. +
+

Pandas supports +many file formats +for tidy data and Numpy supports +some file formats +for array data. However, there are many other file formats that can be used +through other libraries.

+

Table below describes some data formats:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
Name:
+
+
+
Human
+
readable:
+
+
+
Space
+
efficiency:
+
+
+
Arbitrary
+
data:
+
+
+
Tidy
+
data:
+
+
+
Array
+
data:
+
+
+
Long term
+
storage/sharing:
+
+

Pickle

❌

🟨

✅

🟨

🟨

❌

CSV

✅

❌

❌

✅

🟨

✅

Feather

❌

✅

❌

✅

❌

❌

Parquet

❌

✅

🟨

✅

🟨

✅

npy

❌

🟨

❌

❌

✅

❌

HDF5

❌

✅

❌

❌

✅

✅

NetCDF4

❌

✅

❌

❌

✅

✅

JSON

✅

❌

🟨

❌

❌

✅

Excel

❌

❌

❌

🟨

❌

🟨

Graph formats

🟨

🟨

❌

❌

❌

✅

+
+

Important

+
    +

  • ✅ : Good

    • +

  • 🟨 : Ok / depends on a case

    • +

  • ❌ : Bad

    • +
+
+

A more in-depth analysis of the file formats mentioned above, can be found +here.

+
+
+

Pros and cons

+

Let’s have a general look at pros and cons of some types of file formats

+
+

Binary File formats

+
+

Good things

+
    +

  • Can represent floating point numbers with full precision.

    • +

  • Can potentially save lots of space, especially, when storing numbers.

    • +

  • Data reading and writing is usually much faster than loading from text files, +since the format contains information about the data structure, and thus +memory allocation can be done more efficiently.

    • +

  • More explicit specification for storing multiple data sets and metadata in +the same file.

    • +

  • Many binary formats allow for partial loading of the data. +This makes it possible to work with datasets that are larger than your +computer’s memory.

    • +
+
+
+

Bad things

+
    +

  • Commonly requires the use of a specific library to read and write the data.

    • +

  • Library specific formats can be version dependent.

    • +

  • Not human readable.

    • +

  • Sharing can be more difficult (requires some expertise to be able to +read the data).

    • +

  • Might require more documentation efforts.

    • +
+
+
+
+

Textual formats

+
+

Good things

+
    +

  • Human readable.

    • +

  • Easy to check for (structural) errors.

    • +

  • Supported by many tool out of the box.

    • +

  • Easily shared.

    • +
+
+
+

Bad things

+
    +

  • Can be slow to read and write.

    • +

  • High potential to increase required disk space substantially (e.g. when +storing floating point numbers as text).

    • +

  • Prone to losing precision when storing floating point numbers.

    • +

  • Multi-dimensional data can be hard to represent.

    • +

  • While the data format might be specified, the data structure might not be +clear when starting to read the data.

    • +
+
+
+
+

Further considerations

+
    +

  • The closer your stored data is to the code, the more likely it depends on the +environment you are working in. If you pickle, e.g. a generated model, +you can only be sure that the model will work as intended if you load it in +an environment that has the same versions of all libraries the model depends +on.

    • +
+
+
+
+

Exercise

+
+

Exercise

+

You have a model that you have been training for a while. +Lets assume it’s a relatively simple neural network (consisting of a +network structure and it’s associated weights).

+

Let’s consider 2 scenarios

+

A: You have a different project, that is supposed to take this model, and +do some processing with it to determine it’s efficiency after different +times of training.

+

B: You want to publish the model and make it available to others.

+

What are good options to store the model in each of these scenarios?

+
+ +
+
+

Case study: Converting untidy data to tidy data

+

Many data analysis tools (like Pandas) are designed to work with tidy data, +but some data is not in a suitable format. What we have seen often in the +past is people then not using the powerful tools, but write complicated +scripts that extract individual pieces from the data each time they need +to do a calculation.

+

As an example, let’s see how we can use country data from an example REST API +endpoint (for more information on how to work with web APIs, see +this page). Let’s get the data with the following piece +of code:

+
import json
+import requests
+
+url = 'https://api.sampleapis.com/countries/countries'
+
+response = requests.get(url)
+
+countries_json = json.loads(response.content)
+
+
+

Let’s try to find the country with the largest population.

+

An example of a “questionable” way of solving this problem would be something +like the following piece of code that is written in pure Python:

+
max_population = 0
+top_population_country = ''
+
+for country in countries_json:
+    if country.get('population', 0) > max_population:
+        top_population_country = country['name']
+        max_population = country.get('population', 0)
+
+print(top_population_country)
+
+
+

This is a very natural way of writing a solution for the problem, but it has +major caveats:

+
    +

  1. We throw all of the other data out so we cannot answer any +follow up questions.

    2. +

  2. For bigger data, this would be very slow and ineffective.

    3. +

  3. We have to write lots of code to do a simple thing.

    4. +
+

Another typical solution would be something like the following code, +which picks some of the data and creates a Pandas dataframe out of it:

+
import pandas as pd
+
+countries_list = []
+
+for country in countries_json:
+    countries_list.append([country['name'], country.get('population',0)])
+
+countries_df = pd.DataFrame(countries_list, columns=['name', 'population'])
+
+print(countries_df.nlargest(1, 'population')['name'].values[0])
+
+
+

This solution has many of the same problems as the previous one, but now we can +use Pandas to do follow up analysis.

+

Better solution would be to use Pandas’ +pandas.DataFrame.from_dict +or pandas.json_normalize +to read the full data in:

+
countries_df = pd.DataFrame.from_dict(countries_json)
+print(countries_df.nlargest(1, 'population')['name'].values[0])
+
+countries_df = pd.json_normalize(countries_json)
+print(countries_df.nlargest(1, 'population')['name'].values[0])
+
+
+
+

Key points

+
    +

  • Convert your data to a format where it is easy to do analysis on it.

    • +

  • Check the tools you’re using if they have an existing feature that can help +you read the data in.

    • +
+
+
+
+

Things to remember

+
    +

  1. There is no file format that is good for every use case.

    2. +

  2. Usually, your research question determines which libraries you want to use +to solve it. Similarly, the data format you have determines file format you +want to use.

    3. +

  3. However, if you’re using a previously existing framework or tools or you +work in a specific field, you should prioritize using the formats that are +used in said framework/tools/field.

    4. +

  4. When you’re starting your project, it’s a good idea to take your initial +data, clean it, and store the results in a good binary format that works as +a starting point for your future analysis. If you’ve written the cleaning +procedure as a script, you can always reproduce it.

    5. +

  5. Throughout your work, you should use code to turn important data to +a human-readable format (e.g. plots, averages, +pandas.DataFrame.head()), not to keep your full data in a +human-readable format.

    6. +

  6. Once you’ve finished, you should store the data in a format that can be +easily shared to other people.

    7. +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pandas can read and write a variety of data formats.

    • +

  • There are many good, standard formats, and you don’t need to create your own.

    • +

  • There are plenty of other libraries dedicated to various formats.

    • +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/master/xarray/index.html b/branch/master/xarray/index.html new file mode 100644 index 00000000..427aa08f --- /dev/null +++ b/branch/master/xarray/index.html @@ -0,0 +1,606 @@ + + + + + + + + + + + + + + + Xarray — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Xarray

+
+

Questions

+
    +

  • How shall we deal with real-world datasets that are usually more than just raw numbers?

    • +

  • What is the advantage of using labelled multidimensional arrays?

    • +

  • What does Xarray add to Numpy and Pandas to address these questions?

    • +
+
+
+

Objectives

+
    +

  • Learn how to apply operations over dimensions and select values by label

    • +

  • Understand Xarray’s DataArrays and Datasets

    • +

  • Learn how to easily plot data in Xarray

    • +

  • Learn how to turn your own data into an Xarray Dataset

    • +
+
+

We have already seen how Pandas simplifies working with tabular NumPy data by adding labels to columns and rows. In this lesson, we take a look at how xarray can be used to add the same functionality to multidimensional data. Let’s consider the following example:

+

Imagine we have a dataset representing temperature measurements across different heights, latitudes, and longitudes. We can store the temperature data as a 3D NumPy array where each axis corresponds to one of these dimensions:

+
import numpy as np
+# Create a 3D numpy array: height x latitude x longitude
+data = np.random.rand(10, 5, 5)  # 10 heights, 5 latitudes, 5 longitudes
+
+
+

Let’s assume now we want to take a look at a specific value in the dataset at a certain height, latitude, and longitude. We could do this by indexing the array with the corresponding indices:

+
# Get the temperature at height 3, latitude 2, longitude 4
+temperature = data[3, 2, 4]
+
+
+

OK, we got a value, but how do we know whether this value corresponds to the correct height, latitude and longitude? Are we sure that latitude was the second dimension in the dataset? Was it the second or third index that corresponds to the correct position? In pure NumPy, we are mostly left in the dark and need to manually keep track of these things.

+

Unfortunately, Pandas isn’t of much help either since it is not designed for data with more than 2 dimensions. Fortunately, some clever climate scientists have come up with a solution to this problem and created Xarray.

+
+

What is Xarray?

+

Xarray is a powerful Python library that introduces labelled multidimensional arrays. This means the axes have labels (=dimensions), each row/column has a label (coordinates), and labels can even have units of measurement. This makes it much easier to follow what the data in an array means and select specific portions of data.

+

We will first download a dataset similar to the example above to illustrate the advantages of Xarray. We will cover how to transform your own data into an Xarray Dataset later in this lecture.

+
+

Note

+

If you have set up your python-for-scicomp environment yesterday or earlier, you need to install the packages netcdf4 and pythia_datasets manually. You can do this by running the following command in your (JupyterLab) terminal:

+
conda install netcdf4 pythia-datasets -c conda-forge
+
+
+
+

Let us open a python shell and download a public dataset:

+
>>> from pythia_datasets import DATASETS
+>>> filepath = DATASETS.fetch('NARR_19930313_0000.nc')
+
+
+

We can now import xarray and open the dataset. Le’ts take a look at what it contains:

+
>>> import xarray as xr
+>>> ds = xr.open_dataset(filepath)
+>>> ds
+<xarray.Dataset> Size: 15MB
+Dimensions:                       (time1: 1, isobaric1: 29, y: 119, x: 268)
+Coordinates:
+  * time1                         (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1                     (isobaric1) float32 116B 100.0 125.0 ... 1e+03
+  * y                             (y) float32 476B -3.117e+03 ... 714.1
+  * x                             (x) float32 1kB -3.324e+03 ... 5.343e+03
+Data variables:
+    u-component_of_wind_isobaric  (time1, isobaric1, y, x) float32 4MB ...
+    LambertConformal_Projection   int32 4B ...
+    lat                           (y, x) float64 255kB ...
+    lon                           (y, x) float64 255kB ...
+    Geopotential_height_isobaric  (time1, isobaric1, y, x) float32 4MB ...
+    v-component_of_wind_isobaric  (time1, isobaric1, y, x) float32 4MB ...
+    Temperature_isobaric          (time1, isobaric1, y, x) float32 4MB ...
+Attributes:
+    Originating_or_generating_Center:     US National Weather Service, Nation...
+    Originating_or_generating_Subcenter:  North American Regional Reanalysis ...
+    GRIB_table_version:                   0,131
+    Generating_process_or_model:          North American Regional Reanalysis ...
+    Conventions:                          CF-1.6
+    history:                              Read using CDM IOSP GribCollection v3
+    featureType:                          GRID
+    History:                              Translated to CF-1.0 Conventions by...
+    geospatial_lat_min:                   10.753308882144761
+    geospatial_lat_max:                   46.8308828962289
+    geospatial_lon_min:                   -153.88242040519995
+    geospatial_lon_max:                   -42.666108129242815
+
+
+

That was a lot of information at once, but let’s break it down.

+
+
    +

  • Close to the top of the output we see the Dimensions of the dataset: time1, isobaric1, y, and x.

    • +

  • Below the dimensions, we see the Coordinates of the dataset. These are for each dimension the labels for each value along that dimension. For example, we have a timestamp of each value along the first dimension (time1).

    • +

  • The Data variables are the actual data stored in the dataset. We see that the dataset contains a bunch of arrays, most of which are 4-dimensional, where each dimension corresponds to one of the Dimensions described above. There are also some 2-dimensional arrays that only have some of the Dimensions described above.

    • +

  • At the bottom, we see the Attributes of the dataset. This is a dictionary that stores metadata about the dataset.

    • +
+
+

The following image shows the structure of this particular Xarray Dataset:

+
+
../_images/xarray_dataset_image.png +
+
+
+

Accessing and manipulating data in Xarray

+

An xarray Dataset typically consists of multiple DataArrays. Our example dataset has 7 of them (u-component_of_wind_isobaric, LambertConformal_Projection, lat, lon, Geopotential_height_isobaric, v-component_of_wind_isobaric, Temperature_isobaric). +We can select a single DataArray from the dataset using a dictionary-like syntax:

+
>>> temperature_data = ds['Temperature_isobaric']
+>>> temperature_data
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, isobaric1: 29, y: 119,
+                                          x: 268)> Size: 4MB
+[924868 values with dtype=float32]
+Coordinates:
+  * time1      (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1  (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03
+  * y          (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+  * x          (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03
+Attributes:
+    long_name:           Temperature @ Isobaric surface
+    units:               K
+    description:         Temperature
+    grid_mapping:        LambertConformal_Projection
+    Grib_Variable_Id:    VAR_7-15-131-11_L100
+    Grib1_Center:        7
+    Grib1_Subcenter:     15
+    Grib1_TableVersion:  131
+    Grib1_Parameter:     11
+    Grib1_Level_Type:    100
+    Grib1_Level_Desc:    Isobaric surface
+
+
+

Xarray uses Numpy(-like) arrays under the hood, we can always access the underlying Numpy array using the .values attribute:

+
>>> temperature_numpy = ds['Temperature_isobaric'].values
+>>> temperature_numpy
+array([[[[201.88957, 202.2177 , 202.49895, ..., 195.10832, 195.23332,
+          195.37395],
+         [201.68645, 202.0302 , 202.3427 , ..., 195.24895, 195.38957,
+          195.51457],
+         [201.5302 , 201.87395, 202.20207, ..., 195.37395, 195.51457,
+          195.63957],
+         ...,
+         [276.735  , 276.70374, 276.6881 , ..., 289.235  , 289.1725 ,
+          289.07874],
+         [276.86   , 276.84436, 276.78186, ..., 289.1881 , 289.11   ,
+          289.01624],
+         [277.01624, 276.82874, 276.82874, ..., 289.14124, 289.0475 ,
+          288.96936]]]], dtype=float32)
+
+
+

Xarray allows you to select data using the .sel() method, which uses the labels of the dimensions to extract data:

+
>>> ds['Temperature_isobaric'].sel(x='-3292.0078')
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, isobaric1: 29, y: 119)> Size: 14kB
+array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895],
+        [202.58566, 202.58566, ..., 219.16379, 219.28879],
+        ...,
+        [292.1622 , 292.14658, ..., 275.05283, 275.11533],
+        [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32)
+Coordinates:
+  * time1      (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1  (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03
+  * y          (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+    x          float32 4B -3.292e+03
+Attributes:
+    long_name:           Temperature @ Isobaric surface
+    units:               K
+    description:         Temperature
+    grid_mapping:        LambertConformal_Projection
+    Grib_Variable_Id:    VAR_7-15-131-11_L100
+    Grib1_Center:        7
+    Grib1_Subcenter:     15
+    Grib1_TableVersion:  131
+    Grib1_Parameter:     11
+    Grib1_Level_Type:    100
+    Grib1_Level_Desc:    Isobaric surface
+
+
+

We can still access the same data by index using the .isel() method:

+
>>> ds['Temperature_isobaric'].isel(x=1)
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, isobaric1: 29, y: 119)> Size: 14kB
+array([[[202.2177 , 202.0302 , ..., 219.67082, 219.74895],
+        [202.58566, 202.58566, ..., 219.16379, 219.28879],
+        ...,
+        [292.1622 , 292.14658, ..., 275.05283, 275.11533],
+        [294.1256 , 294.14124, ..., 276.84436, 276.82874]]], dtype=float32)
+Coordinates:
+  * time1      (time1) datetime64[ns] 8B 1993-03-13
+  * isobaric1  (isobaric1) float32 116B 100.0 125.0 150.0 ... 950.0 975.0 1e+03
+  * y          (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+    x          float32 4B -3.292e+03
+Attributes:
+    long_name:           Temperature @ Isobaric surface
+    units:               K
+    description:         Temperature
+    grid_mapping:        LambertConformal_Projection
+    Grib_Variable_Id:    VAR_7-15-131-11_L100
+    Grib1_Center:        7
+    Grib1_Subcenter:     15
+    Grib1_TableVersion:  131
+    Grib1_Parameter:     11
+    Grib1_Level_Type:    100
+    Grib1_Level_Desc:    Isobaric surface
+
+
+

A DataArray provides a lot of the functionality we expect from Numpy arrays, such as sum(), mean(), median(), min(), and max() that we can use these methods to aggregate data over one or multiple dimensions:

+
>>> # Calculate the mean over the 'isobaric1' dimension
+>>> ds['Temperature_isobaric'].mean(dim='isobaric1')
+<xarray.DataArray 'Temperature_isobaric' (time1: 1, y: 119, x: 268)> Size: 128kB
+array([[[259.88446, 259.90222, 259.91678, ..., 262.61667, 262.6285 ,
+         262.65167],
+        [259.74866, 259.76752, 259.78638, ..., 262.5757 , 262.58218,
+         262.57516],
+        [259.6156 , 259.63498, 259.65115, ..., 262.52075, 262.51215,
+         262.4976 ],
+        ...,
+        [249.8796 , 249.83649, 249.79501, ..., 254.43617, 254.49059,
+         254.54985],
+        [249.8505 , 249.80202, 249.75244, ..., 254.37044, 254.42378,
+         254.47711],
+        [249.82195, 249.75998, 249.71204, ..., 254.30956, 254.35805,
+         254.41139]]], dtype=float32)
+Coordinates:
+  * time1    (time1) datetime64[ns] 8B 1993-03-13
+  * y        (y) float32 476B -3.117e+03 -3.084e+03 -3.052e+03 ... 681.6 714.1
+  * x        (x) float32 1kB -3.324e+03 -3.292e+03 ... 5.311e+03 5.343e+03
+
+
+

Let’s take a look at a concrete example and compare it to NumPy. We will calculate the max temperature over the ‘isobaric1’ dimension at a specific value for x:

+
>>> # Xarray
+>>> ds['Temperature_isobaric'].sel(x='-3259.5447').max(dim='isobaric1')
+array([[294.11   , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 ,
+        ...,
+        276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]],
+      dtype=float32)
+
+
+

In comparison, if we were to use plain Numpy, this would be:

+
>>> # NumPy
+>>> np.max(temperature_numpy[:, :, :, 2 ], axis = 1)
+array([[294.11   , 294.14124, 294.1256 , 294.0475 , 293.90686, 293.6256 ,
+        ...,
+        276.46936, 276.59436, 276.6881 , 276.78186, 276.82874]],
+      dtype=float32)
+
+
+

As you can see, the Xarray code is much more readable and we didn’t need to keep track of the right indices and order of the dimensions.

+
+
+

Plotting data in Xarray

+

Like Pandas, Xarray comes with basic plotting capabilities. We can easily plot data in 1D and 2D using the .plot() method. Xarray uses a widely used plotting library called matplotlib for this. When calling the .plot() method, Xarray checks the dimensionality of the data and plots it accordingly. Let’s import matplotlib and plot the data:

+
>>> import matplotlib.pyplot as plt
+
+>>> ds['Temperature_isobaric'].isel(x=2).plot()
+>>> plt.show()
+
+
+

For a 2D DataArray the plot would resemble this example:

+
+
../_images/xarray_2d_plot.png +
+

Note, that we didn’t specify the axes labels, Xarray automatically used the coordinates of the DataArray for the plot. This plot might not be one you include directly in a paper, but it is a great way to quickly visualize your data.

+

Let’s have a look at a dataslice of 1D data:

+
>>> ds['Temperature_isobaric'].isel(x=2, y=5).plot()
+>>> plt.show()
+
+
+

The resulting plot detects the dimentionality of the data and plots it accordingly:

+
+
../_images/xarray_1d_plot.png +
+

If the data has more than two dimensions, Xarray will plot a histogram of the data:

+
>>> ds['Temperature_isobaric'].plot()
+>>> plt.show()
+
+
+

The resulting plot would look like this:

+
+
../_images/xarray_hist.png +
+

We can modify the plots by passing additional arguments to the .plot() method. Since we haven’t discussed the plotting library matplotlib in this course, we will not go into further detail here. You can find more information in the Xarray documentation.

+
+
+

Exercises 1

+
+

Exercises: Xarray-1

+

Download the NARR_19930313_0000.nc dataset have a look at all Data variables. Calculate the geopotential height at x=5148.3726 averaged over y and return the median value. You can use the .plot() method to check on the way whether you use the correct dimensions and indices.

+
+ +
+
+

Creating your own Xarray Dataset

+

Creating your own Xarray Dataset is quite simple. We can create a Dataset from scratch using basic Python data structures. Let’s create a simple weather dataset with pressure and humidity data with the following script:

+
import xarray as xr
+import numpy as np
+
+# Define coordinates using basic Python lists
+time = ['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05']
+location = ['Location1', 'Location2', 'Location3']
+
+# Define data variables as numpy arrays
+pressure_data = np.random.rand(5, 3) * 1000  # Random pressure data in hPa
+humidity_data = np.random.rand(5, 3) * 100  # Random humidity data
+
+# Put everything together to create the Dataset
+ds = xr.Dataset(
+    data_vars = {
+        "pressure": (["time", "location"], pressure_data),
+        "humidity": (["time", "location"], humidity_data)
+    },
+    coords={
+        "time": time,
+        "location": location
+    },
+    attrs={
+        "description": "Weather data",
+        "creation_date": "2023-01-01",
+        "author": "Data Scientist"
+    }
+)
+
+
+
+
+

Converting Xarray objects to NumPy, Pandas and NetCDF

+

Another handy feature of Xarray is the simple conversion between Xarray objects, NumPy arrays, Pandas DataFrames and even NetCDF files.

+

To convert an xarray DataArray to a NumPy array, you can use the .values attribute or the .to_numpy() method:

+
# Convert the 'pressure' DataArray to a NumPy array
+pressure_numpy = ds['pressure'].values
+# or
+pressure_numpy = ds['pressure'].to_numpy()
+
+
+

To convert the entire Dataset or individual DataArrays to pandas DataFrames, use the .to_dataframe() method:

+
# Convert the entire Dataset to a DataFrame
+df = ds.to_dataframe()
+# Convert a single DataArray to DataFrame
+pressure_df = ds['pressure'].to_dataframe()
+
+
+

To save the dataset as a NetCDF file, use the .to_netcdf() method:

+
# Save the Dataset as a NetCDF file
+ds.to_netcdf('weather_data.nc')
+
+
+
+
+

Exercises 2

+
+

Exercises: Xarray-2

+

Let’s change from climate science to finance for this example. Put the stock prices and trading volumes of three companies over ten days in one dataset. Create an Xarray Dataset that uses time and company as dimensions and contains two DataArrays: stock_price and trading_volume. You can choose the values for the stock prices and trading volumes yourself. As a last thing, add the currency of the stock prices as an attribute to the Dataset.

+
+ +
+
+

Advanced Topics

+

We have barely scratched the surface of all the features Xarray has to offer. Hopefully this quick introduction has shown you whether Xarray is the right tool for your data analysis needs. If you are interested in learning more about Xarray, here are some topics for further reading:

+
    +

  • Xarray integrates with Dask to support parallel computations and streaming computation on datasets that don’t fit into memory. If you work with datasets that are too large for your memory, have a read of the chapter Parallel computing with Dask in the Xarray documentation.

    • +

  • If you want to accelerate Xarray operations with your GPU, have a look at CuPy-Xarray.

    • +

  • Xarray can be combined with pint, a Python library that adds support for physical quantities to NumPy arrays. This blog post provides a good introduction to the topic.

    • +

  • You can extend Xarray with your own methods using the register_dataset_accessor() method. This is a powerful feature that allows you to add custom methods to your own Xarray Datasets.

    • +
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb b/branch/opengraph/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb new file mode 100644 index 00000000..4a5e214a --- /dev/null +++ b/branch/opengraph/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb @@ -0,0 +1,96 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "url = \"https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv\"\n", + "weather = pd.read_csv(url,comment='#')\n", + "\n", + "# define the start and end time for the plot \n", + "start_date=pd.to_datetime('01/06/2021',dayfirst=True)\n", + "end_date=pd.to_datetime('01/10/2021',dayfirst=True)\n", + "\n", + "# The date format in the file is in a day-first format, which matplotlib does nto understand.\n", + "# so we need to convert it.\n", + "weather['Local time'] = pd.to_datetime(weather['Local time'],dayfirst=True)\n", + "# select the data\n", + "weather = weather[weather['Local time'].between(start_date,end_date)]\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, we have the data loaded, and adapted to our needs. So lets get plotting" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYUAAAEcCAYAAAAoSqjDAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAABtDElEQVR4nO2dd7gcVdnAf+/evSU9pBcggRCE0CHSpSNKERQbKkX9wM+GYPsQsWBFUSwgIgLSwYIoItKbhBJCS0JNgJBCSC83N7lt93x/zJzZs7Nnd2f7bHJ+z3Ofuzs7O/vu7Mx5z1vO+4pSCofD4XA4ABKNFsDhcDgc8cEpBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA4HA5HgFMKDkcDEZHJIqJEJNloWUpBRD4pIvc2Wg5H9XFKwWFFRDYYf2kR2WQ8/2Sj5SsHEVkgIkfV+TOnicgdIrJORDpF5CERObCeMlSKTXEppW5SSr23kXI5aoNTCg4rSqnB+g9YCJxgbLup0fKFqcdMu9TPEJEpwAxgDrAdMAG4HbhXRA6ovoR55RARcfe6IxLuQnGUhIgkROQ8EXldRFaJyF9EZIT/mp5RflpEFonIGhH5XxF5t4jMFpG1InKZcawzRGSGiFzmz6RfEZEjjdeHicjVIrJURJaIyI9EpCX03l+JyCrg+yIyRUQe9OVaKSI3ichwf/8bgG2Bf/nWzjdF5DARWRz6foE1ISLfF5G/iciNIrIeOKOQTBa+DzyhlPq2Umq1UqpTKfVb4AbgZ6F9PyMib/vH/bohz74iMktE1ovIMhG5xHhtfxF53D+vL4jIYcZrD4vIj0VkBrAR+IaIzAp913NF5A7/8XEi8pz/OYtE5PvGro/6/9f65+4A//w/ZhzrQBF52v8dnzatIV+WH/q/V6eI3Csio/zXOvzzu8r/Hk+LyNg859NRD5RS7s/9FfwDFgBH+Y+/AjwJbA20A38AbvFfmwwo4AqgA3gv0A38AxgDTASWA4f6+58B9APnAq3Ax4B1wAj/9dv94w/y3z8T+FzovV8GksAAYAfgaF+u0XiD2a9t38N/fhiwuMB3/T7QB5yEN4EaUEgmy3l7B/i0ZfvhQMo/nj5nt/jH3A1YYcjwBHCq/3gwsL//eCKwCjjWl+1o//lo//WH8Sy8XfzzMwzoBKYacjwNfNw4F7v5x9odWAacFPpdk8Z7zwAe8x+PANYAp/qfdYr/fKQhy+vAjv53fhi4yH/tc8C/gIFAC7APMLTR1/yW/OcsBUep/C/wbaXUYqVUD97A+eGQa+WHSqlupdS9QBee0liulFoC/BfYy9h3Od7A3aeU+jPwKnCcP1s8FjhHKdWllFoO/Ar4uPHet5VSlyql+pVSm5RS85VS9ymlepRSK4BLgEMr/L5PKKX+oZRKA0MjyGQyClhq2b4Ub/AdYWy70D/mHOBPeAMreEppBxEZpZTaoJR60t/+KeAupdRdSqm0Uuo+YJYvn+ZapdSL/vlZB/xTH1dEpgI7AXcAKKUeVkrN8Y81G09JRT13xwHzlFI3+J91C/AKcIKxz5+UUq8ppTYBfwH2NL7fSGAHpVRKKfWMUmp9xM911ACnFBylMgm43Tf11wIv4816TZN/mfF4k+X5YOP5EqWUWZXxLTzf+yQ862Gp8Vl/wJudaxaZgonIWBG51XfrrAduxBuYK8H8jCgymawExlu2jwfSeLNp2+focwDwWbwZ9iu+a+V4Q5aPaDl8WQ4OfV7W+QFuJqNsPgH8Qym1EUBE9hMvCL5CRNbhKf+o526CL7PJW3jWjOYd4/FGMtfADcA9wK2+++znItIa8XMdNcApBUepLALer5Qabvx1+FZAOUwUETGebwu87X9ODzDK+JyhSqldjH3DJX5/4m/bTSk1FG82LQX278JzWwDgxwZGh/Yx3xNFJpP7gY9Ytn8UzwLZaGzbxniszwFKqXlKqVPwFM/PgL+JyCBflhtCv8MgpdRFBb7vfcBoEdkTTzncbLx2M57VsI1SahieC1Cfu2KllN/GU1Im2wJFrwnfQrxQKTUNOBA4Hjit2PsctcMpBUepXAH8WEQmAYjIaBE5sYLjjQHOFpFWEfkIsDOeW2QpcC/wSxEZKl6Ae4qIFHJpDAE2AOtEZCLwjdDry4DtjeevAR1+kLUVuAAvHmGlDJkuBA70A74jRGSIiHwZb9D7v9C+3xGRgSKyC/Bp4M8AIvIpERntu6/W+vum8aygE0TkGBFp8QO2h4nI1gXk7wP+ClyM57q6z3h5CLBaKdUtIvviWRKaFf5nmufO5C5gRxH5hIgkReRjwDTgznyyaETkcBHZzVfI6/HcSeli73PUDqcUHKXyG7wZ5b0i0okXdN6vguM9BUzFc7X8GPiwUmqV/9ppQBvwEp6r5W/Y3TGaC4G98YLV/wb+Hnr9p8AFvrvl676f/QvAVXiz2i5gMYWJLJNSah6eS2cPvAD2UuBk4Bil1IzQ7o8A84EHgF/48RiA9wEvisgGvHP/cT9+sgg4ETgfb9BehKcEi93TNwNHAX9VSvUb278A/MD/Tb+L5/fX32Mj3m8zwz93+4e+5yq8Gf7X8ILd3wSOV0qtLCILwDi8c7gezxX5CJ5LydEgJNud63DUDxE5A/gfpdTBjZbF4XB4OEvB4XA4HAFOKTgcDocjwLmPHA6HwxHgLAWHw+FwBDRVud4wo0aNUpMnT260GA6Hw9FUPPPMMyuVUuE1OUCTK4XJkycza9as4js6HA6HI0BEwivQA5z7yOFwOBwBTik4HA6HI8ApBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA0HU++sYrnFq4pvqPD4SiZpl6n4Ngy+fiVXkfKBRcd12BJHI7ND2cpOBwOhyOg7krB7xA1U0ReEJEXReRCf/t2IvKUiMwXkT+LSFu9ZXM4HI4tnUZYCj3AEUqpPYA9gff5nZx+BvxKKbUDXkerzzZANofD4diiqbtSUB4b/Ket/p8CjsBrywdwHXBSvWVrVv40401+dOdLjRbD4XBsBjQkpuA3Gn8eWI7XPPx1YK3RM3YxMDHPe88SkVkiMmvFihV1kTfuXPivl7jqsTcbLYbD4dgMaIhSUEqllFJ7AlsD+wI7lfDeK5VS05VS00ePtlZ+dWyGvLWqixnzo/SBdzgcldDQlFSl1FoReQg4ABguIknfWtgaWNJI2Rzx4tCLHwZcGqrDUWsakX00WkSG+48HAEcDLwMPAR/2dzsd+Ge9ZXM4HI4tnUa4j8YDD4nIbOBp4D6l1J3A/wFfFZH5wEjg6gbI1nQ0e4/t+cs7uWvO0sj796fSweNX3+nkvpeW1UIsh2OLpe7uI6XUbGAvy/Y38OILjhJIGzohlVa0JKRxwpTBBy6bwcbeFG/85FgSEWTf2JcKHh/z60cB51JyOKqJW9Hc5PQZM+fe/nSBPePJxl5vkF/e2RNp//Wb+nK2Nbu15HDECacUmpyUYSr09KcK7BlPRg1uB2DJ2o2R9u/s7s/Z1tXbfN/b4YgrTik0Of0pUyk0n6XQnvQuwa6e3IF9fXcfk8/7N3+dtSjYtmZjb85+6yzWg8PhKA+nFJqUnv4Ui1ZvpC+dUQTdfc03Y25t8eIImyyyL169CYCrjYV5y9fnupnWbXRKweGoFk4pNCnf/Nts3vPzh+jqybhT+tPN51vXgXGbQhNL3HnZ+u6cbc3oNnM44opTCk3Kw696JT5MH3szBlyTCe8StCkF/XXMr2ULSKeb8Hs7HHHFKYUmRWdv9hrZR/98/m3e8/MHSTeRxaAthU2WYHF/OjdGsmpDrlIw4yq1ZPbitVmBfYdjc8QphSbFNphe+uB8Fq3eRFdvboZOXMnEFHIVgA6cKzIDsS37KFUHS+H5RWv5wGUz+P3D82v+WQ5HI3FKoUlJ+A73jZYZti1oG1dE8geabesubPtZDIqq8846L5Yxe/G62n+Yw9FAnFJoUrSlsNFiFdhcMXFFu2N6LIO9DiCbhoBNCdrcTNVGu+uc98ixudPQKqmO8tGWgk0B2HL+44pekd1niQtYLQXL961loHljb39gJdT6sxyOOOAshSYlYynY3EfNE1PQSsE22NoW4220fLdUDQ2FL938HEf88hHeWuWtuHZKwbG545RCkxIEmi1ulxffXl9vccpGr60opBTMV2yWQqqG7qMHX1kOwDv++gjnPnJs7jil0KRoH7ctpvDdf75YZ2k8+lNpPnj5DB55LXqb1D5/4LeletqsCJtlVEtLQbPBz3pqxrUgDkcpOKXQJOhBM51WKKWs2UeD2loA2G+7EfUXEFi7qY/nFq7l3D8/H/k9fYGlkPua/s6mwrAqhToM1Bv8lePNVprc4SgVpxSagDdXdjHl/Lv49+ylbH/+XXzr73Os6xR0sFZXHi2Xfz6/hLfXbir5fXps7iuhMJ9ummNbcJfJTCp8vHos1gtcWc5QcGzmOKXQBDz+utew/pHXPP/2rU8vsloKenVzJatue/vTfOXW5znwogcjv+eGJxZw5C8fzmQSpdOs29TH/OWdRd+rFZktpqC/R7F1F2bNp9/cP4+P/uGJyLJHpRrn1uFoBlxKahOgZ+0Thg8ItulicbaaQZVkyJRTXO47fgxDp5D2pRQf/v3jzFu+oWhXNK1Iwi6g9d19kZWCaSn86v7XShM+Ir3+eemtRwDD4WggzlJoAvS6g8HtuTq82+KqqUQp2NYLREWXoEilFfOWb4j4ebnuowdeXsbu37+XmW+uBop3lKtHTEHL0Izd7RyOUnBKoQnQVoGtNLZtJfDTC9Yw+bx/s2h1tG5mJpUMems35TbAKUQqrYIAs/nVdPbSCxFLStSjZLhWln3OUnBs5tRdKYjINiLykIi8JCIvishX/O3fF5ElIvK8/3dsvWWLK4KnFfotA5JtgZfuRPb0gtUlf1Y5SiHpB73XWJrdFErhNAdYc7avA8u6WF4xbIFm27mqBC2rsxQcmzuNsBT6ga8ppaYB+wNfFJFp/mu/Ukrt6f/d1QDZYkmikKVQYJAa0tFa8mf1pjKWR9Sc/Da/peZaS6vMQoFZ8/uk04rfPTSft9duotv33ycjKgXbZ9jcapWQiZc4peDYvKm7UlBKLVVKPes/7gReBibWW45mQruPzAFJb7O5jzRDOkrPIzCVjBlUfW1ZJ3OX2N05GaWQaynYFNmm3hSTz/s3f3z0jWDb/OUbuPieV/n8Tc8GlkLC1nqN3I5sKzf0MPm8f3P7c4uDbdVuTdrjYgqOLYSylYKITBGRdv/xYSJytogML/EYk4G9gKf8TV8Skdkico2IbJXnPWeJyCwRmbViRfSVs9Vk+fpuDrroQd5YES2YWim6vLQtX7+QpZCMsNDqV/e9xgX/mBM8Nwc9cw3Ee3/1KMdf+pj1GG0t3mW0xmIp2JSCXgj2mwfmBdu0wuvq6Q8yoPIN7K2J7Mv2jRVdAPz2gUyvg2orBa0ge+vU0MfhaBSVWAq3ASkR2QG4EtgGuDnqm0VksH+Mc5RS64HfA1OAPYGlwC9t71NKXamUmq6Umj569OgKxC+fu+YsZcnaTVz3+IK6fJ6eGdvSIQulkEaJv/7mgXnc+ORC7/j96azso+4ii8Y07a3eZbTOYin09ae54B9z+OusRcE2m7vHVEZakeT7/LBbSdclMvtVR5U9KpmYQvNUoHU4yqESpZBWSvUDHwQuVUp9Axgf5Y0i0oqnEG5SSv0dQCm1TCmVUkqlgT8C+1YgW02p+1zR/0CrpVBg8CulTs+cxevY8YL/8MDLy4JtOrX18fkrC763kKWwvLOHG59cyDf+NjvYZvPLd/lWiWAsWsvTFyJsAS1d563jGGy4y6puKRhrMByOzZlKFq/1icgpwOnACf62opFN8XwhVwMvK6UuMbaPV0ot9Z9+EJhbgWw14bzbZrNyQw8HThkFZNw6tUYPkjZLobtCS0Fzv68MHjMUgFYKr6/sKvjetqRXc8mWfbS6K6MolFLMemsNIwe15eynZ/kihb8vQGtL9lzGXjm18sHbzGoK1im4QLNjM6cSS+HTwAHAj5VSb4rIdsANEd53EHAqcEQo/fTnIjJHRGYDhwPnViBbTbj16UXc//Lyun+uHptMV1FQZ6jAzLUUS2GZ74IZYQzY+u260F6+FNF2P9CsU2FNzIykO154m49c8QR/fWZxzn5ZmUhF5A67j/RAbVpN1VjQ1pfOdWml0ipQON19Kc798/NZTXgcjmanbEtBKfUScLbx/E3gZxHe9xhgG11cCmoe9CBp+t2jTISL7WPOhPVqZDPjR4+rxWbd2ptjcx+tNrYtXuO5eQr1exCk6OclQ4FmrRjNMuKVWgr3vvgOA9vst0dfKk1LooX7XlrG7c8tobc/ze8+uXdFn+dwxIWylYKIvInFva6U2r4iiRw5BNVCDaUQpbFMsRm36QrRfY7NOkP6/fYGOClueWohB+0wKphF21JSzW3aotjQnbufRqS4iyZssejzYxYH7C/i++/pT/Hoays5aucxVjfgWTc8k/e9vak0Ha0tgRxu7YJjc6KSmMJ043EH8BGgMYX8a8zKDT0M9F0oUP9Asx6Us5VCcSmKKQVzMNODqOmf1+/Xu5mH+91Dr/NbP6V05/FD836G6VJqb/XOYaEe0qm0Klq2Itli93r2ZFlShY/xpZuf476XlnHfuYcwdeyQgvuG0aXBtcVSjzIbDke9qMR9tCq06dci8gzw3cpEih/Tf3Q/O4wZHDzXvvo6xZnLVgqFxkWlVJY7Ss+yTReMfrv2z5uHW2MEkAuVlDCP1+4P5ht6srvFtSUTgSy2Jjphoqy/KDZQP+rXVyq0ziMf2pJJOkvBsRlSifvIdKIm8CyHzbYU93xL1U+xhkaqT5CN019aIDXfbHnhqo0ccvFD/PRDuwXb9OBtWgpa+enYgxm4HjesI3hcaAA2B3kdKO8KtRBtN5RCZ3dfsEI6H8VeN2XOR6He0MUUbl+/97qOvxRzVTkczUQlg7i5uKwfWAB8tCJpHFb0GGUunErlGYhaEplAbb6x7YXFawG41FhRrAPNZkzh7bXdjBzUbh0kTXfayg09eWU3lYzuuxA+XnuyhU68z1/f3c+A1hYKUQ1LQctg28/W99pE14fScZj+CPEdh6NZqMR9dHg1BXHkJ20JNJuDWUIyCqAjmQgWginl9XPuS6ms2bVOPzV982t937+pFE67ZiZtLQm++b535chkWi1aodgo1iAHMgHoqO8JZx/ZiBKIB7tFUcyF1duvy2hn/3c4NgdKVgoi8iml1I0i8lXb6+aCtM0V7XGIElO4/6VlbD96ENuPHlx85zykrCmpmYGoLZkIyjq0t7YESiGt4Cd3vcwf//smr//kWOYuWUdnd3/Qp6CjNTO46sVj4fIQval0MKs2h76ofvQoMYL21tKWy0SpnhrVzW+zgrp6ilkK2RVTnaXg2Jwox1IY5P8vLWWjSSllAZiN/7l+FkDRtpSFyCxes1sKrS0ZpdBhzLqVUtz0lFfXqLO7jxN/NwOAHcd6CspUAIUCrrb4RdRqobYBNjw7b08WdhdpWluEvpTKm31kEnWgtimFfJZKW0uC3lQ6owx0f2mnExybESUrBaXUH/z/F1ZfnPhRKOhYbL5aqULRpG2BZsNl0Z5M0KkfG/74tIKO1hY29qaConGQSQmNWh8oE2j2Zscbe1KRq4XaLIWwAgq7j/KRTCToS6VojRBTiNqS1Kbw8hXTa096SsGVvHBszlRSOvvnIjJURFpF5AERWSEin6qmcHHA5i9WEVcqVGvQyCxeMzN5Msc2awGZA2xaqSBo+/SCNcF2nf0TVSmYX+N7d7zIHj+4t6iLRRNOP4Xc4G5kpeC7jaK4j6JmBNmUfr4eFdrN1RuyFOIWUXj0tRVByq3DUSqV1D56r1/y+ni8zKMdgG9UQ6g40VfAN1AsprCxwCKtUsisLM5sMxWOGUTuyLIUVDCQvfZOZ7B9gx8YjtqdzJxN6yqqs95aY903nC4aRXl0FMk20mjlZ7qP2vK4kiJbCtaubXmUgu/minsXttOumclp18xstBiOJqUSpaBdT8cBf1VKReuy3mTYZpzFxptnF67hhEsfY2YZPZJtFBvgzIHRDB4rRWApmGmj/RZ3VMHPNwbOYQO8Qrjv+OWqwwxqyx7gowSaB7VHUwo6FdV0H+WzMkxrpKunP2/arFUpFHAfAcxdso6P/uEJOv1yHdVyE67p6uWDl89g0eqNZR+jWrI4tlwqUQp3isgrwD7AAyIyGtjsykXaVusWu+3+M2cpc5as4/6XlhXZMxrFFlNlu4+yLQU9C1+1IbdYXeTPNwaaoM6RpSIqwKD20nMXJg4fEGk/rRRajJTUfJlL5jk75tePMv1H91v3syncfG41bQVd+uB8Zr65Oq+1VC53zn6b5xau5YpHXi/7GKa7zikIRzmUrRSUUucBBwLTlVJ9QBdwYrUEiwu2uIAecPL1U9D+/nJKKNgoVtEi231kxhTslkLJn28IEPjR88g0uAylsPVWAyPtp91GZpw5X+aSqRR0dVYbtsVreS2FkJsraiwkKvq7VHLdmDGwKFaawxGmnHUKH7JsM5/+vRKB4obNfVTMl6zr+q8vUA20FEpxH5mD5Nf/+gJ7bjMcqEwp9GcphcLffUBbNFeQyTYj8lsKOg0UMgFms7x3voE5aulsu/soX0wh+7N0sb/wzzN3yTp2mTC05CZM2uqppGuc+X16+9MMai/7UI4tlHLWKZxQ4DXF5qYULIFmrRTy3fI6S2hDgZW+pVBsgMtnKQA8v2gt4JWPKJesaqpFex2UXg9q6pj8S16SLYKe8Lb6biNzQXN49q6JqhTSSrGpN5WlzPLN1MNKYaXvkjPPzwuL1nLi72bwjWPexRcP3yGSDBqt3CuxFMwJRKEkCYcjH+WsU/h0LQSJK7aU1GIB2g1+1lHYv1vqzPGuOUuZNn5oUUvBHNDyNYapBHPQK5ZN1GJRCmYVVBtbbzWA0w6YxOD2JJc/nO1PN4+XSUXNbMtXHK+Q8jJ97W+t2sjO372bn35oN07Zd1sgvyUYdlVp68t0Mep033tefKdkpdAfpB6XP5ib37saLUkdWx6VrFMYKyJXi8h//OfTROSz1RMtHtjcR8WUwqY+b2AwawKVc6N/4aZnOfKSR4qumDVnsFEzeUrBlL2riJ/aphSKFbgTEX5w4q7sM2mrnNfMILq2QrJjCvndR/OXd7J4TW4mjzlWLvD7T//juSXBtnxKIWyF6QZC5v5a35QT2NfXVT4X3RdvepbPXPu09TWlFI+/vtIa/3E4SqGSSNm1wD3ABP/5a8A5FcoTO2yBZj1I5pvB69LKnUZMIWrQL5VWrDL8/6m0Klom23TZ1MZSiD64mJlBehY/MGKcIWFRKOZ3aw0CzYalkGedQldvP0dd8iifuuqprO0rOnuyZtBaXtOPn2/RYTIh2Lxj5vnRx0kkvHLrZ9/yHOs29vH5G58p2stZf24+g/Lfc5by4Cv2HuF/f3YJn/jjU/x11qJgm2v+4yiHSpTCKKXUX4A0gFKqH2jKdIcn31jFvS++Y33NNmvTN2++mKt+vdNwtURdAfy7h+azz4/uZ3lnZgAppRNZtTNiINNpLArJhARrFYZ2eGsaoioFWzwiy1JoybUUbIoEMhlHC1ZlLIXl67t594/v55L7Xgu2aavOrHeklXqYhEiWPJn9M+dHZy61iHDm9bO444W3ueyhefxn7jtcfM+r1uNqtKVQTp+ON32LZ6GxxiFqpViHw6SSEaRLREbip+2LyP5AUy5g+/iVT+btyWsbkINCaPksBV8pmC9HKSENMNuvYDpj/krj8wrf3MkIi7nClBLeKGXlbkKE+792KM9ccBSDfVdWVOulxSKUWdJC+/TN2Ey+wLYtyK9jPOY6AB3/MS25vN9X7DEM07IILAWRYKDW7rNiZU8CpVDkt3n1nU4mn/dvnluYWSehr1PTinIlvR3lUIlS+CpwBzBFRGYA1wNfLvYmEdlGRB4SkZdE5EUR+Yq/fYSI3Cci8/z/uQ7mOvLi29mrVk36Aksh+6bTg4DNlxs1zXDsUC+HcHVX5nOL+YbNgSp6xdHoP30pNZySCWH8sAGMHNweLGQbO7SD1hZhu1GDGDW4Le97bbN+M0ahffrmwJfIM4Laai7ZlLi24FYb7UXzKYWEiFXpmvvrEhlZ38WXsZjFle88L1vfnWVp/neeV9fon8+/HWyzTRziFmhesnZTVv0uRzypZPHas8CheAvYPgfsopSaHeGt/cDXlFLTgP2BL4rINOA84AGl1FTgAf95XTEH7h/86yVmvrmaJ9/ILVWhB4H/zM24nJ54fRWH/+Jh/vbMYuugctecd/j37KVFZdCDtSlLsdRCXXoCorWqhPy+eBtRymHosdkcxLVSGDmojbkXHsODXzuUySMH2d6e81792LYGwxxv830Nm6VgmznrwXZjb4rH5q3kpqfeyjvDFuxKN60yA7DpPgoT1VIIs99PHuB0o5aRPq9mhzibRRun2kw9/SkOuuhBvvm3KEOEo5GUrBRE5FMicip4cQSl1ItKqbnAx0XkE8Xer5Ra6isUlFKdwMvARLzV0Nf5u10HnFSqbJVizhaHdHg33jpLOQc9aJjtMXUM4Hv/nGu9+a945HW+ePOzeT978nn/5pt/eyFwh2Td8EUsBVMpRCWq8oBomVN6DUGWUvBjCW3JBO3JFkQkbwwAsmf9+jjmOoTAUrAojzDW6qyW82ju96mrn+Lbt8/l9RXZ/bi1WAmRnAwkjR6AtTI3dYKuulpMufZaLFC9ANIsqaFjNF1GwUVtBZmutafeXM3k8/4drFVpJFpJu+qt8accS+HLwO2W7X8HvlbKgURkMrAX8BQwVimlp9LvAGPzvOcsEZklIrNWrKjuBWaa6Ho2ZgZ8NWbMoLc/zezFaxnqD8xdvamig/iarl4WrspNlfzLrMVB0Nic6RaLKQw1lEJUN1VrhPLTpRxTD85Ji6VguqoKrW3LyjTyHw9ozbUURGCncUP4yD5bB9lD4e9jc/vp3som5m8+xJc3PIgGqbCJ3IquegzWA3omLpCRRyueYpZC0DfauH50cTyz0KA+9oaefr59+xy+9fc5wUTFVEY6ecKMTzUKnZ5dLD3Z0XjKUQqtSqkN4Y1KqS4g8pRVRAYDtwHn+CW4zWMp8tSdU0pdqZSarpSaPnr06NIkL4KZg6/dz+s32dwQmSYrn73uaT5w2QxWrO/Jed1GT3+Kw37xMIdc/BDg3djmYirdq8HMXOor4hs2LYVCAW1beqeNsGspiqWQGTgzn6HrILUm88cAzKfZC9U8GcxBRPvzBeHucw7h4o/sgdYFYZltloLte5h1jnbbepjlm5k9oSVHKQzyg+g6XqAHdvMa0EHsYpaCfq+pPPT1N6Qj8xvr4yjgpqcWcsvMhUGmkRk20d83X9ylnmilELVMuqNxlKMUBohIjmNYRIYA+aOI2fu24imEm5RSuizGMhEZ778+HrAnZNeQjcZAogdXW2As07A9zX/nebOwFcbagkIzwg3d/YFLav7yTnb93j38ddbi4HXdUc2cwRazFEylMKFAxVHzhiwUUwg3senuS+WUxA7T0pJrKeiso3bjs8LunnxBY30cc7W2lt9scqSVUGvIHWbTo7ZB2ZY5FMZcNBd2H+nFgvqa0GtKTKUQWAoRlUKfRSbzN9HHMX+mzGro3EZM5ZQeqTbacnNKIf6UoxSuBv4mIpP0Bt8NdKv/WkHEs32vBl5WSl1ivHQHcLr/+HTgn2XIVhFdvSmO+dWj/PSul9nUq5VC/tpH5sCzdmMmHlHIfWQOQnf7gWqz74K+uU1/cSkxhfdOG8vNZ+5n3c8c0Ap1LwtbEd19qaIlsW2WgsZ8r3Z9tFrWHNhKWnQkcy0F83wEPRYiBM5tg7Lpv8+3wFDLIpItDxiWQigeYH5WVwXuIz05MZW4HvjN8xUOdJv7mUp0eWc3LzQgxrA+sBTsv9Pxl/6Xb/19Tj1FcuShZKWglPoF3oD9qIisEpFVwCPAnUqpiyMc4iDgVOAIEXne/zsWuAg4WkTmAUf5z+tCixHcfXVZJ3949I3ghrINJDb30JqNfQVfD14zFka9scJLYR01OFPKUgcMN2S5jzLHs3kChg1o5Y4vHcRtnz8QEeHdk0dYP9ucdetB1Aw46zEm7J/v7ktblYItWyiZNVClsz4LMrNb25qDLKVgCVzrWaZpOdmylPJNjIsNynktBWMldXimO7A9ew2CbbbfVcR9lE4rb6W1xcooZCmYlpXNUtD7mROM826bw4m/m1F0dXW10d+pL6X4/I3P8EYomD93yXpumbmw6p+rlGL5+s2uzUtNKasmglLqCuAK32Wks4iivvcx8hcYPbIceSqlrSXBpnQqeyBO6ZlX7kBhm7lnWQoFYgBmsPNtv3uZmeGUsRSys49E8vcwGDagNcttFPYhtycT9PSnGdia+bn1QN3ekilW19ri7ZdMhCyF/pS1plJLQoJBUL/HNlCZA5p+vaM1wYae7MHcZilklcn2Z5lmjEW/biq3ZIu9AF8x900+S6E1kZElvE5BxzyiWAr5Jgu/eWAev3lgHkfsNMZ7r7GfthTM8iH62KYVq92O5jZtNZjXks6smr98A+OGdVjlqQV6sjNnyTrmLFnH0nXd/OOLB9X8c391/zx++8A8Zp5/JGOG1u/7NjMV1URQSnWWohDiih5slq0zS0vk3nga24zTtBQK0WtYClq5rDeUgr65zc/oT6tg8LFp03AZifBMeZAl4KsHUXPA1gO0uR94ysi2KtnMxU9aYgp6gDQHe20ZaEvBnHknsyyFTMaPRiuylNV9lPs9whQtZGgoBfN4ZhmRsMLXCxa1BagHP/P307GqfJaIdiPqqqtZ7iNfJlOe3mDWbV4j/vVqfIbNBaqvI1sgvpboa0HHpvRCtrvn2svLVIvbnvHidfX+vs1M9QvlNCF6EHnbVAqWmZfGNuMzLYVCmIOFPs7aTZn3Bi6E0OfaUvku/+Te3HzmfjklucPPtdLIKlbXkuue0cHa1kTuZWEGmvVbkhb3UYsxeH1gD69W4v7bjzT28/5rRZwvzqEVgK2khelO0zGMbEvBbogWcx9tNAZUU7EkDUtBy3X2EV5Z7PfvOj7r2P2B+ygzsOsByXTj2OTSVo+5RiWz7iHznWyDvf4Mc5tNebQ3WCloK29FZw8X/ecV/vfGZ5j5Zu4C0WpRSXOpLRWnFMj46U0/a28oxdBk2frcC21tREsh21/sPTbdR7a0RMjMqM3BYdywDg6cMqroZ+pgqDmI60F0pVHiuVDQ1owp6NdNBRAsXjPkO3CHUSy46DimjB4cbAvcPS1aKZiWQq4rybR6RgzyktvMstQtkitzvqBz1OwfsCsZEThkR+98H7LjaBZcdBzH7uYphSD5wD+GLYDdm0pbs9nCcq3v7g+26WvEjKPo68U8lr7+rJatsU1ngkUt0FgttAVlfo/X/ZhaLWXpKXAfO+xUVGdZRA4EJpvHUUpdX6FMdUdbBSs6M4N9qf0P8jWyD2PeoNpfbCoUm08a7FkbhVINj542lvteWgZkgqHmgD3csgq6NY/7yPv87HTWnv501vESlkCzjXC8w/xeNpeNub/u5Wz2SNCKyZzZt+aRoZQaTllKIYiXwIl7TmTf7UYwftiArP30jN42+Jgup66eVE6pDNuMfnVXL+OGdQTXiOl6WuNbpWamUWZbrtLpybIU/MWRdbcUvP/m6ekzYlm1xhUHjE4lTXZuAH4BHAy82/+bXiW56oq+ac21BqUW7oo6E7Hlxa+3WArhi7jDElMotCjp0lP2Ch7rhU8tFkvBJIgzWNxHNivDln5arHyGfo8+52aKZ5Yry3DZfO3oHZk8ciCTRw1EhKyOZi15As02/masBymGebzWwFLw/muFABm33hl/eppl67uLXgf2mkzZq6Eh4/bIKAVTAeRaCmv8Aoo2pdDbn2buknVZ+3dWqVVsVGw9QcK9t2uJra2uw04llsJ0YJpSRTrANAH6RjZrH22K2BSnVGyWgrmSWl+84bhFxn2U2VboZjKzZIb6dZzMsV4f58tH7MClD873jmcJ2mpMy0nP7ExFoR8VVQr+jpNGDGT+8g2csMeE4DWbC0gEvnzkVL585FQA3vzpcVnHa7G4vPKV8HjDDwpHISumYMgSxrR0Hnl1RdGGSLc+vZAJwwdw8t5bc8E/5nL+sTsF14St7Wm3xVLQ16mpKPQAa7Nwl63v5vhLH+PEPScEn9HTn+KWmQtpa0lw8j5bF5S5uy+FSPQKvDbSFmVpU4a1wlkK0alEKcwFxgHFS3/GHNssoljbyXIxb4Cevlx/px4XwlkuepDyGrDoNND8SsGMPWhLwZZKa1obgfvIMtM2ByXtXrIVsCvmCtAz+0kjBzH3wmOyAtimpaDdHLZqo1nHs7itquGOyFpbkcj9vpoBIfmLWQq6B3V7MsFtzy4mIRhKIfPeniCmkNvvYaXv5rS6iiwDrHYVPfjycnYcNwTwrgW9WMymFLr7Ulz/xAI+fdB27PSduxkzpJ2Z3z6q4HcrhO286O8dtSthJRSrCuDIUMndMwp4SUTuEZE79F+1BKsn9exla8sOMcnXLcs2A49a02bogKR/7Mz3/Mj0bdhqYCsf2ntisE3PsE33ywF+5pD5+VpBZa0/sGQB2dDvaW0RBrcn8zbMaS/gojLRSsOWuVQJ7Zbva5PEzApLtkjexkthdOB+fXefsfAsHVgj+jrRFqtZ06rTkmmksQ2+2uro7OkPZufF3Ck3PvkWP7nrFa57fAEAyzsry+KxyaVlMbOtaoVrTRqdSiyF71dLiEailKrrBVOs4mi+AHcw2JruI4vv38aIgV7WTn9a0Zb0FnZtN3IQz333vVn7BaucjQH2tAMm8cQbq/jU/pOCpi5B9pGZkmpJU7Wh1zvYBm5TQZgVUQuRsMzi87nV9HePQpYS1ArKIkw4eyrqBEOXZjd9+739KQa1JdnQ0x/4/00XUZio38VMhdXXn7leZvbitey+9fCs92il9dLbWbUqy8bmVtObamWVm8Spt0TcKVspKKUeqaYgjaLWEZFkQrKUTjGlsN5S8hnsM/CWiAE6ncrZn05z91few9+eWczwgbnZR7pm/wNGc/h9Jm3F/B+/P8t60LK0WNxHxdAz8GKzeVuXNRtJi1KwrbOA0nzX9kBz7n7todTVfJbC4PZkVsaPPl+mUuhLKYZ0ePtpZRC1jWshzM/VmW7rjLUx85ZtyFEK2gLqqtIs3mYp6HO1qYaWQkKymyA5ilOynS0ij/n/O0VkvfHXKSLVmVbUkSiXStQBz0Z41losgG0r1Q2Z/HLzaMX87d96/0588fApwYKl/pRi+9GD+eb7dspZ4GZijmsikpPNY7MU9KBcTMlqBTmgrfClZ+uyZsMWU6hGNkurNdCce1xzmyow+ITLhOjZu7lwsS+VDhYaZiyFVM6K9Sh85qDtrNv19fegofhtbsygEmuVKqzaAs16S75FfdVAy+8CzdEppyDewf7/IUqpocbfEKXU0OqLWDu+9pcXuOaxN4vuZxt8ozapCbt4is381uRZGW2zFIoNfp87dArfOGanYDYbdbZkprPaBoVM7MGiFIocWwf8ilkKZu+EQujPNQfnUrrK5cO+ornwe/rTafKNPYNCZUL0AjRzIV5/WgXuNZ2EsLqrl10mlH5bTRo50Lpdz/yz1gsYSmFFZw+ru3qDtQ1hS+1jf3giUlvZMIXcR7WMKejrwqWkRmeLXtF827OL+fFdLxfdz5bKGTU9LzyoFlMK+fLHbX7tqF2sgpLTEZWCuQLZrhDzu4+KWQq9/qhZVCn47iNVRM1oxWTuFy5al49CPSXM/gz6exZTUN+/48WsFq0mOoagWeZX7gxn3miL4qf/eZln3lrD8s4e9pk0ouDn2shnXRTrM/HuH9/P3j+8L9hmWmB9qTRPvbm6YFvZfNgshcB9VKGLLJVW1uNDRpGHu9n99K6X875nS2eLVgpRMWf72l8ddeAJB16jtssMo2eQps86asMSvV9Un7o5gInxNW/7/AF8dPrWwazXzAzSj4sN4npWWmhA9l73XV5FblxbzKEtosK2WXv6dzUbAyWKWArfev9OgFcy5Mk3Vlu/m9k5DeDttZusx+oIqq4qTv7944AX1ymVUtw+hUpjmL/xxgrcPIUshULB9ChMOf8uTv/TzKxtj7y2gvnLO4Prw7SGvnLrc/zh0Td4aWnTebvrglMKETDvLz0zjeqiKDWmkI+t/MCweQNHvfFHDfYCzflcU2GGGgOYaQ3sM2kEP//wHlY/vv6axSZfn9hvWwAOnlq4ZpNeC1FsNmc7BzaFbTtVtpXPet1BtmvM+58vDHPinhOznrdbSpLotGBNPqVgy97acexgy56FiZIFNaDAZCFo5GP2mvbdPMUUug1b8o9e92pOlMpdC6s7IGpOv2YmR13yaKAUzMmFji+4NFU7FSkFEZkkIkf5jwfo/grNQCnZCNnNX7zH0S2F0mIK+dhqYKROp1bG+WUZ8i0SuuXM/bnlzP2D56alYHNR6XHCnKUfsfNYAPYMZbGE2XvbrVhw0XEF24ZCZuApduMGv42xm01h29xVmcV6RjzCUnNJf0a+4HxY8dvO2ZD2bEshX3C1JXS9tCcTQc0nk2IDczGLDTxXVWuLFAw0m6d/nZ+5VE4g35aVlakoa1YOrnygNhWL/snMxWva+nEZSXbKTkkVkTOBs4ARwBRga+AKGtQop1RKceOYN2rQnKaIi0Kvbg3PZMs1lcM+6VIY7Oec7zrRHrA8YIq3QO2WM/fn2YVrrG4hk8BSMAaHY3YZy8l7T7T2XSgH/fsUO89W95FRhkMPPG1+o6Hs/STYvy+l+xbkZhplgtl2GcIpsOYq50FtLXT1pnJ+v748gc/wWD9l9GCrNTS4I5lVliXM8btP4Nm31tKWTHDDk29Z9xnQ1sLG3lSgAMyBM1MlOLNNp0uX0/PZNgDbij/2p9O0lTBXtR13vRGX07JmWdi++PUor9GMVHIHfxHYF3gKQCk1T0TGVEWqOlDKjN28UfVAaHMRZL/HUwrhG6hcSyGRyAxM5VjYD339sGC9Qj4OmDIyUBAFZdGriI3BMCFSNYUAsMof8EYWkVlbBeZNr624jtaWIEffNrPW7qPWZAJ6U1nvtfWOzrdmIjxzNov8DfCVwtBQVdp87p2wApiax3U0flhHQaUwsK2Fn314dy5/eH7efQa0ttCWTAQzddN6eWaht2bFtNRe8X3w5WR3FVrRbFoHff0KSjCKbfeT2dtEK3mb27UeK6mbkUrcRz1KqeDsi0iSaGn/saAUSyFrtWzEQLNWBrmWQvbnRvXPJkS46X/246GvHRZp/zDbjRrEMEu57HLIZGBlZK9ONru3ghoyN/GYoe2Fdg9iLeYAmbHmchfcmbQalkJ4P3P8179/vgly2DXVYVoKvpU2ONTjOl/zl7Di2WG0XSlsvVV+95tIxtIpdH0NH9hGm9G6tLMns3DytXe8hormYP7IayuA7J7iUbG5j/RvnNV4qsTUUdvAbvYn0fehed9lmhnVfiV1M1LJ1O4RETkfGCAiRwNfAP5VHbFqT7lKIcjRL1JiQgfoclJSQxfi0AHJrEY3+WWAg3Yo3lCnWvzuE3vn9R3r72ZmP0Wtw1SMCz+wCxd+YBdWd/UypD0ZNLHJh461rLHMDos13tGuqWIlLQL3UR7VF85iGmIoAO02GtDm+e/1rHjpOnsz+fB53Da03mCvbYfz3MK1WXGGcPkOMzhcaFY/fdJWvL12U/BeW48F01LQE/rRQ0pXCtaCeJYqqaXWITMzopat7+ampxZykGHtpizBbH1PbupN8ezCNbz2Ticf33fbkj53c6YSpfB/wP8Ac4DPAXcBVxV7k4hcAxwPLFdK7epv+z5wJrDC3+18pdRdFchWlHJ9+0HzF+NeM292TYtlgddA34drMnJQe0SlkDnOC999b9ESzZVy3O75B+NEoBQSOdsqRc9wRw5u51vH7lx0/7F+M/aJwwfwij+7zVRxzexnSz/Vvn9bsb/sQLP3P18Ji3AA2rQK9ORhcHuSViN2kY+wNTIu1Gz+L587gLfXbuK2Z5cE24YPaGV5Z0+gHMw4UCFLYfLIQbQlE7y+sosnXl+Vda3q60s3agKzblLp947t3OlN2YHm0o5tuo++cutzPPnG6qw1GtpqsN3v3f0pPnS5l/brlEKGstxHItICvKyU+qNS6iNKqQ/7j6OMVNcC77Ns/5VSak//r6YKAXKzWgqld5oKwFprx3LjtVj87kM7WukM1TYaOTiaA9Ucd4YNbC0aH6gl+iuZKZ1S1pVUOaOHtHPjZ/fjko/tGWxrswSLbb+RzhIq6j7S2SoFLu+9th0ePB5sBJW1i2TU4PZIGWRh5TpumKcUPrjXRLYdMZDWlgSTRg7K6i6nj6sHQ1tDJBsD2loY2NbCC4vWcsofn8xqAGSbsdvcPVEplOlTiVIw91+02kvzNSdeWhmYloKtkdVm0BamapR1KyulUsCrIlKyelVKPQqsLudzq0m4RHXB3gQUHlysSsESUxg7tD0rMwKi+2erNROvBmZ7Sk0j5Tt46qiseImtNpMtBqTdX+ZrrTZLQYqvmbjpf/YLHps9Inr8wWjEoLZoE4DQaZzop+7+6mN78ug3Dw+2mwp5mB9XGdia23bVphT0MaeOHZyVHNBpuI9sqcA9FVgKhcZ6c3DuT6uSjp/V6tSPL9jiNd3GMbX1YGZbVbqAbnOikvndVsCLIvJAlfopfElEZovINSKSdwmniJwlIrNEZNaKFSvy7VaUsLsnMxjk7mtbvGaLM5jYGs+PCbkCwG4p2GSoVmGyahDMpo0RLA7iTfBn1bbf0mop2NxHRvaRjgfoc18orX1gWzIIercbsZZdJg4DPKUQZQJgXlffPnbnvK1FzWtuvP+9g0G9yPc+Zd9tePrbR7HTuKFZrq7Zi9YWlC2wFCIM2nfOfpul6zIL9Ar1mTCPd+vMRex4wX9YtHpj3v1NTAtEZ32ttPR+0JZCfyoduBlNhbLzd+/mb89Eb9e6OVOJUvgOXmzgB8Avjb9y+D3eWoc98Tq55T2OUupKpdR0pdT00aNHl/lxueZxMogB2FbDGgogketesPYXsCx4sqVX2gYKe6+B3O/QKNosaZtxsGTu+sp7+PfZBwcDZsIyYzZdRQP8mIhNKYgID339MO4555DMqtgiro1tRnjBX9Py+NnJu3H7Fw5k9JB2timQMaRJCJxx4GT23nY4Zx6yfd79zGtkz22GA5kB0rRorM2ZEhIEi03/+1VFikMGMQXjPMxdso4p59+VtUK7pz/Fl25+jk9e9RQAb6zYwO3PLSEfpgvoz08vBGBhRKVg3sf6u9gshaCFaVbnw+z4ztf/+gILSmjZurkSi34KSqkgmiUifwTurNax8xGumqhdItZy1BZLwZw1mj2L9Y1pq6wZTksEu6JobcldaBWHQVdjW+AVB4YPbGP4wLZglmnOToMGQslEMKhZYwpGP+ZRg9sZNbidmW+uAmBFkYQA7dtva0lwxaf2ZurYIQxsS7LXtp7he+AOo7juCftCMk1ChO9/YJei39UMCn90+jYkRFi/qY9f3vda1gy4vUC8C6LXzwK7pXDr0wtJpRX3v7yM0w6YDGTWO7zjZ1j9o4BCgGwl0xVaL1IM01IY6BcTXLY+Vyk889YaNvb2ZykCM3XVJku9+cldL3PUzmPZd7sRDZMBKrAUQv0UukUkVW4/BRExU10+iNf/uaaELYXM7DJ3X3NAfm2ZZ3o++lrGdZW05LvbOoLpomhmUHKQRVHYXEVxUgqZqqul12GqB3qhmOki1JlS5mCjB8Tsjm+5rjGd/rl4TeHZq65w2t6a4H27js+qNgtw1M5j8/Y50ERVtNn9HoTTD5wcNE5KFbEUzN+qlFIPZvbRg68sY+abq4Pr16zuq9t/Fur5bdJncUdFLXdhrmvQSv5t322l70ftBtzQ3Z816NuUQiO58tE3+Ogfnmi0GOUrBbOfAjAAOBm4vNj7ROQW4AngXSKyWEQ+C/xcROaIyGzgcODccuWKSo6lYHE5BDIbj4+z5M3ri89abtl484hB3k07PCsomvt5tm0xGnMzdYlSuTPxOKDrDJm/sV6TYFMKJrZBdN/tRrDdqEGcfeTUgp+rg7b50kBbEsJ3T5hWMCMo6u9sXiP6mm0LlLVdKWhL1aYEo2Aqhc9cO4uP/uEJBvvfucsIUmsF0dqS4OWl65m5wMsrue3zBwb7mPeFTQF05ylBHiYVClJDJtVVTw50gccuo6QHZJTCZw/OKOpGte2MUxnvqtQl8FNR/yEi3wPOK7LvKZbNV1dDjlIIZ1cE9WuKWArH7T4hxwVguo80ZmmE+849hPXd/cxf7lkZ5ie3JBLcetb+tLYkglLJZuaSnsnFyVWjB5q4drPSmUjeIO25EoKS2IYi0IFmZXEzmdsGtSd56OuHRf7cYr9VoYE/qkVoKuGWkFLIt9+wAa1s6OnHnHOcsu+23Pr0IqaOGcy85RsKfqa+ZXqMgXNge65SyJQWEd7/m/8CsMuEoUFAHPT6HO+3sblswv7+fJj3cfYkRYIYw2BDRlMJrvWVghnXy9cjvdbEqWJrJQXxPmQ8TQDTAfsyzRiS6z7SboMMuqCaeZ/aJoHaysi6UY1A89SxXvFYPRjst91IHn51RXC8/bcfGVqan3F16JzrOFkK+nv2p9Nc9om9Ijf7qRfbjBjA147ekeP3mMDhv3gYyFhx5qCg5TbvRz2wFsqWyccn9tuW9Zv6OHLnwiXACg38UX/nrLpTCe2+LGz5jB/WwZK1m7LcR3tsM5w3f3oszy9aywf9hVzFMGfTWsH0GSdxvX8tm5bzhOEDslylxToXdvelue2ZxUwYPqBgPS7T/WXK1ZFsCVyG2n3kKa6MDPOXeUpw6piMm6+nQampcarYWomlcILxuB9YAJxYkTR1JGwmZjp9ZWhtSdCfToVmfsIZB05mx7FDOP/2Od5+Ce07zexnCzTvte1WPPKNwxg+sI2f3f0KkKnAaloZ+jjZSiE+WiFjKaQ5fvcJDZYmFxHhyyFXj3bpmBVM9QzSFpAux4swZfRgLv7IHkX3K/RbRrUIbW4fWyVd05U1YfgAeGtNTuVbEbFWo7WtwIfsgoxdltcfm+/1Nhg7tIO3VnlxmHFDO7JWwBeLQW3qS/Gtv3v314KLjsu7n+kizAqwtyaC76TdSBt7U1nZhZ2+5bCHn70FmT4S9SZO7UIrUQpXKaVmmBtE5CBgeZ79Y0VYMwc3WVZWkbCpL5x6SZAdEiiFZK6lEFQ1DX3upJGDskxtW+G8pJEpk/ncOCqF+MxuiqFlNnsl68BwltshWJNQu+9W6KeM+jPbqvSOG5a7DsZUHvr7FjueVgYD25JFi8bZCtItXuMFes1J0qjB7da+1/nIV5vsrOtnsee2w/nCYTsA2fexmTLc1pIILHitLC99cB5vr812Zuw8fmgQoIcGuo9idC9VEh28NOK2WNKXoxR8/7KxTbd1tFXMNLFlWSQN91EY23oGeyOfzE0cI50QlCYuVtY6TugByszL14Fmc2BJWmIK1cbWuU4TVfnbguQ2pWArCmgbgEzloQOzhZSIRqefmqdr3Sbv+ljZmUnhHTm4LeteiGIp2Lj3pWX8/O5XAVjR2ZP1XUxLoTelgliLVgrPLlzLO+uzlcJuE4dlnSMXUyjDUhCRA4ADgdEi8lXjpaFAvJzLBQgvRLKZ422WjCQJWQ1plfHvtkac2WeX4s4dIJKG+0gTp5RPnWUTpfdCXGi1uI+00jVN98AKquFNGvSjaJGcwSDqz9xhcfcMaU/y4X22ZvvRg4JtprWpz4Etw0afi2RCgoVe244YGLh/8qGDyuYx1/od2sxFZOG6T/naqOpBWXd5y8c9L77D5254hj22HhZsMxVEKp0pDDioQJ+PXSZkN56KGuCuNnGKKZRjKbQBg/EUyhDjbz3w4eqJVlvCsyVbgFEP8rYuXJDxSbclcwd2fQPa3BDFVj4HgeYaVCGtBh/aayJ/Pmt/PrBH/OIJ+bBZc/r8mgOz9nvbcuerhf75beXXo1sKtlXvwi8+skfgWgG7UrBl++j9WlsS/PRDuzF1zGB2mzgsd79QpkWXTSn4gWbdKOmsQ7bnmF3GZr3P9j1NhV2sn/hCX1m97JesgNz4gj7PhZo/TfRXmd/+BS9dtnGWQhPHFPyVzI+IyLVKqcLLM2NMeIamZ+UqK6aQm5FkXss7jRvKzAWrA7+rrRCZbQaQVUvJMjBkAs1mv4ICX6bOJBLCfts3h5Xw0NcP47VlncEgYvq59W9u5q4HzexrmK8uhqWQ77ViRF2J3NqSYOzQdsYO7Qi+u819pL/36QdO5uR9tubkfbbmN/fPy9lvSEcyGOwhE2jW51AplTPLP2aXsXlrOGV9p2QL4L13rXGMhas28ot7X+XnH9492Bbcv8ZX6UupoIx9Kq0CxVPIDTZykJeOuq1foqSWsaRCxMlSqCTQvFFELgZ2AQJnplLqiIqlqgNh95EtxztTW99ITzVUxG9P2YvLHprHmCEdXoqpcT8Hq34tN2Ax36reZs4G47ROoZnYbtQgths1iGtn6Lo+mfM42s9Pnz55q6BImlbEtVzElLEUyl+kWEp5isf+z7slf//w64D9u7UlE8z78futZbd1n2nwYgNZSiFkKWzsTdGbSmf1GNExChPb9Wxe72aNokMufgggyzINlJChFfpTaYZ0tLK6q5d+oz+6aYEAbD9qEG/4NY5GDfHcWnpy1p9SzFm8jjdWbuDEPSfmyFgr4hRTqCTQfBPwCrAdcCFeSurTVZCpLuQLNOdzHw0NFiZl3jNuWAc/Omm3YNGSebO1F7AUTGyzRW3uxq0KaTNjCyCPGdrB/V89lO8en6k11GaxHqqNrcd1+LVi2NxH+WhtSQR/kN8Kam1JhHpQeI/NK3hsqNKvVgr3v7ycB19ZxqlXe0XwdhqX8dWb/alP3X8SZ+Up9GcqOlv2UZeR6bSxTyuj7ECzDiqn0ir4LgNDSuHK06Zz9enTec/UUYGloJti9afTnHDZY3zl1uetMtaKzSX7aKRS6mqgTyn1iFLqM0BTWAmQ20+hcKAZdvcDWp3duSl4elGOufAlU3Kg8OBisxR0ipx5E8QpptCM5Bvsdxgz2FoltZa+Zf1b2mtcRTuGLdBcDD3I9/VHG4AyNa4U0ydtBeQWdTSv0c9cO4tnF64Fsjv3mSmfPzxpV87P01HPXG1uC/iavUi6Lamy/WkVuMF2nTA0WFhnnqs7vnQQO4wZzJE7j+WGz+6XkwnWqBl7nGIKlSgF7fRbKiLHichewIgqyFQX8gWazY5mmZIHcMlH9+QLh01hb6OYnUbfKGa9lkxmSxFLwTIK6EwNcz2DUwqVMdSfQYabHIXRA2dNLYVE9meZj6O6CcML0KJgLjosZf90WgX9wcOTp64ee7bOrhOGcekpe3HpKXtZF8bZpO8wjm1rerPeWPVvWz+RSiveNW4IXzhsCleeNt2a7m02YzLR92GqzjP27r4UP7zzJZaujU8xiEpiCj8SkWHA1/DWJwylDoXsqkV44ZW+UbYa2BY0VQ+CxUoxYlAb33zfTtZjaZN1k3GhthWIKZjYZou6WYt5wzmdUBnar93Z3YdIdkKBSRB8rmlMIXewakl4Pvha/s4f2GMC/3rhbT53qN19E8YssGdbOwOZlFSTc4/akYOnjipZviz3kWVl8XqjlW2+dQzJRCK4T7WCNedl+ZSC/i1qmYps476XlnH1Y2/y4CvxWfNblqXg92ieqpRap5Saq5Q6XCm1j1LqjirLVzPC7qNJI73c7nOOypRHCNJKi1woej/TytCDS7H1BVal4B/HvOHKmRk6Mmi/9vrufp46/0j+/oUDrfsVyuWvFvqXtBW1q6VFOHxgG3/93wODUuDFMFM537frOAA++u5tsvYJW1R/+dwBfOWowtVk82GeD2tMwbgf8rn3zCQnfcuYccIhlqA3eArEU8z1deO8tcoLeK81UnC7+1K8aqTa1puylILfo9lW7bRpCM8IthrYxoKLjuO9u4wLtpk+1UKM8btYnbJvpmV1Ju+7dKWwna+gzCJ5TidUxtZ+PvrR08YyZkgHe/uNb8JM8PsXv3faOOvr1UAslkKm/0bNPrZkhhjxg6ljh7DgouOs7lOzKYytkZSNsO7zFoJm7jOb+2hTb2ZbvomabQ2QmexRaJKWTAidhjVSy1Xtmk1Bm9DMZ512zUyO+fWjDSvjXYn7aIaIXAb8GQh62Cmlnq1YqjrQn0pnuRFsEzRtzhb7cSaPGsTz3z2a4QPbuOAfXn8grRSK5WfbMlB0L+fJIweywM+vz2f2OqIxfGAbs7//3qD+fz5GDW7nhe+9N2tArBXmtWFbxNhobA2gbPKZcYaoSiGMWSYe7JaCWWcp33oCU77vnbALHckWjp421rpvmGRCWLfJ/AwoMqerGJ2cssH4bjPf9PpPbOjuD7wG9aSSK39P//8PjG2KJslA6k8r2oy2l7YJhE77i5IuNnyg/ccrxVIY3J706t0nhPu/eihbDWxlnx/dDxRelemIhi1fXnP2kVN5eel6oPYKWP/iZpJBog7uo1IZbKm6aqO1JcHQjiTru/utlVoL0dbitUdNiGQN9Db3kKko8t2S5gLSsUM7uORje0aWpSUhWW6cvlSalkRtK/fo2IlNx23o6Wfh6o1MHjmIYQPrNymspEfz4dUUpN70pxRtSbMXsmUxjV7IVEa6mDZvi3UkMweGoR2eUhC8VEnwUug2FalU6aicrx69Y90/096UKfr7p40fyivvrK+2WAFRraXWFm8S8/CrKyLPbPXY3e73zG5JSNHKqWZwOZ9rpxL3W7IlkbWSuh7pqYX6NyxZu4mPX/kkR08byx9Pm15zWTSVNNkZC/wEmKCUer+ITAMO8NcuxJ7+dJr2ZAIdzinoPoqY1519/GhKwbQUhg5o5e113VkB5t23Hl7yZzuaA3PhYjmB5ju/fHDVZTLJF5S95KN7MGP+Km57djHgVRMeM7QjJwgdhfbWBJ093vcOrzwOY8YZ8i0KrSQhI5mQrGB2uOpBLegukPo8w+9LoUuR14tK1ilcC9wD6LXnrwHnVChP3ehLqaziXrabMSiOVsbFoW+oSSMKZ3qYs6Mff3BXdho3JKfhu2PzpM0aU4j+/kRCapqVlm+Q/tDeW/OLj2TqEBVzkRZCp7gmpHjpjiz3Ub5AcwXut2RCsj6jPpZCfi/Ayg2eK6ve7c8r+bhRSqm/AGkApVQ/0DR+jlRaZa1ktV1KA3w/fjk56wfvMIrffWJvvvG+dxXcz7QU9pk0grvPOaTojMmxeWDrlxGnmALAf77yHqtFIiLBpClcOTUKuoSLrlTbkhBG5InLaUz3Ub6U1HxKctTgdg7dcXTB47e0SNbM3RZL7Eulg+KKS9dtsjYZCvP22k15XcCFLAXtMdjUm+KR11bw+RufKZoeXw0qUQpdIjISvzSKiOwPrIvyRhG5RkSWi8hcY9sIEblPROb5/+05g1Wgpz/FwtUbs5WC5VrSi8jKqUvSkvCW+ttWc5rEKdvEUV/M668cS6Ee7Dx+KLtaSmhDZmZvKyYZFX1/tCSEc47ekS8enl01YOzQ9uBxdxSlkOcEzrrgKK77zL4FZUkmElmDd18qnTMIX/ivFznk4odY09XLAT99kNOunlnwmAAHXvQgn7nWXhaukKWg3VfdfWm+cutz/GfuO9z69KKin1cplSiFrwJ3AFNEZAZwPfDliO+9FnhfaNt5wANKqanAA/7zmnD9428xf/mGrIU3tmtJ12wpry5JzO5uR2zQFTqzS6jHL/uoGLrOUDmWgo6nmIX9Brcn+cYxO2Vl2n3n+GnBY3PAztdLuRJXSzIhWSupr/rvG2x//l1Z64UeeNlbebzaz1Ka9daagsfUAfEn3lhlfb2QpaDdV5v6Uozz09Qfea32K58ryT56VkQOBd6FNwK+qpQq3C4p895HRWRyaPOJwGH+4+uAh4H/K1e+QuhyuWYdHNuMXaeZltOLuInubUeDMK8r07feLOj1CQPLWJugu6FlmlFlXusI9YvWmANovqydSpRqS0KyUkOve+ItwHMT6TRlnTa7JGLwt5jrOYqlsLG3n1Vd3vd6Z31P3v2rRdl6VUQ6gLOBH+KVzv6iv61cxiqllvqP3wGsK05E5CwRmSUis1asWFHWB43y6+ibBbZsl5IuohYuvRuF4W6xmSMPB/gNisxeANq33ozuxHLuDx030wFjc42CGXAe0JpROKZlb7qPLjguU3W1EqUQLmOvD2UW39Nj/KI1hduUamwrs00KVePVlkJ3X5oVnZ4yeGHRWn5450s1bcpTifvoerwGO5cCl/mPb6iGUMqzuazfWil1pVJqulJq+ujRhQNH+dA11M3sAtvNuO2IQXxor4nc8aWDSv6MEU3U1N5RXw7fybtuzVmpnnU3k/tI3z6DylAK+j06s8/03ZtKJp/C6elPsc2IAZy6/ySmGX2WKzl/4XLk+ljmgjbtDlq4OppSMN1cvf1prnz09azj9fSlGJlnrAhnPW4/yit/c/Vjb3LBP+ZE+vxyqEQp7KqU+qxS6iH/70w8xVAuy0RkPID/v2bOs0kjBzJ55EDOPSqzYMl2KbUlE1zysT3ZYcyQkj+jGWd8jvrQZpRkD7Y1oftIz+4HlLHaXruc9OzfnPgOMCyF9jzNhHr60+w0big/PGnXrDIblcQUwqux9U+xpquPuUvWsXJDT2DF5Ct1PXvxWlZ3mYN+ZmC/7vEF/OSuV7hlZiZY3N2fDvpEhwknuJy8z9bB41tmLsqKdVSTSpTCs37GEQAish8wq4Lj3QGc7j8+HfhnBccqyKD2JA9/4/Csao7mDOM9ZZT91dx9znu45cz9i+/o2GLRHf1Ml0kzWgpa/HLcR+/3q67qYnpmMseAIN4geYPYvf3pYE2CWT+sknUbr4Qqk2pPwsa+FMdf+hgn//7xwO21qsvu2//AZTM48XePBc+1pdCSEF5d5h3fHMx7+lJBscYw4aKdU8cMZsFFx3H5J/cGvFTXWlBJQZ19gMdFZKH/fFvgVRGZg+cB2j3fG0XkFryg8igRWQx8D7gI+IuIfBZ4C/hoBbKVjHkvXl8kda0QZhtCh8NGYCkY27RSaCKdYFgKpSuF90wdzRs/OZY75yzl+ifeygq6a0tBkILprloXmLGASpSqrTcEwKoNngJ4a9VGdh4/1N/Wm7VPXyodWBaLVmcGax1TaEkIC/ysM3Mw7+5PM2FYPkvB3kdeN+Fas7E35z3VoBKlEE4pjYxSKl/Z7SPLPWalmJeSc/04aom+ubPdR7mKIu7okhBbFVl0lo9EQoJuaylLTKE3lS6Y7qoVgK0vRVny5HnvW6sy8QPdh2WloRT+8dwSzvnz88EM3kRbCsmEBGmsnd19nHfbbB6bv5JUWmX1sDbJ1x1yq0He/mu6YuY+Ukq9BawHhgEj9Z9S6i3/tabCKQJHvcj4wDM3va7gum5jbW70WqBTurctUsqlELbSFgPbM9sKWgoF+lKUw5eP2MG6Xc/sE5JJIzbdR7pr2pwluWt3A0tBJMh27OpNcevTi4KaRh154ibhQHN7nSyFSlJSfwjMBn4L/NL/+0WV5Ko7Tic46oWe2ZqzY10VVy9sawZ0n4KtKijrbFMKZonzQgUltTJoNWMKFdzH//Mee5tSHQNIq8xAbVp5Ol1U/zcxMxz1cbpCbqp8VQ/C1ZnbWrz9hg9s5QN7TGCbCpRxISpxH30UmKKUqo26qjNOJzjqxUE7jOKIncZwwXE789CrjwBw0l4TeWzeSv43Yv/kOHDZJ/aiqydVkZVtmyWb/SwKWQr6Y7OqzdYgfctcz2QrjjnXtxCWW5SCTrXt6u0PMqwWrspOZx2eR6nmcx+1J1v47Sl7RZS+dCpRCnOB4dQwdbSe1Nt9NOO8I1yfhC2UjtYWrjnj3VnbBrcnueLUfRokUXm0J1uK1vYqhs1SMJVCoR4LQfaRoRRqcR+b2UK2Omid/sx/+fpMmuqm3hRvrNwQBOPNRKLOkKWQb8YfrqTQXkGNqVKo5FN+CjwnIveIyB36r1qC1Zt654dPHD4gcBk4HFsq4QVjkK0URIRff2xPa4XTINCcqE6gGeChrx/GN47JrmzcZUzeCpWtMN1HX//bCxz328dy1hKY7UpP3ttbd6B7socJ11yrpPBgKVTyKdcBP8NLJf2l8deUuJiCw1F/bOms4TagJ+01kR3H5k6gdFC5Jct9VJk8240axEl7Tcz7eqGKyauMRWtPveH1WTYXsgFMGJ6pBPTDk3Zh9vffm7dbXSqP+6jWVPIpG5VSv/VXMz+i/6omWd1xWsHhqDe2cjC2xXA2N5W27k1LoRruo9YCboNNfamssh75elJrMVaG1jPsMiFThnxgWzIIqn/T0nclHGgeXEbhwXKoRCn8V0R+KiIHiMje+q9qktWZZiov4HBsLtgCwzaXki0grd9ra2taCcki5sZ+fkFDgMPeNca6jw4w64Vvmn0m2dvEfOGwHfjRSbtmbQtbJcU601WLSlSPDn+bNR0UcEQFx2wYbp2Cw9EYfvPxPbN6KNjWGtgtBV3mwlynULk8xTKYRg+2N/4x0VlKYffRiEFtXHDczllF/DThxXP1aAdqo5J+CodXU5BG41SCw9EYTtwzvw9fM3ZYblV+PYiaE7pq1I4q1nPaTCE996gd6e5L0duf5qk3VwfbdbntcGC6JSF510Pk00X7Th7BAVNG2l+sAZUsXhsrIleLyH/859P8ukVNiTMUHI74stc2w3O22QbRaqxTSFrMjW1GZOoTjTIshWkThnLDZ/dj1JD2rP31LL831C+hUIptPoV285n7ce7RO1pfqwWVGFvXAvcAE/znrwHnVChPw2im6pQOx5aGLchqUwDVuI9tA/f2owYH/aJtqeT5ekqEF7sVUlr5RK/32FSyUhAR/euMUkr9BUgDKKX6gaZdjeV0gsMRX2xBVlscsBoDaCIhweCtlVFLQjhyZ6+sh2k1aAbm6SkRXoBms0KCz80je73HpnJiCjOBvYEuERmJX9XL762QWxGqSTBNQoejXjx1/pF0djdPEbx68dDXD8vy7ZureVtbhL6Usq5JqFaZi9YWIZVWnLDHeB59bSVnHzmVaeOHcvzu461Nt/L1lAi7jwrJZ9MXIvVPgilHKWgJv4rXGGeKiMwARgMfrpZg9cYpBUcjGDu0g7FDK2ltvnmy3ajsVb5mRlIykaAvlbLOrKuVWt6aSNBNmonDBzDjvExC5YFTvAZcV58+nQnDMxbDYe8aw+UPv55znLD7KNwHOus1i1ZohFu7HKUwWkS+6j++HbgLT1H0AEfhVU5tGiYOH8CStZtqUkjL4XBUn2SLQF/2rDuZEPrTqqLS2SZ6lXRLHnePdiVp9t1uBOccNZX+lOKyh+YH23tKsBRstY0aMSyVoxRagMHkZnHWpo5rjfn32QfT2W3vuORwOOJHsGjNGDE7WlvY0NNftZl1poFP9OOdc9SOvPpOZ5ZSyLEUCozytjIWjVg/VY5SWKqU+kHVJWkQwwe2MbzMzlEOh6P+BIvWjKBCezLBhp7qrGg2KXUVcbjsRSnZRzal0AhLoZyUVOdncTgcDcO2klkP3tVY0Qyg/JLXlSqF3HUK+QUstGq7npRzChvWR9nhcGy5nHXI9px/7E5B1pGpFNr92kjVGkR1Imm+Vpn5GNyezFrxHE5JLT2m0ARKQSm1uvheDofDUV3OP3ZnzjpkitFcx3QfebPsaiWM6HabtuJ8hRAR9t42U/QuXOai1JhCswSaa4qILAA68RbC9SulpjdWIofDESfEEgTWM/pqj6HlVCbdeqvcxW2aki2FBmiF2CkFn8OVUisbLYTD4YgfemA100X1jD6cAlouetZeqvsIYPyw/Eqh0DoFu6XQBO4jh8PhaCRaKWStePYH73ylrEtluN8StJxuZ/l6JkDhQHObZYl2s2Qf1RoF3Csiz4jIWeEXReQsEZklIrNWrFjRAPEcDkcj0QNl0mIpdPdVx1IY7Vc9Led47568FT87eTerq6hQ97T2iPWdak0clcLBSqm9gfcDXxSRQ8wXlVJXKqWmK6Wmjx6d28zb4XBs3mTcR5kBc/pkb3Y+blh1ytX88qN7cOr+k9hr2+Elv1dE+Ni7t2WcpXxJIXdUXCyF2MUUlFJL/P/LReR2YF/g0cZK5XA44oK2EEz30WcP3o4Dp4yydjQrh/HDBvDDUHvMUrFZCoVm/ub3EfEyoKQBy8JiZSmIyCARGaIfA+8F5jZWKofDESf0bNtMSRWRqimEalEo/dSGqTAG+aW4W5Mu+2gscLt/cpLAzUqpuxsrksPhiBPB6uWY11YoJ0itGdjm1XKyuZRqTayUglLqDWCPRsvhcDjii1YKPVUKKteK7UcP4pV3Ost676D2JHT20NoApRAr95HD4XAUQy/yqtaahFoxeeSg4jvlYahfQ6kSa6NcnFJwOBxNxYBWnX4a7+6/lQzoQwe0Ft+pRsTKfeRwOBzFOO/YnUgpxft3G9doUQpSietnmK8UwgX16oFTCg6Ho6kYM6SD33x8r0aLUZRwg55SivVllEL9XWTOfeRwOBw1IFzSohyl0O+UgsPhcGwehC2FI941JvJ7hzr3kcPhcGxe6MV1yYRw31cPZfyw3LIX+Wik+8gpBYfD4agB5orm7UZFS09tSybo7U+zzVYDAVjV1VsT2Qrh3EcOh8NRA8rJPhriV1GdNNJTCql0/d1HTik4HA5HDdBKoZRhXVd7bU8m+OR+23LVafVvPOncRw6Hw1EDCnVZy8evPrYnzy9ay5ihHfz4g7vVQKriOEvB4XA4akA4+ygKA9uSHDhlVA2kiY5TCg6Hw1EDCrXejDPNKbXD4XDEHO0+Uqr+weJKcErB4XA4akAjeiFUg+aU2uFwOGKOzj5qQFZpRTil4HA4HDVgSEdzJnc6peBwOBw1YFgDeyJUglMKDofDUQMa2SinEpxScDgcjhrQiP7K1SBWUovI+0TkVRGZLyLnNVoeh8PhqISJwwfwuUO3b7QYJRGbSIiItAC/A44GFgNPi8gdSqmXGiuZw+FwlMeM845otAglEydLYV9gvlLqDaVUL3ArcGKDZXI4HI4tijgphYnAIuP5Yn9bFiJylojMEpFZK1asqJtwDofDsSUQJ6UQCaXUlUqp6Uqp6aNHj260OA6Hw7FZESelsATYxni+tb/N4XA4HHUiTkrhaWCqiGwnIm3Ax4E7GiyTw+FwbFHEJvtIKdUvIl8C7gFagGuUUi82WCyHw+HYooiNUgBQSt0F3NVoORwOh2NLRZqt1reJiKwA3irz7aOAlVUUpxLiJIuNOMkXJ1mKERdZ4yJHFOIka5xksVGJfJOUUtZMnaZWCpUgIrOUUvXvim0hTrLYiJN8cZKlGHGRNS5yRCFOssZJFhu1ki9OgWaHw+FwNBinFBwOh8MRsCUrhSsbLYBBnGSxESf54iRLMeIia1zkiEKcZI2TLDZqIt8WG1NwOBwORy5bsqXgcDgcjhBOKTgcDocjwCkFh8PhcAQ4pVAnRORDIrJVo+VoBty5Kh0ROUJEBjVajmbCXWd2NkulICJnisjlIjIlBrJ8SkSeBA4GuhstTxh3rkrH7+nxQxEZEANZPikizwCHA32Nlicf7jqLTqPPVaxqH1WCiAiekvsw8E1gKbCfiCxRStX9h/flOQO4CjhQKfVUvWXIhztXpePLmAT+B/g/vMHkXuC/DZInCZwDfBt4v1LqyUbIUQh3nUUnTudqs7AURKRDeaSAZ4H9gN8DhwA7N0Im5eX6Pg3cAvSISEJETheRhsijceeqdESkzT9nfXjnbGfgD8CnRWRkI2RSSvUD84AbgbdEpE1EThaRCY2QJ4y7zqITt3PV9EpBRL4D3C0iXxaRXZRS85RSq4G/AQK8p15+QxG5UESOMzbNxysFfifwAnAAcI2I/NTfv67n352r0hGR7wE3i8gZIjJCKfWUUmoT3k27NXBUvWQTkfNFZD9j0xN4BSH/gzeYfBC4TkS+7e/fqHPmrrPo8sXmXAUopZr2D/gM8DCeZv0B8A9gsvH6e4HrgCND75MqyzECb3XhGrwLrdV4bWvgAmCK/3wHPNNwgjtX8TxXhjzn4rmIjgRuAH4DjDdePwX4J7B9jeUYD9wGrAXmhV47APgJsLX/fFf/3I5s0Dlz11mTnavwX9NaCr4PbhvgcuX5Bn8OzAV+qvdRSt0LLAB2E5HjROSL/vZqL+PuAv6hlNoKr4XoV43X3gZ+ppR63f/s+cDjwKQqy5AXd65KR0RagL2AC5VSDwA/BDbi+fHx5bsFWA8cKiLvFpFP1kicdcBflVLDgbUiYp6zp30ZF/syzQXuxiurXFfcdRadmJ2rbOqpGWugab8H3Gk8Hw3MBA4zth0ALMe7EM6toSyD/f/vxjNRx1v2GQD8GngIGObOVWzPlS7/cjHwJ/9xwpf3DmAfY9+jgU3AIuCzNZRpiP//YGAV0KblMvZpBS4F/g101OMcxeE6KyBLLK6zOJ2rSPLW40OqcFKPAMaFTzLQDrwEHKK3A2cDPzFO8n+Bq4GBtZDF9uP7n3dV6LXD8GYjv66WLHlk+ASwh3E+GnmusmSJ27kyPm+48dgcZKcC9+ErAf8cXYA/+OO5HZ4E/ljFc2aVJXTO/o7XrtZ87URgVh3PWUse2RpxnbUUeK3h1xkwwJSnkecqkrz1+qAyT+aBwIvA9cAOoROb9B9/EXjKeO2LwNeMk14V32oRWRL+Yy3TaOAVf1A5ANgdGApMrOG5Osq/gJYDZzT4XBWSpeHnypDn/cAjwE3At4ztLf7/Nrz0wD8br/2WjFIYQZ4JQhVlSRiDiD5nY4HVeC6iXYBt8fzkk+twzo7DC9L+BDjIPGcNuM4KydLw6wwvJvA43qD+SWN7st7nqiS56/2BJZzQFuBPwCdC282Z3Hj//4PARXim9T3ANxohC4Y2xwtKpoHngXfX6BwJnvn7F7yA1THA5cAX9MVXr3NVqiz1PlcWefcFngI+ABwK/BXYNbTPaF/W+/HWA0zxz9npDZKlw3h+lX/Ongam1emc7YPn3jgW+DheIPeM0D71uicjydKo68z/vZ4ETsLzLtyBoezrea5Klr2RH17kpG4FXAsMx5uxnYpnrnf4r1+Cp4UnA9sD/4s30/p2g2R5FM93KcDxwJvAN+t0rk40Hn8KeMJ4nsQLYtXrXEWRpWHnypDlXOBi//H2wK14Sk3PMC/Hyywahzcb/zGee+a7DZDld3iZKdPwLIdT8QKQdR088Bbt/dJ/PAAvY+ZZfJcX8Ms6XmdRZGnIdeZ/3q7AH4xt0/Csu9H+87qNXyXL32gBjJN2Np5vVpvmI/0f9VD/5vwL8Ge8RUOD8Mz4rULHaIuDLHgm6rA6nKszQ9tbgIPwZpHb+Nve5V+AtT5XZclS63OVT05gN7yslEuBxf7vey3wHTz3zPWWc9YeB1mA6Rixhzqes32B14AR/vPv4AVov+/fI7+u13VWqix1uCdPB442nk8G5mC4f4Ar8FJMh+BZLTU5VxV/l0YL4J+MM/BMrffhacsL8LT/RXhZAx/19xuCl3mxh/HevEGmBsiSrKYsEeX7FkaePJ6v9Gn8bJXQe2t9rkqRpebnqoCc38Gz+rYCfgWc4O83DS/wt2Mdz1kpsjTynH0bGIOnuO7Eixn9Cc9NeAWGwqzDOStFlpqeM/93+xveOofZ5nfHU+bXGc9H+PfDNrU6V9X4i8s6hSPx8obvBr4GdABfAL6LN/gOAVBKdQI3482eEBFR3tLwuMjSX2VZosjXjuemwZdrNl5dno9puQz5an2uSpGlHucqn5ytwJeVUmvwZpBv+fu9AszA/41FJFGHc1aKLI08Zx3AaUqpL+PdDz9QSn0a6MGb4fb4ctbrnowqS03Pmf+73YtXjuIZvHFC8yXgWBF5t/98A/AcoAz5qn2uKqahSsFYUv4cns8PpdQs4DE8P+544BvAMSJygohcgOeSeMnfV22OspQo35PARBE52N9P8IJVA/yLTlVbvjjJUqacjwOTRGQaXpDvKhEZiDcD3RVvzQFKqfTmKEuZcs4AdhSR9yilFiql7vP3OxZ4Q7+/TtdZ3WXJI5/4D69XSq3Fi0N9SEQm+Z+/HrgQ+I6InI7nddgF6KyHfOVSd6Vg1hYxLvQZQEJEDvGfz8W7GfZRSl2PZxIejJd6d7zyV29uTrJUKN/beEpLX2hjgK4a3aANl6VKci4GdlJKXQK8iucCmAZ8SCm1fHOTpUpyvo0XeEdEDhGRR/Csmys2R1kiyKcnOd3+/6fx6lD92NjnMrz4xj54K6Y/opRaV0sZK6UupbNFZF9gf6XUb80Zj28Sp/GqPb4IfExEZiilFovIGLwfGaXUgyLycDVmS3GSpYryjcMrwaD5ulKqd3OSpQZyjsULfAN8Fi91ce3mJEuN5NS/7QK8dOMXNydZSpRPL0Qzx4LLgL+IyC7ASrx42oMi8kgcXUU2am4piMg5wO3ABSLyfn9bC2TNBDrxgkXtwC9EpBUvgLNCH6dKCiE2stRAvlWGfNVQCLGRpYZyLtMyVkkhxEaWGsq50t9vYZUUQmxkKUM+pZRKi8gAERmsZfH3n4MXFB/qb28KhQDUPvsIb/n9XsDJwCOW1y/EW6yzE57b4Vo83/QfqH4WQ2xkibt8cZKlWeSMkyzNImecZClTvu/hlR3Z3X9+Cl6ywM8xKrM2018tTuIJeFH3/f3nLf5fB3AXcLa/PYGXn30zfglbY3tOCmOzyxJ3+eIkS7PIGSdZmkXOOMlSI/n2B7ar9W9a0+uliidzPPAvPDPvO8DLwDH+a7p2y5F4tc1HWd6f2Bxlibt8cZKlWeSMkyzNImecZKmRfLFbb1D2uajiST0BYwk58Dng9vAPi2f2Xeg/39c86ZujLHGXL06yNIuccZKlWeSMkyzNKF89/yo9kafhlZ9tBwaS3ZXqI2RKwJqF47bBW9C0Dq/eR1VOaJxkibt8cZKlWeSMkyzNImecZGlG+Rr1V3JKqp+GNQ7Pl5YGXgfOBL6ilFoqIq3Ka3A+Hi9DAOVF6AWvyuSf8PKOz1FKzSn18+MqS9zli5MszSJnnGRpFjnjJEszyhcLStSsus78jsCNehteDZK/h/b5F3CU/1gXrRoDHF4NbRYnWeIuX5xkaRY54yRLs8gZJ1maUb64/EWyFPy83B8CLSJyF17ubQq8/FsR+QrwtogcqpR6RETa8PL6XxORHwPHi8jhyludWdEKzTjJEnf54iRLs8gZJ1maRc44ydKM8sWNoovXRORQvEJPW+FVCf0h0AccLt5KP5S3yOT7eDnF4KVvnQE8gFfQ6yil1OpKhY2TLHGXL06yNIuccZKlWeSMkyzNKF8siWByvQc41Xh+OfB5vJP2jL8tgeen+wteW8B98crG7llNsyZOssRdvjjJ0ixyxkmWZpEzTrI0o3xx/ItyUgfiRee1r+2TwE/9x8/jlf0Fr/HHrTX+gWMjS9zli5MszSJnnGRpFjnjJEszyhfHv6LuI6XURqVUj8rU7jiaTB2gTwM7i8idwC14ZppZUraqxEmWuMsXJ1maRc44ydIscsZJlmaUL45ETkn1gzUKr6nMHf7mTuB8vLrvbyqllkBd6pjHRpa4yxcnWQoRJznjJEsh4iRnnGRpRvniRClVUtN4XaJWArv72vU7QFop9Zg+oXUiTrLYiJN8cZKlEHGSM06yFCJOcsZJFhtxly8+lOJrwiv2lMbrRvbZRvq94iRL3OWLkyzNImecZGkWOeMkSzPKF5c/XegpEiKyNXAqcIny+6A2ijjJYiNO8sVJlkLESc44yVKIOMkZJ1lsxF2+uFCSUnA4HA7H5k3dezQ7HA6HI744peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwqOWCIiKRF5XkReFJEXRORrIlLwehWRySLyiSrKcLaIvCwiN0Xc/wwRuaxan18uInKSiEwznv9ARI5qpEyO5qHkzmsOR53YpJTaE0BExuB1yhoKfK/AeyYDn/D3rQZfwCubvLhKxysZEUkqpfpLfNtJwJ3ASwBKqe9WWy7H5ouzFByxR3nNTc4CviQek0XkvyLyrP93oL/rRcB7fAvjXBFpEZGLReRpEZktIp+zHV9Evioic/2/c/xtVwDbA/8RkXND+3eIyJ9EZI6IPCcihxsvbyMiD4vIPBH5nr//IBH5t2/xzBWRj/nb9xGRR0TkGRG5R0TG+9sfFpFfi8gs4Nsi8pa2kvxjLRKRVhE50/9uL4jIbSIy0D8XHwAu9s/DFBG5VkQ+7L//SF/mOSJyjYi0+9sXiMiF/vmcIyI7VfzDOZqTRi+pdn/uz/YHbLBsW4tX0Gwg0OFvmwrM8h8fBtxp7H8WcIH/uB2YBWwXOuY+wBxgEDAYeBHYy39tATDKIsfXgGv8xzsBC8k0ZlkKjAQGAHPxSjKfDPzReP8wvDo8jwOj/W0fM475MHC5sf8/8dtA+vtd5T8eaezzIzJloK8FPmy8di3wYV/GRcCO/vbr8XoN6++q3/8F/Rnub8v7c5aCoxlpBf4oInOAvwLT8uz3XuA0EXkeeApvsJ4a2udg4HalVJdSagPwd7zGLIU4GLgRQCn1CvAWXt9fgPuUUquUUpv8Yx2Mp3SOFpGfich7lFLrgHfhVee8z5fvArwGL5o/hx5/zH/8ceO1XX2LaQ5en4Bdisj9LrxqoK/5z68DDjFe/7v//xk8V5xjC8TFFBxNgYhsj9dXdzleXGEZsAeeC7Q739vwZr/31EVIj3DdGKWUek1E9gaOBX4kIg8AtwMvKqUOyHOcLuPxHcBPRGQEnmXzoL/9WuAkpdQLInIGnqVUCboeUAo3NmyxOEvBEXtEZDRwBXCZUkrhuV+WKq+37qlAi79rJ15PXc09wOdFpNU/zo4iMih0+P8CJ/n++EHAB/1thfgv3swcEdkR2BZ41X/taBEZISID8AK+M0RkArBRKXUjcDGwt7//aBE5wD9Oq4hYZ/q+BfM08Bs895huGDMEWOp/v08abwmfB82rwGQR2cF/firwSJHv6tjCcLMBR1wZ4LtVWoF+4AbgEv+1y4HbROQ04G4ys+rZQEpEXsCbRf8Gzw3yrIgIXsetk8wPUUo9KyLXAjP9TVcppZ4rItvlwO99t00/cIZSqsf7CGYCt+G5gm5USs0SkWPwAr9pvKbxn1dK9frB39+KyDC8e/HXeDENG3/Gc5UdZmz7Dp5bbIX/XyuCW/Hca2fjxRL0d+0WkU8DfxWRJJ6iuaLId3VsYbgqqQ6Hw+EIcO4jh8PhcAQ4peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwoOh8PhCHBKweFwOBwB/w9rIgmvO/MuNQAAAABJRU5ErkJggg==\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "# start the figure.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(weather['Local time'], weather['T'])\n", + "# label the axes\n", + "ax.set_xlabel(\"Date of observation\")\n", + "ax.set_ylabel(\"Temperature in Celsius\")\n", + "ax.set_title(\"Temperature Observations\")\n", + "# adjust the date labels, so that they look nicer\n", + "fig.autofmt_xdate()\n", + "# save the figure\n", + "fig.savefig('weather.png')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/opengraph/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py b/branch/opengraph/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py new file mode 100644 index 00000000..8742b5f6 --- /dev/null +++ b/branch/opengraph/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py @@ -0,0 +1,38 @@ +import yaml + +def get_parameters(config_file, required, defaults): + ''' + Parameters: + Optionfile: FileName of the yaml file containing the options + required: Dict of required argument names and their object types. + defaults: Dict of default parameters mapping to their default values + + Returns: An object with fields named according to required and optional values. + ''' + f = open(config_file) + options = yaml.safe_load(f) + # create a parameters object that allows setting attributes. + parameters = type('Options', (), {})() + # check required arguments + for arg in required: + if not arg in options: + raise Exception("Could not find required Argument " + arg + " aborting...") + else: + if not isinstance(options[arg],required[arg]): + raise Exception("Expected input of type " + str(required[arg]) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + # check the default values. + for arg in defaults: + if arg in options: + if not isinstance(options[arg],type(defaults[arg])): + #Wrong type for the parameter + raise Exception("Expected input of type " + str(type(defaults[arg])) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + else: + print( arg + " not found in option file. Using default: " +str(defaults[arg])) + setattr(parameters,arg,defaults[arg]) + return parameters + + diff --git a/branch/opengraph/_images/01_memory_layout.svg b/branch/opengraph/_images/01_memory_layout.svg new file mode 100644 index 00000000..93da7c68 --- /dev/null +++ b/branch/opengraph/_images/01_memory_layout.svg @@ -0,0 +1,584 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How you see a matrix: + How NumPy sees a matrix: + [0,] + [1,] + [2,] + [3,] + [,0] + [,1] + [,2] + [,3] + [0] + [1] + [2] + [3] + [4] + [5] + [6] + [7] + [8] + [9] + [10] + [11] + [12] + [13] + [14] + [15] + + + + diff --git a/branch/opengraph/_images/01_table_dataframe.svg b/branch/opengraph/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/branch/opengraph/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/branch/opengraph/_images/02_views.svg b/branch/opengraph/_images/02_views.svg new file mode 100644 index 00000000..925354e0 --- /dev/null +++ b/branch/opengraph/_images/02_views.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + array "a" + array "b" + .shape.strides + .shape.strides + + + + + data pointer + data pointer + memory buffer + + diff --git a/branch/opengraph/_images/anaconda-navigator-jupyterlab.png b/branch/opengraph/_images/anaconda-navigator-jupyterlab.png new file mode 100644 index 00000000..4ea0854f Binary files /dev/null and b/branch/opengraph/_images/anaconda-navigator-jupyterlab.png differ diff --git a/branch/opengraph/_images/anaconda-prompt.png b/branch/opengraph/_images/anaconda-prompt.png new file mode 100644 index 00000000..e4fcf79b Binary files /dev/null and b/branch/opengraph/_images/anaconda-prompt.png differ diff --git a/branch/opengraph/_images/binder.jpg b/branch/opengraph/_images/binder.jpg new file mode 100644 index 00000000..d04c467d Binary files /dev/null and b/branch/opengraph/_images/binder.jpg differ diff --git a/branch/opengraph/_images/exercise.png b/branch/opengraph/_images/exercise.png new file mode 100644 index 00000000..465f23f2 Binary files /dev/null and b/branch/opengraph/_images/exercise.png differ diff --git a/branch/opengraph/_images/gapminder-larger-font.png b/branch/opengraph/_images/gapminder-larger-font.png new file mode 100644 index 00000000..fb11e972 Binary files /dev/null and b/branch/opengraph/_images/gapminder-larger-font.png differ diff --git a/branch/opengraph/_images/gapminder-linear.png b/branch/opengraph/_images/gapminder-linear.png new file mode 100644 index 00000000..4890b46c Binary files /dev/null and b/branch/opengraph/_images/gapminder-linear.png differ diff --git a/branch/opengraph/_images/gapminder-log.png b/branch/opengraph/_images/gapminder-log.png new file mode 100644 index 00000000..3fff7b2f Binary files /dev/null and b/branch/opengraph/_images/gapminder-log.png differ diff --git a/branch/opengraph/_images/getting-started.png b/branch/opengraph/_images/getting-started.png new file mode 100644 index 00000000..e1a0a81f Binary files /dev/null and b/branch/opengraph/_images/getting-started.png differ diff --git a/branch/opengraph/_images/jupyterlab-notebook.png b/branch/opengraph/_images/jupyterlab-notebook.png new file mode 100644 index 00000000..900fdfd9 Binary files /dev/null and b/branch/opengraph/_images/jupyterlab-notebook.png differ diff --git a/branch/opengraph/_images/jupyterlab-terminal.png b/branch/opengraph/_images/jupyterlab-terminal.png new file mode 100644 index 00000000..33a6b02a Binary files /dev/null and b/branch/opengraph/_images/jupyterlab-terminal.png differ diff --git a/branch/opengraph/_images/main-ui.png b/branch/opengraph/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/branch/opengraph/_images/main-ui.png differ diff --git a/branch/opengraph/_images/notebook-ui.png b/branch/opengraph/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/branch/opengraph/_images/notebook-ui.png differ diff --git a/branch/opengraph/_images/tidy_data.png b/branch/opengraph/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/branch/opengraph/_images/tidy_data.png differ diff --git a/branch/opengraph/_sources/binder.rst.txt b/branch/opengraph/_sources/binder.rst.txt new file mode 100644 index 00000000..1c841b3b --- /dev/null +++ b/branch/opengraph/_sources/binder.rst.txt @@ -0,0 +1,202 @@ +Binder +====== + +.. questions:: + + - Why sharing code alone may not be sufficient. + - How to share a computational environment? + - What is Binder? + - How to binderize my Python repository? + - How to publish my Python repository? + +.. objectives:: + + - Learn about reproducible computational environments. + - Learn to create and share custom computing environments with Binder. + - Learn to get a DOI from Zenodo for a repository. + + +Why is it sometimes not enough to share your code? +-------------------------------------------------- + +Before we work in groups, +let's take an example from geospatial +analysis where the first ``import`` in the code would be (please note that it is +not necessary to install any of the packages mentioned below):: + + from osgeo import ogr, osr, gdal + +Depending on how you install this python package, it may be necessary to have +`libgdal` and its development headers already installed on your system; with +information on the version you have used, etc. + + +Exercise 1 +~~~~~~~~~~ + +.. challenge:: Binder-1 (10 min) + + Lea is a PhD student in computational biology and after 2 years of intensive + work, she is finally ready to publish her first paper. The code she has used + for analyzing her data is available on GitHub but her supervisor who is an + advocate of open science told her that sharing code is not sufficient. + + **Why is it possibly not enough to share "just" your code? + What problems can you anticipate 2-5 years from now?** + + We form small groups (4-5 persons) and discuss in groups. If the workshop is + online, each group will join a breakout room. + If joining a group is not possible or practical, we use the shared document + to discuss this collaboratively. + + Each group write a summary (bullet points) of the discussion in the workshop + shared document (the link will be provided by your instructors). + + +Sharing a computing environment with Binder +------------------------------------------- + +`Binder `__ allows you to create +custom computing environments that can be shared and used by many remote users. +It uses `repo2docker `__ to +create a container image (`docker `__ image) of a +project using information contained in included configuration files. + +Repo2docker is a standalone package that you can install locally on your laptop +but an `online Binder `__ service is freely available. +This is what we will be using in the tutorial. + +The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder. + +.. image:: https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png + +Credit: `Juliette Taka, Logilab and the OpenDreamKit project (2017) `_ + + +Binder exercise/demo +~~~~~~~~~~~~~~~~~~~~ + +In an earlier episode (Data visualization with Matplotlib) we have created this notebook: + +.. code-block:: python + + import pandas as pd + import matplotlib.pyplot as plt + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + data_2007 = data[data["year"] == 2007] + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xscale("log") + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + +We will now first share it via `GitHub `__ "statically", +then using `Binder `__. + +.. challenge:: Exercise/demo: Making your notebooks reproducible by anyone (15 min) + + Instructor demonstrates this: + + - Creates a GitHub repository + - Uploads the notebook file + - Then we look at the statically rendered version of the notebook on GitHub + - Create a ``requirements.txt`` file which contains:: + + pandas==1.2.3 + matplotlib==3.4.2 + + - Commit and push also this file to your notebook repository. + - Visit https://mybinder.org and copy paste the code under "Copy the text below ..." into your `README.md`: + + .. image:: img/binder/binder.jpg + + - Check that your notebook repository now has a "launch binder" + badge in your `README.md` file on GitHub. + - Try clicking the button and see how your repository is launched + on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud. + - Enjoy being fully reproducible! + + +How can I get a DOI from Zenodo? +--------------------------------- + +`Zenodo `__ is a general purpose open-access +repository built and operated by `CERN `__ and `OpenAIRE +`__ that allows researchers to archive and get a +`Digital Object Identifier (DOI) `__ to data that they +share. + +.. challenge:: Binder-3 (optional) + + **Everything you deposit on Zenodo is meant to be kept (long-term archive). + Therefore we recommend to practice with the Zenodo "sandbox" (practice/test area) + instead: https://sandbox.zenodo.org** + + 1. **Link GitHub with Zenodo**: + + - Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing). + - Log in to Zenodo with your GitHub account. Be aware that you may need to + authorize Zenodo application (Zenodo will redirect you back to GitHub for + Authorization). + - Choose the repository webhooks options. + - From the drop-down menu next to your email address at the top of the page, select GitHub. + - You will be presented with a list of all your Github repositories. + + 2. **Archiving a repo**: + + - Select a repository you want to archive on Zenodo. + - Toggle the "on" button next to the repository ou need to archive. + - Click on the Repo that you want to reserve. + - Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release. + + 3. **Trigger Zenodo to Archive your repository** + + - Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI. + - If this is the first release of your code then you should give it a + version number of v1.0.0. Add description for your release then click the + Publish release button. + - Zenodo takes an archive of your GitHub repository each time you create a new Release. + + 4. **To ensure that everything is working**: + + - Go to https://zenodo.org/account/settings/github/ (or the corresponding + sandbox at https://sandbox.zenodo.org/account/settings/github/), or the + Upload page (https://zenodo.org/deposit), you will find your repo is + listed. + - Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo. + - You can edit the archive on Zenodo and/or publish a new version of your software. + - It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata + manually, you can also add a ``.zenodo.json`` or a ``CITATION.cff`` file to your repo and Zenodo will infer the metadata from this file. + - Your code is now published on a Github public repository and archived on Zenodo. + - Update the README file in your repository with the newly created zenodo badge. + + +Create a Binder link for your Zenodo DOI +---------------------------------------- + +Rather than specifying a GitHub repository when launching binder, you can instead use a Zenodo DOI. + +.. challenge:: Binder-4 (10 min) + + We will be using an existing Zenodo DOI `10.5281/zenodo.3886864 `_ to start Binder: + + - Go to `https://mybinder.org `__ and fill information using Zenodo DOI (as shown on the animation below): + + .. image:: https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif + + - You can also get a Binder badge and update the README file in the + repository. It is good practice to add both the Zenodo badge and the + corresponding Binder badge. + +.. keypoints:: + + - Sharing reproducible computational environments + - Binder + - Zenodo DOI diff --git a/branch/opengraph/_sources/data-formats.rst.txt b/branch/opengraph/_sources/data-formats.rst.txt new file mode 100644 index 00000000..2b63ee3f --- /dev/null +++ b/branch/opengraph/_sources/data-formats.rst.txt @@ -0,0 +1,629 @@ +Data formats with Pandas and Numpy +================================== + +.. questions:: + + - How do you store your data right now? + - Are you doing data cleaning / preprocessing every time you load the data? + +.. objectives:: + + - Learn the distinguishing characteristics of different data formats. + - Learn how Pandas to read and write data in a variety of formats. + +What is a data format? +---------------------- + +Whenever you have data (e.g. measurement data, simulation results, analysis results), you'll need a way to store it. +This applies both when + +1. you're storing the data in memory while you're working on it; +2. you're storing it to a disk for later work. + +Let's consider this randomly generated dataset with various columns:: + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.info() + +This DataFrame already has a data format: it is in the tidy data format! +In tidy data format we have multiple columns of data that are collected in a Pandas DataFrame. + +.. image:: img/pandas/tidy_data.png + +Let's consider another example:: + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + data_array + + +Here we have a different data format: we have a two-dimentional array of numbers! +This is different to Pandas DataFrame as data is stored as one contiguous block instead of individual columns. +This also means that the whole array must have one data type. + + +.. figure:: https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png + + Source: `Elegant Scipy `__ + +Now the question is: can we store these datasets in a file in a way that **keeps our data format intact**? + +For this we need a **file format** that supports our chosen **data format**. + +Pandas has support for `many file formats `__ for tidy data and Numpy has support for `some file formats `__ for array data. +However, there are many other file formats that can be used through other libraries. + +What to look for in a file format? +---------------------------------- + +When deciding which file format you should use for your program, you should remember the following: + +**There is no file format that is good for every use case.** + +Instead, there are various standard file formats for various use cases: + +.. figure:: https://imgs.xkcd.com/comics/standards.png + + Source: `xkcd #927 `__. + +Usually, you'll want to consider the following things when choosing a file format: + +1. Is everybody else / leading authorities in my field using a certain format? + Maybe they have good reasons for using it. +2. Is the file format good for my data format (is it fast/space efficient/easy to use)? +3. Do I need a human-readable format or is it enought to work on it using programming languages? +4. Do I want to archive / share the data or do I just want to store it while I'm working? + + +Using some of the most popular file formats +------------------------------------------- + +CSV (comma-separated values) +**************************** + +.. admonition:: Key features + + - **Type:** Text format + - **Packages needed:** numpy, pandas + - **Space efficiency:** Bad + - **Good for sharing/archival:** Yes + - Tidy data: + - Speed: Bad + - Ease of use: Great + - Array data: + - Speed: Bad + - Ease of use: Ok for one or two dimensional data. Bad for anything higher. + - **Best use cases:** Sharing data. Small data. Data that needs to be human-readable. + +CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you're working with big data. + +Pandas has a very nice interface for writing and reading CSV files with `to_csv `__- and `read_csv `__-functions:: + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + +Numpy has `routines `__ for saving and loading CSV files as arrays as well :: + + np.savetxt('data_array.csv', data_array) + + data_array_csv = np.loadtxt('data_array.csv') + +.. important:: + + When working with floating point numbers you should be careful to save the data with enough decimal places so that you won't lose precision. + + For example, double-precision floating point numbers have `~16 decimal places of precision `__, but if you use normal Python to write these numbers, you can easily lose some of that precision. + Let's consider the following example: + + .. code-block:: python + + import numpy as np + test_number = np.sqrt(2) + # Write the number in a file + test_file = open('sqrt2.csv', 'w') + test_file.write('%f' % test_number) + test_file.close() + # Read the number from a file + test_file = open('sqrt2.csv', 'r') + test_number2 = np.float64(test_file.readline()) + test_file.close() + # Calculate the distance between these numbers + print(np.abs(test_number - test_number2)) + + CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. + We can check whether our written data matches the generated data: + + .. code-block:: python + + dataset.compare(dataset_csv) + + np.all(data_array == data_array_csv) + + In our case some rows of ``dataset_csv`` loaded from CSV do not match the original ``dataset`` as the last decimal can sometimes be rounded due to `complex technical reasons `__. + + Storage of these high-precision CSV files is usually very inefficient storage-wise. + + Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems. + +Feather +******* + +.. important:: + + Using Feather requires `pyarrow-package `__ to be installed. + + You can try installing pyarrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** Good + - **Good for sharing/archival:** No + - Tidy data: + - Speed: Great + - Ease of use: Good + - Array data: + - Speed: - + - Ease of use: - + - **Best use cases:** Temporary storage of tidy data. + +`Feather `__ is a file format for storing data frames quickly. +There are libraries for Python, R and Julia. + +We can work with Feather files with :external+pandas:ref:`to_feather- and read_feather-functions `:: + + dataset.to_feather('dataset.feather') + dataset_feather = pd.read_feather('dataset.feather') + +Feather is not a good format for storing array data, so we won't present an example of that here. + + +Parquet +******* + +.. important:: + + Using Parquet requires `pyarrow-package `__ to be installed. + + You can try installing PyArrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** Great + - **Good for sharing/archival:** Yes + - Tidy data: + - Speed: Good + - Ease of use: Great + - Array data: + - Speed: Good + - Ease of use: It's complicated + - **Best use cases:** Working with big datasets in tidy data format. Archival of said data. + +`Parquet `__ is a standardized open-source columnar storage format that is commonly used for storing big data in machine learning. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.). + +We can work with Parquet files with :external+pandas:ref:`to_parquet- and read_parquet-functions `:: + + dataset.to_parquet('dataset.parquet') + dataset_parquet = pd.read_parquet('dataset.parquet') + +Parquet can be used to store arbitrary data as well, but doing that is a bit more complicated so we won't do that here. + + +HDF5 (Hierarchical Data Format version 5) +***************************************** + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, PyTables, h5py + - **Space efficiency:** Good for numeric data. + - **Good for sharing/archival:** Yes, if datasets are named well. + - Tidy data: + - Speed: Ok + - Ease of use: Good + - Array data: + - Speed: Great + - Ease of use: Good + - **Best use cases:** Working with big datasets in array data format. + +HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences. + +Pandas allows you to store tables as HDF5 with `PyTables `_, which uses HDF5 to write the files. +You can create a HDF5 file with :external+pandas:ref:`to_hdf- and read_parquet-functions `:: + + dataset.to_hdf('dataset.h5', key='dataset', mode='w') + dataset_hdf5 = pd.read_hdf('dataset.h5') + +PyTables comes installed with the default Anaconda installation. + +For writing data that is not a table, you can use the excellent `h5py-package `__:: + + import h5py + + # Writing: + + # Open HDF5 file + h5_file = h5py.File('data_array.h5', 'w') + # Write dataset + h5_file.create_dataset('data_array', data=data_array) + # Close file and write data to disk. Important! + h5_file.close() + + # Reading: + + # Open HDF5 file again + h5_file = h5py.File('data_array.h5', 'r') + # Read the full dataset + data_array_h5 = h5_file['data_array'][()] + # Close file + h5_file.close() + +h5py comes with Anaconda as well. + + +NetCDF4 (Network Common Data Form version 4) +******************************************** + +.. important:: + + Using NetCDF4 requires `netCDF4 `__- or `h5netcdf `__-package to be installed. + h5netcdf is often mentioned as being faster to the official netCDF4-package, so we'll be using it in the example. + + A great NetCDF4 interface is provided by a `xarray-package `__. + + You can try installing these packages with + + .. code-block:: bash + + !pip install h5netcdf xarray + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** pandas, netCDF4/h5netcdf, xarray + - **Space efficiency:** Good for numeric data. + - **Good for sharing/archival:** Yes. + - Tidy data: + - Speed: Ok + - Ease of use: Good + - Array data: + - Speed: Good + - Ease of use: Great + - **Best use cases:** Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets. + +NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs. + +NetCDF4 is by far the most common format for storing large data from big simulations in physical sciences. + +Using interface provided by ``xarray``:: + + # Write tidy data as NetCDF4 + dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf') + # Read tidy data from NetCDF4 + import xarray as xr + dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf') + dataset_netcdf4 = dataset_xarray.to_pandas() + dataset_xarray.close() + +Working with array data is easy as well:: + + # Write array data as NetCDF4 + xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf') + # Read array data from NetCDF4 + data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf') + data_array_netcdf4 = data_array_xarray.to_numpy() + data_array_xarray.close() + +The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (``x``, ``y``, ``z``) or timestamps (``t``) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis. + +npy (numpy array format) +************************ + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** numpy + - **Space efficiency:** Good. + - **Good for sharing/archival:** No. + - Tidy data: + - Speed: - + - Ease of use: - + - Array data: + - Speed: Great + - Ease of use: Good + - **Best use cases:** Saving numpy arrays temporarily. + +If you want to temporarily store numpy arrays, you can use the :func:`numpy.save`- and :func:`numpy.load`-functions:: + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + +There also exists :func:`numpy.savez`-function for storing multiple datasets in a single file:: + + np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array) + data_arrays = np.load('data_arrays.npz') + data_arrays['data_array0'] + +For big arrays it's good idea to check other binary formats such as HDF5 or NetCDF4. + +Exercise 1 +---------- + +.. challenge:: + + - Create the example dataframe ``dataset`` with: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + - Use the ``%timeit``-magic to calculate how long it takes to save / load the dataset as a CSV-file. + +.. solution:: + + .. code-block:: python + + %timeit dataset.to_csv('dataset.csv', index=False) + + %timeit dataset_csv = pd.read_csv('dataset.csv') + +Exercise 2 +---------- + +.. challenge:: + + - Save the dataset ``dataset`` using a binary format of your choice. + - Use the ``%timeit``-magic to calculate how long it takes to save / load the dataset. + - Did you notice any difference in speed? + +.. solution:: + + .. code-block:: python + + + %timeit dataset.to_hdf('dataset.h5', key='dataset', mode='w') + + %timeit dataset_hdf5 = pd.read_hdf('dataset.h5') + +Exercise 3 +---------- + +.. challenge:: + + - Create a numpy array. Store it as a npy. + - Read the dataframe back in and compare it to the original one. Does the data match? + +.. solution:: + + .. code-block:: python + + import numpy as np + + my_array = np.array(10) + + np.save('my_array.npy', my_array) + my_array_npy = np.load('my_array.npy') + np.all(my_array == my_array_npy) + +Benefits of binary file formats +------------------------------- + +Binary files come with various benefits compared to text files. + +1. They can represent floating point numbers with full precision. +2. Storing data in binary format can potentially save lots of space. + This is because you do not need to write numbers as characters. + Additionally some file formats support compression of the data. +3. Data loading from binary files is usually much faster than loading from text files. + This is because memory can be allocated for the data before data is loaded as the type of data in columns is known. +4. You can often store multiple datasets and metadata to the same file. +5. Many binary formats allow for partial loading of the data. + This makes it possible to work with datasets that are larger than your computer's memory. + +**Performance when writing tidy dataset:** + +For the tidy ``dataset`` we had, we can test the performance of the different file formats: + ++-------------+----------------+-----------------+----------------+ +| File format | File size [MB] | Write time [ms] | Read time [ms] | ++=============+================+=================+================+ +| CSV | 4.571760 | 0.296015 | 0.072096 | ++-------------+----------------+-----------------+----------------+ +| Feather | 2.202471 | 0.013013 | 0.007742 | ++-------------+----------------+-----------------+----------------+ +| Parquet | 1.820971 | 0.009052 | 0.009052 | ++-------------+----------------+-----------------+----------------+ +| HDF5 | 4.892181 | 0.037609 | 0.033721 | ++-------------+----------------+-----------------+----------------+ +| NetCDF4 | 6.894043 | 0.073829 | 0.010776 | ++-------------+----------------+-----------------+----------------+ + +The relatively poor performance of HDF5-based formats in this case is due to the data being mostly one dimensional columns full of character strings. + + +**Performance when writing data array:** + +For the array-shaped ``data_array`` we had, we can test the performance of the different file formats: + ++-------------+----------------+-----------------+----------------+ +| File format | File size [MB] | Write time [ms] | Read time [ms] | ++=============+================+=================+================+ +| CSV | 23.841858 | 0.647893 | 0.639863 | ++-------------+----------------+-----------------+----------------+ +| npy | 7.629517 | 0.009885 | 0.002539 | ++-------------+----------------+-----------------+----------------+ +| HDF5 | 7.631348 | 0.012877 | 0.002737 | ++-------------+----------------+-----------------+----------------+ +| NetCDF4 | 7.637207 | 0.018905 | 0.009876 | ++-------------+----------------+-----------------+----------------+ + +For this kind of a data, HDF5-based formats perform much better. + + +Things to remember +------------------ + +1. **There is no file format that is good for every use case.** +2. Usually, your research question determines which libraries you want to use to solve it. + Similarly, the data format you have determines file format you want to use. +3. However, if you're using a previously existing framework or tools or you work in a specific field, you should prioritize using the formats that are used in said framework/tools/field. +4. When you're starting your project, it's a good idea to take your initial data, clean it, and store the results in a good binary format that works as a starting point for your future analysis. + If you've written the cleaning procedure as a script, you can always reproduce it. +5. Throughout your work, you should use code to turn important data to human-readable format (e.g. plots, averages, :meth:`pandas.DataFrame.head`), not to keep your full data in a human-readable format. +6. Once you've finished, you should store the data in a format that can be easily shared to other people. + + +Other file formats +------------------ + +Pickle +****** + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** None (:mod:`pickle`-module is included with Python). + - **Space efficiency:** Ok. + - **Good for sharing/archival:** No! See warning below. + - Tidy data: + - Speed: Ok + - Ease of use: Ok + - Array data: + - Speed: Ok + - Ease of use: Ok + - **Best use cases:** Saving Python objects for debugging. + +.. warning:: + + Loading pickles that have been provided from untrusted sources is + risky as they can contain arbitrary executable code. + +:mod:`Pickle ` is Python's own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:: + + import pickle + + with open('data_array.pickle', 'wb') as f: + pickle.dump(data_array, f) + + with open('data_array.pickle', 'rb') as f: + data_array_pickle = pickle.load(f) + + +JSON (JavaScript Object Notation) +********************************* + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** None (:mod:`json`-module is included with Python). + - **Space efficiency:** Ok. + - **Good for sharing/archival:** No! See warning below. + - Tidy data: + - Speed: Ok + - Ease of use: Ok + - Array data: + - Speed: Ok + - Ease of use: Ok + - **Best use cases:** Saving Python objects for debugging. + +JSON is another popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.). +However, when you're working with big data, you rarely want to keep your data in this format. + +Similarly to other popular files, Pandas can write and read json files with :meth:`~pandas.DataFrame.to_json`- and :func:`~pandas.read_json`-functions:: + + dataset.to_json('dataset.json') + dataset_json = pd.read_csv('dataset.json') + +However, JSON is often used to represent hierarchical data with multiple layers or multiple connections. +For such data you might need to do a lot more processing. + + +Excel (binary) +************** + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** `openpyxl `__ + - **Space efficiency:** Bad. + - **Good for sharing/archival:** Maybe. + - Tidy data: + - Speed: Bad + - Ease of use: Good + - Array data: + - Speed: Bad + - Ease of use: Ok + - **Best use cases:** Sharing data in many fields. Quick data analysis. + +Excel is very popular in social sciences and economics. +However, it is `not a good format `__ for data science. + +See Pandas' documentation on :external+pandas:ref:`working with Excel files `. + +Using Excel files with Pandas requires `openpyxl `__-package to be installed. + + +See also +-------- + +- `Pandas' IO tools `__ +- `Tidy data comparison notebook `__ +- `Array data comparison notebook `__ + + +.. keypoints:: + + - Pandas can read and write a variety of data formats. + - There are many good, standard formats, and you don't need to create your own. + - There are plenty of other libraries dedicated to various formats. diff --git a/branch/opengraph/_sources/data-visualization.md.txt b/branch/opengraph/_sources/data-visualization.md.txt new file mode 100644 index 00000000..dbaf98f6 --- /dev/null +++ b/branch/opengraph/_sources/data-visualization.md.txt @@ -0,0 +1,514 @@ +# Data visualization with Matplotlib + +```{questions} +- What happens if you can't automatically produce plots? +- When to use Matplotlib for data visualization? +- When to prefer other libraries? +``` + +```{objectives} +- Be able to create simple plots with Matplotlib and tweak them +- Know about object-oriented vs pyplot interfaces of Matplotlib +- Be able to adapt gallery examples +- Know how to look for help +- Know that other tools exist +``` + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **No manual post-processing**. This will bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Matplotlib](https://matplotlib.org/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization (R users will be more at home), statistics built in + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/showcase/): + Jupyter notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative + (using grammar of graphics). + + +## Why are we starting with Matplotlib? + +- Matplotlib is perhaps the most "standard" Python plotting library. +- Many libraries build on top of Matplotlib. +- MATLAB users will feel familiar. +- Even if you choose to use another library (see above list), chances are high + that you need to adapt a Matplotlib plot of somebody else. +- Libraries that are built on top of Matplotlib may need knowledge of Matplotlib + for custom adjustments. + +However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code. + +Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. **Later we will also try other libraries.** + + +## Getting started with Matplotlib + +We can start in a Jupyter notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK. + +Let us create our first plot using +{func}`~matplotlib.pyplot.subplots`, +{obj}`~matplotlib.axes.Axes.scatter`, and some other methods on the +{obj}`~matplotlib.axes.Axes` object: + +```{code-block} python +# this line tells Jupyter to display matplotlib figures in the notebook +%matplotlib inline + +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("my-first-plot.png") +``` + +```{figure} data-visualization/first-plot/getting-started.png +:alt: Result of our first plot + +This is the result of our first plot. +``` + +When running a Matplotlib script on a remote server without a +"display" (e.g. compute cluster), you may need to add the +{obj}`matplotlib.use` call: + +```python +import matplotlib.pyplot as plt +matplotlib.use("Agg") + +# ... rest of the script +``` + +## Exercise: Matplotlib + +````{challenge} Exercise Matplotlib-1: extend the previous example (15 min) +- Extend the previous plot by also plotting this set of values but this time + using a different color (`#56B4E9`): + ```python + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + ``` + +- Then add another color (`#009E73`) which plots the second dataset, scaled + by 2.0. + ```python + # here we multiply all elements of data2_y by 2.0 + data2_y_scaled = [y*2.0 for y in data2_y] + ``` + +- Try to add a legend to the plot with {meth}`matplotlib.axes.Axes.legend` and searching the web for clues on + how to add labels to each dataset. + +- At the end it should look like this one: + ```{figure} data-visualization/first-plot/exercise.png + :alt: Result of the exercise + ``` +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 12, 15, 20-21, 26 +--- +# this line tells Jupyter to display matplotlib figures in the notebook +%matplotlib inline + +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +# this is dataset 2 +data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + +# here we multiply all elements of data2_y by 2.0 +data2_y_scaled = [y*2.0 for y in data2_y] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00", label='set 1') +ax.scatter(x=data_x, y=data2_y, c="#56B4E9", label='set 2') +ax.scatter(x=data_x, y=data2_y_scaled, c="#009E73", label='set 2 (scaled)') + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") +ax.legend() + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("exercise-plot.png") +``` +```` + +```{discussion} Why these colors? +This qualitative color palette is opimized for all color-vision +deficiencies, see and +[Okabe, M., and K. Ito. 2008. "Color Universal Design (CUD): +How to Make Figures and Presentations That Are Friendly to Colorblind People."](http://jfly.iam.u-tokyo.ac.jp/color/). +``` + +--- + +## Matplotlib has two different interfaces + +When plotting with Matplotlib, it is useful to know and understand that +there are **two approaches** even though the reasons of this dual approach is +outside the scope of this lesson. + +- The more modern option is an **object-oriented interface** (the + {class}`fig ` and {class}`ax ` objects + can be configured separately and passed around to functions): + ```{code-block} python + --- + emphasize-lines: 8-14 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + ``` + +- The more traditional option mimics MATLAB plotting and uses the + **pyplot interface** (:py:mod:`plt ` carries + the global settings): + ```{code-block} python + --- + emphasize-lines: 8-12 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + plt.scatter(x=data_x, y=data_y, c="#E69F00") + + plt.xlabel("we should label the x axis") + plt.ylabel("we should label the y axis") + plt.title("some title") + ``` + +When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, **we +recommend to learn and use the object oriented interface.** + +```{discussion} Why do we emphasize this? +One day you may want to write functions which wrap +around Matplotlib function calls and then you can send {class}`~matplotlib.figure.Figure` and {class}`~matplotlib.axes.Axes` +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions. + +When using the pyplot interface, settings are modified for the entire +{mod}`matplotlib.pyplot` package. The latter is acceptable for linear scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls. +``` + +--- + +## Styling and customizing plots + +- **Do not customize "manually"** using a graphical program (not easily repeatable/reproducible). +- **No manual post-processing**. This will bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- Matplotlib and also all the other libraries allow to customize almost every aspect of a plot. +- It is useful to study [Matplotlib parts of a figure](https://matplotlib.org/faq/usage_faq.html#parts-of-a-figure) + so that we know what to search for to customize things. +- Matplotlib cheatsheets: +- You can also select among pre-defined themes/ + [style + sheets](https://matplotlib.org/3.1.1/gallery/style_sheets/style_sheets_reference.html) + with {obj}`~matplotlib.style.use`, for instance: + ```python + plt.style.use('ggplot') + ``` + + +## Exercises: Styling and customization + +Here are 3 exercises where we try to adapt existing scripts to either **tweak +how the plot looks** (exercises 1 and 2) or to **modify the input data** (example 3). + +This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice: +- select an example that is close to what you have in mind +- being able to adapt it to your needs +- being able to search for help +- being able to understand help request answers (not easy) + +````{challenge} Exercise Customization-1: log scale in Matplotlib (15 min) +In this exercise we will learn how to use log scales. + +- To demonstrate this we first fetch some data to plot: + ```python + import pandas as pd + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + + data_2007 = data[data["year"] == 2007] + + data_2007 + ``` +- Try the above snippet in a notebook and it will give you an overview over the data. + +- Then we can plot the data, first using a linear scale: + ```python + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + ``` + + This is the result but we realize that a linear scale is not ideal here: + ```{figure} data-visualization/customizing/gapminder-linear.png + :alt: Gapminder data plotted using a linear scale + ``` + +- Your task is to switch to a log scale and arrive at this result: + ```{figure} data-visualization/customizing/gapminder-log.png + :alt: Gapminder data plotted using log scale + ``` + +- What does ``alpha=0.5`` do? +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 5 +--- +fig, ax = plt.subplots() + +ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP (USD) per capita") +ax.set_ylabel("life expectancy (years)") +``` +* {obj}`alpha ` sets transparency + of points. +```` + +````{challenge} Exercise Customization-2: preparing a plot for publication (15 min) +Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches. + +For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small. + +Your task is to make the tickmarks and the axis label font larger, using +[Matplotlib parts of a figure](https://matplotlib.org/faq/usage_faq.html#parts-of-a-figure) +and web search, and to arrive at this: + +```{figure} data-visualization/customizing/gapminder-larger-font.png +:alt: Gapminder data plotted with larger font and larger ticks +``` +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 7-11 +--- +fig, ax = plt.subplots() + +ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP (USD) per capita", fontsize=15) +ax.set_ylabel("life expectancy (years)", fontsize=15) +ax.tick_params(which="major", length=10) +ax.tick_params(which="minor", length=5) +ax.tick_params(labelsize=15) +``` +```` + +````{challenge} Exercise Customization-3: adapting a gallery example +**This is a great exercise which is very close to real life.** + +- Your task is to select one visualization library (some need to be installed first - in + doubt choose Matplotlib or Seaborn since they are part of Anaconda installation): + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization (R users will be more at home), statistics built in + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/showcase/): + Jupyter notebook extension for 3D visualization + +- Browse the various example galleries (links above). +- Select one example that is close to your recent visualization project or simply interests you. +- First try to reproduce this example in the Jupyter notebook. +- Then try to print out the data that is used in this example just before the call of the plotting function + to learn about its structure. Is it a pandas dataframe? Is it a NumPy array? Is it a dictionary? A list? + a list of lists? +- Then try to modify the data a bit. +- If you have time, try to feed it different, simplified data. + This will be key for adapting the examples to your projects. + +Example "solution" for such an exploration below. +```` + +````{solution} An example exploration +- Let us imagine we were browsing +- And this example plot caught our eye: +- Try to run it in the notebook. +- The `d` seems to be the data. Right before the call to `sns.violinplot`, add a `print(d)`: + ```{code-block} python + --- + emphasize-lines: 12 + --- + import numpy as np + import seaborn as sns + + sns.set_theme() + + # Create a random dataset across several variables + rs = np.random.default_rng(0) + n, p = 40, 8 + d = rs.normal(0, 2, (n, p)) + d += np.log(np.arange(1, p + 1)) * -5 + 10 + + print(d) + + # Show each distribution with both violins and points + sns.violinplot(data=d, palette="light:g", inner="points", orient="h") + ``` +- The print reveals that `d` is a NumPy array and looks like a two-dimensional list: + ```text + [[10.25146044 6.27005437 5.78778386 3.27832843 0.88147169 1.76439276 2.87844934 1.49695422] + [ 8.59252953 4.00342116 3.26038963 3.15118015 -2.69725111 0.60361933 -2.22137264 -1.86174242] + ... many more lines ... + [12.45950762 4.32352988 6.56724895 3.42215312 0.34419915 0.46123886 -1.56953795 0.95292133]] + ``` +- Now let's try with a much simplified two-dimensional list: + ```{code-block} python + --- + emphasize-lines: 12, 13 + --- + # import numpy as np + import seaborn as sns + + sns.set_theme() + + # # Create a random dataset across several variables + # rs = np.random.default_rng(0) + # n, p = 40, 8 + # d = rs.normal(0, 2, (n, p)) + # d += np.log(np.arange(1, p + 1)) * -5 + 10 + + d = [[1.0, 2.0, 2.0, 3.0, 3.0, 3.0], + [1.0, 1.0, 1.0, 2.0, 2.0, 3.0]] + + # Show each distribution with both violins and points + sns.violinplot(data=d, palette="light:g", inner="points", orient="h") + ``` +- Seems to work! And finally we arrive at a working example with our own data with all + the "clutter" removed: + ```python + import seaborn as sns + + # l1 and l2 are note great names but they will do for a quick test + l1 = [1.0, 2.0, 2.0, 3.0, 3.0, 3.0] + l2 = [1.0, 1.0, 1.0, 2.0, 2.0, 3.0] + + sns.violinplot(data=[l1, l2], palette="light:g", inner="points", orient="h") + ``` +- And now we can focus the rest of our work to read our real data. +- Finally we can customize the plot, e.g. web search for "seaborn violin plot axis labels" + and add `ax.set_yticklabels(['dataset 1', 'dataset 2'])`. +```` + +--- + +```{discussion} +After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on. +``` + +--- + +```{keypoints} +- Avoid manual post-processing, script everything. +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Figures for presentation slides and figures for manuscripts have + different requirements. +- Think about color-vision deficiencies when choosing colors. Use + existing solutions for this problem. +``` diff --git a/branch/opengraph/_sources/dependencies.rst.txt b/branch/opengraph/_sources/dependencies.rst.txt new file mode 100644 index 00000000..aad56876 --- /dev/null +++ b/branch/opengraph/_sources/dependencies.rst.txt @@ -0,0 +1,385 @@ +.. _dependency_management: + +Dependency management +===================== + +.. questions:: + + - Do you expect your code to work in one year? Five? What if it + uses ``numpy`` or ``tensorflow`` or ``random-github-package`` ? + - How can my collaborators get the same results as me? What about + future me? + - How can my collaborators easily install my codes with all the necessary dependencies? + - How can I make it easy for my colleagues to reproduce my results? + - How can I work on two (or more) projects with different and conflicting dependencies? + +.. objectives:: + + - Learn how to record dependencies + - Be able to communicate the dependencies as part of a report/thesis/publication + - Learn how to use isolated environments for different projects + - Simplify the use and reuse of scripts and projects + + +How do you track dependencies of your project? +---------------------------------------------- + +* **Dependency**: Reliance on a external component. In this case, a + separately installed software package such as ``numpy``. + + + +Exercises 1 +----------- + +.. challenge:: Dependencies-1 (15 min) + + Please discuss **in breakout rooms** and answer via **collaborative document** the + following questions: + + - How do you install Python packages (libraries) that you use in your work? + From PyPI using pip? From other places using pip? Using conda? + - How do you track/record the dependencies? Do you write them into a file or README? Into + ``requirements.txt`` or ``environment.yml``? + - If you track dependencies in a file, why do you do this? + - Have you ever experienced that a project needed a different version of a Python + library than the one on your computer? If yes, how did you solve it? + + +.. _pypi: + +PyPI (The Python Package Index) and (Ana)conda +---------------------------------------------- + +- PyPI (The Python Package Index) and Conda are popular packaging/dependency + management tools. + +- When you run ``pip install`` you typically install from `PyPI + `__ but one can also ``pip install`` from a GitHub + repository and similar. + +- When you run ``conda install`` you typically install from `Anaconda Cloud + `__ but there are many community-driven conda channels + and you can create your own. + + +Why are there two ecosystems? + +- PyPI is traditionally for Python-only packages but it is no problem to also + distribute packages written in other languages as long as they provide a + Python interface. + +- Conda is more general and while it contains many Python packages and packages + with a Python interface, it is often used to also distribute packages which + do not contain any Python (e.g. C or C++ packages). + +- Many libraries and tools are distributed in both ecosystems. + + +In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages. + + +Creating isolated environments +------------------------------ + +Isolated environments solve a couple of problems: + +- You can install specific, also older, versions into them. + +- You can create one for each project and no problem if the two projects + require different versions. + +- If you make some mistake and install something you did not want or need, you + can remove the environment and create a new one. + + + +Exercises 2 +----------- + +.. challenge:: Dependencies-2 (15 min) + + .. highlight:: console + + Chloe just joined your team and will be working on her Master Thesis. She is + quite familiar with Python, still finishing some Python assignments (due in a + few weeks) and you give her a Python code for analyzing and plotting your + favorite data. The thing is that your Python code has been developed by + another Master Student (from last year) and requires a pretty old version of + Numpy (1.13.1) and Matplotlib (2.2.2) (otherwise the code fails). The code + could probably work with a recent version of Python but has been validated with + Python 3.6 only. Having no idea what the code does, she decides that the best + approach is to **create an isolated environment** with the same dependencies used + previously. This will give her a baseline for future upgrade and + developments. + + For this first exercise, we will be using conda for creating an isolated environment. + + 1. Create a conda environment:: + + $ conda create --name python36-env python=3.6 numpy=1.13.1 matplotlib=2.2.2 + + Conda environments can also be managed (create, update, delete) from the + **anaconda-navigator**. Check out the corresponding documentation `here + `_. + + 2. Activate the environment:: + + $ conda activate python36-env + + .. callout:: conda activate versus source activate + + If you do not have a recent version of Anaconda or anaconda has not been + setup properly, you may encounter an error. With older version of anaconda, + you can try:: + + $ source activate python36-env + + 3. Open a Python console and check that you have effectively the right version for each package:: + + import numpy + import matplotlib + + print('Numpy version: ', numpy.__version__) + print('Matplotlib version: ', matplotlib.__version__) + + Or use the one-liner if you have access to a terminal like bash + + python -c "import numpy; print(numpy.__version__)" + python -c "import matplotlib;print(matplotlib.__version__)" + + 4. Deactivate the environment:: + + $ conda deactivate + + 5. Check Numpy and Matplotlib versions in the default environment to make + sure they are different from **python36-env**. + + There is no need to specify the conda environment when using deactivate. It + deactivates the current environment. + + .. callout:: Remark + + - Sometimes the package version you would need does not seem to be + available. You may have to select another `conda channel + `_ + for instance `conda-forge `_. Channels can then + be indicated when installing a package:: + + $ conda install -c conda-forge matplotlib=2.2.0 + + - We will see below that rather than specifying the list of dependencies as + argument of ``conda create``, it is recommended to record dependencies in + a file. + + + +Exercises 3 +----------- + +.. challenge:: Dependencies-3 (15 min, optional) + + This is the same exercise as before but we use virtualenv rather than conda. + + + 1. Create a venv:: + + $ python -m venv scicomp + + Here ``scicomp`` is the name of the virtual environment. It creates a new + folder called ``scicomp``. + + 2. Activate it. To activate your newly created virtual environment locate the + script called ``activate`` and execute it. + + - **Linux/Mac-OSX**: look at ``bin`` folder in the ``scicomp`` folder:: + + $ source scicomp/bin/activate + + - **Windows**: most likely you can find it in the ``Scripts`` folder. + + 3. Install Numpy 1.13.1 and Matplotlib 2.2.2 into the virtual environment:: + + $ pip install numpy==1.13.1 + $ pip install matplotlib==2.2.2 + + 4. Deactivate it:: + + $ deactivate + + +Recording dependencies +---------------------- + +There are two standard ways to record dependencies for Python projects.: + +Using a ``requirements.txt`` (used by virtual environment) file which +looks like this:: + + numpy + matplotlib + pandas + scipy + +Or using an ``environments.yml`` (for conda) file which looks like this: + +.. code-block:: yaml + + name: my-environment + + dependencies: + - numpy + - matplotlib + - pandas + - scipy + +But all of these dependencies evolve so before publishing our work +it can be very useful for future generations and for the future you +to **pin dependencies** to versions. + +Here are the two files again, but this time with versions pinned: + +``requirements.txt`` with versions:: + + numpy==1.19.2 + matplotlib==3.3.2 + pandas==1.1.2 + scipy==1.5.2 + +``environments.yml`` with versions: + +.. code-block:: yaml + + name: my-environment + + dependencies: + - python=3.6 + - numpy=1.19.2 + - matplotlib=3.3.2 + - pandas=1.1.2 + - scipy=1.5.2 + +- Conda can also read and write ``requirements.txt``. +- ``requirements.txt`` can also refer to packages on Github. +- ``environments.yml`` can also contain a ``pip`` section. +- See also: https://coderefinery.github.io/reproducible-research/03-dependencies/#dependencies. + + + +Dependencies 4 +-------------- + +.. challenge:: Dependencies-4 (15 min) + + - Create the file ``environment.yml`` or ``requirements.txt`` + + - Create an environment based on these dependencies: + - Conda: ``$ conda create --name myenvironment --file requirements.txt`` + - Virtual environment: First create and activate, then ``$ pip install -r requirements.txt`` + + - Freeze the environment: + - Conda: ``$ conda list --export > requirements.txt`` or ``$ conda env export > environment.yml`` + - Virtual environment: ``$ pip freeze > requirements.txt`` + + - Have a look at the generated ("frozen") file. + + +Tip: instead of installing packages with ``$ pip install somepackage``, what I do is +to add ``somepackage`` to ``requirements.txt`` or ``environment.yml`` and install +from the file, then you have a trace of all installed dependencies. + + +How to communicate the dependencies as part of a report/thesis/publication +-------------------------------------------------------------------------- + +Each notebook or script or project which depends on libraries should come with +either a ``requirements.txt`` or a ``environment.yml``, unless you are creating +and distributing this project as Python package (see next section). + +- Attach a ``requirements.txt`` or a ``environment.yml`` to your thesis. +- Even better: put ``requirements.txt`` or a ``environment.yml`` in your Git repository along your code. +- Even better: also binderize your analysis pipeline (more about that in a later session). + + +.. _version_pinning: + +Version pinning for package creators +------------------------------------ + +We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in ``setup.py`` or ``pyproject.toml`` +(PyPI) or ``meta.yaml`` (conda). + +These dependencies will then be used by either other libraries (who in turn +write their own ``setup.py`` or ``pyproject.toml`` or ``meta.yaml``) or by +people directly (filling out ``requirements.txt`` or a ``environment.yml``). + +Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from ``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy==1.19.2', + 'matplotlib==3.3.2' + 'pandas==1.1.2' + 'scipy==1.5.2' + ] + # ... + +or you can define a range or keep them undefined like here (example taken from +``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy', + 'matplotlib' + 'pandas' + 'scipy' + ] + # ... + +Should we pin the versions here or not? + +- Pinning versions here would be good for reproducibility. + +- However pinning versions may make it difficult for this library to be used in a project alongside other + libraries with conflicting version dependencies. + +- Therefore **as library creator make the version requirements as wide as possible**. + + - Set minimum version when you know of a reason: ``>=2.1`` + + - Sometimes set maximum version to next major version (``<4``) (when + you currently use ``3.x.y``) when you expect issues with next + major version. + +- As the "end consumer" of libraries, define your dependencies as narrowly as possible. + + +See also +-------- + +Other tools for dependency management: + +- `Poetry `__: dependency management and packaging +- `Pipenv `__: dependency management, alternative to Poetry +- `pyenv `__: if you need different Python versions for different projects +- `micropipenv `__: lightweight tool to "rule them all" + +Other resources: + +- https://scicomp.aalto.fi/scicomp/packaging-software/ + + +.. keypoints:: + + - Install dependencies by first recording them in ``requirements.txt`` or + ``environment.yml`` and install using these files, then you have a trace. + - Use isolated environments and avoid installing packages system-wide. diff --git a/branch/opengraph/_sources/exercises.md.txt b/branch/opengraph/_sources/exercises.md.txt new file mode 100644 index 00000000..61028b90 --- /dev/null +++ b/branch/opengraph/_sources/exercises.md.txt @@ -0,0 +1,12 @@ +# List of exercises + +## Full list + +This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests. + +```{exerciselist} +``` diff --git a/branch/opengraph/_sources/guide.rst.txt b/branch/opengraph/_sources/guide.rst.txt new file mode 100644 index 00000000..3dc6f602 --- /dev/null +++ b/branch/opengraph/_sources/guide.rst.txt @@ -0,0 +1,125 @@ +Instructor's guide +================== + +Learner personas +---------------- + +A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don't know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren't sure if they +are going in the right direction. + +A2 can use numpy and pandas, but have learned little bits here and +there and hasn't had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages) + +B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves. + + +Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren't familiar. + +Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter + + + +About each section +------------------ + +In general, "Python for Scientific Computing could be a multi-year +course. We can't even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path. + +* **Python intro:** We can't really replace a Python tutorial, but + here we try to outline some of the main points. We don't go over + this in the course. + +* **Jupyter:** Jupyter is somewhat useful, but the main reason we go + over it is that it provides a convenient user interface for the + other programming lessons (it's easier to spend a bit of time with + Jupyter than expect people to be able to use some + editor/IDE/shell/etc). So, we do start from the beginning, so that + people can do the other lessons, but also try to teach some advanced + tips and tricks. + +* **Numpy:** The basic of much of the rest of scipy, so we need to + cover it. We try to get the main principles out, but if someone + already knows it this can be a bit boring. We try to make sure + everyone comes out with an appreciation for vectorization and + broadcasting. + +* **Pandas:** A lot of similar goals to the Numpy section, especially + the concepts behind Dataframes that one needs to know in order to + read other documentation. + +* **Visualization:** Matplotlib is getting a bit old, but is still the + backbone of other plotting packages. We try to get forth the ideas + of the matplotlib API that can be seen in other packages and the + importance of scripted plots. + +* **Data formats:** Input/output/storage is a common task, and can + easily either be a bottleneck or a huge mess. This lessons tries to + show some best practices with data formats and, as usual, get the + idea to not "do it yourself". Pandas is used as a common framework, + but we should point out there are plenty of other options. + +* **Scripts:** The most important lesson here is to break out of + Jupyter/run buttons of editors. If you can't make actual programs + with an actual interface, you can't scale up. + + * This is the first lesson to introduce the command line. We + recommend being as simple as possible: at least demonstrate the + JupyterLab terminal and discuss the bigger picture behind what it + means and why. + + * This is also the first lesson to use non-Jupyter code editor. We + recommend again being simple: use the JupyterLab code editor to + start off, and carefully explain what is going on. + +* **Scipy:** We don't cover much here (this is super short), but the + point is scipy exists and the concept of wrapping existing C/fortran + libraries and so on. + +* **Library ecosystem:** This was an overview of the types of packages + available in the "scipy ecosystem", which is a large and ill-defined + thing. But there is another point: choosing what to use. Do you + trust a half-done thing published on someone's personal webpage? If + it's on Github? How do you make your code more reusable? When + coming from academic courses, you get a "build it yourself" idea, + which isn't sustainable in research. + +* **Parallel programming:** + +* **Dependencies:** The main point here is environments, another thing + you often don't learn in courses. + + * There is a lot of material here. Consider what you will demo, + what will be done as exercises, and what is advanced/optional. + However, it is the fourth-day lesson that is most interactive, so + it is OK if it take a while to go through everything. + + * If someone else installs Anaconda for a user (e.g. admin-managed + laptop), the conda environment creations (with ``--name``, + possibly with ``--prefix`` too?) may not work. Be prepared for + this and mention it. You don't need to solve the problem but + acknowledge that the lesson becomes a demo. The virtualenv part + should hopefully work for them. + +* **Binder:** Binder exists and can help make code + reproducible/reusable by others. + +* **Packaging:** How to make your code reusable by others. By the + time we get here, people are tired and the topics get involved. We + more explicitly say "you might want to watch and take this as a + demo". + diff --git a/branch/opengraph/_sources/index.rst.txt b/branch/opengraph/_sources/index.rst.txt new file mode 100644 index 00000000..8934c7f0 --- /dev/null +++ b/branch/opengraph/_sources/index.rst.txt @@ -0,0 +1,210 @@ +=============================== +Python for Scientific Computing +=============================== + +.. admonition:: Attending the course 22-25.november.2022? + + `See the course page here + `__. + Whether you are or aren't, the course material is below. + +Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing the main Python package for numerical +computing, NumPy, and discusses then SciPy toolbox for various +scientific computing tasks as well as visualization with the +Matplotlib package. In addition, it talks about *how* python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python. + +This course (like any course) can't teach you Python... it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to. + +.. _prerequisites: + +.. prereq:: + + - Knowing basic Python syntax. We assume that you can do some + Python programming, but not much more that that. We don't cover + standard Python programming. `Here a short course on basic Python + syntax, with further references `__. + - Watch or read the `command line crash course + `__, if you aren't + familiar. + - You should be able to use a text editor to edit files some. + - The :doc:`software installation ` described below + (basically, anaconda). + + These are not prerequisites: + + - Any external libraries, e.g. numpy + - Knowing how to make scripts or use Jupyter + + +.. admonition:: Videos + + Videos from the 2021 instance of this course can be found in + `this YouTube playlist `__. + + +.. csv-table:: + :widths: auto + :delim: ; + + (prereq) ; :doc:`python` + 30 min ; :doc:`jupyter` + 60 min ; :doc:`numpy` or :doc:`numpy-advanced` + 60 min ; :doc:`pandas` + 60 min ; :doc:`data-visualization` + 30 min ; :doc:`data-formats` + 60 min ; :doc:`scripts` + 15 min ; :doc:`scipy` + 30 min ; :doc:`libraries` + 45 min ; :doc:`parallel` + 30 min ; :doc:`dependencies` + 30 min ; :doc:`binder` + 60 min ; :doc:`packaging` + + +.. toctree:: + :maxdepth: 1 + :caption: The lesson + :hidden: + + python + jupyter + numpy + numpy-advanced + pandas + data-visualization + data-formats + scripts + scipy + libraries + parallel + dependencies + binder + packaging + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + installation + quick-reference + exercises + guide + + +.. _learner-personas: + +Who is the course for? +====================== + +The course is targeted towards these learner personas: + +* A is a early career PhD researcher who has been using Python a bit, + but is not sure what they know or don't know. They want to be able + to do their research more efficiently and make sure that they are + using the right tools. A may know that numpy exists, etc. and could + theoretically read some about it themselves, but aren't sure if they + are going in the right direction. + +* A2 can use numpy and pandas, but have learned little bits here and + there and hasn't had a comprehensive introduction. They want to + ensure they are using best practices. (Baseline of high-level + packages) + +* B is a mid-to-late undergraduate student who has used Python in some + classes. They have possibly learned the syntax and enough to use it + in courses, but in a course-like manner where they are expected to + create everything themselves. + + +Motivation +========== + +Why Python +---------- + +Python has become popular, largely due to good reasons. It's very easy +to get started, there's lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities. + + +Why not Python for Scientific Computing +--------------------------------------- + +While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools. + +- Implementing performance-critical kernels. Python is a **very** + slow language, which often doesn't matter if you can offload the + heavy lifting to fast compiled code, e.g. by using Numpy array + operations. But if what you're trying to do isn't *vectorizable* + then you're out of luck. An alternative to Python, albeit much less + mature and with a smaller ecosystem, but which provides very fast + generated code, is *Julia*. + +- Creating libraries that can be called from other languages. In this + case you'll often want to create a library with a C interface, which + can then be called from most languages. Suitable languages for this + sort of task, depending on what you are doing, could be Rust, C, + C++, or Fortran. + +- You really like static typing, or functional programming + approaches. *Haskell* might be what you're looking for. + + +Python 2 vs Python 3 +-------------------- + +Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard. + +At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2. + + + +Credits +======= + +This course was originally designed by Janne Blomqvist. + +In 2020 it was completely redesigned by a team of the following: + +* Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, ... +* Editor: +* Testers and advisors: Enrico Glerean + +We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html + + +See also +======== + +* `High Performance Data Analytics in Python + ` is a logical follow-up to + this lesson that goes more in-depth to tools of high-performance + and large-scale Python. diff --git a/branch/opengraph/_sources/installation.rst.txt b/branch/opengraph/_sources/installation.rst.txt new file mode 100644 index 00000000..2a14305a --- /dev/null +++ b/branch/opengraph/_sources/installation.rst.txt @@ -0,0 +1,232 @@ +Software installation +===================== + +This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or some other way access to it. For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line for some lessons). + +**If you need installation help, show this page to someone around you +and they can probably do all you need** + + +Generic list of tools required +------------------------------ + +Note: The actual installation instructions are below. This is a +generic description which will help those who already understand all +of the tools. + +* **Python 3** (Anaconda is recommended, it will include everything) + + * With some extra packages installed. They are all included in + Aanconda, and are listed in the ``environment.yml`` file you can + find under miniconda below. +* Text editor (several lessons, can also be done through Jupyterlab) +* Command-line shell (several lessons, can also be done through Jupyterlab) +* git (not needed, this lesson is usually done as a demo) + +.. admonition:: Generic instructions with miniconda and an environment file (advanced) + :class: dropdown + + This is the advanced, minimal method of installing the Python + packages. For most people, we recommend Anaconda (below). You + will actually learn about miniconda during the workshop. This + doesn't provide the graphical Anaconda navigator, so you'll need to + activate the miniconda environment using the command line. + + You can read how to install miniconda from the `CodeRefinery + installation instructions + `__. + + Then `this environment file + `__ + contains all packages needed, and can be installed with: + + .. code:: console + + $ conda env create -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + Each time you start a new shell, you need to activate miniconda (if + you don't do run ``conda init``), and then you need to activate the + proper environment with ``conda activate python-for-scicomp``. + + We might have missed some packages, though, which can be later + installed with ``conda install``. + + + +Python +------ + +We expect you to have a working Python installation with some common +libraries. We recommend that you install the `Anaconda python +distribution `__. The +`Anaconda Navigator `__ +provides a convenient way to access the software. + +.. admonition:: Other options + :class: toggle + + We recommend Anaconda, Anaconda Navigator, and JupyterLab in these + instructions because it is simple and can be used by everyone. As + you advance in your career, we + recommend that you explore other options as well, but + that can come later. + + Any other Python distribution which you can install libraries into + would work, but because there are so many different ways to do this, + we don't support them. You would need the extra libraries mentioned + in the Miniconda instructions above. + + +JupyterLab +~~~~~~~~~~ + +We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). If you install the full +Anaconda distribution, this will be available and can be started +either through Anaconda Navigator or command line. + + + +Verification of Python and JupyterLab +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. admonition:: Watch the video + + See this `verification in video form + `__ - if you can do this, you are + ready to go for day one. Your exact steps may be a bit different. + +**You should be able to start JupyterLab.** You can do this from the +`Anaconda Navigator `__ (recommended if you have it): + +.. figure:: img/installation/anaconda-navigator-jupyterlab.png + :class: with-border + + Starting JupyterLab from the Anaconda Navigator. + +... or you can start JupyterLab from the command line: + +.. code-block:: console + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + +**Verify that you can start a Jupyter notebook.** We will learn how to +do this in day 1, but you can try running ``print("Hello, world!")`` +if you want. + +.. figure:: img/installation/jupyterlab-notebook.png + :class: with-border + + Starting a Jupyter Notebook from JupyterLab. + + +Text editor +----------- + +For one portion of the course, you will need a text editor. **If you +don't know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.** + +.. admonition:: Other editors + :class: toggle + + Because we need to be simple in our teaching, we only teach the + most basic editors. We encourage you to try out more advanced ones + yourself. + + For other editors, see the `CodeRefinery instructions + `__. You don't + exactly need a terminal editor - the graphical ones, such as VSCode or + whatever you use now, will work as well. + + + +Command line +------------ + +**You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed.** If you want to +test in advance: + +* You can start it from JupyterLab (recommended): + + .. figure:: img/installation/jupyterlab-terminal.png + :class: with-border + :scale: 75% + + From the JupyterLab launcher, select "Terminal". + +.. admonition:: Other ways to access the command line + :class: toggle + + * From the Anaconda Navigator: + + .. figure:: img/installation/anaconda-prompt.png + :class: with-border + + From the Anaconda Navigator, you can select "environments" on the + left, then click on one, then the arrow, then "Open terminal". + + * From your operating system's terminal applications, if you activate + Anaconda. + + + +Verification of the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify command line usage, type the following commands (without the +``$``), and you should see the corresponding output that lists the +Python version: + +.. code-block:: console + + $ python -V + Python 3.8.3 + + ## Or python3... + $ python3 -V + Python 3.8.3 + +Any version of Python 3 through a recent Anaconda should work for the +course. + + + +Zoom +---- + +If this is an online workshop, it might use Zoom. You can see +`CodeRefinery instructions for it +`__. + + + +Need help? +---------- + +If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up! + + + +See also +-------- + +* `Research Software Hour on conda + `__ +* `Conda manual `__ (technical) +* `Anaconda individual edition home + `__ +* `Anaconda getting started + `__ diff --git a/branch/opengraph/_sources/jupyter.ipynb.txt b/branch/opengraph/_sources/jupyter.ipynb.txt new file mode 100644 index 00000000..1e08a42d --- /dev/null +++ b/branch/opengraph/_sources/jupyter.ipynb.txt @@ -0,0 +1,408 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter\n", + "\n", + "\n", + "```{questions}\n", + "\n", + " - What is the purpose of a \"Computational narrative\"?\n", + " - What role does Jupyter play in development?\n", + " - When is Jupyter not a good tool?\n", + "```\n", + "\n", + "```{objectives}\n", + "\n", + " This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.\n", + "\n", + " - Be able to use Jupyter to run examples for the rest of the course.\n", + " - Be able to run Jupyter in a directory do your own work.\n", + " - You won't be a Jupyter expert after this, but should be able to do the rest of the course.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is Jupyter?\n", + "\n", + "Jupyter is a web-based interactive computing system. It is most well known for having the *notebook file format* and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a *computational narrative*.\n", + "\n", + "Jupyter is good for data exploration and interactive work, and making \n", + "\n", + "**We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.**\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting started with Jupyter\n", + "\n", + "* Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run `jupyter-lab`. You can also start in from Anaconda Navigator.\n", + "\n", + "For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here, we see a tour of the JupyterLab interface:\n", + "\n", + "![Main UI tour](img/jupyter/main-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 1\n", + "```{challenge} Exercises: Jupyter-1\n", + "\n", + " 1. Start Jupyter in the directory you want to use for this course.\n", + " - If you are starting from the navigator, change to the directory you want to use.\n", + " - If you are starting from the command line, you should navigate to the directory you want to use first.\n", + "\n", + " 2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.\n", + "\n", + " 4. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.\n", + "\n", + " 5. (optional, advanced) Look at the notebook file in a text\n", + " editor. How does it work?\n", + "\n", + "If everything works for you, this will end very quickly. You can begin reading the next sections independently.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Running code in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A notebook is divided into **cells**. Each cell has some **input**, and when it is executed an **output** appears right below it.\n", + "\n", + "There are different types of cells: primarily **code** cells and **markdown** cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/). For example the previous sentence is:\n", + "\n", + "```none\n", + "Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/).\n", + "```\n", + "\n", + "![notebook UI](img/jupyter/notebook-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When using keyboard shortcuts, you can switch between edit mode and command mode with `Enter` and `Esc`. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:\n", + "* `Ctrl-Enter`: Run cell\n", + "* `Shift-Enter`: Run cell and select cell below\n", + "* `Alt-Enter`: Run cell and insert new cell below\n", + "* `a` / `b`: insert new cell above/below\n", + "* `m` / `y`: markdown cell / code cell\n", + "* `x`: cut cell\n", + "* `c`: copy cell\n", + "* `v`: paste cell\n", + "* `d, d`: delete cell" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, let's look at some code samples:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0\n", + "1\n", + "2\n" + ] + } + ], + "source": [ + "for i in range(3):\n", + " print(i)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "10\n" + ] + } + ], + "source": [ + "print(sum(range(5)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By convention, if the last thing in a cell is an object, that object gets printed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "45" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sum(range(5))\n", + "sum(range(10))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to raw cells, there are **magics**, which exist outside of Python. They are a property of the runtime itself (in Python's case, they come from **IPython**. For example, the following cell magic `%%bash` turns the cell into a shell script (may not work on all operating systems):" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1\n", + "2\n", + "3\n" + ] + } + ], + "source": [ + "%%bash\n", + "for x in $(seq 3) ; do\n", + " echo $x\n", + "done" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "* A **cell magic** starts with `%%`, goes on the first line of a cell, and applies to the whole cell\n", + "* A **line magic** starts with `%`, goes on any line, and applies to that line." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "```{challenge} Exercises: Jupyter-2\n", + "\n", + " 1. Run some trivial code, such as ``print(1)``.\n", + "\n", + " 2. Run some slightly less trivial code, like print out the first\n", + " ten [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number).\n", + "\n", + " 3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the [reference](https://commonmark.org/help/) to add a heading, bullet list, and some (bold, italic, or inline code)\n", + "\n", + " 4. Use the ``%%timeit`` magic function to time your Fibonacci\n", + " function.\n", + "\n", + " 5. Again using ``%%timeit``, figure out the fastest way to sum the\n", + " numbers 0 to 1000000.\n", + " \n", + " 6. Once you are done, close your notebooks and other tabs you don't need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.\n", + "```\n", + "\n", + "`````{solution} Solutions: Jupyter-2\n", + "\n", + "1. --\n", + "\n", + "2. Simple fibonacci code\n", + "\n", + " ```python\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " print(a)\n", + " a, b = b, a+b\n", + " ```\n", + "\n", + "3. Markdown description\n", + "\n", + " ```md\n", + " # Fibonacci\n", + " * Start with two variables `a` and `b`\n", + " * Repeat 10 times\n", + " * Print old `a`, then increment both\n", + " * Makes use of the Python *tuple assignment*: `a, b = new_a, new_b`\n", + " ```\n", + "\n", + "4. In this case, the print() statements get out of hand, so we comment that out. In general, writing output usually takes a lot of time reletive to the computation, so we don't want to time that (unless output is the main point of the code, then we do have to time it!\n", + "\n", + " ```ipython\n", + " %%timeit\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " #print(a)\n", + " a, b = b, a+b\n", + " ```\n", + " ```none\n", + " 395 ns ± 10.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n", + " ```\n", + "\n", + "5. --\n", + "\n", + "6. --\n", + "\n", + "`````" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why Jupyter?\n", + "\n", + "- Being able to **edit, check, re-edit** quickly is great for **prototyping and testing new ideas**\n", + " - Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.\n", + "- You can make a **complete story** - in one place. No more having code, figures, and description in different places.\n", + " - Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.\n", + "- Notebook as an interactive publication itself - for example the discovery of gravitational waves data is [released as a notebook](https://www.gw-openscience.org/tutorials/).\n", + "- Jupyter Notebooks display on Github - low-barrier way to share your analysis.\n", + "- Teaching - great for getting difficult software distribution out of the way." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why not Jupyter?\n", + "\n", + "Jupyter is great for many things, but there are some problems if not used well:\n", + "\n", + "- They **don't promote modularity**, and once you get started in a\n", + " notebook it can be hard to migrate to modules.\n", + "- They are **difficult to test**. There are things to run notebooks as\n", + " unit tests like [nbval](https://nbval.readthedocs.io/), but it's not\n", + " perfect.\n", + "- Notebooks can be **version controlled**\n", + " ([nbdime](https://nbdime.readthedocs.io/) helps with that), but\n", + " there are **still limitations**.\n", + "- You can **change code after you run it** and run code out of order.\n", + " This can make debugging hard and results irreproducible if you\n", + " aren't careful.\n", + "- Notebooks **aren't named by default** and tend to **acquire a bunch of\n", + " unrelated stuff**. Be careful with organization!\n", + "- Once lots of code is in notebooks, it can be **hard to change to\n", + " proper programs that can be scripted**.\n", + "\n", + "You can read more about these downsides .\n", + "\n", + "**But these downsides aren't specific to Jupyter!** They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "```{challenge} Exercises: Jupyter-3\n", + "\n", + " (optional) Discuss the following in groups:\n", + "\n", + " 1. Have any of you used Jupyter in a way that became impossible to\n", + " maintain: too many files, code all spread out, not able to find\n", + " your code and run it in the right order. How did you solve that?\n", + "\n", + " 2. On the other hand, what are your successes with Jupyter?\n", + " \n", + " 3. How can you prevent these problems by better development strategies?\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## See also\n", + "\n", + "- The [CodeRefinery Jupyter lesson](https://coderefinery.github.io/jupyter/) has much more, and the source of some of the content above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{keypoints}\n", + "\n", + " - Jupyter is powerful and can be used for interactive work\n", + " - ... but not the end solution when you need to scale up.\n", + "```" + ] + } + ], + "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.10.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/opengraph/_sources/libraries.rst.txt b/branch/opengraph/_sources/libraries.rst.txt new file mode 100644 index 00000000..724ef81d --- /dev/null +++ b/branch/opengraph/_sources/libraries.rst.txt @@ -0,0 +1,353 @@ +Library ecosystem +================= + +.. questions:: + + - What happens when you need some method Beyond what we discuss in this course, what is available? + - How do you decide what to build on for your work? + +.. objectives:: + + - Know of some other available packages, but don't necessarily know + how to use them. + - Be able to evaluate what you should reuse and what you should + develop yourself. + +You can't do everything yourself. In fact, once we heard a quote such +as this: + + When you are a student, you are expected to do everything + yourself, and that is how you are evaluated. When you become a + researcher, you *have* to be able to reuse what others have done. + We don't have much practice in doing this. + -- A student + +In this lesson, we'll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types: + +- Well-maintained libraries that are used by many others. +- A wide variety of public code that might work but isn't necessarily + well-maintained (for example, code from articles). + +We'll start with the first then go to the second. + + + +Glossary +-------- + +Library + A collection of code used by a program. + +Package + A library that has been made easily installable and reusable. + Often published on public repositories such as the `Python Package + Index `__ + +Dependency + A requirement of another program, not included in that program. + + + +The Python/SciPy ecosystem +-------------------------- + +This section is nothing more than a tour of what exists in Python. +You aren't expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work. + +The "core" packages `could be considered +`__. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy): + +* Python +* Numpy - arrays, everything builds on this +* Scipy - scientific functions (not necessarily a lot builds on this) +* matplotlib - plotting, many other plotting tools build on this +* pandas - data structures +* IPython / Jupyter: interactive work + + + +Core numerics libraries +~~~~~~~~~~~~~~~~~~~~~~~ + +* `numpy `__ - arrays and array math. +* `scipy `__ - software + for math, science, and engineering. + + + +Plotting +~~~~~~~~ + +* `matplotlib `__ - base plotting package, + somewhat low level but almost everything builds on it. +* `seaborn `__ - higher level plotting + interface; statistical graphics. +* `mayavi `__ - 3D plotting +* `PIL `__ - image manipulation. The + original PIL is no longer maintained, the new "Pillow" is a drop-in + replacement. + + + +Data analysis and other important core packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `pandas `__ - columnar + data analysis +* `statsmodels `__ - just what it says +* `SymPy `__ - symbolic math +* `networkx `__ - graph and network analysis +* `h5py `__ and `PyTables `__ - interfaces to + the `HDF5 `__ on-disk file format +* `dateutil `__ and `pytz + `__ - date arithmetic and handling, + timezone database and conversion + + + +Interactive computing and human interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Interactive computing + + * `IPython `__ - nicer interactive interpreter + * `Jupyter `__ (notebook, lab, hub, ...) - + web-based interface to IPython and other languages + +* Testing + + * `pytest `__ - automated testing interface + +* Documentation + + * `Sphinx `__ - documentation generator + (also used for this lesson...) + +* Development environments + + * `Spyder `__ - interactive Python + development environment. + +* `Binder `__ - load any git repository in + Jupyter automatically, good for reproducible research + + + +Speeding up code and parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `PyMPI `__ - Message + Passing Interface (MPI) in Python for parallelizing jobs. +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `numba `__ - just in time compiling of + functions for speed-up +* `PyPy `__ - Python written in Python so that + it can internally optimize more. +* `Dask `__ - distributed array data structure for + distributed computation +* `Joblib `__ - easy embarrassingly + parallel computing +* `IPyParallel `__ - easy + parallel task engine +* `numexpr `__ - Fast evaluation of + array expressions by automatically compiling the arithmetic. + + + +Machine learning +~~~~~~~~~~~~~~~~ + +If you need some machine learning, you probably already know what you +need and this list is short and irrelevant. + +- `tensorflow `__ +- `pytorch `__ +- `nltk `__ - natural language processing +- `scikit-learn `__ - simple tools for + predictive data analysis + + + +Connecting Python to other languages +------------------------------------ + +As we discussed with Scipy, very many of the above packages aren't +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things: + +* **Extending Python** by writing your own modules in C. + + * It's actually common to first have (or write) an analysis package + in C or C++, then make the Python interface. Then it can be + supported by other languages, too. + + * Or one starts an analysis package in Python, and slowly moves bits + of it to C over time as there is need. + +* **Embedding Python**, where you have another primary application + that uses Python under the hood as an internal scripting language. + +These features aren't exactly unique to Python, but Python does +support them very well. Read more: `Extending and embedding Python +`__. + + + +Tools for interfacing with other languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These days, one rarely directly extends the Python interpreter, but uses + +* `cffi `__ and `ctypes + `__ - interface to C + and compatible libraries +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `f2py `__ - interface to Fortran + code +* `swig `__ - connect to a variety of programming languages. +* ``Boost.python`` - Another Python/C++ interface +* TODO: Julia modules for Python? + + + +Evaluating Python packages for reuse +------------------------------------ + +Above, we talked about well-maintained mainstream packages. **Do you +trust random code you find online (for example included in a paper)?** + +Especially consider scientific results, which *have* to be correct. +Still, you also *can't* build everything yourself, so you have to +carefully evaluate the situation. + +Below are some things to consider: + +* Are there releases? Have they been going on for a while? + +* Are releases installable without copy-paste? + +* Are dependencies handled well? + +* Does the code randomly change, so that it no longer works with your + code. Is this relevant? + +* Is there good documentation, that not just tells how to use it but + how it works? + +* Is there automated testing? What's your evaluation of the risk of + undetectable scientific errors? + +* Is there a community, or is it one person? Is it backed by some + organization? Does it have a permanent home? + +* Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) + where a community *could* form? + +* Do others post issues and make contributions? Are these issues + dealt with in a timely manner? Can you search past bug reports? + +* Is the software citeable? + + + +Is your work reuseable? +----------------------- + +Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a `CodeRefinery workshop `__ will make +sure you have the tools to produce high-quality, reusable code. + + + +What's next? +------------ + +* The `CodeRefinery workshop `__ mentioned + above will prepare you for others to reuse your code and for you to + contribute to other code. +* The upcoming :doc:`dependencies` lesson will teach you how to + record and manage dependencies so that anyone can seamlessly reuse + your code. + + + +Exercises +--------- + +.. exercise:: Libraries 1.1: Libraries in your work + + What libraries do you use in your work? What have you made, which + you could have reused from some other source. What have you used + from some other source that you wished you had re-created? + + Discuss in your groups or HackMD. + +.. solution:: Libraries 1.1 + + ... is there anything to say here? + + +.. exercise:: Libraries 1.2: Evaluating packages + + Below are some links to some packages, both public and made by the + authors of this lesson. Evaluate them, considering "would I use + this in my project?" + + a) https://github.com/networkx/networkx/ + b) some code on webpage in a paper's footnote + c) https://github.com/rkdarst/pcd + d) https://github.com/dftlibs/numgrid + e) https://github.com/rkdarst/dynbench + f) https://vpython.org/ + +.. solution:: Libraries 1.2 + + a) networkx: This seems to be a relatively large, active project + using best practices. Probably usable. + b) I would probably use it if I had to, but would prefer not to. + c) This (written by one of the authors of this lesson) has no + documenting, no community, no best practices, and is very old. + Probably not a good idea to try to use it + d) This project uses best practices, but doesn't seem to have a big + community. It's probably fine to use, but who knows if it will + be maintained 10 years from now. It does have automated tests + via Github Actions (``.github/workflows`` and the green checks), + so the authors have put some work into making it correct. + e) This (also written by one of the authors) looks like it was made + for a paper of some sort. It has some minimal documentation, + but still is missing many best practices and is clearly not + maintained anymore (look at the ancient pull request). Probably + not a good idea to use unless you have to. + f) This project has a pretty website, and some information. But + seems to not be using best practices of an open repository, and + custom locations which could disappear at any time. + + You notice that several of the older projects here were written by + one of the authors of this lesson. It goes to show that everyone + starts somewhere and improves over time - don't feel bad if your + work isn't perfect, as long as you keep trying to get better! + + + +See also +-------- + +* `Topical Software in the SciPy ecosystem + `__ - relatively + detailed (but not comprehensive) list of projects + + +.. keypoints:: + + - Almost everything you need can already be found, except your + incremental work. + - When do you build on that other work, and when do you create + things yourself? diff --git a/branch/opengraph/_sources/numpy-advanced.rst.txt b/branch/opengraph/_sources/numpy-advanced.rst.txt new file mode 100644 index 00000000..dad04043 --- /dev/null +++ b/branch/opengraph/_sources/numpy-advanced.rst.txt @@ -0,0 +1,392 @@ +Advanced NumPy +============== + +.. questions:: + + - How can NumPy be so fast? + - Why are some things fast and some things slow? + - How can I control whether NumPy makes a copy or operates in-place? + +.. objectives:: + + - Understand why NumPy has so many specialized functions for specific operations + - Understand the underlying machinery of the Numpy ``ndarray`` object + - Understand when and why NumPy makes a copy of the data rather than a view + + This is intended as a follow-up to the basic NumPy lesson. The indended + audience for this advanced lesson is those who have used NumPy before and + now want to learn how to get the most out of this amazing package. + + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +`Guide to NumPy `_ by +Travis E. Oliphant, its initial creator. + + + +NumPy can be really fast +------------------------ + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast. + +.. highlight:: c + +How fast can NumPy be? Let's race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:: + + #include + #include + #define N_ELEMENTS 100000000 + int main(int argc, char** argv) { + double* a = (double*) malloc(sizeof(double) * N_ELEMENTS); + int i; + for(i=0; i` before continuing with this advanced lesson. + +.. solution:: Solutions: Numpy-Advanced-2 + + The script can be implemented like this:: + + import numpy as np + print(np.random.rand(100_000_000).sum()) + + +.. highlight:: python + +The library behind the curtain: BLAS +------------------------------------ + +NumPy is fast because it outsources most of its heavy lifting to +`Basic Linear Algebra Subprograms (BLAS) `_. +BLAS for Fortran was `published in 1979 `_ +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as element-wise sum, matrix +multiplication, computing the vector length, etc. + +The API of that software library was later standardized, and today there are +many modern implementations available. These libraries represent over 40 years +of optimizing efforts and make use of +`specialized CPU instructions for manipulating arrays `_. +In other words, they are *fast*. + +One of the functions inside the BLAS library is a +`function `_ +to compute the "norm" of a vector, which is the same as computing its length, using the +`Pythagorean theorem `_: +:math:`\sqrt(a[0]^2 + a[1]^2 + \ldots)`. + +Let's race the BLAS function versus a naive "manual" version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:: + + import numpy as np + rng = np.random.default_rng(seed=0) + a = rng.random(100_000_000) + +We now implement the Pythagorean theorem using basic NumPy functionality and +use ``%%timeit`` to record how long it takes to execute:: + + %%timeit + l = np.sqrt(np.sum(a ** 2)) + print(l) + +And here is the version using the specialized BLAS function:: + + %%timeit + l = np.linalg.norm(a) + print(l) + + +NumPy tries to avoid copying data +---------------------------------- + +Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy's +:class:`numpy.ndarray` datastructure works behind the scenes. + +The ndarray exposed +~~~~~~~~~~~~~~~~~~~ +The first thing you need to know about :class:`numpy.ndarray` is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector. + +.. image:: img/numpy-advanced/01_memory_layout.svg + +NumPy is faking the second dimension behind the scenes! When we request the +element at say, ``[2, 3]``, NumPy converts this to the correct index in the +long 1D array ``[11]``. + + * Converting ``[2, 3]`` → ``[11]`` is called "raveling" + * The reverse, converting ``[11]`` → ``[2, 3]`` is called "unraveling" + +The implications of this are many, so take let's take some time to understand +it properly by writing our own ``ravel()`` function. + +Exercise 2 +---------- + +.. challenge:: Exercises: Numpy-Advanced-2 + + Write a function called ``ravel()`` that takes as input: + + - ``row`` The row of the requested element in the matrix as integer index. + - ``col`` The column of the requested element in the matrix as integer index. + - ``n_rows`` The total number of rows of the matrix. + - ``n_cols`` The total number of columns of the matrix. + + And produces as output the appropriate index in the 1D array. Use the image above as a + guide. Here are some examples of input and desired output: + + - ``ravel(2, 3, n_rows=4, n_cols=4)`` → ``11`` + - ``ravel(2, 3, n_rows=4, n_cols=8)`` → ``19`` + - ``ravel(0, 0, n_rows=1, n_cols=1)`` → ``0`` + - ``ravel(3, 3, n_rows=4, n_cols=4)`` → ``15`` + - ``ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000)`` → ``69_318_923`` + +.. solution:: Solutions: Numpy-Advanced-2 + + The function can be implemented like this:: + + def ravel(row, col, n_rows, n_cols): + return row * n_cols + col + +Strides +------- + +As seen in the exercise, to get to the next row, we have to skip over +``n_cols`` indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of "strides":: + + np.zeros((4, 8)).strides # (64, 8) + np.zeros((4, 5, 6, 7, 8)).strides # (13440, 2688, 448, 64, 8) + +The ``.strides`` attribute contains for each dimension, the number of *bytes* (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes. + + +An example: matrix transpose +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let's see how long NumPy's +transpose function takes, by transposing a huge (10 000 ✕ 20 000) matrix:: + + import numpy as np + a = rng.rand(10_000, 20_000) + print(f'Matrix `a` takes up {a.nbytes / 10**6} MB') + +Let's time the :func:`numpy.transpose` function:: + + %%timeit + b = a.transpose() + +It takes mere nanoseconds to transpose 1600 MB of data! NumPy avoided copying +any data by *only* modifying the ``.strides`` of the existing array in-place:: + + print(a.strides) # (160000, 8) + print(b.strides) # (8, 160000) + +Another example: reshaping +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modifying the shape of an array through :func:`numpy.reshape` is also +accomplished without any copying of data by modifying the ``.strides``:: + + a = rng.rand(20_000, 10_000) + print(f'{a.strides=}') # (80000, 8) + b = a.reshape(40_000, 5_000) + print(f'{b.strides=}') # (40000, 8) + c = a.reshape(20_000, 5_000, 2) + print(f'{c.strides=}') # (80000, 16, 8) + + +Exercises 3 +----------- + +.. challenge:: Exercises: Numpy-Advanced-3 + + A little known feature of NumPy is the :data:`numpy.stride_tricks` module + that allows you to modify the ``.strides`` attribute directly. Playing + around with this is very educational. + + 1. Create your own ``transpose()`` function that will transpose a 2D matrix + by reversing its ``.shape`` and ``.strides`` attributes using + :func:`numpy.lib.stride_tricks.as_strided`. + + 2. Create a (5 ✕ 100 000 000 000) array containing on the first row all + 1's, the second row all 2's, and so on. Start with an 1D array + ``a = np.array([1., 2., 3., 4., 5.])`` + and modify its ``shape`` and ``strides`` attributes using + :func:`numpy.lib.stride_tricks.as_strided` to obtain the desired 2D + matrix:: + + array([[1., 1., 1., ..., 1., 1., 1.], + [2., 2., 2., ..., 2., 2., 2.], + [3., 3., 3., ..., 3., 3., 3.], + [4., 4., 4., ..., 4., 4., 4.], + [5., 5., 5., ..., 5., 5., 5.]]) + + +.. solution:: Solutions: Numpy-Advanced-3 + + 1. The ``transpose()`` function can be implemented like this:: + + from numpy.lib.stride_tricks import as_strided + def transpose(a): + return as_strided(a, shape=a.shape[::-1], strides=a.strides[::-1]) + + # Testing the function on a small matrix + a = np.array([[1, 2, 3], + [4, 5, 6]]) + print('Before transpose:') + print(a) + print('After transpose:') + print(transpose(a)) + + 2. By setting one of the ``.strides`` to `0`, we can repeat a value + infinitely many times without using any additional memory:: + + from numpy.lib.stride_tricks import as_strided + a = np.array([1., 2., 3., 4., 5.]) + as_strided(a, shape=(5, 100_000_000_000), strides=(8, 0)) + + +A fast thing + a fast thing = a fast thing? +------------------------------------------- + +If :func:`numpy.transpose` is fast, and :func:`numpy.reshape` is fast, then +doing them both must be fast too, right?:: + + # Create a large array + a = np.random.rand(10_000, 20_000) + +Measuring the time it takes to first transpose and then reshape:: + + %%timeit -n 1 -r 1 + a.T.reshape(40_000, 5_000) + +In this case, the data actually had to be copied and it's super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the ``.strides``:: + + a = np.array([[1, 2, 3], [4, 5, 6]]) + + print('Original array:') + print(a) + + print('\nTransposed:') + print(a.T) + + print('\nTransposed and then reshaped:') + print(a.T.reshape(2, 3)) + + +Copy versus view +---------------- + +Whenever NumPy constructs a new array by modifying the ``.strides`` instead of +copying data, we way it created a "view". This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +:class:`numpy.ndarray` object will have a reference to the original array in +its ``.base`` attribute:: + + a = np.zeros((5, 5)) + print(a.base) # None + b = a[:2, :2] + print(b.base.shape) # (5, 5) + +.. warning:: + When you create a large array and select only a portion of it, the large + array will stay in memory if a view was created! + +The new array ``b`` object has a pointer to the same memory buffer as the array +it has been derived from:: + + print(a.__array_interface__['data']) + print(b.__array_interface__['data']) + +Views are created by virtue of modifying the value of the `.shape` attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:: + + b = a[1:3, 1:3] # This view does not start at the beginning + offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0] + print('Offset:' offset, 'bytes') # Offset: 48 bytes + +.. image:: img/numpy-advanced/02_views.svg + +Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:: + + b[0, 0] = 1. + print(a) # Original matrix was modified + +Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:: + + c = a[[0, 2]] # Select rows 0 and 2 + print(c.base) # None. So not a view. + + +See also +-------- + +* `Guide to Numpy `__ +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + * `Advanced NumPy: Master stride tricks with 25 illustrated exercises `__ + + + +.. keypoints:: + + - The best way to make your code more efficient is to learn more about the + NumPy API and use specialized functions whenever possible. + - NumPy will avoid copying data whenever it can. Whether it can depends on + what kind of layout the data is currently in. diff --git a/branch/opengraph/_sources/numpy.rst.txt b/branch/opengraph/_sources/numpy.rst.txt new file mode 100644 index 00000000..66fb4bef --- /dev/null +++ b/branch/opengraph/_sources/numpy.rst.txt @@ -0,0 +1,518 @@ +.. _numpy: + +NumPy +===== + +.. questions:: + + - Why using NumPy instead of pure python? + - How to use basic NumPy? + - What is vectorization? + +.. objectives:: + + - Understand the Numpy array object + - Be able to use basic NumPy functionality + - Understand enough of NumPy to seach for answers to the rest of your questions ;) + + We expect most people to be able to do all the basic exercises + here. It is probably quite easy for many people; we have advanced + exercises at the end in that case. + + + +So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible. + +.. highlight:: python + +What is an array? +----------------- + +For example, consider ``[1, 2.5, 'asdf', False, [1.5, True]]`` - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately. + +NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it. + +An array is a 'grid' of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has: + +* :ref:`dtype ` - data type. Arrays always contain one type +* :term:`shape` - shape of the data, for example ``3×2`` or ``3×2×500`` or even + ``500`` (one dimensional) or ``[]`` (zero dimensional). +* :attr:`data ` - raw data storage in memory. This can be passed to C or + Fortran code for efficient calculations. + + +To test the performance of pure Python vs NumPy we can write in our jupyter notebook: + +Create one list and one 'empty' list, to store the result in :: + + a = list(range(10000)) + b = [ 0 ] * 10000 + +In a new cell starting with ``%%timeit``, loop through the list ``a`` and fill the second list ``b`` with ``a`` squared :: + + %%timeit + for i in range(len(a)): + b[i] = a[i]**2 + +That looks and feels quite fast. But let's take a look at how NumPy performs for the same task. + +So for the NumPy example, create one array and one 'empty' array to store the result in :: + + import numpy as np + a = np.arange(10000) + b = np.zeros(10000) + +In a new cell starting with ``%%timeit``, fill ``b`` with ``a`` squared :: + + %%timeit + b = a ** 2 + +We see that compared to working with numpy arrays, working with traditional python lists is actually slow. + + +Creating arrays +--------------- + +There are different ways of creating arrays (:func:`numpy.array`, :attr:`numpy.ndarray.shape`, :attr:`numpy.ndarray.size`):: + + a = np.array([1,2,3]) # 1-dimensional array (rank 1) + b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2) + + b.shape # the shape (rows,columns) + b.size # number of elements + +In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (:func:`numpy.zeros`, :func:`numpy.ones`, :func:`numpy.full`, :func:`numpy.eye`, :func:`numpy.arange`, :func:`numpy.linspace`):: + + np.zeros((2, 3)) # 2x3 array with all elements 0 + np.ones((1,2)) # 1x2 array with all elements 1 + np.full((2,2),7) # 2x2 array with all elements 7 + np.eye(2) # 2x2 identity matrix + + np.arange(10) # Evenly spaced values in an interval + np.linspace(0,9,10) # same as above, see exercise + + c = np.ones((3,3)) + d = np.ones((3, 2), 'bool') # 3x2 boolean array + +Arrays can also be stored and read from a (.npy) file (:func:`numpy.save`, :func:`numpy.load`):: + + np.save('x.npy', a) # save the array a to a .npy file + x = np.load('x.npy') # load an array from a .npy file and store it in variable x + +In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (:attr:`numpy.ndarray.dtype`, :meth:`numpy.ndarray.astype`):: + + d.dtype # datatype of the array + d.astype('int') # change datatype from boolean to integer + +In the last example, ``.astype('int')``, it will make a **copy** of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed. + + + +Exercises 1 +----------- + +.. challenge:: Exercises: Numpy-1 + + 1. **Datatypes** Try out :func:`np.arange(10) ` and :func:`np.linspace(0,9,10) `, what is the difference? Can you adjust one to do the same as the other? + + 2. **Datatypes** Create a 3x2 array of random float numbers (check :func:`numpy.random.random`) between 0 and 1. Now change the arrays datatype to int (:meth:`array.astype `). How does the array look like? + + 3. **Reshape** Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check :meth:`array.reshape `) in any way possible. What is not possible? + + 4. **NumPyI/O** Save above array to .npy file (:func:`numpy.save`) and read it in again. + +.. solution:: Solutions: Numpy-1 + + 1. **Datatypes** + + - ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**, + - while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**. + + Both ``np.linspace`` and ``np.arange`` take dtype as an argument and can be adjusted to match each other in that way. + + 2. **Datatypes** eg ``a = np.random.random((3,2))``. ``a.astype('int')`` results in an all zero array, not as maybe expected the rounded int (all numbers [0, 1) are cast to 0). + + 3. **Reshape** eg ``b = np.random.randint(0,10,(3,2))``. + + ``b.reshape((6,1))`` and ``b.reshape((2,3))`` possible. + + It is not possible to reshape to shapes using more or less elements than ``b.size = 6``, so for example ``b.reshape((12,1))`` gives an error. + + 4. **NumPyI/O** ``np.save('x.npy', b)`` and ``x = np.load('x.npy')`` + + + +Array maths and vectorization +----------------------------- + +Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do. + +By default, basic arithmetic (``+``, ``-``, ``*``, ``/``) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is "vectorized" +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop. + +Note that unlike Matlab, where ``*`` means matrix multiplication, NumPy uses +``*`` to perform element-by-element multiplication and uses the ``@`` symbol to +perform matrix multiplication:: + + a = np.array([[1,2],[3,4]]) + b = np.array([[5,6],[7,8]]) + + # Addition + c = a + b + d = np.add(a,b) + + # Matrix multiplication + e = a @ b + f = np.dot(a, b) + +Other common mathematical operations include: ``-`` (:data:`numpy.subtract`), ``*`` (:data:`numpy.multiply`), ``/`` (:data:`numpy.divide`), ``.T`` (:func:`numpy.transpose`), :data:`numpy.sqrt`, :func:`numpy.sum`, :func:`numpy.mean`, ... + + + +Exercises 2 +----------- + +.. challenge:: Exercises: Numpy-2 + + - **Matrix multiplication** What is the difference between :data:`numpy.multiply` and :func:`numpy.dot` ? Try it. + - **Axis** What is the difference between :func:`np.sum(axis=1) ` vs + :func:`np.sum(axis=0) ` on a two-dimensional array? What if you leave out the axis parameter? + + +.. solution:: Solutions: Numpy-2 + + - **Matrix multiplication** ``np.multiply`` does elementwise multiplication on two arrays, while ``np.dot`` enables matrix multiplication. + - **Axis** ``axis=1`` does the operation (here: ``np.sum``) over each row, while axis=0 does it over each column. If axis is left out, the sum of the full array is given. + + + +Indexing and Slicing +-------------------- + +.. seealso:: + + :ref:`Numpy basic indexing docs ` + +NumPy has many ways to extract values out of arrays: + +- You can select a single element +- You can select rows or columns +- You can select ranges where a condition is true. + +Clever and efficient use of these operations is a key to NumPy's +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C. + +:: + + a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15 + a[0] # first row + a[:,0] # first column + a[1:3,1:3] # middle 2x2 array + + a[(0, 1), (1, 1)] # second element of first and second row as array + +Boolean indexing on above created array:: + + idx = (a > 0) # creates boolean matrix of same size as a + a[idx] # array with matching values of above criterion + + a[a > 0] # same as above in one line + + + +Exercises 3 +----------- + +.. challenge:: Exercise: Numpy-3 + + :: + + a = np.eye(4) + b = a[:,0] + b[0] = 5 + + - **View vs copy** Try out above code. How does ``a`` look like before ``b`` has changed and after? How could it be avoided? + +.. solution:: Solution: Numpy-3 + + - **View vs copy** The change in ``b`` has also changed the array ``a``! + This is because ``b`` is merely a view of a part of array ``a``. Both + variables point to the same memory. Hence, if one is changed, the other + one also changes. If you need to keep the original array as is, use + ``np.copy(a)``. + + +Types of operations +------------------- + +There are different types of standard operations in NumPy: + +**ufuncs**, ":ref:`universal functions `": These are element-by-element +functions with standardized arguments: + +- One, two, or three input arguments +- For example, ``a + b`` is similar to :data:`np.add(a, b) ` but the ufunc + has more control. +- ``out=`` output argument, store output in this array (rather than + make a new array) - saves copying data! +- See the `full reference + `__ + +- They also do **broadcasting** (:ref:`ref `). Can you add a 1-dimensional array of shape `(3)` + to an 2-dimensional array of shape `(3, 2)`? With broadcasting you + can! + + :: + + a = np.array([[1, 2, 3], + [4, 5, 6]]) + b = np.array([10, 10, 10]) + a + b # array([[11, 12, 13], + # [14, 15, 16]]) + + Broadcasting is smart and consistent about what it does, which I'm + not clever enough to explain quickly here: `the manual page on + broadcasting + `__. + The basic idea is that it expands dimensions of the smaller array so + that they are compatible in shape. + +**Array methods** do something to one array: + +- Some of these are the same as ufuncs:: + + x = np.arange(12) + x.shape = (3, 4) + x # array([[ 0, 1, 2, 3], + # [ 4, 5, 6, 7], + # [ 8, 9, 10, 11]]) + x.max() # 11 + x.max(axis=0) # array([ 8, 9, 10, 11]) + x.max(axis=1) # array([ 3, 7, 11]) + +**Other functions**: there are countless other functions covering +linear algebra, scientific functions, etc. + + + +Exercises 4 +----------- + +.. challenge:: Exercises: Numpy-4 + + - **In-place addition**: Create an array, add it to itself using a + ufunc. + + - **In-place addition** (advanced): Create an array of + ``dtype='float'``, and an array of ``dtype='int'``. Try to use the + int array is the output argument of the first two arrays. + + - **Output arguments and timing** Repeat the initial ``b = a ** + 2`` example using the output arguments and time it. Can you make + it even faster using the output argument? + +.. solution:: Solution: Numpy-4 + + - **in-place addition**:: + + x = np.array([1, 2, 3]) + id(x) # get the memory-ID of x + np.add(x, x, x) # Third argument is output array + np.add(x, x, x) + print(x) + id(x) # get the memory-ID of x + # - notice it is the same + + You note that ``np.add()`` has a third argument that is the + output array (same as ``out=``), *and* the function returns that + same array. + + + - **Output arguments and timing** In this case, on my computer, it was + actually slower (this is due to it being such a small array!):: + + a = np.arange(10000) + b = np.zeros(10000) + + :: + + %%timeit + numpy.square(a, out=b) + + This is a good example of why you always need to time things + before deciding what is best. + + +Linear algebra and other advanced math +-------------------------------------- + +In general, you use :class:`arrays ` (n-dimensions), not :class:`matrixes ` +(specialized 2-dimensional) in NumPy. + +Internally, NumPy doesn't invent its own math routines: it relies on +`BLAS +`__ +and `LAPACK `__ to do this kind +of math - the same as many other languages. + +- `Linear algebra in numpy + `__ + +- `Many, many other array functions + `__ + +- `Scipy `__ has even + more functions + +- Many other libraries use NumPy arrays as the standard data + structure: they take data in this format, and return it similarly. + Thus, all the other packages you may want to use are compatible + +- If you need to write your own fast code in C, NumPy arrays can be + used to pass data. This is known as `extending Python + `__. + + + + +Additional exercises +-------------------- + +.. challenge:: Numpy-5 + + If you have extra time, try these out. These are advanced and + optional, and will not be done in most courses. + + 1. Reverse a vector. Given a vector, reverse it such that the last + element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]`` + + 2. Create a 2D array with zeros on the borders and 1 inside. + + 3. Create a random array with elements [0, 1), then add 10 to all + elements in the range [0.2, 0.7). + + 4. What is :func:`np.round(0.5) `? What is ``np.round(1.5)``? Why? + + 5. In addition to ``np.round``, explore :data:`numpy.ceil`, :data:`numpy.floor`, + :data:`numpy.trunc`. In particular, take note of how they behave with + negative numbers. + + 6. Recall the identity :math:`\sin^2(x) + \cos^2(x) = 1`. Create a + random 4x4 array with values in the range [0, 10). Now test the + equality with :data:`numpy.equal`. What result do you get with + :func:`numpy.allclose` instead of ``np.equal``? + + 7. Create a 1D array with 10 random elements. Sort it. + + 8. What's the difference between :meth:`np_array.sort() ` and + :func:`np.sort(np_array) `? + + 9. For the random array in question 8, instead of sorting it, perform + an indirect sort. That is, return the list of indices which would + index the array in sorted order. + + 10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next + combine them into a single 8x4 array with the content of the zeros + array on top and the ones on the bottom. Finally, do the same, + but create a 4x8 array with the zeros on the left and the ones on + the right. + + 11. NumPy functionality Create two 2D arrays and do matrix multiplication + first manually (for loop), then using the np.dot function. Use %%timeit + to compare execution times. What is happening? + + +.. solution:: Solution Numpy-5 + + 1. One solution is:: + + a = np.array([1, 2, 3]) + a[::-1] + + 2. One solution is:: + + b = np.ones((10,10)) + b[:,[0, -1]]=0 + b[[0, -1],:]=0 + + 3. A possible solution is:: + + x = np.random.rand(100) + y = x + 10*(x >= 0.2)*(x < 0.7) + + 4. For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. + + 5. Let's test those functions with few negative and positive values:: + + a = np.array([-3.3, -2.5, -1.5, -0.75, -0.5, 0.5, 0.75, 1.5, 2.5, 3]) + np.round(a) + np.ceil(a) + np.floor(a) + np.trun(a) + + 6. One solution is:: + + x = 10*np.random.rand(4,4) + oo = np.ones((4,4)) + s2c2 = np.square(np.sin(x))+np.square(np.cos(x)) + np.equal(oo,s2c2) + np.allclose(oo,s2c2) + + 7. Sorting the array itself, without copying it:: + + x = np.random.rand(10) + x.sort() + + 8. NumPy.sort() returns a sorted copy of an array. + + 9. ``np.argsort(x)`` + + 10. One solution is:: + + z = np.zeros((4,4)) + o = np.ones((4,4)) + np.concatenate((z,o)) + np.concatenate((z,o),axis=1) + + 11. Using numpy without numpy functionality (np.dot) in this case, is still slow. + + + +See also +-------- + +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + +* `2020 Nature paper on NumPy's role and basic concepts `__ + + + +.. keypoints:: + + - NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally. + - Be aware of some NumPy specific peculiarities diff --git a/branch/opengraph/_sources/packaging.rst.txt b/branch/opengraph/_sources/packaging.rst.txt new file mode 100644 index 00000000..c8eadbbd --- /dev/null +++ b/branch/opengraph/_sources/packaging.rst.txt @@ -0,0 +1,321 @@ +Packaging +========= + +.. questions:: + + - How to organize Python projects larger than one script? + - What is a good file and folder structure for Python projects? + - How can you make your Python functions most usable by your collaborators? + - How to prepare your code to make a Python package? + - How to publish your Python package? + +.. objectives:: + + - Learn to identify the components of a Python package + - Learn to create a Python package + - Learn to publish a Python package + + +Organizing Python projects +-------------------------- + +Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file. + +In the :ref:`scripts` episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further. + +**Recommendations**: + +- Collect related functions into modules (files). +- Collect related modules into packages (we will show how). +- Add a ``LICENSE`` file to your code + see `Software Licensing and Open source explained with cakes `__) +- Write a ``README.md`` file describing what the code does and how to use it. +- It is also recommended to `document your package `__. +- When the project grows, you might need `automated testing `__. + +To have a concrete example but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: ``scipy``. + +These are the 3 files: + +.. literalinclude:: packaging-example-project/calculator/adding.py + :caption: adding.py + +.. literalinclude:: packaging-example-project/calculator/subtracting.py + :caption: subtracting.py + +.. literalinclude:: packaging-example-project/calculator/integrating.py + :caption: integrating.py + +We will add a fourth file: + +.. literalinclude:: packaging-example-project/calculator/__init__.py + :caption: __init__.py + +This ``__init__.py`` file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using *relative imports* +(with the dot). + +This is how we will arrange the files in the project folder/repository: + +.. code-block:: none + :emphasize-lines: 3-6 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + └── README.md + +Now we are ready to test the package. For this we need to be in the "root" +folder, what we have called the *project-folder*. We also need to have +``scipy`` available in our environment: + +.. literalinclude:: packaging-example-project/test.py + +The package is not yet pip-installable, though. We will make this possible in +the next section. + + +Testing a local pip install +--------------------------- + +To make our example package pip-installable we need to add one more file: + +.. code-block:: none + :emphasize-lines: 9 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + ├── README.md + └── setup.py + +This is how ``setup.py`` looks: + +.. literalinclude:: packaging-example-project/setup.py + :caption: setup.py + :emphasize-lines: 18-20 + +Note how our package requires ``scipy`` and we decided to not pin the version +here (see :ref:`version_pinning`). + +Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see :ref:`pypi`) + + + +Exercises 1 +----------- + +.. challenge:: Packaging-1 + + To test a local pip install: + + - Create a new folder outside of our example project + - Create a new virtual environment (:ref:`dependency_management`) + - Install the example package from the project folder + into the new environment: ``$ pip install /path/to/project-folder/`` + - Test the local installation: + + .. literalinclude:: packaging-example-project/test.py + + +Sharing packages via PyPI +------------------------- + +Once we are able to pip-install the example package locally, we are ready for +upload. + +We exercise by uploading to `test-PyPI `__, not the +real `PyPI `__, so that if we mess things up, nothing bad +happens. + +We need two more things: + +- We will do this using `Twine `__ so you need + to pip install that, too. +- You need an account on `test-PyPI `__. + +.. highlight:: console + +Let's try it out. First we create the distribution package:: + + $ python setup.py sdist + +We need twine:: + + $ pip install twine + +And use twine to upload the distribution files to test-PyPI:: + + $ twine upload -r testpypi dist/* + + Uploading distributions to https://test.pypi.org/legacy/ + Enter your username: + Enter your password: + +Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt "myname"):: + + $ pip install -i https://test.pypi.org/simple/ calculator-myname + + +Tools that simplify sharing via PyPI +------------------------------------ + +The solution that we have used to create the example package (using +``setuptools`` and ``twine``) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using ``pyproject.toml`` as more general alternative to +``setup.py``. + +There are at least two tools which try to make the packaging and PyPI interaction easier: + +- `Poetry `__ +- `Flit `__ + + +Building a conda package and share it +------------------------------------- + +.. demo:: + + Most people will watch and observe this, due to speed which we will + move. + +.. callout:: Prerequisites + + To create a conda package, `conda-build` package is required. You may install it with **Anaconda Navigator** or from the command line:: + + $ conda install conda-build + + +The simplest way for creating a conda package for your python script is to +first publish it in `PyPI `__ following the steps explained +above. + + +Building a python package with conda skeleton pypi +*************************************************** + +Once build, the conda package can be installed locally. For this example, we +will use `runtest `__. `runtest +`__ is a numerically tolerant end-to-end test +library for research software. + +1. Create pypi skeleton:: + + $ conda skeleton pypi runtest + + The command above will create a new folder called `runtest` containing a file `meta.yaml`, the conda recipe for `runtest`. + +2. Edit `meta.yaml` and update requirements: + + .. code-block:: yaml + + requirements: + host: + - pip + - python + - flit + run: + - python + - flit + + In the requirements above, we specified what is required for the `host `__ and for `running `__ the package. + + .. callout:: Remark + + For pure python recipes, this is all you need for building a python package with conda. + If your package needs to be built (for instance compilation), you would need additional files e.g. `build.sh` (to build on Linux/Mac-OSX) and `bld.bat` (to build on Windows systems). You can also add test scripts for testing your package. See `documentation `__ + + +3. Build your package with conda + + Your package is now ready to be build with conda:: + + $ conda-build runtest + + + .. callout:: Conda package location + + Look at the messages produced while building. The location of the local conda package is given (search for `anaconda upload`):: + + ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2 + + The prefix `~/anaconda3/` may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder `win-64` differs too (for instance `linux-64` on Linux machines). + + The conda package we have created is specific to your platform (here `win-64`). It can be converted to other platforms using `conda convert `__. + +4. Check within new environment + + It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments. + + :: + + $ conda create -n local-runtest --use-local runtest + + We can then check `runtest` has been successfully installed in `local-runtest` conda environment. Open a new Terminal with `local-runtest` environment (either from the command line:: + + $ conda activate local-runtest + + or via **Anaconda Navigator** (Open Terminal), import runtest and + check its version: + + .. code-block:: python + + import runtest + print(runtest.__version__) + + +.. callout:: Building a conda package from scratch + + It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the `conda-build documentation `__ for more information. + +To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a `conda channel `__ (see below). + + + +Publishing a python package +*************************** + +- Upload your package to *Anaconda.org*: see instructions `here + `__. + Please note that you will have to create an account on Anaconda. + +- Upload your package to `conda-forge `__: + conda-forge is a conda channel: it contains community-led collection of + recipes, build infrastructure and distributions for the conda package + manager. Anyone can public conda packages to conda-forge if certain + `guidelines `__ are respected. + +- Upload your package to `bioconda `_: bioconda is + a very popular channel for the conda package manager specializing in + bioinformatics software. As for conda-forge, you need to follow their + `guidelines `__ when + building conda recipes. + +You can also `create your own conda channel +`__ +for publishing your packages. + + +.. keypoints:: + + - Organize your code for publishing + - Pypi + - conda diff --git a/branch/opengraph/_sources/pandas.rst.txt b/branch/opengraph/_sources/pandas.rst.txt new file mode 100644 index 00000000..e5ed2190 --- /dev/null +++ b/branch/opengraph/_sources/pandas.rst.txt @@ -0,0 +1,459 @@ +Pandas +====== + +.. questions:: + + - How do I learn a new Python package? + - How can I use pandas dataframes in my research? + +.. objectives:: + + - Learn simple and some more advanced usage of pandas dataframes + - Get a feeling for when pandas is useful and know where to find more information + - Understand enough of pandas to be able to read its documentation. + +.. default-domain:: py + + +Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including: + +- a `Getting started guide `__ + (including tutorials and a 10 minute flash intro) +- a `"10 minutes to pandas" `__ + tutorial +- thorough `Documentation `__ containing a user guide, + API reference and contribution guide +- a `cheatsheet `__ +- a `cookbook `__. + +Let's get a flavor of what we can do with pandas. We will be working with an +example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:: + + import pandas as pd + +We can download the data from `this GitHub repository `__ +by visiting the page and saving it to disk, or by directly reading into +a **dataframe**:: + + url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv" + titanic = pd.read_csv(url, index_col='Name') + +We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:: + + # print the first 5 lines of the dataframe + titanic.head() + + # print summary statistics for each column + titanic.describe() + +Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38\% of passengers survived, etc. + +Let's say we're interested in the survival probability of different age groups. With two one-liners, we can find the average age of those who survived or didn't survive, and plot corresponding histograms of the age distribution:: + + print(titanic.groupby("Survived")["Age"].mean()) + +:: + + titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10), + layout=(2,1), zorder=2, sharex=True, rwidth=0.9); + + +Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let's get back to basics. + +.. callout:: Getting help + + Series and DataFrames have a lot functionality, but + how can we find out what methods are available and how they work? One way is to visit + the `API reference `__ + and reading through the list. + Another way is to use the autocompletion feature in Jupyter and type e.g. + ``titanic["Age"].`` in a notebook and then hit ``TAB`` twice - this should open + up a list menu of available methods and attributes. + + Jupyter also offers quick access to help pages (docstrings) which can be + more efficient than searching the internet. Two ways exist: + + - Write a function name followed by question mark and execute the cell, e.g. + write ``titanic.hist?`` and hit ``SHIFT + ENTER``. + - Write the function name and hit ``SHIFT + TAB``. + + +What's in a dataframe? +---------------------- + +As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +`DataFrame object `__ +is composed of rows and columns: + +.. image:: img/pandas/01_table_dataframe.svg + +Each column of a dataframe is a +`series object `__ +- a dataframe is thus a collection of series:: + + # print some information about the columns + titanic.info() + +Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type ``int64`` or of type ``object``. + +Let's inspect one column of the Titanic passanger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):: + + titanic["Age"] + titanic.Age # same as above + type(titanic["Age"]) + +The columns have names. Here's how to get them:: + + titanic.columns + +However, the rows also have names! This is what Pandas calls the **index**:: + + titanic.index + +We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and values. We can +refer to columns and rows either by number or by their name:: + + titanic.loc['Lam, Mr. Ali',"Age"] # select single value by row and column + titanic.loc[:'Lam, Mr. Ali',"Name":"Age"] # slice the dataframe by row and column *names* + titanic.iloc[0:2,3:6] # same slice as above by row and column *numbers* + + titanic.at['Lam, Mr. Ali',"Age"] = 42 # set single value by row and column *name* (fast) + titanic.at['Lam, Mr. Ali',"Age"] # select single value by row and column *name* (fast) + titanic.at['Lam, Mr. Ali',"Age"] = 42 # set single value by row and column *name* (fast) + titanic.iat[0,5] # select same value by row and column *number* (fast) + + titanic["foo"] = "bar" # set a whole column + +Dataframes also support boolean indexing, just like we saw for ``numpy`` +arrays:: + + titanic[titanic["Age"] > 70] + # ".str" creates a string object from a column + titanic[titanic.index.str.contains("Margaret")] + +What if your dataset has missing data? Pandas uses the value :py:data:`numpy.nan` +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:: + + titanic.isna() # returns boolean mask of NaN values + titanic.dropna() # drop missing values + titanic.dropna(how="any") # or how="all" + titanic.dropna(subset=["Cabin"]) # only drop NaNs from one column + titanic.fillna(0) # replace NaNs with zero + titanic.fillna(method='ffill') # forward-fill NaNs + + + +Exercises 1 +----------- + +.. challenge:: Exploring dataframes + + - Have a look at the available methods and attributes using the + `API reference `__ + or the autocomplete feature in Jupyter. + - Try out a few methods using the Titanic dataset and have a look at + the docstrings (help pages) of methods that pique your interest + - Compute the mean age of the first 10 passengers by slicing and the :py:meth:`pandas.DataFrame.mean` method + - (Advanced) Using boolean indexing, compute the survival rate + (mean of "Survived" values) among passengers over and under the average age. + +.. solution:: + + - Mean age of the first 10 passengers: ``titanic.iloc[:10,:]["Age"].mean()`` + or ``titanic.loc[:9,"Age"].mean()`` or ``df.iloc[:10,5].mean()``. + - Survival rate among passengers over and under average age: + ``titanic[titanic["Age"] > titanic["Age"].mean()]["Survived"].mean()`` and + ``titanic[titanic["Age"] < titanic["Age"].mean()]["Survived"].mean()``. + + +Tidy data +--------- + +The above analysis was rather straightforward thanks to the fact +that the dataset is *tidy*. + +.. image:: img/pandas/tidy_data.png + +In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data. + +What would untidy data look like? Here's an example from +some run time statistics from a 1500 m running event:: + + runners = pd.DataFrame([ + {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240}, + {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300}, + {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360}, + ]) + +What makes this data untidy is that the column names `400, 800, 1200, 1500` +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row. + +To make untidy data tidy, a common operation is to "melt" it, +which is to convert it from wide form to a long form:: + + runners = pd.melt(runners, id_vars="Runner", + value_vars=[400, 800, 1200, 1500], + var_name="distance", + value_name="time" + ) + +In this form it's easier to **filter**, **group**, **join** +and **aggregate** the data, and it's also easier to model relationships +between variables. + +The opposite of melting is to *pivot* data, which can be useful to +view data in different ways as we'll see below. + +For a detailed exposition of data tidying, have a look at +`this article `__. + + + +Working with dataframes +----------------------- + +We saw above how we can read in data into a dataframe using the :obj:`~pandas.read_csv` method. +Pandas also understands multiple other formats, for example using :obj:`~pandas.read_excel`, +:obj:`~pandas.read_hdf`, :obj:`~pandas.read_json`, etc. (and corresponding methods to write to file: +:obj:`~pandas.DataFrame.to_csv`, :obj:`~pandas.DataFrame.to_excel`, :obj:`~pandas.DataFrame.to_hdf`, :obj:`~pandas.DataFrame.to_json`, etc.) + +But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array:: + + dates = pd.date_range('20130101', periods=6) + df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD')) + +or a dictionary:: + + df = pd.DataFrame({'A': ['foo', 'bar', 'foo', 'bar', 'foo', 'bar', 'foo', 'foo'], + 'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'], + 'C': np.array([3] * 8, dtype='int32'), + 'D': np.random.randn(8), + 'E': np.random.randn(8)}) + +There are many ways to operate on dataframes. Let's look at a +few examples in order to get a feeling of what's possible +and what the use cases can be. + +We can easily split and concatenate or append dataframes:: + + sub1, sub2, sub3 = df[:2], df[2:4], df[4:] + pd.concat([sub1, sub2, sub3]) + sub1.append([sub2, sub3]) # same as above + +When pulling data from multiple dataframes, a powerful :obj:`pandas.DataFrame.merge` method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:: + + age = pd.DataFrame([ + {"Runner": "Runner 4", "Age": 18}, + {"Runner": "Runner 2", "Age": 21}, + {"Runner": "Runner 1", "Age": 23}, + {"Runner": "Runner 3", "Age": 19}, + ]) + +We now want to use this table to annotate the original ``runners`` table from +before with their age. Note that the ``runners`` and ``age`` dataframes have a +different ordering to it, and ``age`` has an entry for ``Dave`` which is not +present in the ``runners`` table. We can let Pandas deal with all of it using +the :obj:`~pandas.DataFrame.merge` method:: + + # Add the age for each runner + runners.merge(age, on="Runner") + +In fact, much of what can be done in SQL +`is also possible with pandas `__. + +:obj:`~pandas.DataFrame.groupby` is a powerful method which splits a dataframe and aggregates data +in groups. To see what's possible, let's return to the Titanic dataset. Let's +test the old saying "Women and children first". We start by creating a new +column ``Child`` to indicate whether a passenger was a child or not, based on +the existing ``Age`` column. For this example, let's assume that you are a +child when you are younger than 12 years:: + + titanic["Child"] = titanic["Age"] < 12 + +Now we can test the saying by grouping the data on ``Sex`` and then creating further sub-groups based on ``Child``:: + + titanic.groupby(["Sex", "Child"])["Survived"].mean() + +Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +:obj:`~pandas.DataFrame.std`, :obj:`~pandas.DataFrame.min`, +:obj:`~pandas.DataFrame.max`, :obj:`~pandas.DataFrame.cumsum`, +:obj:`~pandas.DataFrame.median`, :obj:`~pandas.DataFrame.skew`, +:obj:`~pandas.DataFrame.var` etc. + + + +Exercises 2 +----------- + +.. challenge:: Analyze the Titanic passenger list dataset + + In the Titanic passenger list dataset, + investigate the family size of the passengers (i.e. the "SibSp" column). + + - What different family sizes exist in the passenger list? Hint: try the :obj:`~pandas.Series.unique` method + - What are the names of the people in the largest family group? + - (Advanced) Create histograms showing the distribution of family sizes for + passengers split by the fare, i.e. one group of high-fare passengers (where + the fare is above average) and one for low-fare passengers + (Hint: instead of an existing column name, you can give a lambda function + as a parameter to ``hist`` to compute a value on the fly. For example + ``lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich"``). + +.. solution:: Solution + + - Existing family sizes: ``df["SibSp"].unique()`` + - Names of members of largest family(ies): ``df[df["SibSp"] == 8]["Name"]`` + - ``df.hist("SibSp", lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich", rwidth=0.9)`` + + + + +Time series superpowers +----------------------- + +An introduction of pandas wouldn't be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates:: + + nobel = pd.read_csv("http://api.nobelprize.org/v1/laureate.csv") + nobel.head() + +This dataset has three columns for time, "born"/"died" and "year". +These are represented as strings and integers, respectively, and +need to be converted to datetime format:: + + # the errors='coerce' argument is needed because the dataset is a bit messy + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + +Pandas knows a lot about dates:: + + print(nobel["born"].dt.day) + print(nobel["born"].dt.year) + print(nobel["born"].dt.weekday) + +We can add a column containing the (approximate) lifespan in years rounded +to one decimal:: + + nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1) + +and then plot a histogram of lifespans:: + + nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9) + +Finally, let's see one more example of an informative plot +produced by a single line of code:: + + nobel.boxplot(column="lifespan", by="category") + + + +Exercises 3 +----------- + +.. challenge:: Analyze the Nobel prize dataset + + - What country has received the largest number of Nobel prizes, and how many? + How many countries are represented in the dataset? Hint: use the :obj:`~pandas.Series.describe` method + on the ``bornCountryCode`` column. + - Create a histogram of the age when the laureates received their Nobel prizes. + Hint: follow the above steps we performed for the lifespan. + - List all the Nobel laureates from your country. + + Now more advanced steps: + + - Now define an array of 4 countries of your choice and extract + only laureates from these countries:: + + countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4]) + subset = nobel.loc[nobel['bornCountry'].isin(countries)] + + - Use ``groupby`` to compute how many nobel prizes each country received in + each category. The ``size()`` method tells us how many rows, hence nobel + prizes, are in each group:: + + nobel.groupby(['bornCountry', 'category']).size() + + - (Optional) Create a pivot table to view a spreadsheet like structure, and view it + + - First add a column “number” to the nobel dataframe containing 1’s + (to enable the counting below). + + - Then create the pivot table:: + + table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum) + + - (Optional) Install the **seaborn** visualization library if you don't + already have it, and create a heatmap of your table:: + + import seaborn as sns + sns.heatmap(table,linewidths=.5); + + - Play around with other nice looking plots:: + + sns.violinplot(y="year", x="bornCountry",inner="stick", data=subset); + + :: + + sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5); + + :: + + subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))] + sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm"); + + :: + + sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count"); + + +Beyond the basics +----------------- + +There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its `API +`__. And when there is not, you can always +apply your own functions to the data using :obj:`~pandas.DataFrame.apply`:: + + from functools import lru_cache + + @lru_cache + def fib(x): + """Compute Fibonacci numbers. The @lru_cache remembers values we + computed before, which speeds up this function a lot.""" + if x < 0: + raise NotImplementedError('Not defined for negative values') + elif x < 2: + return x + else: + return fib(x - 2) + fib(x - 1) + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = df['Generation'].apply(fib) + + +.. keypoints:: + + - pandas dataframes are a good data structure for tabular data + - Dataframes allow both simple and advanced analysis in very compact form diff --git a/branch/opengraph/_sources/parallel-pi-multiprocessing.ipynb.txt b/branch/opengraph/_sources/parallel-pi-multiprocessing.ipynb.txt new file mode 100644 index 00000000..970dbada --- /dev/null +++ b/branch/opengraph/_sources/parallel-pi-multiprocessing.ipynb.txt @@ -0,0 +1,303 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Python multithreading solution\n", + "Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import random" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "def sample(n):\n", + " \"\"\"Make n trials of points in the square. Return (n, number_in_circle)\n", + " \n", + " This is our basic function. By design, it returns everything it\\\n", + " needs to compute the final answer: both n (even though it is an input\n", + " argument) and n_inside_circle. To compute our final answer, all we\n", + " have to do is sum up the n:s and the n_inside_circle:s and do our\n", + " computation\"\"\"\n", + " n_inside_circle = 0\n", + " for i in range(n):\n", + " x = random.random()\n", + " y = random.random()\n", + " if x**2 + y**2 < 1.0:\n", + " n_inside_circle += 1\n", + " return n, n_inside_circle" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it just for timing\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Do the actual calculation (the previous result doesn't get saved)\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is the \"calculate answer\" phase." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.144548" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "pi = 4.0 * (n_inside_circle / n)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in parallel with multiprocessing\n", + "This divides the calculation into 10 tasks and runs `sample` on each of them. Then it re-combines the results." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import multiprocessing.pool\n", + "pool = multiprocessing.pool.Pool()\n", + "# The default pool makes one process per CPU" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it once to time it\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "pool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.140768" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in \"parallel\" with threads\n", + "To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool = multiprocessing.pool.ThreadPool()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%timeit -o\n", + "# Do it once to time it\n", + "threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.142388" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Future ideas\n", + "\n", + "You could make a separate `calculate` function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.\n", + "\n", + "Notice the similarity to [split-apply-combine](https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html) or [map-reduce](https://en.wikipedia.org/wiki/MapReduce) which is a specialization of split-apply-combine." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/opengraph/_sources/parallel.rst.txt b/branch/opengraph/_sources/parallel.rst.txt new file mode 100644 index 00000000..22aa21ed --- /dev/null +++ b/branch/opengraph/_sources/parallel.rst.txt @@ -0,0 +1,438 @@ +Parallel programming +==================== + +.. questions:: + + - When you need more than one processor, what do you do? + - How can we use more than one processor/core in Python? + +.. objectives:: + + - Understand the major strategies of parallelizing code + - Understand mechanics of the ``multiprocessing`` package + - Know when to use more advanced packages or approaches + + + +Modes of parallelism +-------------------- + +You realize you do have more computation to do than you can on one processor? +What do you do? + +1. Profile your code, identify the *actual* slow spots. + +2. Can you improve your code in those areas? Use an existing library? + +3. Are there are any low-effort optimizations that you can make? + +4. Think about parallelizing. + + +Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers). + +**Parallel computing** is when many different tasks are carried out +simultaneously. There are three main models: + +* **Embarrassingly parallel:** the code does not need to synchronize/communicate + with other instances, and you can run + multiple instances of the code separately, and combine the results + later. If you can do this, great! (array jobs, task queues) + +* **Shared memory parallelism:** Parallel threads need to communicate and do so via + the same memory (variables, state, etc). (OpenMP) + +* **Message passing:** Different processes manage their own memory segments. They share data + by communicating (passing messages) as needed. (Message Passing Interface (MPI)). + +Programming shared memory or message passing is beyond the scope of +this course, but the simpler strategies are most often used anyway. + +.. warning:: + + Parallel programming is not magic, but many things can go wrong and + you can get unexpected results or difficult to debug problems. + Parallel programming is a fascinating world to get involved in, but + make sure you invest enough time to do it well. + + See the video by Raymond Hettinger ("See Also" at bottom + of page) for an entertaining take on this. + + + +Multithreading and the GIL +-------------------------- + +The designers of the Python language made the choice +that **only one thread in a process can run actual Python code** +by using the so-called **global interpreter lock (GIL)**. +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python without being a bit careful. +At first glance, this is bad for parallelism. *But it's not all bad!:* + +* External libraries (NumPy, SciPy, Pandas, etc), written in C or other + languages, can release the lock and run multi-threaded. Also, most + input/output releases the GIL, and input/output is slow. + +* If speed is important enough you need things parallel, you usually + wouldn't use pure Python. + +We won't cover threading in this course. + +.. seealso:: + + * `More on the global interpreter lock + `__ + * `Threading python module + `__. This is + very low level and you shouldn't use it unless you really know what + you are doing. + * We recommend you find a UNIX threading tutorial first before embarking + on using the `threading + `__ module. + + + +multiprocessing +--------------- + +As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +:py:mod:`multiprocessing` module. + +* The interface is a lot like threading, but in the background creates + new processes to get around the global interpreter lock. + +* There are low-level functions which have a lot of the same risks and + difficulties as when using :py:mod:`threading`. + +To show an example, +the `split-apply-combine `__ +or `map-reduce `__ paradigm is +quite useful for many scientific workflows. Consider you have this:: + + def square(x): + return x*x + +You can apply the function to every element in a list using the +:py:func:`map` function: + +.. code-block:: pycon + + >>> list(map(square, [1, 2, 3, 4, 5, 6])) + [1, 4, 9, 16, 25, 36] + +The :py:class:`multiprocessing.pool.Pool` class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list: + +.. code-block:: pycon + + >>> from multiprocessing import Pool + >>> with Pool() as pool: + ... pool.map(square, [1, 2, 3, 4, 5, 6]) + [1, 4, 9, 16, 25, 36] + + + +Exercises, multiprocessing +-------------------------- + +.. challenge:: Parallel-1, multiprocessing + + Here, you find some code which calculates pi by a stochastic + algorithm. You don't really need to worry how the algorithm works, + but it computes random points in a 1x1 square, and computes the + number that fall into a circle. Copy it into a Jupyter notebook + and use the ``%%timeit`` cell magic on the computation part (the + one highlighted line after timeit below): + + .. code-block:: python + :emphasize-lines: 20 + + import random + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x**2 + y**2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + %%timeit + n, n_inside_circle = sample(10**6) + + pi = 4.0 * (n_inside_circle / n) + pi + + Using the :py:class:`multiprocessing.pool.Pool` code from the lesson, run + the ``sample`` function 10 times, each with ``10**5`` samples + only. Combine the results and time the calculation. What is the + difference in time taken? + + (optional, advanced) Do the same but with + :py:class:`multiprocessing.pool.ThreadPool` instead. This works identically + to ``Pool``, but uses threads instead of different processes. + Compare the time taken. + + .. solution:: + + See the finished notebook here: + + .. toctree:: + + parallel-pi-multiprocessing + + You notice the version with ``ThreadPool`` is no faster, and + probably takes even longer. This is because this is a + pure-Python function which can not run simultaneously in + multiple threads. + +.. challenge:: (advanced) Parallel-2 Running on a cluster + + How does the pool know how many CPUs to take? What happens if you + run on a computer cluster and request only part of the CPUs on a + node? + + .. solution:: + + Pool by default uses one process for each CPU on the node - it + doesn't know about your cluster's scheduling system. It's + possible that you have permission to use 2 CPUs but it is trying + to use 12. This is generally a bad situation, and will just + slow you down (and make other users on the same node upset)! + + You either need to be able to specify the number of CPUs to use + (and pass it the right number), or make it aware of the cluster + system. For example, on a Slurm cluster you would check the + environment variable ``SLURM_CPUS_PER_TASK``. + + Whatever you do, document what your code is doing under the + hood, so that other users know what is going on (we've learned + this from experience...). + + +MPI +--- + +The message passing interface (MPI) approach to parallelization +is that: + +- Tasks (cores) have a rank and are numbered 0, 1, 2, 3, ... +- Each task (core) manages its own memory +- Tasks communicate and share data by sending messages +- Many higher-level functions exist to distribute information to other tasks + and gather information from other tasks +- All tasks typically run the entire code and we have to be careful to avoid + that all tasks do the same thing + +Introductory MPI lessons where Python is included: + +- https://rantahar.github.io/introduction-to-mpi/ +- https://pdc-support.github.io/introduction-to-mpi/ + +These blog posts are good for gentle MPI/mpi4py introduction: + +- https://www.kth.se/blogs/pdc/2019/08/parallel-programming-in-python-mpi4py-part-1/ +- https://www.kth.se/blogs/pdc/2019/11/parallel-programming-in-python-mpi4py-part-2/ + +Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together. + +Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work: + +.. code-block:: python + :emphasize-lines: 3,23-25,29,39,42 + + import random + import time + from mpi4py import MPI + + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x ** 2 + y ** 2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + + comm = MPI.COMM_WORLD + size = comm.Get_size() + rank = comm.Get_rank() + + n = 10 ** 7 + + if size > 1: + n_task = int(n / size) + else: + n_task = n + + t0 = time.perf_counter() + _, n_inside_circle = sample(n_task) + t = time.perf_counter() - t0 + + print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}") + n_inside_circle = comm.gather(n_inside_circle, root=0) + print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}") + + if rank == 0: + pi_estimate = 4.0 * sum(n_inside_circle) / n + print( + f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds" + ) + + + +Exercises, MPI +-------------- + +.. challenge:: Parallel-2, MPI + + We can do this as **exercise or as demo**. Note that this example requires ``mpi4py`` and a + MPI installation such as for instance `OpenMPI `__. + + - Try to run this example on one core: ``$ python example.py``. + - Then compare the output with a run on multiple cores (in this case 2): ``$ mpiexec -n 2 python example.py``. + - Can you guess what the ``comm.gather`` function does by looking at the print-outs right before and after. + - Why do we have the if-statement ``if rank == 0`` at the end? + - Why did we use ``_, n_inside_circle = sample(n_task)`` and not ``n, n_inside_circle = sample(n_task)``? + + +Coupling to other languages +--------------------------- + +As mentioned further up in "Multithreading and the GIL", Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP "directly". + +However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don't +need parallelism, but need to make an optimized algorithm for a small part of the code. + +Two strategies are common: + +- Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization: + + - C: use the `cffi `__ package (C foreign function interface). :py:mod:`ctypes` is a similar but slightly more primitive module that is in the standard library. + - C++: use `pybind11 `__ + - Fortran: create a C interface using ``iso_c_binding`` and then couple the C layer to Python + using `cffi `__ + - Rust: use `PyO3 `__ + +- Let compiled languages do the shared-memory parallelization part (as in above + point) and let Python do the MPI work and distribute tasks across nodes using + an ``mpi4py`` layer. + +Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course. + +Before you take this route, **profile the application** first to be sure where +the bottleneck is. + +Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason. + + + +Dask and task queues +-------------------- + +There are other strategies that go completely beyond the manual +parallelization methods above. We won't go into much detail. + +Dask +~~~~ + +`Dask `__ is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs. + +Dask is very popular for data analysis and is used by a number of high-level python library: + +- Dask arrays scale Numpy (see also `xarray `__ +- Dask dataframes scale Pandas workflows +- Dask-ML scales Scikit-Learn + +Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block. + +.. discussion:: Example from dask.org + + .. code-block:: + + # Arrays implement the Numpy API + import dask.array as da + x = da.random.random(size=(10000, 10000), + chunks=(1000, 1000)) + x + x.T - x.mean(axis=0) + # It runs using multiple threads on your machine. + # It could also be distributed to multiple machines + + + +Exercises, Dask +--------------- + +.. challenge:: Dask-Examples (optional) + + `Dask examples `__ illustrate the usage of dask and can be run interactively through `mybinder `__. Start an `interactive session on mybinder `__ and test/run a few dask examples. + +.. warning: dask on HPC + + On HPC, it is important to use `dask-mpi `__ that deploys dask using MPI4Py. The setup can be a bit tricky and we recommend the usage of `dask-jobqueue and dask-drmaa `__: these packages need to be installed on the target platform (not through conda) to fully benefit from the native underlying MPI libraries. + +Task queues +~~~~~~~~~~~ + +A **task queue** has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for *embarrassingly parallel* jobs. + +There are different descriptions of `task queues in Python +`__. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant. + + + +See also +-------- + +* `Thinking about Concurrency, Raymond Hettinger + `__. Good introduction to simple and + safe concurrent code. + +.. keypoints:: + + - Pure Python is not very good for highly parallel code. + - Luckily it interfaces to many things which *are* good, and give + you the full control you need. + - Combining vectorized functions (numpy, scipy, pandas, etc.) with + the parallel strategies listed here will get you very far. diff --git a/branch/opengraph/_sources/python.rst.txt b/branch/opengraph/_sources/python.rst.txt new file mode 100644 index 00000000..20a0cf9a --- /dev/null +++ b/branch/opengraph/_sources/python.rst.txt @@ -0,0 +1,186 @@ +Introduction to Python +====================== + +.. questions:: + + - What are the basic blocks of Python language? + - How are functions and classes defined in Python? + +.. objectives:: + + - Get a *very* short introduction to Python types and syntax + - Be able to follow the rest of the examples in the course, even if you don't understand everything perfectly. + + We expect everyone to be able to know the following basic material + to follow the course (though it is not *everything* you need to + know about Python). + +If you are not familiar with Python, here is a *very* short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise. + +.. seealso:: + + This page contains an overview of the basics of Python. You can + also refer to `This Python overview from a different lesson + `__ + which is slightly more engaging. + + + +Scalars +------- + +Scalar types, that is, single elements of various types: + +:: + + i = 42 # integer + i = 2**77 # Integers have arbitrary precision + g = 3.14 # floating point number + c = 2 - 3j # Complex number + b = True # boolean + s = "Hello!" # String (Unicode) + q = b'Hello' # bytes (8-bit values) + +Read more: :class:`int`, :class:`float`, :class:`complex`, +:class:`bool`, :class:`str`, :class:`bytes`. + + +Collections +----------- + +Collections are data structures capable of storing multiple values. + +:: + + l = [1, 2, 3] # list + l[1] # lists are indexed by int + l[1] = True # list elements can be any type + d = {"Janne": 123, "Richard": 456} # dictionary + d["Janne"] + s = set(("apple", "cherry", "banana", "apple")) # Set of unique values + s + +Read more: :class:`list`, :class:`tuple`, :class:`dict`, :class:`set`. + + +Control structures +------------------ + +Python has the usual control structures, that is conditional +statements and loops. For example, the :ref:`if` statement: + +:: + + x = 2 + if x == 3: + print('x is 3') + elif x == 2: + print('x is 2') + else: + print('x is something else') + +:ref:`While ` loops loop until some condition is met: + +:: + + x = 0 + while x < 42: + print('x is ', x) + x += 0.2 + +:ref:`For ` loops loop over some collection of values: + +:: + + xs = [1, 2, 3, 4] + for x in xs: + print(x) + + +Often you want to loop over a sequence of integers, in that case the +:func:`range` function is useful: + +:: + + for x in range(9): + print(x) + +Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the :func:`enumerate` +function: + +:: + + xs = [1, 'hello', 'world'] + for ii, x in enumerate(xs): + print(ii, x) + + +Functions and classes +--------------------- + +Python functions are defined by the :ref:`def` keyword. They take a +number of arguments, and return a number of return values. + +:: + + def hello(name): + """Say hello to the person given by the argument""" + print('Hello', name) + return 'Hello ' + name + + hello("Anne") + +Classes are defined by the :ref:`class` keyword: + +:: + + class Hello: + def __init__(self, name): + self._name = name + def say(self): + print('Hello', self._name) + + h = Hello("Richard") + h.say() + + +Python type system +------------------ + +Python is strongly and dynamically typed. + +Strong here means, roughly, that it's not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior). + +:: + + x = 42 + type(x) + x + "hello" + +Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type: + +:: + + x = 42 + x = "hello" + + +*Jargon*: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation. + + +??? (lesson here) + + + +.. keypoints:: + + - Python offers a nice set of basic types as many other programming languages + - Python is strongly typed and dynamically typed diff --git a/branch/opengraph/_sources/quick-reference.rst.txt b/branch/opengraph/_sources/quick-reference.rst.txt new file mode 100644 index 00000000..077859af --- /dev/null +++ b/branch/opengraph/_sources/quick-reference.rst.txt @@ -0,0 +1,26 @@ +Quick reference +=============== + +* `Pandas cheatsheet + `__ (pandas.pydata.org) + +* `Pandas cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy cheatsheet + `__ + (via `Datacamp + `__) + +* `JupyterLab cheatsheet + `__ + +* `Matplotlib cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy, Pandas, Matplotlib, Scikit-learn all together + `__ diff --git a/branch/opengraph/_sources/scipy.rst.txt b/branch/opengraph/_sources/scipy.rst.txt new file mode 100644 index 00000000..df4ee8a4 --- /dev/null +++ b/branch/opengraph/_sources/scipy.rst.txt @@ -0,0 +1,183 @@ +SciPy +===== + +.. questions:: + + - When you need more advanced mathematical functions, where do you + look? + +.. objectives:: + + - Understand that SciPy exists and what kinds of things it has. + - Understand the importance of using external libraries and how to + use them. + - Understand the purpose of wrapping existing C/Fortran code. + - Non-objective: know details of everything (or anything) in SciPy. + +.. seealso:: + + * Main article: `SciPy documentation `__ + + + +SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms. + + + +What's in SciPy? +---------------- + +Briefly, it contains functionality for + +- Special functions (Bessel, Gamma, etc.) +- Numerical integration +- Optimization +- Interpolation +- Fast Fourier Transform (FFT) +- Signal processing +- Linear algebra (more complete than in NumPy) +- Sparse matrices +- Statistics +- More I/O routine, e.g. Matrix Market format for sparse matrices, + MATLAB files (.mat), etc. + +Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages. + +Most functions are documented ridiculously well from a scientific +standpoint: you aren't just using some unknown function, but have a +full scientific description and citation to the method and +implementation. + + + +Exercises: use SciPy +-------------------- + +These exercises do not exist because *you* might need *these* +functions someday. They are because *you* will need to *read +documentation and understand documentation of an an external library* +eventually. + +1: Numerical integration +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Define a function of one variable and using + `scipy.integrate.quad `__ + calculate the integral of your function in the + interval ``[0.0, 4.0]``. Then vary the interval and also modify the function and check + whether scipy can integrate it. + + +.. solution:: + + .. code-block:: python + + from scipy import integrate + + def myfunction(x): + # you need to define result + return result + + integral = integrate.quad(myfunction, 0.0, 4.0) + print(integral) + + `quad + `__ + uses the Fortran library QUADPACK, which one can assume is pretty + good. You can also see a whole lot of scientific information about + the function on the docs page - including the scientific names of + the methods used. + + + +2: Sparse matrices +~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Use the SciPy sparse matrix functionality to create a random sparse + matrix with a probability of non-zero elements of 0.05 and size 10000 + x 10000. The use the SciPy sparse linear algebra support to calculate + the matrix-vector product of the sparse matrix you just created and a + random vector. Use the %timeit macro to measure how long it + takes. Does the optional ``format`` argument when you create the + sparse matrix make a difference? + + Then, compare to how long it takes if you'd instead first convert the + sparse matrix to a normal NumPy dense array, and use the NumPy ``dot`` + method to calculate the matrix-vector product. + + Can you figure out a quick rule of thumb when it's worth using a + sparse matrix representation vs. a dense representation? + +.. solution:: + + The basic code to do the test is: + + .. code-block:: + + import numpy + import scipy.sparse + + vector = numpy.random.random(10000) + matrix = scipy.sparse.rand(10000, 10000, density=.05, format='csc') + + # We time this line + matrix.dot(vector) + + From the top of the `spare matrix module documentation + `__, we can + see there are a variety of different available sparse matrix types: + ``bsr``, ``coo``, ``csr``, ``csc``, etc. These each represent a + different way of storing the matrices. + + It seems that ``csr`` and ``csc`` are fairly fast. ``lil`` and + ``dok`` are slow but it says that these are good for creating + matrices with random insertions. + + For example, ``csr`` takes 7ms, ``lil`` 42ms, ``dok`` 1600ms, and + converting to a non-sparse array ``matrix.toarray()`` and + multiplying takes 64ms on one particular computer. + + This code allows us to time the performance at different + densities. It seems that with the ``csr`` format, sparse is better + below densities of around .4 to .5: + + ..code-block:: + + for density in [.01, .05, .1, .2, .3, .4, .5]: + matrix = scipy.sparse.rand(10000, 10000, density=density, format='csr') + time_sparse = timeit.timeit('matrix.dot(vector)', number=10, globals=globals()) + matrix2 = matrix.toarray() + time_full = timeit.timeit('matrix2.dot(vector)', number=10, globals=globals()) + print(f"{density} {time_sparse:.3f} {time_full:.3f}") + + + +See also +-------- + +* `SciPy general introduction `__ +* `SciPy documentation + `__ + + + +.. keypoints:: + + - When you need advance math or scientific functions, let's just + admit it: you do a web search first. + - But when you see something in SciPy come up, you know your + solutions are in good hands. diff --git a/branch/opengraph/_sources/scripts.rst.txt b/branch/opengraph/_sources/scripts.rst.txt new file mode 100644 index 00000000..93f0c3b2 --- /dev/null +++ b/branch/opengraph/_sources/scripts.rst.txt @@ -0,0 +1,362 @@ +.. _scripts: + +Scripts +======= + +.. questions:: + + - Why are command line programs useful, compared to Jupyter + notebooks and similar? + - How to create a python script? + - How to generalize a python script? + +.. objectives:: + + - Learn how to streamline your python notebooks by creating repeatable python scripts + - Learn how to import other python files + - Learn to parse command line arguments in python + +Why scripts? +------------- + +So far we have been learning python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype python code so we may think that is more than enough for your day to day work. + +But after several weeks of hard work with python, you may end up: + +- either with 10 different notebooks (so that you can run them concurrently) +- or with a very long notebook which is becoming hardly readable! + +Let's imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks? + +In this episode, we will learn how to automate your work using python scripts so that + +* you do not need to manually configure your notebooks to be able to run with different parameters +* can easily run you work via other tools, such as on computing clusters. + + +From jupyter notebooks to python scripts +----------------------------------------- + +Save as python script +--------------------- + +Jupyter notebooks can be parameterized for instance using `papermill `_. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate python scripts. This will also force you to modularize your code. See `CodeRefinery's lesson on Modular code development `__. + +Within JupyterLab, you can export any jupyter notebook to a python script: + +.. figure:: https://jupyterlab.readthedocs.io/en/stable/_images/exporting_menu.png + + Select File (top menu bar) → Export Notebook as → **Export notebook to Executable Script**. + + +.. highlight:: console + +Actually, you could also export your notebook in many other formats. +Check the `JupyterLab documentation `_ for more information. +If you keep working in the jupyterlab folder, you can also convert files in the terminal (File -> New -> Terminal) by running:: + + + $ jupyter nbconvert --to script your_notebook_name.ipynb + + +Exercises 1 +----------- + +.. challenge:: Scripts-1 + + .. highlight:: console + + + 1. Download the :download:`weather_observations.ipynb <../resources/code/scripts/weather_observations.ipynb>` and the weather_data file and upload them to your jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from `rp5.kz `_ and was slightly adjusted for this lecture. + + **Note:** If you haven't downloaded the file directly to your jupyterlab folder, it will be located in your **Downloads** folder or the folder you selected. In jupyterlab click on the 'upload file' button, navigate to the folder containing the file and select it to load it into your jupyterlab folder. + + 2. Open a terminal in jupyter (File -> New -> Terminal). + + 3. Convert the jupyter script to a python script by calling:: + + $ jupyter nbconvert --to script weather_observations.ipynb + + 4. Run the script (note: you may have ``python3`` rather than ``python``):: + + $ python weather_observations.py + +Importing other python files +---------------------------- + +We have a very short notebook that loads and plots data. But even in this script, we have to do a bit of processing (changing the format of the dates). We also extract a subset of our data for a +given date range. + +In general, it is good practice to separate processing from plotting. The reason is that you often need to generate multiple plots using the data while pre-processing data once only. +When data preprocessing is expensive this is even more important. + +.. highlight:: python + +For example, we can create a new python file (**weather_functions.py**) containing a function to adjust the dates in our dataset:: + + import pandas as pd + + def preprocess(dataset, start_date, end_date): + dataset['Local time'] = pd.to_datetime(dataset['Local time'],dayfirst=True) + dataset = dataset[dataset['Local time'].between(start_date,end_date)] + return dataset + +and modify the ``weather_observations.py`` file to + +.. code-block:: python + :emphasize-lines: 2,11 + + import pandas as pd + import weather_functions + + url = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv" + # read the data skipping comment lines + weather = pd.read_csv(url,comment='#') + # set start and end time + start_date=pd.to_datetime('01/06/2021',dayfirst=True) + end_date=pd.to_datetime('01/10/2021',dayfirst=True) + # preprocess the data + weather = weather_functions.preprocess(weather, start_date, end_date) + ... + + +Exercises 2 +----------- + +.. challenge:: Scripts-2 (optional) + + 1. Create **weather_functions.py** with the above function and add an additional function for plotting the dataset. + + 2. Update **weather_observations.py** to call it. + +.. solution:: + + **weather_observations.py**: + + .. literalinclude:: ../resources/code/scripts/weather_observations.py + :language: python + :emphasize-lines: 5,13,16 + + **weather_functions.py**: + + .. literalinclude:: ../resources/code/scripts/weather_functions.py + :language: python + :emphasize-lines: 2, 12-21 + + +Command line arguments with ``sys.argv`` +---------------------------------------- + +We now have a better organized code but it still cannot easily process time ranges or a +specified output file name. To achieve this, rather than copying the same code several times for +different time ranges or output file names, we can update the main code to take the +start/end time and output file name from the command line + +**Example**: We modify the **weather_observations.py** script such that we allow start +and end times as well as the output file to be passed in as arguments to the function: + +.. code-block:: python + :emphasize-lines: 1,6-7,9 + + import sys + import pandas as pd + import weather_functions + + # set start and end time + start_date = pd.to_datetime(sys.argv[1],dayfirst=True) + end_date = pd.to_datetime(sys.argv[2],dayfirst=True) + + output_file_name = sys.argv[3] + + ... + + # preprocess the data + weather = weather_functions.preprocess(weather, start_date, end_date) + + ... + + fig.savefig(output_file_name) + +We can try it out: + +.. code-block:: console + + $ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png + + +.. discussion:: + + - Does it work? + + - Why is this better than modifying the script every time I want it to + plot data for a different period? + + - What problems do you expect when using this approach (using ``sys.argv``)? + +This approach is brittle and more robust solutions exist that allow to fully +customize your scripts and generate help texts at the same time: + +- `argparse `__: + built-in to Python, this is the one that we will show below. +- `doctopt `__: you write the help text and this generates a parser for you. +- `click `__: another nice + library for command line interfaces - very easy to use. + + +Parsing command line arguments with ``argparse`` +------------------------------------------------ + +This example not only gives you descriptive command line +arguments, it also automatically generates a ``--help`` option for you: + +.. code-block:: python + :emphasize-lines: 1,5-14 + + import argparse + import pandas as pd + import weather_functions + + parser = argparse.ArgumentParser() + # set start and end time + parser.add_argument('-o', '--output', type=str, default="Out.png" + help="end time") + parser.add_argument('-s', '--start', type=str, default="1/1/2019" + help="start time") + parser.add_argument('-e', '--end', type=str, default="1/1/2021" + help="output filename") + + args = parser.parse_args() + + start_date = pd.to_datetime(args.start,dayfirst=True) + end_date = pd.to_datetime(args.end,dayfirst=True) + + ... + + # preprocess the data + weather = weather_functions.preprocess(weather, start_date, end_date) + + ... + + fig.savefig(args.output) + + + +Exercises 3 +----------- + +.. challenge:: Scripts-3 + + 1. Take the python script we have written in the preceding exercise and use + ``argparse`` to specify the input and output files and allow the start and end dates to be set. + + 2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from Mai 2020 to October 2020). + Also use data for cairo (``https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv``) + + +.. solution:: + + .. literalinclude:: ../resources/code/scripts/weather_observations_argparse.py + :language: python + :emphasize-lines: 2,5-9,11,14,17-18,27 + + + + +.. discussion:: + + **What was the point of doing this?** + + Now you can do this: + + .. code-block:: console + + $ python weather_observations.py --help + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png + $ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png + $ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output temperature_cairo.png + + - We can now process different input files without changing the script. + - We can select multiple time ranges without modifying the script. + - This way we can also loop over file patterns (using shell loops or similar) or use + the script in a workflow management system and process many files in parallel. + - By changing from ``sys.argv`` to ``argparse`` we made the script more robust against + user input errors and also got a help text (accessible via ``--help``). + + +Load larger option lists using config files +------------------------------------------- + +In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line: + +.. code-block:: console + + + $ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021 + + +This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple ``Parameter = Value`` +format, and parse it yourself, or you can use e.g. the ``JSON`` or ``YAML`` formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won't go into the details of the formats, and will only give +a short example using YAML here. + +The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a python module (``yaml``) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the ``json`` package). + +The python module :download:`optionsparser.py <../resources/code/scripts/optionsparser.py>` provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values. + +In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation ...), set the labels and titles explicitly etc. + +In the YAML format, names and values are separated by ``:``. Our above example would therefore translate to the following YAML file: + +.. literalinclude:: ../resources/code/scripts/weather_options.yml + :language: yaml + +Exercises 4 (optional) +---------------------- + +.. challenge:: Scripts-4 + + 1. Download the :download:`optionsparser.py ` + function and load it into your working folder in jupyterlab. + Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line + (using e.g. argparse or sys.argv) still needs to be read from the command line. + + + 2. Run your script with different config files. + + +.. solution:: + + The modified **weather_observations.py** script: + + .. literalinclude:: ../resources/code/scripts/weather_observations_config.py + :language: python + :emphasize-lines: 5,16-27,31,34,44,47 + + The modified **weather_functions.py** script: + + .. literalinclude:: ../resources/code/scripts/weather_functions_config.py + :language: python + :emphasize-lines: 12,16-18 + + +.. admonition:: Further reading + + - Linking Jupyterlab notebooks to python scripts (making linking ``.py``- and ``.ipynb``-files easier) using `jupytext `_ + - The `wikipedia page about YAML `_ contains a lot of additional information on the YAML syntax. + - `The Coderefinery Lesson about reproducible research `_ can give additional information about good coding practices and workflow automation. + + - `CodeRefinery's lesson on Modular code development `__ diff --git a/branch/opengraph/_static/_sphinx_javascript_frameworks_compat.js b/branch/opengraph/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..8549469d --- /dev/null +++ b/branch/opengraph/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,134 @@ +/* + * _sphinx_javascript_frameworks_compat.js + * ~~~~~~~~~~ + * + * Compatability shim for jQuery and underscores.js. + * + * WILL BE REMOVED IN Sphinx 6.0 + * xref RemovedInSphinx60Warning + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/branch/opengraph/_static/basic.css b/branch/opengraph/_static/basic.css new file mode 100644 index 00000000..eeb0519a --- /dev/null +++ b/branch/opengraph/_static/basic.css @@ -0,0 +1,899 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} +dl.footnote > dt, +dl.citation > dt { + float: left; + margin-right: 0.5em; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} +dl.field-list > dt:after { + content: ":"; +} + + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/branch/opengraph/_static/check-solid.svg b/branch/opengraph/_static/check-solid.svg new file mode 100644 index 00000000..92fad4b5 --- /dev/null +++ b/branch/opengraph/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/branch/opengraph/_static/clipboard.min.js b/branch/opengraph/_static/clipboard.min.js new file mode 100644 index 00000000..54b3c463 --- /dev/null +++ b/branch/opengraph/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/branch/opengraph/_static/copybutton.css b/branch/opengraph/_static/copybutton.css new file mode 100644 index 00000000..f1916ec7 --- /dev/null +++ b/branch/opengraph/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/branch/opengraph/_static/copybutton.js b/branch/opengraph/_static/copybutton.js new file mode 100644 index 00000000..02c5c82d --- /dev/null +++ b/branch/opengraph/_static/copybutton.js @@ -0,0 +1,248 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copié dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = ``; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = 'div.highlight pre'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} + + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '.linenos, .gp'; + + let text = filterText(target, exclude); + return formatCopyText(text, '', false, true, true, true, '', '') +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) \ No newline at end of file diff --git a/branch/opengraph/_static/copybutton_funcs.js b/branch/opengraph/_static/copybutton_funcs.js new file mode 100644 index 00000000..dbe1aaad --- /dev/null +++ b/branch/opengraph/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/branch/opengraph/_static/css/badge_only.css b/branch/opengraph/_static/css/badge_only.css new file mode 100644 index 00000000..c718cee4 --- /dev/null +++ b/branch/opengraph/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}} \ No newline at end of file diff --git a/branch/opengraph/_static/css/fonts/Roboto-Slab-Bold.woff b/branch/opengraph/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/branch/opengraph/_static/css/fonts/Roboto-Slab-Bold.woff2 b/branch/opengraph/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/branch/opengraph/_static/css/fonts/Roboto-Slab-Regular.woff b/branch/opengraph/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/opengraph/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/branch/opengraph/_static/css/fonts/Roboto-Slab-Regular.woff2 b/branch/opengraph/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/opengraph/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/branch/opengraph/_static/css/fonts/fontawesome-webfont.eot b/branch/opengraph/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/branch/opengraph/_static/css/fonts/fontawesome-webfont.svg b/branch/opengraph/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/branch/opengraph/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/branch/opengraph/_static/css/fonts/fontawesome-webfont.ttf b/branch/opengraph/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/branch/opengraph/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/branch/opengraph/_static/css/fonts/fontawesome-webfont.woff b/branch/opengraph/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/branch/opengraph/_static/css/fonts/fontawesome-webfont.woff2 b/branch/opengraph/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/branch/opengraph/_static/css/fonts/lato-bold-italic.woff b/branch/opengraph/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-bold-italic.woff differ diff --git a/branch/opengraph/_static/css/fonts/lato-bold-italic.woff2 b/branch/opengraph/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/branch/opengraph/_static/css/fonts/lato-bold.woff b/branch/opengraph/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-bold.woff differ diff --git a/branch/opengraph/_static/css/fonts/lato-bold.woff2 b/branch/opengraph/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-bold.woff2 differ diff --git a/branch/opengraph/_static/css/fonts/lato-normal-italic.woff b/branch/opengraph/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-normal-italic.woff differ diff --git a/branch/opengraph/_static/css/fonts/lato-normal-italic.woff2 b/branch/opengraph/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/branch/opengraph/_static/css/fonts/lato-normal.woff b/branch/opengraph/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-normal.woff differ diff --git a/branch/opengraph/_static/css/fonts/lato-normal.woff2 b/branch/opengraph/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/opengraph/_static/css/fonts/lato-normal.woff2 differ diff --git a/branch/opengraph/_static/css/theme.css b/branch/opengraph/_static/css/theme.css new file mode 100644 index 00000000..09a1af86 --- /dev/null +++ b/branch/opengraph/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search>a:hover{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.version{margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dt:after,html.writer-html5 .rst-content dl.field-list>dt:after,html.writer-html5 .rst-content dl.footnote>dt:after{content:":"}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets,html.writer-html5 .rst-content dl.footnote>dt>span.brackets{margin-right:.5rem}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{font-style:italic}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p,html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content dl.citation,.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content dl.citation code,.rst-content dl.citation tt,.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel{border:1px solid #7fbbe3;background:#e7f2fa;font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/branch/opengraph/_static/doctools.js b/branch/opengraph/_static/doctools.js new file mode 100644 index 00000000..527b876c --- /dev/null +++ b/branch/opengraph/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/branch/opengraph/_static/documentation_options.js b/branch/opengraph/_static/documentation_options.js new file mode 100644 index 00000000..b57ae3b8 --- /dev/null +++ b/branch/opengraph/_static/documentation_options.js @@ -0,0 +1,14 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/branch/opengraph/_static/file.png b/branch/opengraph/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/branch/opengraph/_static/file.png differ diff --git a/branch/opengraph/_static/jquery-3.6.0.js b/branch/opengraph/_static/jquery-3.6.0.js new file mode 100644 index 00000000..fc6c299b --- /dev/null +++ b/branch/opengraph/_static/jquery-3.6.0.js @@ -0,0 +1,10881 @@ +/*! + * jQuery JavaScript Library v3.6.0 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright OpenJS Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + * + * Date: 2021-03-02T17:08Z + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var flat = arr.flat ? function( array ) { + return arr.flat.call( array ); +} : function( array ) { + return arr.concat.apply( [], array ); +}; + + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + +var isFunction = function isFunction( obj ) { + + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML elements + // (i.e., `typeof document.createElement( "object" ) === "function"`). + // We don't want to classify *any* DOM node as a function. + // Support: QtWeb <=3.8.5, WebKit <=534.34, wkhtmltopdf tool <=0.12.5 + // Plus for old WebKit, typeof returns "function" for HTML collections + // (e.g., `typeof document.getElementsByTagName("div") === "function"`). (gh-4756) + return typeof obj === "function" && typeof obj.nodeType !== "number" && + typeof obj.item !== "function"; + }; + + +var isWindow = function isWindow( obj ) { + return obj != null && obj === obj.window; + }; + + +var document = window.document; + + + + var preservedScriptAttributes = { + type: true, + src: true, + nonce: true, + noModule: true + }; + + function DOMEval( code, node, doc ) { + doc = doc || document; + + var i, val, + script = doc.createElement( "script" ); + + script.text = code; + if ( node ) { + for ( i in preservedScriptAttributes ) { + + // Support: Firefox 64+, Edge 18+ + // Some browsers don't support the "nonce" property on scripts. + // On the other hand, just using `getAttribute` is not enough as + // the `nonce` attribute is reset to an empty string whenever it + // becomes browsing-context connected. + // See https://github.com/whatwg/html/issues/2369 + // See https://html.spec.whatwg.org/#nonce-attributes + // The `node.getAttribute` check was added for the sake of + // `jQuery.globalEval` so that it can fake a nonce-containing node + // via an object. + val = node[ i ] || node.getAttribute && node.getAttribute( i ); + if ( val ) { + script.setAttribute( i, val ); + } + } + } + doc.head.appendChild( script ).parentNode.removeChild( script ); + } + + +function toType( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; +} +/* global Symbol */ +// Defining this global in .eslintrc.json would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.6.0", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + + // Return all the elements in a clean array + if ( num == null ) { + return slice.call( this ); + } + + // Return just the one element from the set + return num < 0 ? this[ num + this.length ] : this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + even: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return ( i + 1 ) % 2; + } ) ); + }, + + odd: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return i % 2; + } ) ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + copy = options[ name ]; + + // Prevent Object.prototype pollution + // Prevent never-ending loop + if ( name === "__proto__" || target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = Array.isArray( copy ) ) ) ) { + src = target[ name ]; + + // Ensure proper type for the source value + if ( copyIsArray && !Array.isArray( src ) ) { + clone = []; + } else if ( !copyIsArray && !jQuery.isPlainObject( src ) ) { + clone = {}; + } else { + clone = src; + } + copyIsArray = false; + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + // Evaluates a script in a provided context; falls back to the global one + // if not specified. + globalEval: function( code, options, doc ) { + DOMEval( code, { nonce: options && options.nonce }, doc ); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return flat( ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), + function( _i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); + } ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = toType( obj ); + + if ( isFunction( obj ) || isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.6 + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://js.foundation/ + * + * Date: 2021-02-16 + */ +( function( window ) { +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + nonnativeSelectorCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ( {} ).hasOwnProperty, + arr = [], + pop = arr.pop, + pushNative = arr.push, + push = arr.push, + slice = arr.slice, + + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[ i ] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|" + + "ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // https://www.w3.org/TR/css-syntax-3/#ident-token-diagram + identifier = "(?:\\\\[\\da-fA-F]{1,6}" + whitespace + + "?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + + // "Attribute values must be CSS identifiers [capture 5] + // or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + + whitespace + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + + "*" ), + rdescend = new RegExp( whitespace + "|>" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + + whitespace + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + + whitespace + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + whitespace + + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rhtml = /HTML$/i, + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\[\\da-fA-F]{1,6}" + whitespace + "?|\\\\([^\\r\\n\\f])", "g" ), + funescape = function( escape, nonHex ) { + var high = "0x" + escape.slice( 1 ) - 0x10000; + + return nonHex ? + + // Strip the backslash prefix from a non-hex escape sequence + nonHex : + + // Replace a hexadecimal escape sequence with the encoded Unicode code point + // Support: IE <=11+ + // For values outside the Basic Multilingual Plane (BMP), manually construct a + // surrogate pair + high < 0 ? + String.fromCharCode( high + 0x10000 ) : + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + inDisabledFieldset = addCombinator( + function( elem ) { + return elem.disabled === true && elem.nodeName.toLowerCase() === "fieldset"; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + ( arr = slice.call( preferredDoc.childNodes ) ), + preferredDoc.childNodes + ); + + // Support: Android<4.0 + // Detect silently failing push.apply + // eslint-disable-next-line no-unused-expressions + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + pushNative.apply( target, slice.call( els ) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + + // Can't trust NodeList.length + while ( ( target[ j++ ] = els[ i++ ] ) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + setDocument( context ); + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && ( match = rquickExpr.exec( selector ) ) ) { + + // ID selector + if ( ( m = match[ 1 ] ) ) { + + // Document context + if ( nodeType === 9 ) { + if ( ( elem = context.getElementById( m ) ) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && ( elem = newContext.getElementById( m ) ) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[ 2 ] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( ( m = match[ 3 ] ) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !nonnativeSelectorCache[ selector + " " ] && + ( !rbuggyQSA || !rbuggyQSA.test( selector ) ) && + + // Support: IE 8 only + // Exclude object elements + ( nodeType !== 1 || context.nodeName.toLowerCase() !== "object" ) ) { + + newSelector = selector; + newContext = context; + + // qSA considers elements outside a scoping root when evaluating child or + // descendant combinators, which is not what we want. + // In such cases, we work around the behavior by prefixing every selector in the + // list with an ID selector referencing the scope context. + // The technique has to be used as well when a leading combinator is used + // as such selectors are not recognized by querySelectorAll. + // Thanks to Andrew Dupont for this technique. + if ( nodeType === 1 && + ( rdescend.test( selector ) || rcombinators.test( selector ) ) ) { + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + + // We can use :scope instead of the ID hack if the browser + // supports it & if we're not changing the context. + if ( newContext !== context || !support.scope ) { + + // Capture the context ID, setting it first if necessary + if ( ( nid = context.getAttribute( "id" ) ) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", ( nid = expando ) ); + } + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[ i ] = ( nid ? "#" + nid : ":scope" ) + " " + + toSelector( groups[ i ] ); + } + newSelector = groups.join( "," ); + } + + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + nonnativeSelectorCache( selector, true ); + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return ( cache[ key + " " ] = value ); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement( "fieldset" ); + + try { + return !!fn( el ); + } catch ( e ) { + return false; + } finally { + + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split( "|" ), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[ i ] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( ( cur = cur.nextSibling ) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return ( name === "input" || name === "button" ) && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + + // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Only certain elements can match :enabled or :disabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled + if ( "form" in elem ) { + + // Check for inherited disabledness on relevant non-disabled elements: + // * listed form-associated elements in a disabled fieldset + // https://html.spec.whatwg.org/multipage/forms.html#category-listed + // https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled + // * option elements in a disabled optgroup + // https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled + // All such elements have a "form" property. + if ( elem.parentNode && elem.disabled === false ) { + + // Option elements defer to a parent optgroup if present + if ( "label" in elem ) { + if ( "label" in elem.parentNode ) { + return elem.parentNode.disabled === disabled; + } else { + return elem.disabled === disabled; + } + } + + // Support: IE 6 - 11 + // Use the isDisabled shortcut property to check for disabled fieldset ancestors + return elem.isDisabled === disabled || + + // Where there is no isDisabled, check manually + /* jshint -W018 */ + elem.isDisabled !== !disabled && + inDisabledFieldset( elem ) === disabled; + } + + return elem.disabled === disabled; + + // Try to winnow out elements that can't be disabled before trusting the disabled property. + // Some victims get caught in our net (label, legend, menu, track), but it shouldn't + // even exist on them, let alone have a boolean value. + } else if ( "label" in elem ) { + return elem.disabled === disabled; + } + + // Remaining elements are neither :enabled nor :disabled + return false; + }; +} + +/** + * Returns a function to use in pseudos for positionals + * @param {Function} fn + */ +function createPositionalPseudo( fn ) { + return markFunction( function( argument ) { + argument = +argument; + return markFunction( function( seed, matches ) { + var j, + matchIndexes = fn( [], seed.length, argument ), + i = matchIndexes.length; + + // Match elements found at the specified indexes + while ( i-- ) { + if ( seed[ ( j = matchIndexes[ i ] ) ] ) { + seed[ j ] = !( matches[ j ] = seed[ j ] ); + } + } + } ); + } ); +} + +/** + * Checks a node for validity as a Sizzle context + * @param {Element|Object=} context + * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + */ +function testContext( context ) { + return context && typeof context.getElementsByTagName !== "undefined" && context; +} + +// Expose support vars for convenience +support = Sizzle.support = {}; + +/** + * Detects XML nodes + * @param {Element|Object} elem An element or a document + * @returns {Boolean} True iff elem is a non-HTML XML node + */ +isXML = Sizzle.isXML = function( elem ) { + var namespace = elem && elem.namespaceURI, + docElem = elem && ( elem.ownerDocument || elem ).documentElement; + + // Support: IE <=8 + // Assume HTML when documentElement doesn't yet exist, such as inside loading iframes + // https://bugs.jquery.com/ticket/4833 + return !rhtml.test( namespace || docElem && docElem.nodeName || "HTML" ); +}; + +/** + * Sets document-related variables once based on the current document + * @param {Element|Object} [doc] An element or document object to use to set the document + * @returns {Object} Returns the current document + */ +setDocument = Sizzle.setDocument = function( node ) { + var hasCompare, subWindow, + doc = node ? node.ownerDocument || node : preferredDoc; + + // Return early if doc is invalid or already selected + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( doc == document || doc.nodeType !== 9 || !doc.documentElement ) { + return document; + } + + // Update global variables + document = doc; + docElem = document.documentElement; + documentIsHTML = !isXML( document ); + + // Support: IE 9 - 11+, Edge 12 - 18+ + // Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936) + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( preferredDoc != document && + ( subWindow = document.defaultView ) && subWindow.top !== subWindow ) { + + // Support: IE 11, Edge + if ( subWindow.addEventListener ) { + subWindow.addEventListener( "unload", unloadHandler, false ); + + // Support: IE 9 - 10 only + } else if ( subWindow.attachEvent ) { + subWindow.attachEvent( "onunload", unloadHandler ); + } + } + + // Support: IE 8 - 11+, Edge 12 - 18+, Chrome <=16 - 25 only, Firefox <=3.6 - 31 only, + // Safari 4 - 5 only, Opera <=11.6 - 12.x only + // IE/Edge & older browsers don't support the :scope pseudo-class. + // Support: Safari 6.0 only + // Safari 6.0 supports :scope but it's an alias of :root there. + support.scope = assert( function( el ) { + docElem.appendChild( el ).appendChild( document.createElement( "div" ) ); + return typeof el.querySelectorAll !== "undefined" && + !el.querySelectorAll( ":scope fieldset div" ).length; + } ); + + /* Attributes + ---------------------------------------------------------------------- */ + + // Support: IE<8 + // Verify that getAttribute really returns attributes and not properties + // (excepting IE8 booleans) + support.attributes = assert( function( el ) { + el.className = "i"; + return !el.getAttribute( "className" ); + } ); + + /* getElement(s)By* + ---------------------------------------------------------------------- */ + + // Check if getElementsByTagName("*") returns only elements + support.getElementsByTagName = assert( function( el ) { + el.appendChild( document.createComment( "" ) ); + return !el.getElementsByTagName( "*" ).length; + } ); + + // Support: IE<9 + support.getElementsByClassName = rnative.test( document.getElementsByClassName ); + + // Support: IE<10 + // Check if getElementById returns elements by name + // The broken getElementById methods don't pick up programmatically-set names, + // so use a roundabout getElementsByName test + support.getById = assert( function( el ) { + docElem.appendChild( el ).id = expando; + return !document.getElementsByName || !document.getElementsByName( expando ).length; + } ); + + // ID filter and find + if ( support.getById ) { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + return elem.getAttribute( "id" ) === attrId; + }; + }; + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var elem = context.getElementById( id ); + return elem ? [ elem ] : []; + } + }; + } else { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + var node = typeof elem.getAttributeNode !== "undefined" && + elem.getAttributeNode( "id" ); + return node && node.value === attrId; + }; + }; + + // Support: IE 6 - 7 only + // getElementById is not reliable as a find shortcut + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var node, i, elems, + elem = context.getElementById( id ); + + if ( elem ) { + + // Verify the id attribute + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + + // Fall back on getElementsByName + elems = context.getElementsByName( id ); + i = 0; + while ( ( elem = elems[ i++ ] ) ) { + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + } + } + + return []; + } + }; + } + + // Tag + Expr.find[ "TAG" ] = support.getElementsByTagName ? + function( tag, context ) { + if ( typeof context.getElementsByTagName !== "undefined" ) { + return context.getElementsByTagName( tag ); + + // DocumentFragment nodes don't have gEBTN + } else if ( support.qsa ) { + return context.querySelectorAll( tag ); + } + } : + + function( tag, context ) { + var elem, + tmp = [], + i = 0, + + // By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too + results = context.getElementsByTagName( tag ); + + // Filter out possible comments + if ( tag === "*" ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem.nodeType === 1 ) { + tmp.push( elem ); + } + } + + return tmp; + } + return results; + }; + + // Class + Expr.find[ "CLASS" ] = support.getElementsByClassName && function( className, context ) { + if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) { + return context.getElementsByClassName( className ); + } + }; + + /* QSA/matchesSelector + ---------------------------------------------------------------------- */ + + // QSA and matchesSelector support + + // matchesSelector(:active) reports false when true (IE9/Opera 11.5) + rbuggyMatches = []; + + // qSa(:focus) reports false when true (Chrome 21) + // We allow this because of a bug in IE8/9 that throws an error + // whenever `document.activeElement` is accessed on an iframe + // So, we allow :focus to pass through QSA all the time to avoid the IE error + // See https://bugs.jquery.com/ticket/13378 + rbuggyQSA = []; + + if ( ( support.qsa = rnative.test( document.querySelectorAll ) ) ) { + + // Build QSA regex + // Regex strategy adopted from Diego Perini + assert( function( el ) { + + var input; + + // Select is set to empty string on purpose + // This is to test IE's treatment of not explicitly + // setting a boolean content attribute, + // since its presence should be enough + // https://bugs.jquery.com/ticket/12359 + docElem.appendChild( el ).innerHTML = "" + + ""; + + // Support: IE8, Opera 11-12.16 + // Nothing should be selected when empty strings follow ^= or $= or *= + // The test attribute must be unknown in Opera but "safe" for WinRT + // https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section + if ( el.querySelectorAll( "[msallowcapture^='']" ).length ) { + rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); + } + + // Support: IE8 + // Boolean attributes and "value" are not treated correctly + if ( !el.querySelectorAll( "[selected]" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); + } + + // Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+ + if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) { + rbuggyQSA.push( "~=" ); + } + + // Support: IE 11+, Edge 15 - 18+ + // IE 11/Edge don't find elements on a `[name='']` query in some cases. + // Adding a temporary attribute to the document before the selection works + // around the issue. + // Interestingly, IE 10 & older don't seem to have the issue. + input = document.createElement( "input" ); + input.setAttribute( "name", "" ); + el.appendChild( input ); + if ( !el.querySelectorAll( "[name='']" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*name" + whitespace + "*=" + + whitespace + "*(?:''|\"\")" ); + } + + // Webkit/Opera - :checked should return selected option elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + // IE8 throws error here and will not see later tests + if ( !el.querySelectorAll( ":checked" ).length ) { + rbuggyQSA.push( ":checked" ); + } + + // Support: Safari 8+, iOS 8+ + // https://bugs.webkit.org/show_bug.cgi?id=136851 + // In-page `selector#id sibling-combinator selector` fails + if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) { + rbuggyQSA.push( ".#.+[+~]" ); + } + + // Support: Firefox <=3.6 - 5 only + // Old Firefox doesn't throw on a badly-escaped identifier. + el.querySelectorAll( "\\\f" ); + rbuggyQSA.push( "[\\r\\n\\f]" ); + } ); + + assert( function( el ) { + el.innerHTML = "" + + ""; + + // Support: Windows 8 Native Apps + // The type and name attributes are restricted during .innerHTML assignment + var input = document.createElement( "input" ); + input.setAttribute( "type", "hidden" ); + el.appendChild( input ).setAttribute( "name", "D" ); + + // Support: IE8 + // Enforce case-sensitivity of name attribute + if ( el.querySelectorAll( "[name=d]" ).length ) { + rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); + } + + // FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled) + // IE8 throws error here and will not see later tests + if ( el.querySelectorAll( ":enabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: IE9-11+ + // IE's :disabled selector does not pick up the children of disabled fieldsets + docElem.appendChild( el ).disabled = true; + if ( el.querySelectorAll( ":disabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: Opera 10 - 11 only + // Opera 10-11 does not throw on post-comma invalid pseudos + el.querySelectorAll( "*,:x" ); + rbuggyQSA.push( ",.*:" ); + } ); + } + + if ( ( support.matchesSelector = rnative.test( ( matches = docElem.matches || + docElem.webkitMatchesSelector || + docElem.mozMatchesSelector || + docElem.oMatchesSelector || + docElem.msMatchesSelector ) ) ) ) { + + assert( function( el ) { + + // Check to see if it's possible to do matchesSelector + // on a disconnected node (IE 9) + support.disconnectedMatch = matches.call( el, "*" ); + + // This should fail with an exception + // Gecko does not error, returns false instead + matches.call( el, "[s!='']:x" ); + rbuggyMatches.push( "!=", pseudos ); + } ); + } + + rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join( "|" ) ); + rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join( "|" ) ); + + /* Contains + ---------------------------------------------------------------------- */ + hasCompare = rnative.test( docElem.compareDocumentPosition ); + + // Element contains another + // Purposefully self-exclusive + // As in, an element does not contain itself + contains = hasCompare || rnative.test( docElem.contains ) ? + function( a, b ) { + var adown = a.nodeType === 9 ? a.documentElement : a, + bup = b && b.parentNode; + return a === bup || !!( bup && bup.nodeType === 1 && ( + adown.contains ? + adown.contains( bup ) : + a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 + ) ); + } : + function( a, b ) { + if ( b ) { + while ( ( b = b.parentNode ) ) { + if ( b === a ) { + return true; + } + } + } + return false; + }; + + /* Sorting + ---------------------------------------------------------------------- */ + + // Document order sorting + sortOrder = hasCompare ? + function( a, b ) { + + // Flag for duplicate removal + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + // Sort on method existence if only one input has compareDocumentPosition + var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; + if ( compare ) { + return compare; + } + + // Calculate position if both inputs belong to the same document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + compare = ( a.ownerDocument || a ) == ( b.ownerDocument || b ) ? + a.compareDocumentPosition( b ) : + + // Otherwise we know they are disconnected + 1; + + // Disconnected nodes + if ( compare & 1 || + ( !support.sortDetached && b.compareDocumentPosition( a ) === compare ) ) { + + // Choose the first element that is related to our preferred document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( a == document || a.ownerDocument == preferredDoc && + contains( preferredDoc, a ) ) { + return -1; + } + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( b == document || b.ownerDocument == preferredDoc && + contains( preferredDoc, b ) ) { + return 1; + } + + // Maintain original order + return sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + } + + return compare & 4 ? -1 : 1; + } : + function( a, b ) { + + // Exit early if the nodes are identical + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + var cur, + i = 0, + aup = a.parentNode, + bup = b.parentNode, + ap = [ a ], + bp = [ b ]; + + // Parentless nodes are either documents or disconnected + if ( !aup || !bup ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + return a == document ? -1 : + b == document ? 1 : + /* eslint-enable eqeqeq */ + aup ? -1 : + bup ? 1 : + sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + + // If the nodes are siblings, we can do a quick check + } else if ( aup === bup ) { + return siblingCheck( a, b ); + } + + // Otherwise we need full lists of their ancestors for comparison + cur = a; + while ( ( cur = cur.parentNode ) ) { + ap.unshift( cur ); + } + cur = b; + while ( ( cur = cur.parentNode ) ) { + bp.unshift( cur ); + } + + // Walk down the tree looking for a discrepancy + while ( ap[ i ] === bp[ i ] ) { + i++; + } + + return i ? + + // Do a sibling check if the nodes have a common ancestor + siblingCheck( ap[ i ], bp[ i ] ) : + + // Otherwise nodes in our document sort first + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + ap[ i ] == preferredDoc ? -1 : + bp[ i ] == preferredDoc ? 1 : + /* eslint-enable eqeqeq */ + 0; + }; + + return document; +}; + +Sizzle.matches = function( expr, elements ) { + return Sizzle( expr, null, null, elements ); +}; + +Sizzle.matchesSelector = function( elem, expr ) { + setDocument( elem ); + + if ( support.matchesSelector && documentIsHTML && + !nonnativeSelectorCache[ expr + " " ] && + ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && + ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { + + try { + var ret = matches.call( elem, expr ); + + // IE 9's matchesSelector returns false on disconnected nodes + if ( ret || support.disconnectedMatch || + + // As well, disconnected nodes are said to be in a document + // fragment in IE 9 + elem.document && elem.document.nodeType !== 11 ) { + return ret; + } + } catch ( e ) { + nonnativeSelectorCache( expr, true ); + } + } + + return Sizzle( expr, document, null, [ elem ] ).length > 0; +}; + +Sizzle.contains = function( context, elem ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( context.ownerDocument || context ) != document ) { + setDocument( context ); + } + return contains( context, elem ); +}; + +Sizzle.attr = function( elem, name ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( elem.ownerDocument || elem ) != document ) { + setDocument( elem ); + } + + var fn = Expr.attrHandle[ name.toLowerCase() ], + + // Don't get fooled by Object.prototype properties (jQuery #13807) + val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? + fn( elem, name, !documentIsHTML ) : + undefined; + + return val !== undefined ? + val : + support.attributes || !documentIsHTML ? + elem.getAttribute( name ) : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; +}; + +Sizzle.escape = function( sel ) { + return ( sel + "" ).replace( rcssescape, fcssescape ); +}; + +Sizzle.error = function( msg ) { + throw new Error( "Syntax error, unrecognized expression: " + msg ); +}; + +/** + * Document sorting and removing duplicates + * @param {ArrayLike} results + */ +Sizzle.uniqueSort = function( results ) { + var elem, + duplicates = [], + j = 0, + i = 0; + + // Unless we *know* we can detect duplicates, assume their presence + hasDuplicate = !support.detectDuplicates; + sortInput = !support.sortStable && results.slice( 0 ); + results.sort( sortOrder ); + + if ( hasDuplicate ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem === results[ i ] ) { + j = duplicates.push( i ); + } + } + while ( j-- ) { + results.splice( duplicates[ j ], 1 ); + } + } + + // Clear input after sorting to release objects + // See https://github.com/jquery/sizzle/pull/225 + sortInput = null; + + return results; +}; + +/** + * Utility function for retrieving the text value of an array of DOM nodes + * @param {Array|Element} elem + */ +getText = Sizzle.getText = function( elem ) { + var node, + ret = "", + i = 0, + nodeType = elem.nodeType; + + if ( !nodeType ) { + + // If no nodeType, this is expected to be an array + while ( ( node = elem[ i++ ] ) ) { + + // Do not traverse comment nodes + ret += getText( node ); + } + } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { + + // Use textContent for elements + // innerText usage removed for consistency of new lines (jQuery #11153) + if ( typeof elem.textContent === "string" ) { + return elem.textContent; + } else { + + // Traverse its children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + ret += getText( elem ); + } + } + } else if ( nodeType === 3 || nodeType === 4 ) { + return elem.nodeValue; + } + + // Do not include comment or processing instruction nodes + + return ret; +}; + +Expr = Sizzle.selectors = { + + // Can be adjusted by the user + cacheLength: 50, + + createPseudo: markFunction, + + match: matchExpr, + + attrHandle: {}, + + find: {}, + + relative: { + ">": { dir: "parentNode", first: true }, + " ": { dir: "parentNode" }, + "+": { dir: "previousSibling", first: true }, + "~": { dir: "previousSibling" } + }, + + preFilter: { + "ATTR": function( match ) { + match[ 1 ] = match[ 1 ].replace( runescape, funescape ); + + // Move the given value to match[3] whether quoted or unquoted + match[ 3 ] = ( match[ 3 ] || match[ 4 ] || + match[ 5 ] || "" ).replace( runescape, funescape ); + + if ( match[ 2 ] === "~=" ) { + match[ 3 ] = " " + match[ 3 ] + " "; + } + + return match.slice( 0, 4 ); + }, + + "CHILD": function( match ) { + + /* matches from matchExpr["CHILD"] + 1 type (only|nth|...) + 2 what (child|of-type) + 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) + 4 xn-component of xn+y argument ([+-]?\d*n|) + 5 sign of xn-component + 6 x of xn-component + 7 sign of y-component + 8 y of y-component + */ + match[ 1 ] = match[ 1 ].toLowerCase(); + + if ( match[ 1 ].slice( 0, 3 ) === "nth" ) { + + // nth-* requires argument + if ( !match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + // numeric x and y parameters for Expr.filter.CHILD + // remember that false/true cast respectively to 0/1 + match[ 4 ] = +( match[ 4 ] ? + match[ 5 ] + ( match[ 6 ] || 1 ) : + 2 * ( match[ 3 ] === "even" || match[ 3 ] === "odd" ) ); + match[ 5 ] = +( ( match[ 7 ] + match[ 8 ] ) || match[ 3 ] === "odd" ); + + // other types prohibit arguments + } else if ( match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + return match; + }, + + "PSEUDO": function( match ) { + var excess, + unquoted = !match[ 6 ] && match[ 2 ]; + + if ( matchExpr[ "CHILD" ].test( match[ 0 ] ) ) { + return null; + } + + // Accept quoted arguments as-is + if ( match[ 3 ] ) { + match[ 2 ] = match[ 4 ] || match[ 5 ] || ""; + + // Strip excess characters from unquoted arguments + } else if ( unquoted && rpseudo.test( unquoted ) && + + // Get excess from tokenize (recursively) + ( excess = tokenize( unquoted, true ) ) && + + // advance to the next closing parenthesis + ( excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length ) ) { + + // excess is a negative index + match[ 0 ] = match[ 0 ].slice( 0, excess ); + match[ 2 ] = unquoted.slice( 0, excess ); + } + + // Return only captures needed by the pseudo filter method (type and argument) + return match.slice( 0, 3 ); + } + }, + + filter: { + + "TAG": function( nodeNameSelector ) { + var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); + return nodeNameSelector === "*" ? + function() { + return true; + } : + function( elem ) { + return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; + }; + }, + + "CLASS": function( className ) { + var pattern = classCache[ className + " " ]; + + return pattern || + ( pattern = new RegExp( "(^|" + whitespace + + ")" + className + "(" + whitespace + "|$)" ) ) && classCache( + className, function( elem ) { + return pattern.test( + typeof elem.className === "string" && elem.className || + typeof elem.getAttribute !== "undefined" && + elem.getAttribute( "class" ) || + "" + ); + } ); + }, + + "ATTR": function( name, operator, check ) { + return function( elem ) { + var result = Sizzle.attr( elem, name ); + + if ( result == null ) { + return operator === "!="; + } + if ( !operator ) { + return true; + } + + result += ""; + + /* eslint-disable max-len */ + + return operator === "=" ? result === check : + operator === "!=" ? result !== check : + operator === "^=" ? check && result.indexOf( check ) === 0 : + operator === "*=" ? check && result.indexOf( check ) > -1 : + operator === "$=" ? check && result.slice( -check.length ) === check : + operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 : + operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : + false; + /* eslint-enable max-len */ + + }; + }, + + "CHILD": function( type, what, _argument, first, last ) { + var simple = type.slice( 0, 3 ) !== "nth", + forward = type.slice( -4 ) !== "last", + ofType = what === "of-type"; + + return first === 1 && last === 0 ? + + // Shortcut for :nth-*(n) + function( elem ) { + return !!elem.parentNode; + } : + + function( elem, _context, xml ) { + var cache, uniqueCache, outerCache, node, nodeIndex, start, + dir = simple !== forward ? "nextSibling" : "previousSibling", + parent = elem.parentNode, + name = ofType && elem.nodeName.toLowerCase(), + useCache = !xml && !ofType, + diff = false; + + if ( parent ) { + + // :(first|last|only)-(child|of-type) + if ( simple ) { + while ( dir ) { + node = elem; + while ( ( node = node[ dir ] ) ) { + if ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) { + + return false; + } + } + + // Reverse direction for :only-* (if we haven't yet done so) + start = dir = type === "only" && !start && "nextSibling"; + } + return true; + } + + start = [ forward ? parent.firstChild : parent.lastChild ]; + + // non-xml :nth-child(...) stores cache data on `parent` + if ( forward && useCache ) { + + // Seek `elem` from a previously-cached index + + // ...in a gzip-friendly way + node = parent; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex && cache[ 2 ]; + node = nodeIndex && parent.childNodes[ nodeIndex ]; + + while ( ( node = ++nodeIndex && node && node[ dir ] || + + // Fallback to seeking `elem` from the start + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + // When found, cache indexes on `parent` and break + if ( node.nodeType === 1 && ++diff && node === elem ) { + uniqueCache[ type ] = [ dirruns, nodeIndex, diff ]; + break; + } + } + + } else { + + // Use previously-cached element index if available + if ( useCache ) { + + // ...in a gzip-friendly way + node = elem; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex; + } + + // xml :nth-child(...) + // or :nth-last-child(...) or :nth(-last)?-of-type(...) + if ( diff === false ) { + + // Use the same loop as above to seek `elem` from the start + while ( ( node = ++nodeIndex && node && node[ dir ] || + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + if ( ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) && + ++diff ) { + + // Cache the index of each encountered element + if ( useCache ) { + outerCache = node[ expando ] || + ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + uniqueCache[ type ] = [ dirruns, diff ]; + } + + if ( node === elem ) { + break; + } + } + } + } + } + + // Incorporate the offset, then check against cycle size + diff -= last; + return diff === first || ( diff % first === 0 && diff / first >= 0 ); + } + }; + }, + + "PSEUDO": function( pseudo, argument ) { + + // pseudo-class names are case-insensitive + // http://www.w3.org/TR/selectors/#pseudo-classes + // Prioritize by case sensitivity in case custom pseudos are added with uppercase letters + // Remember that setFilters inherits from pseudos + var args, + fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || + Sizzle.error( "unsupported pseudo: " + pseudo ); + + // The user may use createPseudo to indicate that + // arguments are needed to create the filter function + // just as Sizzle does + if ( fn[ expando ] ) { + return fn( argument ); + } + + // But maintain support for old signatures + if ( fn.length > 1 ) { + args = [ pseudo, pseudo, "", argument ]; + return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? + markFunction( function( seed, matches ) { + var idx, + matched = fn( seed, argument ), + i = matched.length; + while ( i-- ) { + idx = indexOf( seed, matched[ i ] ); + seed[ idx ] = !( matches[ idx ] = matched[ i ] ); + } + } ) : + function( elem ) { + return fn( elem, 0, args ); + }; + } + + return fn; + } + }, + + pseudos: { + + // Potentially complex pseudos + "not": markFunction( function( selector ) { + + // Trim the selector passed to compile + // to avoid treating leading and trailing + // spaces as combinators + var input = [], + results = [], + matcher = compile( selector.replace( rtrim, "$1" ) ); + + return matcher[ expando ] ? + markFunction( function( seed, matches, _context, xml ) { + var elem, + unmatched = matcher( seed, null, xml, [] ), + i = seed.length; + + // Match elements unmatched by `matcher` + while ( i-- ) { + if ( ( elem = unmatched[ i ] ) ) { + seed[ i ] = !( matches[ i ] = elem ); + } + } + } ) : + function( elem, _context, xml ) { + input[ 0 ] = elem; + matcher( input, null, xml, results ); + + // Don't keep the element (issue #299) + input[ 0 ] = null; + return !results.pop(); + }; + } ), + + "has": markFunction( function( selector ) { + return function( elem ) { + return Sizzle( selector, elem ).length > 0; + }; + } ), + + "contains": markFunction( function( text ) { + text = text.replace( runescape, funescape ); + return function( elem ) { + return ( elem.textContent || getText( elem ) ).indexOf( text ) > -1; + }; + } ), + + // "Whether an element is represented by a :lang() selector + // is based solely on the element's language value + // being equal to the identifier C, + // or beginning with the identifier C immediately followed by "-". + // The matching of C against the element's language value is performed case-insensitively. + // The identifier C does not have to be a valid language name." + // http://www.w3.org/TR/selectors/#lang-pseudo + "lang": markFunction( function( lang ) { + + // lang value must be a valid identifier + if ( !ridentifier.test( lang || "" ) ) { + Sizzle.error( "unsupported lang: " + lang ); + } + lang = lang.replace( runescape, funescape ).toLowerCase(); + return function( elem ) { + var elemLang; + do { + if ( ( elemLang = documentIsHTML ? + elem.lang : + elem.getAttribute( "xml:lang" ) || elem.getAttribute( "lang" ) ) ) { + + elemLang = elemLang.toLowerCase(); + return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; + } + } while ( ( elem = elem.parentNode ) && elem.nodeType === 1 ); + return false; + }; + } ), + + // Miscellaneous + "target": function( elem ) { + var hash = window.location && window.location.hash; + return hash && hash.slice( 1 ) === elem.id; + }, + + "root": function( elem ) { + return elem === docElem; + }, + + "focus": function( elem ) { + return elem === document.activeElement && + ( !document.hasFocus || document.hasFocus() ) && + !!( elem.type || elem.href || ~elem.tabIndex ); + }, + + // Boolean properties + "enabled": createDisabledPseudo( false ), + "disabled": createDisabledPseudo( true ), + + "checked": function( elem ) { + + // In CSS3, :checked should return both checked and selected elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + var nodeName = elem.nodeName.toLowerCase(); + return ( nodeName === "input" && !!elem.checked ) || + ( nodeName === "option" && !!elem.selected ); + }, + + "selected": function( elem ) { + + // Accessing this property makes selected-by-default + // options in Safari work properly + if ( elem.parentNode ) { + // eslint-disable-next-line no-unused-expressions + elem.parentNode.selectedIndex; + } + + return elem.selected === true; + }, + + // Contents + "empty": function( elem ) { + + // http://www.w3.org/TR/selectors/#empty-pseudo + // :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5), + // but not by others (comment: 8; processing instruction: 7; etc.) + // nodeType < 6 works because attributes (2) do not appear as children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + if ( elem.nodeType < 6 ) { + return false; + } + } + return true; + }, + + "parent": function( elem ) { + return !Expr.pseudos[ "empty" ]( elem ); + }, + + // Element/input types + "header": function( elem ) { + return rheader.test( elem.nodeName ); + }, + + "input": function( elem ) { + return rinputs.test( elem.nodeName ); + }, + + "button": function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === "button" || name === "button"; + }, + + "text": function( elem ) { + var attr; + return elem.nodeName.toLowerCase() === "input" && + elem.type === "text" && + + // Support: IE<8 + // New HTML5 attribute values (e.g., "search") appear with elem.type === "text" + ( ( attr = elem.getAttribute( "type" ) ) == null || + attr.toLowerCase() === "text" ); + }, + + // Position-in-collection + "first": createPositionalPseudo( function() { + return [ 0 ]; + } ), + + "last": createPositionalPseudo( function( _matchIndexes, length ) { + return [ length - 1 ]; + } ), + + "eq": createPositionalPseudo( function( _matchIndexes, length, argument ) { + return [ argument < 0 ? argument + length : argument ]; + } ), + + "even": createPositionalPseudo( function( matchIndexes, length ) { + var i = 0; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "odd": createPositionalPseudo( function( matchIndexes, length ) { + var i = 1; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "lt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? + argument + length : + argument > length ? + length : + argument; + for ( ; --i >= 0; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "gt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? argument + length : argument; + for ( ; ++i < length; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ) + } +}; + +Expr.pseudos[ "nth" ] = Expr.pseudos[ "eq" ]; + +// Add button/input type pseudos +for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { + Expr.pseudos[ i ] = createInputPseudo( i ); +} +for ( i in { submit: true, reset: true } ) { + Expr.pseudos[ i ] = createButtonPseudo( i ); +} + +// Easy API for creating new setFilters +function setFilters() {} +setFilters.prototype = Expr.filters = Expr.pseudos; +Expr.setFilters = new setFilters(); + +tokenize = Sizzle.tokenize = function( selector, parseOnly ) { + var matched, match, tokens, type, + soFar, groups, preFilters, + cached = tokenCache[ selector + " " ]; + + if ( cached ) { + return parseOnly ? 0 : cached.slice( 0 ); + } + + soFar = selector; + groups = []; + preFilters = Expr.preFilter; + + while ( soFar ) { + + // Comma and first run + if ( !matched || ( match = rcomma.exec( soFar ) ) ) { + if ( match ) { + + // Don't consume trailing commas as valid + soFar = soFar.slice( match[ 0 ].length ) || soFar; + } + groups.push( ( tokens = [] ) ); + } + + matched = false; + + // Combinators + if ( ( match = rcombinators.exec( soFar ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + + // Cast descendant combinators to space + type: match[ 0 ].replace( rtrim, " " ) + } ); + soFar = soFar.slice( matched.length ); + } + + // Filters + for ( type in Expr.filter ) { + if ( ( match = matchExpr[ type ].exec( soFar ) ) && ( !preFilters[ type ] || + ( match = preFilters[ type ]( match ) ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + type: type, + matches: match + } ); + soFar = soFar.slice( matched.length ); + } + } + + if ( !matched ) { + break; + } + } + + // Return the length of the invalid excess + // if we're just parsing + // Otherwise, throw an error or return tokens + return parseOnly ? + soFar.length : + soFar ? + Sizzle.error( selector ) : + + // Cache the tokens + tokenCache( selector, groups ).slice( 0 ); +}; + +function toSelector( tokens ) { + var i = 0, + len = tokens.length, + selector = ""; + for ( ; i < len; i++ ) { + selector += tokens[ i ].value; + } + return selector; +} + +function addCombinator( matcher, combinator, base ) { + var dir = combinator.dir, + skip = combinator.next, + key = skip || dir, + checkNonElements = base && key === "parentNode", + doneName = done++; + + return combinator.first ? + + // Check against closest ancestor/preceding element + function( elem, context, xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + return matcher( elem, context, xml ); + } + } + return false; + } : + + // Check against all ancestor/preceding elements + function( elem, context, xml ) { + var oldCache, uniqueCache, outerCache, + newCache = [ dirruns, doneName ]; + + // We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching + if ( xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + if ( matcher( elem, context, xml ) ) { + return true; + } + } + } + } else { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + outerCache = elem[ expando ] || ( elem[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ elem.uniqueID ] || + ( outerCache[ elem.uniqueID ] = {} ); + + if ( skip && skip === elem.nodeName.toLowerCase() ) { + elem = elem[ dir ] || elem; + } else if ( ( oldCache = uniqueCache[ key ] ) && + oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { + + // Assign to newCache so results back-propagate to previous elements + return ( newCache[ 2 ] = oldCache[ 2 ] ); + } else { + + // Reuse newcache so results back-propagate to previous elements + uniqueCache[ key ] = newCache; + + // A match means we're done; a fail means we have to keep checking + if ( ( newCache[ 2 ] = matcher( elem, context, xml ) ) ) { + return true; + } + } + } + } + } + return false; + }; +} + +function elementMatcher( matchers ) { + return matchers.length > 1 ? + function( elem, context, xml ) { + var i = matchers.length; + while ( i-- ) { + if ( !matchers[ i ]( elem, context, xml ) ) { + return false; + } + } + return true; + } : + matchers[ 0 ]; +} + +function multipleContexts( selector, contexts, results ) { + var i = 0, + len = contexts.length; + for ( ; i < len; i++ ) { + Sizzle( selector, contexts[ i ], results ); + } + return results; +} + +function condense( unmatched, map, filter, context, xml ) { + var elem, + newUnmatched = [], + i = 0, + len = unmatched.length, + mapped = map != null; + + for ( ; i < len; i++ ) { + if ( ( elem = unmatched[ i ] ) ) { + if ( !filter || filter( elem, context, xml ) ) { + newUnmatched.push( elem ); + if ( mapped ) { + map.push( i ); + } + } + } + } + + return newUnmatched; +} + +function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { + if ( postFilter && !postFilter[ expando ] ) { + postFilter = setMatcher( postFilter ); + } + if ( postFinder && !postFinder[ expando ] ) { + postFinder = setMatcher( postFinder, postSelector ); + } + return markFunction( function( seed, results, context, xml ) { + var temp, i, elem, + preMap = [], + postMap = [], + preexisting = results.length, + + // Get initial elements from seed or context + elems = seed || multipleContexts( + selector || "*", + context.nodeType ? [ context ] : context, + [] + ), + + // Prefilter to get matcher input, preserving a map for seed-results synchronization + matcherIn = preFilter && ( seed || !selector ) ? + condense( elems, preMap, preFilter, context, xml ) : + elems, + + matcherOut = matcher ? + + // If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results, + postFinder || ( seed ? preFilter : preexisting || postFilter ) ? + + // ...intermediate processing is necessary + [] : + + // ...otherwise use results directly + results : + matcherIn; + + // Find primary matches + if ( matcher ) { + matcher( matcherIn, matcherOut, context, xml ); + } + + // Apply postFilter + if ( postFilter ) { + temp = condense( matcherOut, postMap ); + postFilter( temp, [], context, xml ); + + // Un-match failing elements by moving them back to matcherIn + i = temp.length; + while ( i-- ) { + if ( ( elem = temp[ i ] ) ) { + matcherOut[ postMap[ i ] ] = !( matcherIn[ postMap[ i ] ] = elem ); + } + } + } + + if ( seed ) { + if ( postFinder || preFilter ) { + if ( postFinder ) { + + // Get the final matcherOut by condensing this intermediate into postFinder contexts + temp = []; + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) ) { + + // Restore matcherIn since elem is not yet a final match + temp.push( ( matcherIn[ i ] = elem ) ); + } + } + postFinder( null, ( matcherOut = [] ), temp, xml ); + } + + // Move matched elements from seed to results to keep them synchronized + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) && + ( temp = postFinder ? indexOf( seed, elem ) : preMap[ i ] ) > -1 ) { + + seed[ temp ] = !( results[ temp ] = elem ); + } + } + } + + // Add elements to results, through postFinder if defined + } else { + matcherOut = condense( + matcherOut === results ? + matcherOut.splice( preexisting, matcherOut.length ) : + matcherOut + ); + if ( postFinder ) { + postFinder( null, results, matcherOut, xml ); + } else { + push.apply( results, matcherOut ); + } + } + } ); +} + +function matcherFromTokens( tokens ) { + var checkContext, matcher, j, + len = tokens.length, + leadingRelative = Expr.relative[ tokens[ 0 ].type ], + implicitRelative = leadingRelative || Expr.relative[ " " ], + i = leadingRelative ? 1 : 0, + + // The foundational matcher ensures that elements are reachable from top-level context(s) + matchContext = addCombinator( function( elem ) { + return elem === checkContext; + }, implicitRelative, true ), + matchAnyContext = addCombinator( function( elem ) { + return indexOf( checkContext, elem ) > -1; + }, implicitRelative, true ), + matchers = [ function( elem, context, xml ) { + var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( + ( checkContext = context ).nodeType ? + matchContext( elem, context, xml ) : + matchAnyContext( elem, context, xml ) ); + + // Avoid hanging onto element (issue #299) + checkContext = null; + return ret; + } ]; + + for ( ; i < len; i++ ) { + if ( ( matcher = Expr.relative[ tokens[ i ].type ] ) ) { + matchers = [ addCombinator( elementMatcher( matchers ), matcher ) ]; + } else { + matcher = Expr.filter[ tokens[ i ].type ].apply( null, tokens[ i ].matches ); + + // Return special upon seeing a positional matcher + if ( matcher[ expando ] ) { + + // Find the next relative operator (if any) for proper handling + j = ++i; + for ( ; j < len; j++ ) { + if ( Expr.relative[ tokens[ j ].type ] ) { + break; + } + } + return setMatcher( + i > 1 && elementMatcher( matchers ), + i > 1 && toSelector( + + // If the preceding token was a descendant combinator, insert an implicit any-element `*` + tokens + .slice( 0, i - 1 ) + .concat( { value: tokens[ i - 2 ].type === " " ? "*" : "" } ) + ).replace( rtrim, "$1" ), + matcher, + i < j && matcherFromTokens( tokens.slice( i, j ) ), + j < len && matcherFromTokens( ( tokens = tokens.slice( j ) ) ), + j < len && toSelector( tokens ) + ); + } + matchers.push( matcher ); + } + } + + return elementMatcher( matchers ); +} + +function matcherFromGroupMatchers( elementMatchers, setMatchers ) { + var bySet = setMatchers.length > 0, + byElement = elementMatchers.length > 0, + superMatcher = function( seed, context, xml, results, outermost ) { + var elem, j, matcher, + matchedCount = 0, + i = "0", + unmatched = seed && [], + setMatched = [], + contextBackup = outermostContext, + + // We must always have either seed elements or outermost context + elems = seed || byElement && Expr.find[ "TAG" ]( "*", outermost ), + + // Use integer dirruns iff this is the outermost matcher + dirrunsUnique = ( dirruns += contextBackup == null ? 1 : Math.random() || 0.1 ), + len = elems.length; + + if ( outermost ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + outermostContext = context == document || context || outermost; + } + + // Add elements passing elementMatchers directly to results + // Support: IE<9, Safari + // Tolerate NodeList properties (IE: "length"; Safari: ) matching elements by id + for ( ; i !== len && ( elem = elems[ i ] ) != null; i++ ) { + if ( byElement && elem ) { + j = 0; + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( !context && elem.ownerDocument != document ) { + setDocument( elem ); + xml = !documentIsHTML; + } + while ( ( matcher = elementMatchers[ j++ ] ) ) { + if ( matcher( elem, context || document, xml ) ) { + results.push( elem ); + break; + } + } + if ( outermost ) { + dirruns = dirrunsUnique; + } + } + + // Track unmatched elements for set filters + if ( bySet ) { + + // They will have gone through all possible matchers + if ( ( elem = !matcher && elem ) ) { + matchedCount--; + } + + // Lengthen the array for every element, matched or not + if ( seed ) { + unmatched.push( elem ); + } + } + } + + // `i` is now the count of elements visited above, and adding it to `matchedCount` + // makes the latter nonnegative. + matchedCount += i; + + // Apply set filters to unmatched elements + // NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount` + // equals `i`), unless we didn't visit _any_ elements in the above loop because we have + // no element matchers and no seed. + // Incrementing an initially-string "0" `i` allows `i` to remain a string only in that + // case, which will result in a "00" `matchedCount` that differs from `i` but is also + // numerically zero. + if ( bySet && i !== matchedCount ) { + j = 0; + while ( ( matcher = setMatchers[ j++ ] ) ) { + matcher( unmatched, setMatched, context, xml ); + } + + if ( seed ) { + + // Reintegrate element matches to eliminate the need for sorting + if ( matchedCount > 0 ) { + while ( i-- ) { + if ( !( unmatched[ i ] || setMatched[ i ] ) ) { + setMatched[ i ] = pop.call( results ); + } + } + } + + // Discard index placeholder values to get only actual matches + setMatched = condense( setMatched ); + } + + // Add matches to results + push.apply( results, setMatched ); + + // Seedless set matches succeeding multiple successful matchers stipulate sorting + if ( outermost && !seed && setMatched.length > 0 && + ( matchedCount + setMatchers.length ) > 1 ) { + + Sizzle.uniqueSort( results ); + } + } + + // Override manipulation of globals by nested matchers + if ( outermost ) { + dirruns = dirrunsUnique; + outermostContext = contextBackup; + } + + return unmatched; + }; + + return bySet ? + markFunction( superMatcher ) : + superMatcher; +} + +compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { + var i, + setMatchers = [], + elementMatchers = [], + cached = compilerCache[ selector + " " ]; + + if ( !cached ) { + + // Generate a function of recursive functions that can be used to check each element + if ( !match ) { + match = tokenize( selector ); + } + i = match.length; + while ( i-- ) { + cached = matcherFromTokens( match[ i ] ); + if ( cached[ expando ] ) { + setMatchers.push( cached ); + } else { + elementMatchers.push( cached ); + } + } + + // Cache the compiled function + cached = compilerCache( + selector, + matcherFromGroupMatchers( elementMatchers, setMatchers ) + ); + + // Save selector and tokenization + cached.selector = selector; + } + return cached; +}; + +/** + * A low-level selection function that works with Sizzle's compiled + * selector functions + * @param {String|Function} selector A selector or a pre-compiled + * selector function built with Sizzle.compile + * @param {Element} context + * @param {Array} [results] + * @param {Array} [seed] A set of elements to match against + */ +select = Sizzle.select = function( selector, context, results, seed ) { + var i, tokens, token, type, find, + compiled = typeof selector === "function" && selector, + match = !seed && tokenize( ( selector = compiled.selector || selector ) ); + + results = results || []; + + // Try to minimize operations if there is only one selector in the list and no seed + // (the latter of which guarantees us context) + if ( match.length === 1 ) { + + // Reduce context if the leading compound selector is an ID + tokens = match[ 0 ] = match[ 0 ].slice( 0 ); + if ( tokens.length > 2 && ( token = tokens[ 0 ] ).type === "ID" && + context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[ 1 ].type ] ) { + + context = ( Expr.find[ "ID" ]( token.matches[ 0 ] + .replace( runescape, funescape ), context ) || [] )[ 0 ]; + if ( !context ) { + return results; + + // Precompiled matchers will still verify ancestry, so step up a level + } else if ( compiled ) { + context = context.parentNode; + } + + selector = selector.slice( tokens.shift().value.length ); + } + + // Fetch a seed set for right-to-left matching + i = matchExpr[ "needsContext" ].test( selector ) ? 0 : tokens.length; + while ( i-- ) { + token = tokens[ i ]; + + // Abort if we hit a combinator + if ( Expr.relative[ ( type = token.type ) ] ) { + break; + } + if ( ( find = Expr.find[ type ] ) ) { + + // Search, expanding context for leading sibling combinators + if ( ( seed = find( + token.matches[ 0 ].replace( runescape, funescape ), + rsibling.test( tokens[ 0 ].type ) && testContext( context.parentNode ) || + context + ) ) ) { + + // If seed is empty or no tokens remain, we can return early + tokens.splice( i, 1 ); + selector = seed.length && toSelector( tokens ); + if ( !selector ) { + push.apply( results, seed ); + return results; + } + + break; + } + } + } + } + + // Compile and execute a filtering function if one is not provided + // Provide `match` to avoid retokenization if we modified the selector above + ( compiled || compile( selector, match ) )( + seed, + context, + !documentIsHTML, + results, + !context || rsibling.test( selector ) && testContext( context.parentNode ) || context + ); + return results; +}; + +// One-time assignments + +// Sort stability +support.sortStable = expando.split( "" ).sort( sortOrder ).join( "" ) === expando; + +// Support: Chrome 14-35+ +// Always assume duplicates if they aren't passed to the comparison function +support.detectDuplicates = !!hasDuplicate; + +// Initialize against the default document +setDocument(); + +// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27) +// Detached nodes confoundingly follow *each other* +support.sortDetached = assert( function( el ) { + + // Should return 1, but returns 4 (following) + return el.compareDocumentPosition( document.createElement( "fieldset" ) ) & 1; +} ); + +// Support: IE<8 +// Prevent attribute/property "interpolation" +// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx +if ( !assert( function( el ) { + el.innerHTML = ""; + return el.firstChild.getAttribute( "href" ) === "#"; +} ) ) { + addHandle( "type|href|height|width", function( elem, name, isXML ) { + if ( !isXML ) { + return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); + } + } ); +} + +// Support: IE<9 +// Use defaultValue in place of getAttribute("value") +if ( !support.attributes || !assert( function( el ) { + el.innerHTML = ""; + el.firstChild.setAttribute( "value", "" ); + return el.firstChild.getAttribute( "value" ) === ""; +} ) ) { + addHandle( "value", function( elem, _name, isXML ) { + if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { + return elem.defaultValue; + } + } ); +} + +// Support: IE<9 +// Use getAttributeNode to fetch booleans when getAttribute lies +if ( !assert( function( el ) { + return el.getAttribute( "disabled" ) == null; +} ) ) { + addHandle( booleans, function( elem, name, isXML ) { + var val; + if ( !isXML ) { + return elem[ name ] === true ? name.toLowerCase() : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; + } + } ); +} + +return Sizzle; + +} )( window ); + + + +jQuery.find = Sizzle; +jQuery.expr = Sizzle.selectors; + +// Deprecated +jQuery.expr[ ":" ] = jQuery.expr.pseudos; +jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort; +jQuery.text = Sizzle.getText; +jQuery.isXMLDoc = Sizzle.isXML; +jQuery.contains = Sizzle.contains; +jQuery.escapeSelector = Sizzle.escape; + + + + +var dir = function( elem, dir, until ) { + var matched = [], + truncate = until !== undefined; + + while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) { + if ( elem.nodeType === 1 ) { + if ( truncate && jQuery( elem ).is( until ) ) { + break; + } + matched.push( elem ); + } + } + return matched; +}; + + +var siblings = function( n, elem ) { + var matched = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType === 1 && n !== elem ) { + matched.push( n ); + } + } + + return matched; +}; + + +var rneedsContext = jQuery.expr.match.needsContext; + + + +function nodeName( elem, name ) { + + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + +} +var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i ); + + + +// Implement the identical functionality for filter and not +function winnow( elements, qualifier, not ) { + if ( isFunction( qualifier ) ) { + return jQuery.grep( elements, function( elem, i ) { + return !!qualifier.call( elem, i, elem ) !== not; + } ); + } + + // Single element + if ( qualifier.nodeType ) { + return jQuery.grep( elements, function( elem ) { + return ( elem === qualifier ) !== not; + } ); + } + + // Arraylike of elements (jQuery, arguments, Array) + if ( typeof qualifier !== "string" ) { + return jQuery.grep( elements, function( elem ) { + return ( indexOf.call( qualifier, elem ) > -1 ) !== not; + } ); + } + + // Filtered directly for both simple and complex selectors + return jQuery.filter( qualifier, elements, not ); +} + +jQuery.filter = function( expr, elems, not ) { + var elem = elems[ 0 ]; + + if ( not ) { + expr = ":not(" + expr + ")"; + } + + if ( elems.length === 1 && elem.nodeType === 1 ) { + return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : []; + } + + return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) { + return elem.nodeType === 1; + } ) ); +}; + +jQuery.fn.extend( { + find: function( selector ) { + var i, ret, + len = this.length, + self = this; + + if ( typeof selector !== "string" ) { + return this.pushStack( jQuery( selector ).filter( function() { + for ( i = 0; i < len; i++ ) { + if ( jQuery.contains( self[ i ], this ) ) { + return true; + } + } + } ) ); + } + + ret = this.pushStack( [] ); + + for ( i = 0; i < len; i++ ) { + jQuery.find( selector, self[ i ], ret ); + } + + return len > 1 ? jQuery.uniqueSort( ret ) : ret; + }, + filter: function( selector ) { + return this.pushStack( winnow( this, selector || [], false ) ); + }, + not: function( selector ) { + return this.pushStack( winnow( this, selector || [], true ) ); + }, + is: function( selector ) { + return !!winnow( + this, + + // If this is a positional/relative selector, check membership in the returned set + // so $("p:first").is("p:last") won't return true for a doc with two "p". + typeof selector === "string" && rneedsContext.test( selector ) ? + jQuery( selector ) : + selector || [], + false + ).length; + } +} ); + + +// Initialize a jQuery object + + +// A central reference to the root jQuery(document) +var rootjQuery, + + // A simple way to check for HTML strings + // Prioritize #id over to avoid XSS via location.hash (#9521) + // Strict HTML recognition (#11290: must start with <) + // Shortcut simple #id case for speed + rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/, + + init = jQuery.fn.init = function( selector, context, root ) { + var match, elem; + + // HANDLE: $(""), $(null), $(undefined), $(false) + if ( !selector ) { + return this; + } + + // Method init() accepts an alternate rootjQuery + // so migrate can support jQuery.sub (gh-2101) + root = root || rootjQuery; + + // Handle HTML strings + if ( typeof selector === "string" ) { + if ( selector[ 0 ] === "<" && + selector[ selector.length - 1 ] === ">" && + selector.length >= 3 ) { + + // Assume that strings that start and end with <> are HTML and skip the regex check + match = [ null, selector, null ]; + + } else { + match = rquickExpr.exec( selector ); + } + + // Match html or make sure no context is specified for #id + if ( match && ( match[ 1 ] || !context ) ) { + + // HANDLE: $(html) -> $(array) + if ( match[ 1 ] ) { + context = context instanceof jQuery ? context[ 0 ] : context; + + // Option to run scripts is true for back-compat + // Intentionally let the error be thrown if parseHTML is not present + jQuery.merge( this, jQuery.parseHTML( + match[ 1 ], + context && context.nodeType ? context.ownerDocument || context : document, + true + ) ); + + // HANDLE: $(html, props) + if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) { + for ( match in context ) { + + // Properties of context are called as methods if possible + if ( isFunction( this[ match ] ) ) { + this[ match ]( context[ match ] ); + + // ...and otherwise set as attributes + } else { + this.attr( match, context[ match ] ); + } + } + } + + return this; + + // HANDLE: $(#id) + } else { + elem = document.getElementById( match[ 2 ] ); + + if ( elem ) { + + // Inject the element directly into the jQuery object + this[ 0 ] = elem; + this.length = 1; + } + return this; + } + + // HANDLE: $(expr, $(...)) + } else if ( !context || context.jquery ) { + return ( context || root ).find( selector ); + + // HANDLE: $(expr, context) + // (which is just equivalent to: $(context).find(expr) + } else { + return this.constructor( context ).find( selector ); + } + + // HANDLE: $(DOMElement) + } else if ( selector.nodeType ) { + this[ 0 ] = selector; + this.length = 1; + return this; + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( isFunction( selector ) ) { + return root.ready !== undefined ? + root.ready( selector ) : + + // Execute immediately if ready is not present + selector( jQuery ); + } + + return jQuery.makeArray( selector, this ); + }; + +// Give the init function the jQuery prototype for later instantiation +init.prototype = jQuery.fn; + +// Initialize central reference +rootjQuery = jQuery( document ); + + +var rparentsprev = /^(?:parents|prev(?:Until|All))/, + + // Methods guaranteed to produce a unique set when starting from a unique set + guaranteedUnique = { + children: true, + contents: true, + next: true, + prev: true + }; + +jQuery.fn.extend( { + has: function( target ) { + var targets = jQuery( target, this ), + l = targets.length; + + return this.filter( function() { + var i = 0; + for ( ; i < l; i++ ) { + if ( jQuery.contains( this, targets[ i ] ) ) { + return true; + } + } + } ); + }, + + closest: function( selectors, context ) { + var cur, + i = 0, + l = this.length, + matched = [], + targets = typeof selectors !== "string" && jQuery( selectors ); + + // Positional selectors never match, since there's no _selection_ context + if ( !rneedsContext.test( selectors ) ) { + for ( ; i < l; i++ ) { + for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) { + + // Always skip document fragments + if ( cur.nodeType < 11 && ( targets ? + targets.index( cur ) > -1 : + + // Don't pass non-elements to Sizzle + cur.nodeType === 1 && + jQuery.find.matchesSelector( cur, selectors ) ) ) { + + matched.push( cur ); + break; + } + } + } + } + + return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched ); + }, + + // Determine the position of an element within the set + index: function( elem ) { + + // No argument, return index in parent + if ( !elem ) { + return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; + } + + // Index in selector + if ( typeof elem === "string" ) { + return indexOf.call( jQuery( elem ), this[ 0 ] ); + } + + // Locate the position of the desired element + return indexOf.call( this, + + // If it receives a jQuery object, the first element is used + elem.jquery ? elem[ 0 ] : elem + ); + }, + + add: function( selector, context ) { + return this.pushStack( + jQuery.uniqueSort( + jQuery.merge( this.get(), jQuery( selector, context ) ) + ) + ); + }, + + addBack: function( selector ) { + return this.add( selector == null ? + this.prevObject : this.prevObject.filter( selector ) + ); + } +} ); + +function sibling( cur, dir ) { + while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {} + return cur; +} + +jQuery.each( { + parent: function( elem ) { + var parent = elem.parentNode; + return parent && parent.nodeType !== 11 ? parent : null; + }, + parents: function( elem ) { + return dir( elem, "parentNode" ); + }, + parentsUntil: function( elem, _i, until ) { + return dir( elem, "parentNode", until ); + }, + next: function( elem ) { + return sibling( elem, "nextSibling" ); + }, + prev: function( elem ) { + return sibling( elem, "previousSibling" ); + }, + nextAll: function( elem ) { + return dir( elem, "nextSibling" ); + }, + prevAll: function( elem ) { + return dir( elem, "previousSibling" ); + }, + nextUntil: function( elem, _i, until ) { + return dir( elem, "nextSibling", until ); + }, + prevUntil: function( elem, _i, until ) { + return dir( elem, "previousSibling", until ); + }, + siblings: function( elem ) { + return siblings( ( elem.parentNode || {} ).firstChild, elem ); + }, + children: function( elem ) { + return siblings( elem.firstChild ); + }, + contents: function( elem ) { + if ( elem.contentDocument != null && + + // Support: IE 11+ + // elements with no `data` attribute has an object + // `contentDocument` with a `null` prototype. + getProto( elem.contentDocument ) ) { + + return elem.contentDocument; + } + + // Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only + // Treat the template element as a regular one in browsers that + // don't support it. + if ( nodeName( elem, "template" ) ) { + elem = elem.content || elem; + } + + return jQuery.merge( [], elem.childNodes ); + } +}, function( name, fn ) { + jQuery.fn[ name ] = function( until, selector ) { + var matched = jQuery.map( this, fn, until ); + + if ( name.slice( -5 ) !== "Until" ) { + selector = until; + } + + if ( selector && typeof selector === "string" ) { + matched = jQuery.filter( selector, matched ); + } + + if ( this.length > 1 ) { + + // Remove duplicates + if ( !guaranteedUnique[ name ] ) { + jQuery.uniqueSort( matched ); + } + + // Reverse order for parents* and prev-derivatives + if ( rparentsprev.test( name ) ) { + matched.reverse(); + } + } + + return this.pushStack( matched ); + }; +} ); +var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g ); + + + +// Convert String-formatted options into Object-formatted ones +function createOptions( options ) { + var object = {}; + jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) { + object[ flag ] = true; + } ); + return object; +} + +/* + * Create a callback list using the following parameters: + * + * options: an optional list of space-separated options that will change how + * the callback list behaves or a more traditional option object + * + * By default a callback list will act like an event callback list and can be + * "fired" multiple times. + * + * Possible options: + * + * once: will ensure the callback list can only be fired once (like a Deferred) + * + * memory: will keep track of previous values and will call any callback added + * after the list has been fired right away with the latest "memorized" + * values (like a Deferred) + * + * unique: will ensure a callback can only be added once (no duplicate in the list) + * + * stopOnFalse: interrupt callings when a callback returns false + * + */ +jQuery.Callbacks = function( options ) { + + // Convert options from String-formatted to Object-formatted if needed + // (we check in cache first) + options = typeof options === "string" ? + createOptions( options ) : + jQuery.extend( {}, options ); + + var // Flag to know if list is currently firing + firing, + + // Last fire value for non-forgettable lists + memory, + + // Flag to know if list was already fired + fired, + + // Flag to prevent firing + locked, + + // Actual callback list + list = [], + + // Queue of execution data for repeatable lists + queue = [], + + // Index of currently firing callback (modified by add/remove as needed) + firingIndex = -1, + + // Fire callbacks + fire = function() { + + // Enforce single-firing + locked = locked || options.once; + + // Execute callbacks for all pending executions, + // respecting firingIndex overrides and runtime changes + fired = firing = true; + for ( ; queue.length; firingIndex = -1 ) { + memory = queue.shift(); + while ( ++firingIndex < list.length ) { + + // Run callback and check for early termination + if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false && + options.stopOnFalse ) { + + // Jump to end and forget the data so .add doesn't re-fire + firingIndex = list.length; + memory = false; + } + } + } + + // Forget the data if we're done with it + if ( !options.memory ) { + memory = false; + } + + firing = false; + + // Clean up if we're done firing for good + if ( locked ) { + + // Keep an empty list if we have data for future add calls + if ( memory ) { + list = []; + + // Otherwise, this object is spent + } else { + list = ""; + } + } + }, + + // Actual Callbacks object + self = { + + // Add a callback or a collection of callbacks to the list + add: function() { + if ( list ) { + + // If we have memory from a past run, we should fire after adding + if ( memory && !firing ) { + firingIndex = list.length - 1; + queue.push( memory ); + } + + ( function add( args ) { + jQuery.each( args, function( _, arg ) { + if ( isFunction( arg ) ) { + if ( !options.unique || !self.has( arg ) ) { + list.push( arg ); + } + } else if ( arg && arg.length && toType( arg ) !== "string" ) { + + // Inspect recursively + add( arg ); + } + } ); + } )( arguments ); + + if ( memory && !firing ) { + fire(); + } + } + return this; + }, + + // Remove a callback from the list + remove: function() { + jQuery.each( arguments, function( _, arg ) { + var index; + while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) { + list.splice( index, 1 ); + + // Handle firing indexes + if ( index <= firingIndex ) { + firingIndex--; + } + } + } ); + return this; + }, + + // Check if a given callback is in the list. + // If no argument is given, return whether or not list has callbacks attached. + has: function( fn ) { + return fn ? + jQuery.inArray( fn, list ) > -1 : + list.length > 0; + }, + + // Remove all callbacks from the list + empty: function() { + if ( list ) { + list = []; + } + return this; + }, + + // Disable .fire and .add + // Abort any current/pending executions + // Clear all callbacks and values + disable: function() { + locked = queue = []; + list = memory = ""; + return this; + }, + disabled: function() { + return !list; + }, + + // Disable .fire + // Also disable .add unless we have memory (since it would have no effect) + // Abort any pending executions + lock: function() { + locked = queue = []; + if ( !memory && !firing ) { + list = memory = ""; + } + return this; + }, + locked: function() { + return !!locked; + }, + + // Call all callbacks with the given context and arguments + fireWith: function( context, args ) { + if ( !locked ) { + args = args || []; + args = [ context, args.slice ? args.slice() : args ]; + queue.push( args ); + if ( !firing ) { + fire(); + } + } + return this; + }, + + // Call all the callbacks with the given arguments + fire: function() { + self.fireWith( this, arguments ); + return this; + }, + + // To know if the callbacks have already been called at least once + fired: function() { + return !!fired; + } + }; + + return self; +}; + + +function Identity( v ) { + return v; +} +function Thrower( ex ) { + throw ex; +} + +function adoptValue( value, resolve, reject, noValue ) { + var method; + + try { + + // Check for promise aspect first to privilege synchronous behavior + if ( value && isFunction( ( method = value.promise ) ) ) { + method.call( value ).done( resolve ).fail( reject ); + + // Other thenables + } else if ( value && isFunction( ( method = value.then ) ) ) { + method.call( value, resolve, reject ); + + // Other non-thenables + } else { + + // Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer: + // * false: [ value ].slice( 0 ) => resolve( value ) + // * true: [ value ].slice( 1 ) => resolve() + resolve.apply( undefined, [ value ].slice( noValue ) ); + } + + // For Promises/A+, convert exceptions into rejections + // Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in + // Deferred#then to conditionally suppress rejection. + } catch ( value ) { + + // Support: Android 4.0 only + // Strict mode functions invoked without .call/.apply get global-object context + reject.apply( undefined, [ value ] ); + } +} + +jQuery.extend( { + + Deferred: function( func ) { + var tuples = [ + + // action, add listener, callbacks, + // ... .then handlers, argument index, [final state] + [ "notify", "progress", jQuery.Callbacks( "memory" ), + jQuery.Callbacks( "memory" ), 2 ], + [ "resolve", "done", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 0, "resolved" ], + [ "reject", "fail", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 1, "rejected" ] + ], + state = "pending", + promise = { + state: function() { + return state; + }, + always: function() { + deferred.done( arguments ).fail( arguments ); + return this; + }, + "catch": function( fn ) { + return promise.then( null, fn ); + }, + + // Keep pipe for back-compat + pipe: function( /* fnDone, fnFail, fnProgress */ ) { + var fns = arguments; + + return jQuery.Deferred( function( newDefer ) { + jQuery.each( tuples, function( _i, tuple ) { + + // Map tuples (progress, done, fail) to arguments (done, fail, progress) + var fn = isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ]; + + // deferred.progress(function() { bind to newDefer or newDefer.notify }) + // deferred.done(function() { bind to newDefer or newDefer.resolve }) + // deferred.fail(function() { bind to newDefer or newDefer.reject }) + deferred[ tuple[ 1 ] ]( function() { + var returned = fn && fn.apply( this, arguments ); + if ( returned && isFunction( returned.promise ) ) { + returned.promise() + .progress( newDefer.notify ) + .done( newDefer.resolve ) + .fail( newDefer.reject ); + } else { + newDefer[ tuple[ 0 ] + "With" ]( + this, + fn ? [ returned ] : arguments + ); + } + } ); + } ); + fns = null; + } ).promise(); + }, + then: function( onFulfilled, onRejected, onProgress ) { + var maxDepth = 0; + function resolve( depth, deferred, handler, special ) { + return function() { + var that = this, + args = arguments, + mightThrow = function() { + var returned, then; + + // Support: Promises/A+ section 2.3.3.3.3 + // https://promisesaplus.com/#point-59 + // Ignore double-resolution attempts + if ( depth < maxDepth ) { + return; + } + + returned = handler.apply( that, args ); + + // Support: Promises/A+ section 2.3.1 + // https://promisesaplus.com/#point-48 + if ( returned === deferred.promise() ) { + throw new TypeError( "Thenable self-resolution" ); + } + + // Support: Promises/A+ sections 2.3.3.1, 3.5 + // https://promisesaplus.com/#point-54 + // https://promisesaplus.com/#point-75 + // Retrieve `then` only once + then = returned && + + // Support: Promises/A+ section 2.3.4 + // https://promisesaplus.com/#point-64 + // Only check objects and functions for thenability + ( typeof returned === "object" || + typeof returned === "function" ) && + returned.then; + + // Handle a returned thenable + if ( isFunction( then ) ) { + + // Special processors (notify) just wait for resolution + if ( special ) { + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ) + ); + + // Normal processors (resolve) also hook into progress + } else { + + // ...and disregard older resolution values + maxDepth++; + + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ), + resolve( maxDepth, deferred, Identity, + deferred.notifyWith ) + ); + } + + // Handle all other returned values + } else { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Identity ) { + that = undefined; + args = [ returned ]; + } + + // Process the value(s) + // Default process is resolve + ( special || deferred.resolveWith )( that, args ); + } + }, + + // Only normal processors (resolve) catch and reject exceptions + process = special ? + mightThrow : + function() { + try { + mightThrow(); + } catch ( e ) { + + if ( jQuery.Deferred.exceptionHook ) { + jQuery.Deferred.exceptionHook( e, + process.stackTrace ); + } + + // Support: Promises/A+ section 2.3.3.3.4.1 + // https://promisesaplus.com/#point-61 + // Ignore post-resolution exceptions + if ( depth + 1 >= maxDepth ) { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Thrower ) { + that = undefined; + args = [ e ]; + } + + deferred.rejectWith( that, args ); + } + } + }; + + // Support: Promises/A+ section 2.3.3.3.1 + // https://promisesaplus.com/#point-57 + // Re-resolve promises immediately to dodge false rejection from + // subsequent errors + if ( depth ) { + process(); + } else { + + // Call an optional hook to record the stack, in case of exception + // since it's otherwise lost when execution goes async + if ( jQuery.Deferred.getStackHook ) { + process.stackTrace = jQuery.Deferred.getStackHook(); + } + window.setTimeout( process ); + } + }; + } + + return jQuery.Deferred( function( newDefer ) { + + // progress_handlers.add( ... ) + tuples[ 0 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onProgress ) ? + onProgress : + Identity, + newDefer.notifyWith + ) + ); + + // fulfilled_handlers.add( ... ) + tuples[ 1 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onFulfilled ) ? + onFulfilled : + Identity + ) + ); + + // rejected_handlers.add( ... ) + tuples[ 2 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onRejected ) ? + onRejected : + Thrower + ) + ); + } ).promise(); + }, + + // Get a promise for this deferred + // If obj is provided, the promise aspect is added to the object + promise: function( obj ) { + return obj != null ? jQuery.extend( obj, promise ) : promise; + } + }, + deferred = {}; + + // Add list-specific methods + jQuery.each( tuples, function( i, tuple ) { + var list = tuple[ 2 ], + stateString = tuple[ 5 ]; + + // promise.progress = list.add + // promise.done = list.add + // promise.fail = list.add + promise[ tuple[ 1 ] ] = list.add; + + // Handle state + if ( stateString ) { + list.add( + function() { + + // state = "resolved" (i.e., fulfilled) + // state = "rejected" + state = stateString; + }, + + // rejected_callbacks.disable + // fulfilled_callbacks.disable + tuples[ 3 - i ][ 2 ].disable, + + // rejected_handlers.disable + // fulfilled_handlers.disable + tuples[ 3 - i ][ 3 ].disable, + + // progress_callbacks.lock + tuples[ 0 ][ 2 ].lock, + + // progress_handlers.lock + tuples[ 0 ][ 3 ].lock + ); + } + + // progress_handlers.fire + // fulfilled_handlers.fire + // rejected_handlers.fire + list.add( tuple[ 3 ].fire ); + + // deferred.notify = function() { deferred.notifyWith(...) } + // deferred.resolve = function() { deferred.resolveWith(...) } + // deferred.reject = function() { deferred.rejectWith(...) } + deferred[ tuple[ 0 ] ] = function() { + deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments ); + return this; + }; + + // deferred.notifyWith = list.fireWith + // deferred.resolveWith = list.fireWith + // deferred.rejectWith = list.fireWith + deferred[ tuple[ 0 ] + "With" ] = list.fireWith; + } ); + + // Make the deferred a promise + promise.promise( deferred ); + + // Call given func if any + if ( func ) { + func.call( deferred, deferred ); + } + + // All done! + return deferred; + }, + + // Deferred helper + when: function( singleValue ) { + var + + // count of uncompleted subordinates + remaining = arguments.length, + + // count of unprocessed arguments + i = remaining, + + // subordinate fulfillment data + resolveContexts = Array( i ), + resolveValues = slice.call( arguments ), + + // the primary Deferred + primary = jQuery.Deferred(), + + // subordinate callback factory + updateFunc = function( i ) { + return function( value ) { + resolveContexts[ i ] = this; + resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value; + if ( !( --remaining ) ) { + primary.resolveWith( resolveContexts, resolveValues ); + } + }; + }; + + // Single- and empty arguments are adopted like Promise.resolve + if ( remaining <= 1 ) { + adoptValue( singleValue, primary.done( updateFunc( i ) ).resolve, primary.reject, + !remaining ); + + // Use .then() to unwrap secondary thenables (cf. gh-3000) + if ( primary.state() === "pending" || + isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) { + + return primary.then(); + } + } + + // Multiple arguments are aggregated like Promise.all array elements + while ( i-- ) { + adoptValue( resolveValues[ i ], updateFunc( i ), primary.reject ); + } + + return primary.promise(); + } +} ); + + +// These usually indicate a programmer mistake during development, +// warn about them ASAP rather than swallowing them by default. +var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/; + +jQuery.Deferred.exceptionHook = function( error, stack ) { + + // Support: IE 8 - 9 only + // Console exists when dev tools are open, which can happen at any time + if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) { + window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack ); + } +}; + + + + +jQuery.readyException = function( error ) { + window.setTimeout( function() { + throw error; + } ); +}; + + + + +// The deferred used on DOM ready +var readyList = jQuery.Deferred(); + +jQuery.fn.ready = function( fn ) { + + readyList + .then( fn ) + + // Wrap jQuery.readyException in a function so that the lookup + // happens at the time of error handling instead of callback + // registration. + .catch( function( error ) { + jQuery.readyException( error ); + } ); + + return this; +}; + +jQuery.extend( { + + // Is the DOM ready to be used? Set to true once it occurs. + isReady: false, + + // A counter to track how many items to wait for before + // the ready event fires. See #6781 + readyWait: 1, + + // Handle when the DOM is ready + ready: function( wait ) { + + // Abort if there are pending holds or we're already ready + if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) { + return; + } + + // Remember that the DOM is ready + jQuery.isReady = true; + + // If a normal DOM Ready event fired, decrement, and wait if need be + if ( wait !== true && --jQuery.readyWait > 0 ) { + return; + } + + // If there are functions bound, to execute + readyList.resolveWith( document, [ jQuery ] ); + } +} ); + +jQuery.ready.then = readyList.then; + +// The ready event handler and self cleanup method +function completed() { + document.removeEventListener( "DOMContentLoaded", completed ); + window.removeEventListener( "load", completed ); + jQuery.ready(); +} + +// Catch cases where $(document).ready() is called +// after the browser event has already occurred. +// Support: IE <=9 - 10 only +// Older IE sometimes signals "interactive" too soon +if ( document.readyState === "complete" || + ( document.readyState !== "loading" && !document.documentElement.doScroll ) ) { + + // Handle it asynchronously to allow scripts the opportunity to delay ready + window.setTimeout( jQuery.ready ); + +} else { + + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", completed ); + + // A fallback to window.onload, that will always work + window.addEventListener( "load", completed ); +} + + + + +// Multifunctional method to get and set values of a collection +// The value/s can optionally be executed if it's a function +var access = function( elems, fn, key, value, chainable, emptyGet, raw ) { + var i = 0, + len = elems.length, + bulk = key == null; + + // Sets many values + if ( toType( key ) === "object" ) { + chainable = true; + for ( i in key ) { + access( elems, fn, i, key[ i ], true, emptyGet, raw ); + } + + // Sets one value + } else if ( value !== undefined ) { + chainable = true; + + if ( !isFunction( value ) ) { + raw = true; + } + + if ( bulk ) { + + // Bulk operations run against the entire set + if ( raw ) { + fn.call( elems, value ); + fn = null; + + // ...except when executing function values + } else { + bulk = fn; + fn = function( elem, _key, value ) { + return bulk.call( jQuery( elem ), value ); + }; + } + } + + if ( fn ) { + for ( ; i < len; i++ ) { + fn( + elems[ i ], key, raw ? + value : + value.call( elems[ i ], i, fn( elems[ i ], key ) ) + ); + } + } + } + + if ( chainable ) { + return elems; + } + + // Gets + if ( bulk ) { + return fn.call( elems ); + } + + return len ? fn( elems[ 0 ], key ) : emptyGet; +}; + + +// Matches dashed string for camelizing +var rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g; + +// Used by camelCase as callback to replace() +function fcamelCase( _all, letter ) { + return letter.toUpperCase(); +} + +// Convert dashed to camelCase; used by the css and data modules +// Support: IE <=9 - 11, Edge 12 - 15 +// Microsoft forgot to hump their vendor prefix (#9572) +function camelCase( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); +} +var acceptData = function( owner ) { + + // Accepts only: + // - Node + // - Node.ELEMENT_NODE + // - Node.DOCUMENT_NODE + // - Object + // - Any + return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType ); +}; + + + + +function Data() { + this.expando = jQuery.expando + Data.uid++; +} + +Data.uid = 1; + +Data.prototype = { + + cache: function( owner ) { + + // Check if the owner object already has a cache + var value = owner[ this.expando ]; + + // If not, create one + if ( !value ) { + value = {}; + + // We can accept data for non-element nodes in modern browsers, + // but we should not, see #8335. + // Always return an empty object. + if ( acceptData( owner ) ) { + + // If it is a node unlikely to be stringify-ed or looped over + // use plain assignment + if ( owner.nodeType ) { + owner[ this.expando ] = value; + + // Otherwise secure it in a non-enumerable property + // configurable must be true to allow the property to be + // deleted when data is removed + } else { + Object.defineProperty( owner, this.expando, { + value: value, + configurable: true + } ); + } + } + } + + return value; + }, + set: function( owner, data, value ) { + var prop, + cache = this.cache( owner ); + + // Handle: [ owner, key, value ] args + // Always use camelCase key (gh-2257) + if ( typeof data === "string" ) { + cache[ camelCase( data ) ] = value; + + // Handle: [ owner, { properties } ] args + } else { + + // Copy the properties one-by-one to the cache object + for ( prop in data ) { + cache[ camelCase( prop ) ] = data[ prop ]; + } + } + return cache; + }, + get: function( owner, key ) { + return key === undefined ? + this.cache( owner ) : + + // Always use camelCase key (gh-2257) + owner[ this.expando ] && owner[ this.expando ][ camelCase( key ) ]; + }, + access: function( owner, key, value ) { + + // In cases where either: + // + // 1. No key was specified + // 2. A string key was specified, but no value provided + // + // Take the "read" path and allow the get method to determine + // which value to return, respectively either: + // + // 1. The entire cache object + // 2. The data stored at the key + // + if ( key === undefined || + ( ( key && typeof key === "string" ) && value === undefined ) ) { + + return this.get( owner, key ); + } + + // When the key is not a string, or both a key and value + // are specified, set or extend (existing objects) with either: + // + // 1. An object of properties + // 2. A key and value + // + this.set( owner, key, value ); + + // Since the "set" path can have two possible entry points + // return the expected data based on which path was taken[*] + return value !== undefined ? value : key; + }, + remove: function( owner, key ) { + var i, + cache = owner[ this.expando ]; + + if ( cache === undefined ) { + return; + } + + if ( key !== undefined ) { + + // Support array or space separated string of keys + if ( Array.isArray( key ) ) { + + // If key is an array of keys... + // We always set camelCase keys, so remove that. + key = key.map( camelCase ); + } else { + key = camelCase( key ); + + // If a key with the spaces exists, use it. + // Otherwise, create an array by matching non-whitespace + key = key in cache ? + [ key ] : + ( key.match( rnothtmlwhite ) || [] ); + } + + i = key.length; + + while ( i-- ) { + delete cache[ key[ i ] ]; + } + } + + // Remove the expando if there's no more data + if ( key === undefined || jQuery.isEmptyObject( cache ) ) { + + // Support: Chrome <=35 - 45 + // Webkit & Blink performance suffers when deleting properties + // from DOM nodes, so set to undefined instead + // https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted) + if ( owner.nodeType ) { + owner[ this.expando ] = undefined; + } else { + delete owner[ this.expando ]; + } + } + }, + hasData: function( owner ) { + var cache = owner[ this.expando ]; + return cache !== undefined && !jQuery.isEmptyObject( cache ); + } +}; +var dataPriv = new Data(); + +var dataUser = new Data(); + + + +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + +var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, + rmultiDash = /[A-Z]/g; + +function getData( data ) { + if ( data === "true" ) { + return true; + } + + if ( data === "false" ) { + return false; + } + + if ( data === "null" ) { + return null; + } + + // Only convert to a number if it doesn't change the string + if ( data === +data + "" ) { + return +data; + } + + if ( rbrace.test( data ) ) { + return JSON.parse( data ); + } + + return data; +} + +function dataAttr( elem, key, data ) { + var name; + + // If nothing was found internally, try to fetch any + // data from the HTML5 data-* attribute + if ( data === undefined && elem.nodeType === 1 ) { + name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase(); + data = elem.getAttribute( name ); + + if ( typeof data === "string" ) { + try { + data = getData( data ); + } catch ( e ) {} + + // Make sure we set the data so it isn't changed later + dataUser.set( elem, key, data ); + } else { + data = undefined; + } + } + return data; +} + +jQuery.extend( { + hasData: function( elem ) { + return dataUser.hasData( elem ) || dataPriv.hasData( elem ); + }, + + data: function( elem, name, data ) { + return dataUser.access( elem, name, data ); + }, + + removeData: function( elem, name ) { + dataUser.remove( elem, name ); + }, + + // TODO: Now that all calls to _data and _removeData have been replaced + // with direct calls to dataPriv methods, these can be deprecated. + _data: function( elem, name, data ) { + return dataPriv.access( elem, name, data ); + }, + + _removeData: function( elem, name ) { + dataPriv.remove( elem, name ); + } +} ); + +jQuery.fn.extend( { + data: function( key, value ) { + var i, name, data, + elem = this[ 0 ], + attrs = elem && elem.attributes; + + // Gets all values + if ( key === undefined ) { + if ( this.length ) { + data = dataUser.get( elem ); + + if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) { + i = attrs.length; + while ( i-- ) { + + // Support: IE 11 only + // The attrs elements can be null (#14894) + if ( attrs[ i ] ) { + name = attrs[ i ].name; + if ( name.indexOf( "data-" ) === 0 ) { + name = camelCase( name.slice( 5 ) ); + dataAttr( elem, name, data[ name ] ); + } + } + } + dataPriv.set( elem, "hasDataAttrs", true ); + } + } + + return data; + } + + // Sets multiple values + if ( typeof key === "object" ) { + return this.each( function() { + dataUser.set( this, key ); + } ); + } + + return access( this, function( value ) { + var data; + + // The calling jQuery object (element matches) is not empty + // (and therefore has an element appears at this[ 0 ]) and the + // `value` parameter was not undefined. An empty jQuery object + // will result in `undefined` for elem = this[ 0 ] which will + // throw an exception if an attempt to read a data cache is made. + if ( elem && value === undefined ) { + + // Attempt to get data from the cache + // The key will always be camelCased in Data + data = dataUser.get( elem, key ); + if ( data !== undefined ) { + return data; + } + + // Attempt to "discover" the data in + // HTML5 custom data-* attrs + data = dataAttr( elem, key ); + if ( data !== undefined ) { + return data; + } + + // We tried really hard, but the data doesn't exist. + return; + } + + // Set the data... + this.each( function() { + + // We always store the camelCased key + dataUser.set( this, key, value ); + } ); + }, null, value, arguments.length > 1, null, true ); + }, + + removeData: function( key ) { + return this.each( function() { + dataUser.remove( this, key ); + } ); + } +} ); + + +jQuery.extend( { + queue: function( elem, type, data ) { + var queue; + + if ( elem ) { + type = ( type || "fx" ) + "queue"; + queue = dataPriv.get( elem, type ); + + // Speed up dequeue by getting out quickly if this is just a lookup + if ( data ) { + if ( !queue || Array.isArray( data ) ) { + queue = dataPriv.access( elem, type, jQuery.makeArray( data ) ); + } else { + queue.push( data ); + } + } + return queue || []; + } + }, + + dequeue: function( elem, type ) { + type = type || "fx"; + + var queue = jQuery.queue( elem, type ), + startLength = queue.length, + fn = queue.shift(), + hooks = jQuery._queueHooks( elem, type ), + next = function() { + jQuery.dequeue( elem, type ); + }; + + // If the fx queue is dequeued, always remove the progress sentinel + if ( fn === "inprogress" ) { + fn = queue.shift(); + startLength--; + } + + if ( fn ) { + + // Add a progress sentinel to prevent the fx queue from being + // automatically dequeued + if ( type === "fx" ) { + queue.unshift( "inprogress" ); + } + + // Clear up the last queue stop function + delete hooks.stop; + fn.call( elem, next, hooks ); + } + + if ( !startLength && hooks ) { + hooks.empty.fire(); + } + }, + + // Not public - generate a queueHooks object, or return the current one + _queueHooks: function( elem, type ) { + var key = type + "queueHooks"; + return dataPriv.get( elem, key ) || dataPriv.access( elem, key, { + empty: jQuery.Callbacks( "once memory" ).add( function() { + dataPriv.remove( elem, [ type + "queue", key ] ); + } ) + } ); + } +} ); + +jQuery.fn.extend( { + queue: function( type, data ) { + var setter = 2; + + if ( typeof type !== "string" ) { + data = type; + type = "fx"; + setter--; + } + + if ( arguments.length < setter ) { + return jQuery.queue( this[ 0 ], type ); + } + + return data === undefined ? + this : + this.each( function() { + var queue = jQuery.queue( this, type, data ); + + // Ensure a hooks for this queue + jQuery._queueHooks( this, type ); + + if ( type === "fx" && queue[ 0 ] !== "inprogress" ) { + jQuery.dequeue( this, type ); + } + } ); + }, + dequeue: function( type ) { + return this.each( function() { + jQuery.dequeue( this, type ); + } ); + }, + clearQueue: function( type ) { + return this.queue( type || "fx", [] ); + }, + + // Get a promise resolved when queues of a certain type + // are emptied (fx is the type by default) + promise: function( type, obj ) { + var tmp, + count = 1, + defer = jQuery.Deferred(), + elements = this, + i = this.length, + resolve = function() { + if ( !( --count ) ) { + defer.resolveWith( elements, [ elements ] ); + } + }; + + if ( typeof type !== "string" ) { + obj = type; + type = undefined; + } + type = type || "fx"; + + while ( i-- ) { + tmp = dataPriv.get( elements[ i ], type + "queueHooks" ); + if ( tmp && tmp.empty ) { + count++; + tmp.empty.add( resolve ); + } + } + resolve(); + return defer.promise( obj ); + } +} ); +var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source; + +var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" ); + + +var cssExpand = [ "Top", "Right", "Bottom", "Left" ]; + +var documentElement = document.documentElement; + + + + var isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ); + }, + composed = { composed: true }; + + // Support: IE 9 - 11+, Edge 12 - 18+, iOS 10.0 - 10.2 only + // Check attachment across shadow DOM boundaries when possible (gh-3504) + // Support: iOS 10.0-10.2 only + // Early iOS 10 versions support `attachShadow` but not `getRootNode`, + // leading to errors. We need to check for `getRootNode`. + if ( documentElement.getRootNode ) { + isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ) || + elem.getRootNode( composed ) === elem.ownerDocument; + }; + } +var isHiddenWithinTree = function( elem, el ) { + + // isHiddenWithinTree might be called from jQuery#filter function; + // in that case, element will be second argument + elem = el || elem; + + // Inline style trumps all + return elem.style.display === "none" || + elem.style.display === "" && + + // Otherwise, check computed style + // Support: Firefox <=43 - 45 + // Disconnected elements can have computed display: none, so first confirm that elem is + // in the document. + isAttached( elem ) && + + jQuery.css( elem, "display" ) === "none"; + }; + + + +function adjustCSS( elem, prop, valueParts, tween ) { + var adjusted, scale, + maxIterations = 20, + currentValue = tween ? + function() { + return tween.cur(); + } : + function() { + return jQuery.css( elem, prop, "" ); + }, + initial = currentValue(), + unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ), + + // Starting value computation is required for potential unit mismatches + initialInUnit = elem.nodeType && + ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) && + rcssNum.exec( jQuery.css( elem, prop ) ); + + if ( initialInUnit && initialInUnit[ 3 ] !== unit ) { + + // Support: Firefox <=54 + // Halve the iteration target value to prevent interference from CSS upper bounds (gh-2144) + initial = initial / 2; + + // Trust units reported by jQuery.css + unit = unit || initialInUnit[ 3 ]; + + // Iteratively approximate from a nonzero starting point + initialInUnit = +initial || 1; + + while ( maxIterations-- ) { + + // Evaluate and update our best guess (doubling guesses that zero out). + // Finish if the scale equals or crosses 1 (making the old*new product non-positive). + jQuery.style( elem, prop, initialInUnit + unit ); + if ( ( 1 - scale ) * ( 1 - ( scale = currentValue() / initial || 0.5 ) ) <= 0 ) { + maxIterations = 0; + } + initialInUnit = initialInUnit / scale; + + } + + initialInUnit = initialInUnit * 2; + jQuery.style( elem, prop, initialInUnit + unit ); + + // Make sure we update the tween properties later on + valueParts = valueParts || []; + } + + if ( valueParts ) { + initialInUnit = +initialInUnit || +initial || 0; + + // Apply relative offset (+=/-=) if specified + adjusted = valueParts[ 1 ] ? + initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] : + +valueParts[ 2 ]; + if ( tween ) { + tween.unit = unit; + tween.start = initialInUnit; + tween.end = adjusted; + } + } + return adjusted; +} + + +var defaultDisplayMap = {}; + +function getDefaultDisplay( elem ) { + var temp, + doc = elem.ownerDocument, + nodeName = elem.nodeName, + display = defaultDisplayMap[ nodeName ]; + + if ( display ) { + return display; + } + + temp = doc.body.appendChild( doc.createElement( nodeName ) ); + display = jQuery.css( temp, "display" ); + + temp.parentNode.removeChild( temp ); + + if ( display === "none" ) { + display = "block"; + } + defaultDisplayMap[ nodeName ] = display; + + return display; +} + +function showHide( elements, show ) { + var display, elem, + values = [], + index = 0, + length = elements.length; + + // Determine new display value for elements that need to change + for ( ; index < length; index++ ) { + elem = elements[ index ]; + if ( !elem.style ) { + continue; + } + + display = elem.style.display; + if ( show ) { + + // Since we force visibility upon cascade-hidden elements, an immediate (and slow) + // check is required in this first loop unless we have a nonempty display value (either + // inline or about-to-be-restored) + if ( display === "none" ) { + values[ index ] = dataPriv.get( elem, "display" ) || null; + if ( !values[ index ] ) { + elem.style.display = ""; + } + } + if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) { + values[ index ] = getDefaultDisplay( elem ); + } + } else { + if ( display !== "none" ) { + values[ index ] = "none"; + + // Remember what we're overwriting + dataPriv.set( elem, "display", display ); + } + } + } + + // Set the display of the elements in a second loop to avoid constant reflow + for ( index = 0; index < length; index++ ) { + if ( values[ index ] != null ) { + elements[ index ].style.display = values[ index ]; + } + } + + return elements; +} + +jQuery.fn.extend( { + show: function() { + return showHide( this, true ); + }, + hide: function() { + return showHide( this ); + }, + toggle: function( state ) { + if ( typeof state === "boolean" ) { + return state ? this.show() : this.hide(); + } + + return this.each( function() { + if ( isHiddenWithinTree( this ) ) { + jQuery( this ).show(); + } else { + jQuery( this ).hide(); + } + } ); + } +} ); +var rcheckableType = ( /^(?:checkbox|radio)$/i ); + +var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]*)/i ); + +var rscriptType = ( /^$|^module$|\/(?:java|ecma)script/i ); + + + +( function() { + var fragment = document.createDocumentFragment(), + div = fragment.appendChild( document.createElement( "div" ) ), + input = document.createElement( "input" ); + + // Support: Android 4.0 - 4.3 only + // Check state lost if the name is set (#11217) + // Support: Windows Web Apps (WWA) + // `name` and `type` must use .setAttribute for WWA (#14901) + input.setAttribute( "type", "radio" ); + input.setAttribute( "checked", "checked" ); + input.setAttribute( "name", "t" ); + + div.appendChild( input ); + + // Support: Android <=4.1 only + // Older WebKit doesn't clone checked state correctly in fragments + support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + + // Support: IE <=11 only + // Make sure textarea (and checkbox) defaultValue is properly cloned + div.innerHTML = ""; + support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; + + // Support: IE <=9 only + // IE <=9 replaces "; + support.option = !!div.lastChild; +} )(); + + +// We have to close these tags to support XHTML (#13200) +var wrapMap = { + + // XHTML parsers do not magically insert elements in the + // same way that tag soup parsers do. So we cannot shorten + // this by omitting or other required elements. + thead: [ 1, "", "
" ], + col: [ 2, "", "
" ], + tr: [ 2, "", "
" ], + td: [ 3, "", "
" ], + + _default: [ 0, "", "" ] +}; + +wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; +wrapMap.th = wrapMap.td; + +// Support: IE <=9 only +if ( !support.option ) { + wrapMap.optgroup = wrapMap.option = [ 1, "" ]; +} + + +function getAll( context, tag ) { + + // Support: IE <=9 - 11 only + // Use typeof to avoid zero-argument method invocation on host objects (#15151) + var ret; + + if ( typeof context.getElementsByTagName !== "undefined" ) { + ret = context.getElementsByTagName( tag || "*" ); + + } else if ( typeof context.querySelectorAll !== "undefined" ) { + ret = context.querySelectorAll( tag || "*" ); + + } else { + ret = []; + } + + if ( tag === undefined || tag && nodeName( context, tag ) ) { + return jQuery.merge( [ context ], ret ); + } + + return ret; +} + + +// Mark scripts as having already been evaluated +function setGlobalEval( elems, refElements ) { + var i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + dataPriv.set( + elems[ i ], + "globalEval", + !refElements || dataPriv.get( refElements[ i ], "globalEval" ) + ); + } +} + + +var rhtml = /<|&#?\w+;/; + +function buildFragment( elems, context, scripts, selection, ignored ) { + var elem, tmp, tag, wrap, attached, j, + fragment = context.createDocumentFragment(), + nodes = [], + i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + elem = elems[ i ]; + + if ( elem || elem === 0 ) { + + // Add nodes directly + if ( toType( elem ) === "object" ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); + + // Convert non-html into a text node + } else if ( !rhtml.test( elem ) ) { + nodes.push( context.createTextNode( elem ) ); + + // Convert html into DOM nodes + } else { + tmp = tmp || fragment.appendChild( context.createElement( "div" ) ); + + // Deserialize a standard representation + tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase(); + wrap = wrapMap[ tag ] || wrapMap._default; + tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ]; + + // Descend through wrappers to the right content + j = wrap[ 0 ]; + while ( j-- ) { + tmp = tmp.lastChild; + } + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, tmp.childNodes ); + + // Remember the top-level container + tmp = fragment.firstChild; + + // Ensure the created nodes are orphaned (#12392) + tmp.textContent = ""; + } + } + } + + // Remove wrapper from fragment + fragment.textContent = ""; + + i = 0; + while ( ( elem = nodes[ i++ ] ) ) { + + // Skip elements already in the context collection (trac-4087) + if ( selection && jQuery.inArray( elem, selection ) > -1 ) { + if ( ignored ) { + ignored.push( elem ); + } + continue; + } + + attached = isAttached( elem ); + + // Append to fragment + tmp = getAll( fragment.appendChild( elem ), "script" ); + + // Preserve script evaluation history + if ( attached ) { + setGlobalEval( tmp ); + } + + // Capture executables + if ( scripts ) { + j = 0; + while ( ( elem = tmp[ j++ ] ) ) { + if ( rscriptType.test( elem.type || "" ) ) { + scripts.push( elem ); + } + } + } + } + + return fragment; +} + + +var rtypenamespace = /^([^.]*)(?:\.(.+)|)/; + +function returnTrue() { + return true; +} + +function returnFalse() { + return false; +} + +// Support: IE <=9 - 11+ +// focus() and blur() are asynchronous, except when they are no-op. +// So expect focus to be synchronous when the element is already active, +// and blur to be synchronous when the element is not already active. +// (focus and blur are always synchronous in other supported browsers, +// this just defines when we can count on it). +function expectSync( elem, type ) { + return ( elem === safeActiveElement() ) === ( type === "focus" ); +} + +// Support: IE <=9 only +// Accessing document.activeElement can throw unexpectedly +// https://bugs.jquery.com/ticket/13393 +function safeActiveElement() { + try { + return document.activeElement; + } catch ( err ) { } +} + +function on( elem, types, selector, data, fn, one ) { + var origFn, type; + + // Types can be a map of types/handlers + if ( typeof types === "object" ) { + + // ( types-Object, selector, data ) + if ( typeof selector !== "string" ) { + + // ( types-Object, data ) + data = data || selector; + selector = undefined; + } + for ( type in types ) { + on( elem, type, selector, data, types[ type ], one ); + } + return elem; + } + + if ( data == null && fn == null ) { + + // ( types, fn ) + fn = selector; + data = selector = undefined; + } else if ( fn == null ) { + if ( typeof selector === "string" ) { + + // ( types, selector, fn ) + fn = data; + data = undefined; + } else { + + // ( types, data, fn ) + fn = data; + data = selector; + selector = undefined; + } + } + if ( fn === false ) { + fn = returnFalse; + } else if ( !fn ) { + return elem; + } + + if ( one === 1 ) { + origFn = fn; + fn = function( event ) { + + // Can use an empty set, since event contains the info + jQuery().off( event ); + return origFn.apply( this, arguments ); + }; + + // Use same guid so caller can remove using origFn + fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ ); + } + return elem.each( function() { + jQuery.event.add( this, types, fn, data, selector ); + } ); +} + +/* + * Helper functions for managing events -- not part of the public interface. + * Props to Dean Edwards' addEvent library for many of the ideas. + */ +jQuery.event = { + + global: {}, + + add: function( elem, types, handler, data, selector ) { + + var handleObjIn, eventHandle, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.get( elem ); + + // Only attach events to objects that accept data + if ( !acceptData( elem ) ) { + return; + } + + // Caller can pass in an object of custom data in lieu of the handler + if ( handler.handler ) { + handleObjIn = handler; + handler = handleObjIn.handler; + selector = handleObjIn.selector; + } + + // Ensure that invalid selectors throw exceptions at attach time + // Evaluate against documentElement in case elem is a non-element node (e.g., document) + if ( selector ) { + jQuery.find.matchesSelector( documentElement, selector ); + } + + // Make sure that the handler has a unique ID, used to find/remove it later + if ( !handler.guid ) { + handler.guid = jQuery.guid++; + } + + // Init the element's event structure and main handler, if this is the first + if ( !( events = elemData.events ) ) { + events = elemData.events = Object.create( null ); + } + if ( !( eventHandle = elemData.handle ) ) { + eventHandle = elemData.handle = function( e ) { + + // Discard the second event of a jQuery.event.trigger() and + // when an event is called after a page has unloaded + return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ? + jQuery.event.dispatch.apply( elem, arguments ) : undefined; + }; + } + + // Handle multiple events separated by a space + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // There *must* be a type, no attaching namespace-only handlers + if ( !type ) { + continue; + } + + // If event changes its type, use the special event handlers for the changed type + special = jQuery.event.special[ type ] || {}; + + // If selector defined, determine special event api type, otherwise given type + type = ( selector ? special.delegateType : special.bindType ) || type; + + // Update special based on newly reset type + special = jQuery.event.special[ type ] || {}; + + // handleObj is passed to all event handlers + handleObj = jQuery.extend( { + type: type, + origType: origType, + data: data, + handler: handler, + guid: handler.guid, + selector: selector, + needsContext: selector && jQuery.expr.match.needsContext.test( selector ), + namespace: namespaces.join( "." ) + }, handleObjIn ); + + // Init the event handler queue if we're the first + if ( !( handlers = events[ type ] ) ) { + handlers = events[ type ] = []; + handlers.delegateCount = 0; + + // Only use addEventListener if the special events handler returns false + if ( !special.setup || + special.setup.call( elem, data, namespaces, eventHandle ) === false ) { + + if ( elem.addEventListener ) { + elem.addEventListener( type, eventHandle ); + } + } + } + + if ( special.add ) { + special.add.call( elem, handleObj ); + + if ( !handleObj.handler.guid ) { + handleObj.handler.guid = handler.guid; + } + } + + // Add to the element's handler list, delegates in front + if ( selector ) { + handlers.splice( handlers.delegateCount++, 0, handleObj ); + } else { + handlers.push( handleObj ); + } + + // Keep track of which events have ever been used, for event optimization + jQuery.event.global[ type ] = true; + } + + }, + + // Detach an event or set of events from an element + remove: function( elem, types, handler, selector, mappedTypes ) { + + var j, origCount, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.hasData( elem ) && dataPriv.get( elem ); + + if ( !elemData || !( events = elemData.events ) ) { + return; + } + + // Once for each type.namespace in types; type may be omitted + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // Unbind all events (on this namespace, if provided) for the element + if ( !type ) { + for ( type in events ) { + jQuery.event.remove( elem, type + types[ t ], handler, selector, true ); + } + continue; + } + + special = jQuery.event.special[ type ] || {}; + type = ( selector ? special.delegateType : special.bindType ) || type; + handlers = events[ type ] || []; + tmp = tmp[ 2 ] && + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ); + + // Remove matching events + origCount = j = handlers.length; + while ( j-- ) { + handleObj = handlers[ j ]; + + if ( ( mappedTypes || origType === handleObj.origType ) && + ( !handler || handler.guid === handleObj.guid ) && + ( !tmp || tmp.test( handleObj.namespace ) ) && + ( !selector || selector === handleObj.selector || + selector === "**" && handleObj.selector ) ) { + handlers.splice( j, 1 ); + + if ( handleObj.selector ) { + handlers.delegateCount--; + } + if ( special.remove ) { + special.remove.call( elem, handleObj ); + } + } + } + + // Remove generic event handler if we removed something and no more handlers exist + // (avoids potential for endless recursion during removal of special event handlers) + if ( origCount && !handlers.length ) { + if ( !special.teardown || + special.teardown.call( elem, namespaces, elemData.handle ) === false ) { + + jQuery.removeEvent( elem, type, elemData.handle ); + } + + delete events[ type ]; + } + } + + // Remove data and the expando if it's no longer used + if ( jQuery.isEmptyObject( events ) ) { + dataPriv.remove( elem, "handle events" ); + } + }, + + dispatch: function( nativeEvent ) { + + var i, j, ret, matched, handleObj, handlerQueue, + args = new Array( arguments.length ), + + // Make a writable jQuery.Event from the native event object + event = jQuery.event.fix( nativeEvent ), + + handlers = ( + dataPriv.get( this, "events" ) || Object.create( null ) + )[ event.type ] || [], + special = jQuery.event.special[ event.type ] || {}; + + // Use the fix-ed jQuery.Event rather than the (read-only) native event + args[ 0 ] = event; + + for ( i = 1; i < arguments.length; i++ ) { + args[ i ] = arguments[ i ]; + } + + event.delegateTarget = this; + + // Call the preDispatch hook for the mapped type, and let it bail if desired + if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) { + return; + } + + // Determine handlers + handlerQueue = jQuery.event.handlers.call( this, event, handlers ); + + // Run delegates first; they may want to stop propagation beneath us + i = 0; + while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) { + event.currentTarget = matched.elem; + + j = 0; + while ( ( handleObj = matched.handlers[ j++ ] ) && + !event.isImmediatePropagationStopped() ) { + + // If the event is namespaced, then each handler is only invoked if it is + // specially universal or its namespaces are a superset of the event's. + if ( !event.rnamespace || handleObj.namespace === false || + event.rnamespace.test( handleObj.namespace ) ) { + + event.handleObj = handleObj; + event.data = handleObj.data; + + ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle || + handleObj.handler ).apply( matched.elem, args ); + + if ( ret !== undefined ) { + if ( ( event.result = ret ) === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + } + } + } + + // Call the postDispatch hook for the mapped type + if ( special.postDispatch ) { + special.postDispatch.call( this, event ); + } + + return event.result; + }, + + handlers: function( event, handlers ) { + var i, handleObj, sel, matchedHandlers, matchedSelectors, + handlerQueue = [], + delegateCount = handlers.delegateCount, + cur = event.target; + + // Find delegate handlers + if ( delegateCount && + + // Support: IE <=9 + // Black-hole SVG instance trees (trac-13180) + cur.nodeType && + + // Support: Firefox <=42 + // Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861) + // https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click + // Support: IE 11 only + // ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343) + !( event.type === "click" && event.button >= 1 ) ) { + + for ( ; cur !== this; cur = cur.parentNode || this ) { + + // Don't check non-elements (#13208) + // Don't process clicks on disabled elements (#6911, #8165, #11382, #11764) + if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) { + matchedHandlers = []; + matchedSelectors = {}; + for ( i = 0; i < delegateCount; i++ ) { + handleObj = handlers[ i ]; + + // Don't conflict with Object.prototype properties (#13203) + sel = handleObj.selector + " "; + + if ( matchedSelectors[ sel ] === undefined ) { + matchedSelectors[ sel ] = handleObj.needsContext ? + jQuery( sel, this ).index( cur ) > -1 : + jQuery.find( sel, this, null, [ cur ] ).length; + } + if ( matchedSelectors[ sel ] ) { + matchedHandlers.push( handleObj ); + } + } + if ( matchedHandlers.length ) { + handlerQueue.push( { elem: cur, handlers: matchedHandlers } ); + } + } + } + } + + // Add the remaining (directly-bound) handlers + cur = this; + if ( delegateCount < handlers.length ) { + handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } ); + } + + return handlerQueue; + }, + + addProp: function( name, hook ) { + Object.defineProperty( jQuery.Event.prototype, name, { + enumerable: true, + configurable: true, + + get: isFunction( hook ) ? + function() { + if ( this.originalEvent ) { + return hook( this.originalEvent ); + } + } : + function() { + if ( this.originalEvent ) { + return this.originalEvent[ name ]; + } + }, + + set: function( value ) { + Object.defineProperty( this, name, { + enumerable: true, + configurable: true, + writable: true, + value: value + } ); + } + } ); + }, + + fix: function( originalEvent ) { + return originalEvent[ jQuery.expando ] ? + originalEvent : + new jQuery.Event( originalEvent ); + }, + + special: { + load: { + + // Prevent triggered image.load events from bubbling to window.load + noBubble: true + }, + click: { + + // Utilize native event to ensure correct state for checkable inputs + setup: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Claim the first handler + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + // dataPriv.set( el, "click", ... ) + leverageNative( el, "click", returnTrue ); + } + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Force setup before triggering a click + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + leverageNative( el, "click" ); + } + + // Return non-false to allow normal event-path propagation + return true; + }, + + // For cross-browser consistency, suppress native .click() on links + // Also prevent it if we're currently inside a leveraged native-event stack + _default: function( event ) { + var target = event.target; + return rcheckableType.test( target.type ) && + target.click && nodeName( target, "input" ) && + dataPriv.get( target, "click" ) || + nodeName( target, "a" ); + } + }, + + beforeunload: { + postDispatch: function( event ) { + + // Support: Firefox 20+ + // Firefox doesn't alert if the returnValue field is not set. + if ( event.result !== undefined && event.originalEvent ) { + event.originalEvent.returnValue = event.result; + } + } + } + } +}; + +// Ensure the presence of an event listener that handles manually-triggered +// synthetic events by interrupting progress until reinvoked in response to +// *native* events that it fires directly, ensuring that state changes have +// already occurred before other listeners are invoked. +function leverageNative( el, type, expectSync ) { + + // Missing expectSync indicates a trigger call, which must force setup through jQuery.event.add + if ( !expectSync ) { + if ( dataPriv.get( el, type ) === undefined ) { + jQuery.event.add( el, type, returnTrue ); + } + return; + } + + // Register the controller as a special universal handler for all event namespaces + dataPriv.set( el, type, false ); + jQuery.event.add( el, type, { + namespace: false, + handler: function( event ) { + var notAsync, result, + saved = dataPriv.get( this, type ); + + if ( ( event.isTrigger & 1 ) && this[ type ] ) { + + // Interrupt processing of the outer synthetic .trigger()ed event + // Saved data should be false in such cases, but might be a leftover capture object + // from an async native handler (gh-4350) + if ( !saved.length ) { + + // Store arguments for use when handling the inner native event + // There will always be at least one argument (an event object), so this array + // will not be confused with a leftover capture object. + saved = slice.call( arguments ); + dataPriv.set( this, type, saved ); + + // Trigger the native event and capture its result + // Support: IE <=9 - 11+ + // focus() and blur() are asynchronous + notAsync = expectSync( this, type ); + this[ type ](); + result = dataPriv.get( this, type ); + if ( saved !== result || notAsync ) { + dataPriv.set( this, type, false ); + } else { + result = {}; + } + if ( saved !== result ) { + + // Cancel the outer synthetic event + event.stopImmediatePropagation(); + event.preventDefault(); + + // Support: Chrome 86+ + // In Chrome, if an element having a focusout handler is blurred by + // clicking outside of it, it invokes the handler synchronously. If + // that handler calls `.remove()` on the element, the data is cleared, + // leaving `result` undefined. We need to guard against this. + return result && result.value; + } + + // If this is an inner synthetic event for an event with a bubbling surrogate + // (focus or blur), assume that the surrogate already propagated from triggering the + // native event and prevent that from happening again here. + // This technically gets the ordering wrong w.r.t. to `.trigger()` (in which the + // bubbling surrogate propagates *after* the non-bubbling base), but that seems + // less bad than duplication. + } else if ( ( jQuery.event.special[ type ] || {} ).delegateType ) { + event.stopPropagation(); + } + + // If this is a native event triggered above, everything is now in order + // Fire an inner synthetic event with the original arguments + } else if ( saved.length ) { + + // ...and capture the result + dataPriv.set( this, type, { + value: jQuery.event.trigger( + + // Support: IE <=9 - 11+ + // Extend with the prototype to reset the above stopImmediatePropagation() + jQuery.extend( saved[ 0 ], jQuery.Event.prototype ), + saved.slice( 1 ), + this + ) + } ); + + // Abort handling of the native event + event.stopImmediatePropagation(); + } + } + } ); +} + +jQuery.removeEvent = function( elem, type, handle ) { + + // This "if" is needed for plain objects + if ( elem.removeEventListener ) { + elem.removeEventListener( type, handle ); + } +}; + +jQuery.Event = function( src, props ) { + + // Allow instantiation without the 'new' keyword + if ( !( this instanceof jQuery.Event ) ) { + return new jQuery.Event( src, props ); + } + + // Event object + if ( src && src.type ) { + this.originalEvent = src; + this.type = src.type; + + // Events bubbling up the document may have been marked as prevented + // by a handler lower down the tree; reflect the correct value. + this.isDefaultPrevented = src.defaultPrevented || + src.defaultPrevented === undefined && + + // Support: Android <=2.3 only + src.returnValue === false ? + returnTrue : + returnFalse; + + // Create target properties + // Support: Safari <=6 - 7 only + // Target should not be a text node (#504, #13143) + this.target = ( src.target && src.target.nodeType === 3 ) ? + src.target.parentNode : + src.target; + + this.currentTarget = src.currentTarget; + this.relatedTarget = src.relatedTarget; + + // Event type + } else { + this.type = src; + } + + // Put explicitly provided properties onto the event object + if ( props ) { + jQuery.extend( this, props ); + } + + // Create a timestamp if incoming event doesn't have one + this.timeStamp = src && src.timeStamp || Date.now(); + + // Mark it as fixed + this[ jQuery.expando ] = true; +}; + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + constructor: jQuery.Event, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse, + isSimulated: false, + + preventDefault: function() { + var e = this.originalEvent; + + this.isDefaultPrevented = returnTrue; + + if ( e && !this.isSimulated ) { + e.preventDefault(); + } + }, + stopPropagation: function() { + var e = this.originalEvent; + + this.isPropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopPropagation(); + } + }, + stopImmediatePropagation: function() { + var e = this.originalEvent; + + this.isImmediatePropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopImmediatePropagation(); + } + + this.stopPropagation(); + } +}; + +// Includes all common event props including KeyEvent and MouseEvent specific props +jQuery.each( { + altKey: true, + bubbles: true, + cancelable: true, + changedTouches: true, + ctrlKey: true, + detail: true, + eventPhase: true, + metaKey: true, + pageX: true, + pageY: true, + shiftKey: true, + view: true, + "char": true, + code: true, + charCode: true, + key: true, + keyCode: true, + button: true, + buttons: true, + clientX: true, + clientY: true, + offsetX: true, + offsetY: true, + pointerId: true, + pointerType: true, + screenX: true, + screenY: true, + targetTouches: true, + toElement: true, + touches: true, + which: true +}, jQuery.event.addProp ); + +jQuery.each( { focus: "focusin", blur: "focusout" }, function( type, delegateType ) { + jQuery.event.special[ type ] = { + + // Utilize native event if possible so blur/focus sequence is correct + setup: function() { + + // Claim the first handler + // dataPriv.set( this, "focus", ... ) + // dataPriv.set( this, "blur", ... ) + leverageNative( this, type, expectSync ); + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function() { + + // Force setup before trigger + leverageNative( this, type ); + + // Return non-false to allow normal event-path propagation + return true; + }, + + // Suppress native focus or blur as it's already being fired + // in leverageNative. + _default: function() { + return true; + }, + + delegateType: delegateType + }; +} ); + +// Create mouseenter/leave events using mouseover/out and event-time checks +// so that event delegation works in jQuery. +// Do the same for pointerenter/pointerleave and pointerover/pointerout +// +// Support: Safari 7 only +// Safari sends mouseenter too often; see: +// https://bugs.chromium.org/p/chromium/issues/detail?id=470258 +// for the description of the bug (it existed in older Chrome versions as well). +jQuery.each( { + mouseenter: "mouseover", + mouseleave: "mouseout", + pointerenter: "pointerover", + pointerleave: "pointerout" +}, function( orig, fix ) { + jQuery.event.special[ orig ] = { + delegateType: fix, + bindType: fix, + + handle: function( event ) { + var ret, + target = this, + related = event.relatedTarget, + handleObj = event.handleObj; + + // For mouseenter/leave call the handler if related is outside the target. + // NB: No relatedTarget if the mouse left/entered the browser window + if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) { + event.type = handleObj.origType; + ret = handleObj.handler.apply( this, arguments ); + event.type = fix; + } + return ret; + } + }; +} ); + +jQuery.fn.extend( { + + on: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn ); + }, + one: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn, 1 ); + }, + off: function( types, selector, fn ) { + var handleObj, type; + if ( types && types.preventDefault && types.handleObj ) { + + // ( event ) dispatched jQuery.Event + handleObj = types.handleObj; + jQuery( types.delegateTarget ).off( + handleObj.namespace ? + handleObj.origType + "." + handleObj.namespace : + handleObj.origType, + handleObj.selector, + handleObj.handler + ); + return this; + } + if ( typeof types === "object" ) { + + // ( types-object [, selector] ) + for ( type in types ) { + this.off( type, selector, types[ type ] ); + } + return this; + } + if ( selector === false || typeof selector === "function" ) { + + // ( types [, fn] ) + fn = selector; + selector = undefined; + } + if ( fn === false ) { + fn = returnFalse; + } + return this.each( function() { + jQuery.event.remove( this, types, fn, selector ); + } ); + } +} ); + + +var + + // Support: IE <=10 - 11, Edge 12 - 13 only + // In IE/Edge using regex groups here causes severe slowdowns. + // See https://connect.microsoft.com/IE/feedback/details/1736512/ + rnoInnerhtml = /\s*$/g; + +// Prefer a tbody over its parent table for containing new rows +function manipulationTarget( elem, content ) { + if ( nodeName( elem, "table" ) && + nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) { + + return jQuery( elem ).children( "tbody" )[ 0 ] || elem; + } + + return elem; +} + +// Replace/restore the type attribute of script elements for safe DOM manipulation +function disableScript( elem ) { + elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type; + return elem; +} +function restoreScript( elem ) { + if ( ( elem.type || "" ).slice( 0, 5 ) === "true/" ) { + elem.type = elem.type.slice( 5 ); + } else { + elem.removeAttribute( "type" ); + } + + return elem; +} + +function cloneCopyEvent( src, dest ) { + var i, l, type, pdataOld, udataOld, udataCur, events; + + if ( dest.nodeType !== 1 ) { + return; + } + + // 1. Copy private data: events, handlers, etc. + if ( dataPriv.hasData( src ) ) { + pdataOld = dataPriv.get( src ); + events = pdataOld.events; + + if ( events ) { + dataPriv.remove( dest, "handle events" ); + + for ( type in events ) { + for ( i = 0, l = events[ type ].length; i < l; i++ ) { + jQuery.event.add( dest, type, events[ type ][ i ] ); + } + } + } + } + + // 2. Copy user data + if ( dataUser.hasData( src ) ) { + udataOld = dataUser.access( src ); + udataCur = jQuery.extend( {}, udataOld ); + + dataUser.set( dest, udataCur ); + } +} + +// Fix IE bugs, see support tests +function fixInput( src, dest ) { + var nodeName = dest.nodeName.toLowerCase(); + + // Fails to persist the checked state of a cloned checkbox or radio button. + if ( nodeName === "input" && rcheckableType.test( src.type ) ) { + dest.checked = src.checked; + + // Fails to return the selected option to the default selected state when cloning options + } else if ( nodeName === "input" || nodeName === "textarea" ) { + dest.defaultValue = src.defaultValue; + } +} + +function domManip( collection, args, callback, ignored ) { + + // Flatten any nested arrays + args = flat( args ); + + var fragment, first, scripts, hasScripts, node, doc, + i = 0, + l = collection.length, + iNoClone = l - 1, + value = args[ 0 ], + valueIsFunction = isFunction( value ); + + // We can't cloneNode fragments that contain checked, in WebKit + if ( valueIsFunction || + ( l > 1 && typeof value === "string" && + !support.checkClone && rchecked.test( value ) ) ) { + return collection.each( function( index ) { + var self = collection.eq( index ); + if ( valueIsFunction ) { + args[ 0 ] = value.call( this, index, self.html() ); + } + domManip( self, args, callback, ignored ); + } ); + } + + if ( l ) { + fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored ); + first = fragment.firstChild; + + if ( fragment.childNodes.length === 1 ) { + fragment = first; + } + + // Require either new content or an interest in ignored elements to invoke the callback + if ( first || ignored ) { + scripts = jQuery.map( getAll( fragment, "script" ), disableScript ); + hasScripts = scripts.length; + + // Use the original fragment for the last item + // instead of the first because it can end up + // being emptied incorrectly in certain situations (#8070). + for ( ; i < l; i++ ) { + node = fragment; + + if ( i !== iNoClone ) { + node = jQuery.clone( node, true, true ); + + // Keep references to cloned scripts for later restoration + if ( hasScripts ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( scripts, getAll( node, "script" ) ); + } + } + + callback.call( collection[ i ], node, i ); + } + + if ( hasScripts ) { + doc = scripts[ scripts.length - 1 ].ownerDocument; + + // Reenable scripts + jQuery.map( scripts, restoreScript ); + + // Evaluate executable scripts on first document insertion + for ( i = 0; i < hasScripts; i++ ) { + node = scripts[ i ]; + if ( rscriptType.test( node.type || "" ) && + !dataPriv.access( node, "globalEval" ) && + jQuery.contains( doc, node ) ) { + + if ( node.src && ( node.type || "" ).toLowerCase() !== "module" ) { + + // Optional AJAX dependency, but won't run scripts if not present + if ( jQuery._evalUrl && !node.noModule ) { + jQuery._evalUrl( node.src, { + nonce: node.nonce || node.getAttribute( "nonce" ) + }, doc ); + } + } else { + DOMEval( node.textContent.replace( rcleanScript, "" ), node, doc ); + } + } + } + } + } + } + + return collection; +} + +function remove( elem, selector, keepData ) { + var node, + nodes = selector ? jQuery.filter( selector, elem ) : elem, + i = 0; + + for ( ; ( node = nodes[ i ] ) != null; i++ ) { + if ( !keepData && node.nodeType === 1 ) { + jQuery.cleanData( getAll( node ) ); + } + + if ( node.parentNode ) { + if ( keepData && isAttached( node ) ) { + setGlobalEval( getAll( node, "script" ) ); + } + node.parentNode.removeChild( node ); + } + } + + return elem; +} + +jQuery.extend( { + htmlPrefilter: function( html ) { + return html; + }, + + clone: function( elem, dataAndEvents, deepDataAndEvents ) { + var i, l, srcElements, destElements, + clone = elem.cloneNode( true ), + inPage = isAttached( elem ); + + // Fix IE cloning issues + if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && + !jQuery.isXMLDoc( elem ) ) { + + // We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2 + destElements = getAll( clone ); + srcElements = getAll( elem ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + fixInput( srcElements[ i ], destElements[ i ] ); + } + } + + // Copy the events from the original to the clone + if ( dataAndEvents ) { + if ( deepDataAndEvents ) { + srcElements = srcElements || getAll( elem ); + destElements = destElements || getAll( clone ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + cloneCopyEvent( srcElements[ i ], destElements[ i ] ); + } + } else { + cloneCopyEvent( elem, clone ); + } + } + + // Preserve script evaluation history + destElements = getAll( clone, "script" ); + if ( destElements.length > 0 ) { + setGlobalEval( destElements, !inPage && getAll( elem, "script" ) ); + } + + // Return the cloned set + return clone; + }, + + cleanData: function( elems ) { + var data, elem, type, + special = jQuery.event.special, + i = 0; + + for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) { + if ( acceptData( elem ) ) { + if ( ( data = elem[ dataPriv.expando ] ) ) { + if ( data.events ) { + for ( type in data.events ) { + if ( special[ type ] ) { + jQuery.event.remove( elem, type ); + + // This is a shortcut to avoid jQuery.event.remove's overhead + } else { + jQuery.removeEvent( elem, type, data.handle ); + } + } + } + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataPriv.expando ] = undefined; + } + if ( elem[ dataUser.expando ] ) { + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataUser.expando ] = undefined; + } + } + } + } +} ); + +jQuery.fn.extend( { + detach: function( selector ) { + return remove( this, selector, true ); + }, + + remove: function( selector ) { + return remove( this, selector ); + }, + + text: function( value ) { + return access( this, function( value ) { + return value === undefined ? + jQuery.text( this ) : + this.empty().each( function() { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + this.textContent = value; + } + } ); + }, null, value, arguments.length ); + }, + + append: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.appendChild( elem ); + } + } ); + }, + + prepend: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.insertBefore( elem, target.firstChild ); + } + } ); + }, + + before: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this ); + } + } ); + }, + + after: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this.nextSibling ); + } + } ); + }, + + empty: function() { + var elem, + i = 0; + + for ( ; ( elem = this[ i ] ) != null; i++ ) { + if ( elem.nodeType === 1 ) { + + // Prevent memory leaks + jQuery.cleanData( getAll( elem, false ) ); + + // Remove any remaining nodes + elem.textContent = ""; + } + } + + return this; + }, + + clone: function( dataAndEvents, deepDataAndEvents ) { + dataAndEvents = dataAndEvents == null ? false : dataAndEvents; + deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents; + + return this.map( function() { + return jQuery.clone( this, dataAndEvents, deepDataAndEvents ); + } ); + }, + + html: function( value ) { + return access( this, function( value ) { + var elem = this[ 0 ] || {}, + i = 0, + l = this.length; + + if ( value === undefined && elem.nodeType === 1 ) { + return elem.innerHTML; + } + + // See if we can take a shortcut and just use innerHTML + if ( typeof value === "string" && !rnoInnerhtml.test( value ) && + !wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) { + + value = jQuery.htmlPrefilter( value ); + + try { + for ( ; i < l; i++ ) { + elem = this[ i ] || {}; + + // Remove element nodes and prevent memory leaks + if ( elem.nodeType === 1 ) { + jQuery.cleanData( getAll( elem, false ) ); + elem.innerHTML = value; + } + } + + elem = 0; + + // If using innerHTML throws an exception, use the fallback method + } catch ( e ) {} + } + + if ( elem ) { + this.empty().append( value ); + } + }, null, value, arguments.length ); + }, + + replaceWith: function() { + var ignored = []; + + // Make the changes, replacing each non-ignored context element with the new content + return domManip( this, arguments, function( elem ) { + var parent = this.parentNode; + + if ( jQuery.inArray( this, ignored ) < 0 ) { + jQuery.cleanData( getAll( this ) ); + if ( parent ) { + parent.replaceChild( elem, this ); + } + } + + // Force callback invocation + }, ignored ); + } +} ); + +jQuery.each( { + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function( name, original ) { + jQuery.fn[ name ] = function( selector ) { + var elems, + ret = [], + insert = jQuery( selector ), + last = insert.length - 1, + i = 0; + + for ( ; i <= last; i++ ) { + elems = i === last ? this : this.clone( true ); + jQuery( insert[ i ] )[ original ]( elems ); + + // Support: Android <=4.0 only, PhantomJS 1 only + // .get() because push.apply(_, arraylike) throws on ancient WebKit + push.apply( ret, elems.get() ); + } + + return this.pushStack( ret ); + }; +} ); +var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" ); + +var getStyles = function( elem ) { + + // Support: IE <=11 only, Firefox <=30 (#15098, #14150) + // IE throws on elements created in popups + // FF meanwhile throws on frame elements through "defaultView.getComputedStyle" + var view = elem.ownerDocument.defaultView; + + if ( !view || !view.opener ) { + view = window; + } + + return view.getComputedStyle( elem ); + }; + +var swap = function( elem, options, callback ) { + var ret, name, + old = {}; + + // Remember the old values, and insert the new ones + for ( name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + ret = callback.call( elem ); + + // Revert the old values + for ( name in options ) { + elem.style[ name ] = old[ name ]; + } + + return ret; +}; + + +var rboxStyle = new RegExp( cssExpand.join( "|" ), "i" ); + + + +( function() { + + // Executing both pixelPosition & boxSizingReliable tests require only one layout + // so they're executed at the same time to save the second computation. + function computeStyleTests() { + + // This is a singleton, we need to execute it only once + if ( !div ) { + return; + } + + container.style.cssText = "position:absolute;left:-11111px;width:60px;" + + "margin-top:1px;padding:0;border:0"; + div.style.cssText = + "position:relative;display:block;box-sizing:border-box;overflow:scroll;" + + "margin:auto;border:1px;padding:1px;" + + "width:60%;top:1%"; + documentElement.appendChild( container ).appendChild( div ); + + var divStyle = window.getComputedStyle( div ); + pixelPositionVal = divStyle.top !== "1%"; + + // Support: Android 4.0 - 4.3 only, Firefox <=3 - 44 + reliableMarginLeftVal = roundPixelMeasures( divStyle.marginLeft ) === 12; + + // Support: Android 4.0 - 4.3 only, Safari <=9.1 - 10.1, iOS <=7.0 - 9.3 + // Some styles come back with percentage values, even though they shouldn't + div.style.right = "60%"; + pixelBoxStylesVal = roundPixelMeasures( divStyle.right ) === 36; + + // Support: IE 9 - 11 only + // Detect misreporting of content dimensions for box-sizing:border-box elements + boxSizingReliableVal = roundPixelMeasures( divStyle.width ) === 36; + + // Support: IE 9 only + // Detect overflow:scroll screwiness (gh-3699) + // Support: Chrome <=64 + // Don't get tricked when zoom affects offsetWidth (gh-4029) + div.style.position = "absolute"; + scrollboxSizeVal = roundPixelMeasures( div.offsetWidth / 3 ) === 12; + + documentElement.removeChild( container ); + + // Nullify the div so it wouldn't be stored in the memory and + // it will also be a sign that checks already performed + div = null; + } + + function roundPixelMeasures( measure ) { + return Math.round( parseFloat( measure ) ); + } + + var pixelPositionVal, boxSizingReliableVal, scrollboxSizeVal, pixelBoxStylesVal, + reliableTrDimensionsVal, reliableMarginLeftVal, + container = document.createElement( "div" ), + div = document.createElement( "div" ); + + // Finish early in limited (non-browser) environments + if ( !div.style ) { + return; + } + + // Support: IE <=9 - 11 only + // Style of cloned element affects source element cloned (#8908) + div.style.backgroundClip = "content-box"; + div.cloneNode( true ).style.backgroundClip = ""; + support.clearCloneStyle = div.style.backgroundClip === "content-box"; + + jQuery.extend( support, { + boxSizingReliable: function() { + computeStyleTests(); + return boxSizingReliableVal; + }, + pixelBoxStyles: function() { + computeStyleTests(); + return pixelBoxStylesVal; + }, + pixelPosition: function() { + computeStyleTests(); + return pixelPositionVal; + }, + reliableMarginLeft: function() { + computeStyleTests(); + return reliableMarginLeftVal; + }, + scrollboxSize: function() { + computeStyleTests(); + return scrollboxSizeVal; + }, + + // Support: IE 9 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Behavior in IE 9 is more subtle than in newer versions & it passes + // some versions of this test; make sure not to make it pass there! + // + // Support: Firefox 70+ + // Only Firefox includes border widths + // in computed dimensions. (gh-4529) + reliableTrDimensions: function() { + var table, tr, trChild, trStyle; + if ( reliableTrDimensionsVal == null ) { + table = document.createElement( "table" ); + tr = document.createElement( "tr" ); + trChild = document.createElement( "div" ); + + table.style.cssText = "position:absolute;left:-11111px;border-collapse:separate"; + tr.style.cssText = "border:1px solid"; + + // Support: Chrome 86+ + // Height set through cssText does not get applied. + // Computed height then comes back as 0. + tr.style.height = "1px"; + trChild.style.height = "9px"; + + // Support: Android 8 Chrome 86+ + // In our bodyBackground.html iframe, + // display for all div elements is set to "inline", + // which causes a problem only in Android 8 Chrome 86. + // Ensuring the div is display: block + // gets around this issue. + trChild.style.display = "block"; + + documentElement + .appendChild( table ) + .appendChild( tr ) + .appendChild( trChild ); + + trStyle = window.getComputedStyle( tr ); + reliableTrDimensionsVal = ( parseInt( trStyle.height, 10 ) + + parseInt( trStyle.borderTopWidth, 10 ) + + parseInt( trStyle.borderBottomWidth, 10 ) ) === tr.offsetHeight; + + documentElement.removeChild( table ); + } + return reliableTrDimensionsVal; + } + } ); +} )(); + + +function curCSS( elem, name, computed ) { + var width, minWidth, maxWidth, ret, + + // Support: Firefox 51+ + // Retrieving style before computed somehow + // fixes an issue with getting wrong values + // on detached elements + style = elem.style; + + computed = computed || getStyles( elem ); + + // getPropertyValue is needed for: + // .css('filter') (IE 9 only, #12537) + // .css('--customProperty) (#3144) + if ( computed ) { + ret = computed.getPropertyValue( name ) || computed[ name ]; + + if ( ret === "" && !isAttached( elem ) ) { + ret = jQuery.style( elem, name ); + } + + // A tribute to the "awesome hack by Dean Edwards" + // Android Browser returns percentage for some values, + // but width seems to be reliably pixels. + // This is against the CSSOM draft spec: + // https://drafts.csswg.org/cssom/#resolved-values + if ( !support.pixelBoxStyles() && rnumnonpx.test( ret ) && rboxStyle.test( name ) ) { + + // Remember the original values + width = style.width; + minWidth = style.minWidth; + maxWidth = style.maxWidth; + + // Put in the new values to get a computed value out + style.minWidth = style.maxWidth = style.width = ret; + ret = computed.width; + + // Revert the changed values + style.width = width; + style.minWidth = minWidth; + style.maxWidth = maxWidth; + } + } + + return ret !== undefined ? + + // Support: IE <=9 - 11 only + // IE returns zIndex value as an integer. + ret + "" : + ret; +} + + +function addGetHookIf( conditionFn, hookFn ) { + + // Define the hook, we'll check on the first run if it's really needed. + return { + get: function() { + if ( conditionFn() ) { + + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. + delete this.get; + return; + } + + // Hook needed; redefine it so that the support test is not executed again. + return ( this.get = hookFn ).apply( this, arguments ); + } + }; +} + + +var cssPrefixes = [ "Webkit", "Moz", "ms" ], + emptyStyle = document.createElement( "div" ).style, + vendorProps = {}; + +// Return a vendor-prefixed property or undefined +function vendorPropName( name ) { + + // Check for vendor prefixed names + var capName = name[ 0 ].toUpperCase() + name.slice( 1 ), + i = cssPrefixes.length; + + while ( i-- ) { + name = cssPrefixes[ i ] + capName; + if ( name in emptyStyle ) { + return name; + } + } +} + +// Return a potentially-mapped jQuery.cssProps or vendor prefixed property +function finalPropName( name ) { + var final = jQuery.cssProps[ name ] || vendorProps[ name ]; + + if ( final ) { + return final; + } + if ( name in emptyStyle ) { + return name; + } + return vendorProps[ name ] = vendorPropName( name ) || name; +} + + +var + + // Swappable if display is none or starts with table + // except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + rdisplayswap = /^(none|table(?!-c[ea]).+)/, + rcustomProp = /^--/, + cssShow = { position: "absolute", visibility: "hidden", display: "block" }, + cssNormalTransform = { + letterSpacing: "0", + fontWeight: "400" + }; + +function setPositiveNumber( _elem, value, subtract ) { + + // Any relative (+/-) values have already been + // normalized at this point + var matches = rcssNum.exec( value ); + return matches ? + + // Guard against undefined "subtract", e.g., when used as in cssHooks + Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) : + value; +} + +function boxModelAdjustment( elem, dimension, box, isBorderBox, styles, computedVal ) { + var i = dimension === "width" ? 1 : 0, + extra = 0, + delta = 0; + + // Adjustment may not be necessary + if ( box === ( isBorderBox ? "border" : "content" ) ) { + return 0; + } + + for ( ; i < 4; i += 2 ) { + + // Both box models exclude margin + if ( box === "margin" ) { + delta += jQuery.css( elem, box + cssExpand[ i ], true, styles ); + } + + // If we get here with a content-box, we're seeking "padding" or "border" or "margin" + if ( !isBorderBox ) { + + // Add padding + delta += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + + // For "border" or "margin", add border + if ( box !== "padding" ) { + delta += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + + // But still keep track of it otherwise + } else { + extra += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + + // If we get here with a border-box (content + padding + border), we're seeking "content" or + // "padding" or "margin" + } else { + + // For "content", subtract padding + if ( box === "content" ) { + delta -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + } + + // For "content" or "padding", subtract border + if ( box !== "margin" ) { + delta -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + } + } + + // Account for positive content-box scroll gutter when requested by providing computedVal + if ( !isBorderBox && computedVal >= 0 ) { + + // offsetWidth/offsetHeight is a rounded sum of content, padding, scroll gutter, and border + // Assuming integer scroll gutter, subtract the rest and round down + delta += Math.max( 0, Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + computedVal - + delta - + extra - + 0.5 + + // If offsetWidth/offsetHeight is unknown, then we can't determine content-box scroll gutter + // Use an explicit zero to avoid NaN (gh-3964) + ) ) || 0; + } + + return delta; +} + +function getWidthOrHeight( elem, dimension, extra ) { + + // Start with computed style + var styles = getStyles( elem ), + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-4322). + // Fake content-box until we know it's needed to know the true value. + boxSizingNeeded = !support.boxSizingReliable() || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + valueIsBorderBox = isBorderBox, + + val = curCSS( elem, dimension, styles ), + offsetProp = "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ); + + // Support: Firefox <=54 + // Return a confounding non-pixel value or feign ignorance, as appropriate. + if ( rnumnonpx.test( val ) ) { + if ( !extra ) { + return val; + } + val = "auto"; + } + + + // Support: IE 9 - 11 only + // Use offsetWidth/offsetHeight for when box sizing is unreliable. + // In those cases, the computed value can be trusted to be border-box. + if ( ( !support.boxSizingReliable() && isBorderBox || + + // Support: IE 10 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Interestingly, in some cases IE 9 doesn't suffer from this issue. + !support.reliableTrDimensions() && nodeName( elem, "tr" ) || + + // Fall back to offsetWidth/offsetHeight when value is "auto" + // This happens for inline elements with no explicit setting (gh-3571) + val === "auto" || + + // Support: Android <=4.1 - 4.3 only + // Also use offsetWidth/offsetHeight for misreported inline dimensions (gh-3602) + !parseFloat( val ) && jQuery.css( elem, "display", false, styles ) === "inline" ) && + + // Make sure the element is visible & connected + elem.getClientRects().length ) { + + isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; + + // Where available, offsetWidth/offsetHeight approximate border box dimensions. + // Where not available (e.g., SVG), assume unreliable box-sizing and interpret the + // retrieved value as a content box dimension. + valueIsBorderBox = offsetProp in elem; + if ( valueIsBorderBox ) { + val = elem[ offsetProp ]; + } + } + + // Normalize "" and auto + val = parseFloat( val ) || 0; + + // Adjust for the element's box model + return ( val + + boxModelAdjustment( + elem, + dimension, + extra || ( isBorderBox ? "border" : "content" ), + valueIsBorderBox, + styles, + + // Provide the current computed size to request scroll gutter calculation (gh-3589) + val + ) + ) + "px"; +} + +jQuery.extend( { + + // Add in style property hooks for overriding the default + // behavior of getting and setting a style property + cssHooks: { + opacity: { + get: function( elem, computed ) { + if ( computed ) { + + // We should always get a number back from opacity + var ret = curCSS( elem, "opacity" ); + return ret === "" ? "1" : ret; + } + } + } + }, + + // Don't automatically add "px" to these possibly-unitless properties + cssNumber: { + "animationIterationCount": true, + "columnCount": true, + "fillOpacity": true, + "flexGrow": true, + "flexShrink": true, + "fontWeight": true, + "gridArea": true, + "gridColumn": true, + "gridColumnEnd": true, + "gridColumnStart": true, + "gridRow": true, + "gridRowEnd": true, + "gridRowStart": true, + "lineHeight": true, + "opacity": true, + "order": true, + "orphans": true, + "widows": true, + "zIndex": true, + "zoom": true + }, + + // Add in properties whose names you wish to fix before + // setting or getting the value + cssProps: {}, + + // Get and set the style property on a DOM Node + style: function( elem, name, value, extra ) { + + // Don't set styles on text and comment nodes + if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { + return; + } + + // Make sure that we're working with the right name + var ret, type, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ), + style = elem.style; + + // Make sure that we're working with the right name. We don't + // want to query the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Gets hook for the prefixed version, then unprefixed version + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // Check if we're setting a value + if ( value !== undefined ) { + type = typeof value; + + // Convert "+=" or "-=" to relative numbers (#7345) + if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) { + value = adjustCSS( elem, name, ret ); + + // Fixes bug #9237 + type = "number"; + } + + // Make sure that null and NaN values aren't set (#7116) + if ( value == null || value !== value ) { + return; + } + + // If a number was passed in, add the unit (except for certain CSS properties) + // The isCustomProp check can be removed in jQuery 4.0 when we only auto-append + // "px" to a few hardcoded values. + if ( type === "number" && !isCustomProp ) { + value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" ); + } + + // background-* props affect original clone's values + if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { + style[ name ] = "inherit"; + } + + // If a hook was provided, use that value, otherwise just set the specified value + if ( !hooks || !( "set" in hooks ) || + ( value = hooks.set( elem, value, extra ) ) !== undefined ) { + + if ( isCustomProp ) { + style.setProperty( name, value ); + } else { + style[ name ] = value; + } + } + + } else { + + // If a hook was provided get the non-computed value from there + if ( hooks && "get" in hooks && + ( ret = hooks.get( elem, false, extra ) ) !== undefined ) { + + return ret; + } + + // Otherwise just get the value from the style object + return style[ name ]; + } + }, + + css: function( elem, name, extra, styles ) { + var val, num, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ); + + // Make sure that we're working with the right name. We don't + // want to modify the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Try prefixed name followed by the unprefixed name + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // If a hook was provided get the computed value from there + if ( hooks && "get" in hooks ) { + val = hooks.get( elem, true, extra ); + } + + // Otherwise, if a way to get the computed value exists, use that + if ( val === undefined ) { + val = curCSS( elem, name, styles ); + } + + // Convert "normal" to computed value + if ( val === "normal" && name in cssNormalTransform ) { + val = cssNormalTransform[ name ]; + } + + // Make numeric if forced or a qualifier was provided and val looks numeric + if ( extra === "" || extra ) { + num = parseFloat( val ); + return extra === true || isFinite( num ) ? num || 0 : val; + } + + return val; + } +} ); + +jQuery.each( [ "height", "width" ], function( _i, dimension ) { + jQuery.cssHooks[ dimension ] = { + get: function( elem, computed, extra ) { + if ( computed ) { + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit + return rdisplayswap.test( jQuery.css( elem, "display" ) ) && + + // Support: Safari 8+ + // Table columns in Safari have non-zero offsetWidth & zero + // getBoundingClientRect().width unless display is changed. + // Support: IE <=11 only + // Running getBoundingClientRect on a disconnected node + // in IE throws an error. + ( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ? + swap( elem, cssShow, function() { + return getWidthOrHeight( elem, dimension, extra ); + } ) : + getWidthOrHeight( elem, dimension, extra ); + } + }, + + set: function( elem, value, extra ) { + var matches, + styles = getStyles( elem ), + + // Only read styles.position if the test has a chance to fail + // to avoid forcing a reflow. + scrollboxSizeBuggy = !support.scrollboxSize() && + styles.position === "absolute", + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-3991) + boxSizingNeeded = scrollboxSizeBuggy || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + subtract = extra ? + boxModelAdjustment( + elem, + dimension, + extra, + isBorderBox, + styles + ) : + 0; + + // Account for unreliable border-box dimensions by comparing offset* to computed and + // faking a content-box to get border and padding (gh-3699) + if ( isBorderBox && scrollboxSizeBuggy ) { + subtract -= Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + parseFloat( styles[ dimension ] ) - + boxModelAdjustment( elem, dimension, "border", false, styles ) - + 0.5 + ); + } + + // Convert to pixels if value adjustment is needed + if ( subtract && ( matches = rcssNum.exec( value ) ) && + ( matches[ 3 ] || "px" ) !== "px" ) { + + elem.style[ dimension ] = value; + value = jQuery.css( elem, dimension ); + } + + return setPositiveNumber( elem, value, subtract ); + } + }; +} ); + +jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft, + function( elem, computed ) { + if ( computed ) { + return ( parseFloat( curCSS( elem, "marginLeft" ) ) || + elem.getBoundingClientRect().left - + swap( elem, { marginLeft: 0 }, function() { + return elem.getBoundingClientRect().left; + } ) + ) + "px"; + } + } +); + +// These hooks are used by animate to expand properties +jQuery.each( { + margin: "", + padding: "", + border: "Width" +}, function( prefix, suffix ) { + jQuery.cssHooks[ prefix + suffix ] = { + expand: function( value ) { + var i = 0, + expanded = {}, + + // Assumes a single number if not a string + parts = typeof value === "string" ? value.split( " " ) : [ value ]; + + for ( ; i < 4; i++ ) { + expanded[ prefix + cssExpand[ i ] + suffix ] = + parts[ i ] || parts[ i - 2 ] || parts[ 0 ]; + } + + return expanded; + } + }; + + if ( prefix !== "margin" ) { + jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber; + } +} ); + +jQuery.fn.extend( { + css: function( name, value ) { + return access( this, function( elem, name, value ) { + var styles, len, + map = {}, + i = 0; + + if ( Array.isArray( name ) ) { + styles = getStyles( elem ); + len = name.length; + + for ( ; i < len; i++ ) { + map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles ); + } + + return map; + } + + return value !== undefined ? + jQuery.style( elem, name, value ) : + jQuery.css( elem, name ); + }, name, value, arguments.length > 1 ); + } +} ); + + +function Tween( elem, options, prop, end, easing ) { + return new Tween.prototype.init( elem, options, prop, end, easing ); +} +jQuery.Tween = Tween; + +Tween.prototype = { + constructor: Tween, + init: function( elem, options, prop, end, easing, unit ) { + this.elem = elem; + this.prop = prop; + this.easing = easing || jQuery.easing._default; + this.options = options; + this.start = this.now = this.cur(); + this.end = end; + this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" ); + }, + cur: function() { + var hooks = Tween.propHooks[ this.prop ]; + + return hooks && hooks.get ? + hooks.get( this ) : + Tween.propHooks._default.get( this ); + }, + run: function( percent ) { + var eased, + hooks = Tween.propHooks[ this.prop ]; + + if ( this.options.duration ) { + this.pos = eased = jQuery.easing[ this.easing ]( + percent, this.options.duration * percent, 0, 1, this.options.duration + ); + } else { + this.pos = eased = percent; + } + this.now = ( this.end - this.start ) * eased + this.start; + + if ( this.options.step ) { + this.options.step.call( this.elem, this.now, this ); + } + + if ( hooks && hooks.set ) { + hooks.set( this ); + } else { + Tween.propHooks._default.set( this ); + } + return this; + } +}; + +Tween.prototype.init.prototype = Tween.prototype; + +Tween.propHooks = { + _default: { + get: function( tween ) { + var result; + + // Use a property on the element directly when it is not a DOM element, + // or when there is no matching style property that exists. + if ( tween.elem.nodeType !== 1 || + tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) { + return tween.elem[ tween.prop ]; + } + + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. + result = jQuery.css( tween.elem, tween.prop, "" ); + + // Empty strings, null, undefined and "auto" are converted to 0. + return !result || result === "auto" ? 0 : result; + }, + set: function( tween ) { + + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. + if ( jQuery.fx.step[ tween.prop ] ) { + jQuery.fx.step[ tween.prop ]( tween ); + } else if ( tween.elem.nodeType === 1 && ( + jQuery.cssHooks[ tween.prop ] || + tween.elem.style[ finalPropName( tween.prop ) ] != null ) ) { + jQuery.style( tween.elem, tween.prop, tween.now + tween.unit ); + } else { + tween.elem[ tween.prop ] = tween.now; + } + } + } +}; + +// Support: IE <=9 only +// Panic based approach to setting things on disconnected nodes +Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { + set: function( tween ) { + if ( tween.elem.nodeType && tween.elem.parentNode ) { + tween.elem[ tween.prop ] = tween.now; + } + } +}; + +jQuery.easing = { + linear: function( p ) { + return p; + }, + swing: function( p ) { + return 0.5 - Math.cos( p * Math.PI ) / 2; + }, + _default: "swing" +}; + +jQuery.fx = Tween.prototype.init; + +// Back compat <1.8 extension point +jQuery.fx.step = {}; + + + + +var + fxNow, inProgress, + rfxtypes = /^(?:toggle|show|hide)$/, + rrun = /queueHooks$/; + +function schedule() { + if ( inProgress ) { + if ( document.hidden === false && window.requestAnimationFrame ) { + window.requestAnimationFrame( schedule ); + } else { + window.setTimeout( schedule, jQuery.fx.interval ); + } + + jQuery.fx.tick(); + } +} + +// Animations created synchronously will run synchronously +function createFxNow() { + window.setTimeout( function() { + fxNow = undefined; + } ); + return ( fxNow = Date.now() ); +} + +// Generate parameters to create a standard animation +function genFx( type, includeWidth ) { + var which, + i = 0, + attrs = { height: type }; + + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right + includeWidth = includeWidth ? 1 : 0; + for ( ; i < 4; i += 2 - includeWidth ) { + which = cssExpand[ i ]; + attrs[ "margin" + which ] = attrs[ "padding" + which ] = type; + } + + if ( includeWidth ) { + attrs.opacity = attrs.width = type; + } + + return attrs; +} + +function createTween( value, prop, animation ) { + var tween, + collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ), + index = 0, + length = collection.length; + for ( ; index < length; index++ ) { + if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) { + + // We're done with this property + return tween; + } + } +} + +function defaultPrefilter( elem, props, opts ) { + var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display, + isBox = "width" in props || "height" in props, + anim = this, + orig = {}, + style = elem.style, + hidden = elem.nodeType && isHiddenWithinTree( elem ), + dataShow = dataPriv.get( elem, "fxshow" ); + + // Queue-skipping animations hijack the fx hooks + if ( !opts.queue ) { + hooks = jQuery._queueHooks( elem, "fx" ); + if ( hooks.unqueued == null ) { + hooks.unqueued = 0; + oldfire = hooks.empty.fire; + hooks.empty.fire = function() { + if ( !hooks.unqueued ) { + oldfire(); + } + }; + } + hooks.unqueued++; + + anim.always( function() { + + // Ensure the complete handler is called before this completes + anim.always( function() { + hooks.unqueued--; + if ( !jQuery.queue( elem, "fx" ).length ) { + hooks.empty.fire(); + } + } ); + } ); + } + + // Detect show/hide animations + for ( prop in props ) { + value = props[ prop ]; + if ( rfxtypes.test( value ) ) { + delete props[ prop ]; + toggle = toggle || value === "toggle"; + if ( value === ( hidden ? "hide" : "show" ) ) { + + // Pretend to be hidden if this is a "show" and + // there is still data from a stopped show/hide + if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) { + hidden = true; + + // Ignore all other no-op show/hide data + } else { + continue; + } + } + orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop ); + } + } + + // Bail out if this is a no-op like .hide().hide() + propTween = !jQuery.isEmptyObject( props ); + if ( !propTween && jQuery.isEmptyObject( orig ) ) { + return; + } + + // Restrict "overflow" and "display" styles during box animations + if ( isBox && elem.nodeType === 1 ) { + + // Support: IE <=9 - 11, Edge 12 - 15 + // Record all 3 overflow attributes because IE does not infer the shorthand + // from identically-valued overflowX and overflowY and Edge just mirrors + // the overflowX value there. + opts.overflow = [ style.overflow, style.overflowX, style.overflowY ]; + + // Identify a display type, preferring old show/hide data over the CSS cascade + restoreDisplay = dataShow && dataShow.display; + if ( restoreDisplay == null ) { + restoreDisplay = dataPriv.get( elem, "display" ); + } + display = jQuery.css( elem, "display" ); + if ( display === "none" ) { + if ( restoreDisplay ) { + display = restoreDisplay; + } else { + + // Get nonempty value(s) by temporarily forcing visibility + showHide( [ elem ], true ); + restoreDisplay = elem.style.display || restoreDisplay; + display = jQuery.css( elem, "display" ); + showHide( [ elem ] ); + } + } + + // Animate inline elements as inline-block + if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) { + if ( jQuery.css( elem, "float" ) === "none" ) { + + // Restore the original display value at the end of pure show/hide animations + if ( !propTween ) { + anim.done( function() { + style.display = restoreDisplay; + } ); + if ( restoreDisplay == null ) { + display = style.display; + restoreDisplay = display === "none" ? "" : display; + } + } + style.display = "inline-block"; + } + } + } + + if ( opts.overflow ) { + style.overflow = "hidden"; + anim.always( function() { + style.overflow = opts.overflow[ 0 ]; + style.overflowX = opts.overflow[ 1 ]; + style.overflowY = opts.overflow[ 2 ]; + } ); + } + + // Implement show/hide animations + propTween = false; + for ( prop in orig ) { + + // General show/hide setup for this element animation + if ( !propTween ) { + if ( dataShow ) { + if ( "hidden" in dataShow ) { + hidden = dataShow.hidden; + } + } else { + dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } ); + } + + // Store hidden/visible for toggle so `.stop().toggle()` "reverses" + if ( toggle ) { + dataShow.hidden = !hidden; + } + + // Show elements before animating them + if ( hidden ) { + showHide( [ elem ], true ); + } + + /* eslint-disable no-loop-func */ + + anim.done( function() { + + /* eslint-enable no-loop-func */ + + // The final step of a "hide" animation is actually hiding the element + if ( !hidden ) { + showHide( [ elem ] ); + } + dataPriv.remove( elem, "fxshow" ); + for ( prop in orig ) { + jQuery.style( elem, prop, orig[ prop ] ); + } + } ); + } + + // Per-property setup + propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim ); + if ( !( prop in dataShow ) ) { + dataShow[ prop ] = propTween.start; + if ( hidden ) { + propTween.end = propTween.start; + propTween.start = 0; + } + } + } +} + +function propFilter( props, specialEasing ) { + var index, name, easing, value, hooks; + + // camelCase, specialEasing and expand cssHook pass + for ( index in props ) { + name = camelCase( index ); + easing = specialEasing[ name ]; + value = props[ index ]; + if ( Array.isArray( value ) ) { + easing = value[ 1 ]; + value = props[ index ] = value[ 0 ]; + } + + if ( index !== name ) { + props[ name ] = value; + delete props[ index ]; + } + + hooks = jQuery.cssHooks[ name ]; + if ( hooks && "expand" in hooks ) { + value = hooks.expand( value ); + delete props[ name ]; + + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" + for ( index in value ) { + if ( !( index in props ) ) { + props[ index ] = value[ index ]; + specialEasing[ index ] = easing; + } + } + } else { + specialEasing[ name ] = easing; + } + } +} + +function Animation( elem, properties, options ) { + var result, + stopped, + index = 0, + length = Animation.prefilters.length, + deferred = jQuery.Deferred().always( function() { + + // Don't match elem in the :animated selector + delete tick.elem; + } ), + tick = function() { + if ( stopped ) { + return false; + } + var currentTime = fxNow || createFxNow(), + remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), + + // Support: Android 2.3 only + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) + temp = remaining / animation.duration || 0, + percent = 1 - temp, + index = 0, + length = animation.tweens.length; + + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( percent ); + } + + deferred.notifyWith( elem, [ animation, percent, remaining ] ); + + // If there's more to do, yield + if ( percent < 1 && length ) { + return remaining; + } + + // If this was an empty animation, synthesize a final progress notification + if ( !length ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + } + + // Resolve the animation and report its conclusion + deferred.resolveWith( elem, [ animation ] ); + return false; + }, + animation = deferred.promise( { + elem: elem, + props: jQuery.extend( {}, properties ), + opts: jQuery.extend( true, { + specialEasing: {}, + easing: jQuery.easing._default + }, options ), + originalProperties: properties, + originalOptions: options, + startTime: fxNow || createFxNow(), + duration: options.duration, + tweens: [], + createTween: function( prop, end ) { + var tween = jQuery.Tween( elem, animation.opts, prop, end, + animation.opts.specialEasing[ prop ] || animation.opts.easing ); + animation.tweens.push( tween ); + return tween; + }, + stop: function( gotoEnd ) { + var index = 0, + + // If we are going to the end, we want to run all the tweens + // otherwise we skip this part + length = gotoEnd ? animation.tweens.length : 0; + if ( stopped ) { + return this; + } + stopped = true; + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( 1 ); + } + + // Resolve when we played the last frame; otherwise, reject + if ( gotoEnd ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + deferred.resolveWith( elem, [ animation, gotoEnd ] ); + } else { + deferred.rejectWith( elem, [ animation, gotoEnd ] ); + } + return this; + } + } ), + props = animation.props; + + propFilter( props, animation.opts.specialEasing ); + + for ( ; index < length; index++ ) { + result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts ); + if ( result ) { + if ( isFunction( result.stop ) ) { + jQuery._queueHooks( animation.elem, animation.opts.queue ).stop = + result.stop.bind( result ); + } + return result; + } + } + + jQuery.map( props, createTween, animation ); + + if ( isFunction( animation.opts.start ) ) { + animation.opts.start.call( elem, animation ); + } + + // Attach callbacks from options + animation + .progress( animation.opts.progress ) + .done( animation.opts.done, animation.opts.complete ) + .fail( animation.opts.fail ) + .always( animation.opts.always ); + + jQuery.fx.timer( + jQuery.extend( tick, { + elem: elem, + anim: animation, + queue: animation.opts.queue + } ) + ); + + return animation; +} + +jQuery.Animation = jQuery.extend( Animation, { + + tweeners: { + "*": [ function( prop, value ) { + var tween = this.createTween( prop, value ); + adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween ); + return tween; + } ] + }, + + tweener: function( props, callback ) { + if ( isFunction( props ) ) { + callback = props; + props = [ "*" ]; + } else { + props = props.match( rnothtmlwhite ); + } + + var prop, + index = 0, + length = props.length; + + for ( ; index < length; index++ ) { + prop = props[ index ]; + Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || []; + Animation.tweeners[ prop ].unshift( callback ); + } + }, + + prefilters: [ defaultPrefilter ], + + prefilter: function( callback, prepend ) { + if ( prepend ) { + Animation.prefilters.unshift( callback ); + } else { + Animation.prefilters.push( callback ); + } + } +} ); + +jQuery.speed = function( speed, easing, fn ) { + var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : { + complete: fn || !fn && easing || + isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !isFunction( easing ) && easing + }; + + // Go to the end state if fx are off + if ( jQuery.fx.off ) { + opt.duration = 0; + + } else { + if ( typeof opt.duration !== "number" ) { + if ( opt.duration in jQuery.fx.speeds ) { + opt.duration = jQuery.fx.speeds[ opt.duration ]; + + } else { + opt.duration = jQuery.fx.speeds._default; + } + } + } + + // Normalize opt.queue - true/undefined/null -> "fx" + if ( opt.queue == null || opt.queue === true ) { + opt.queue = "fx"; + } + + // Queueing + opt.old = opt.complete; + + opt.complete = function() { + if ( isFunction( opt.old ) ) { + opt.old.call( this ); + } + + if ( opt.queue ) { + jQuery.dequeue( this, opt.queue ); + } + }; + + return opt; +}; + +jQuery.fn.extend( { + fadeTo: function( speed, to, easing, callback ) { + + // Show any hidden elements after setting opacity to 0 + return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show() + + // Animate to the value specified + .end().animate( { opacity: to }, speed, easing, callback ); + }, + animate: function( prop, speed, easing, callback ) { + var empty = jQuery.isEmptyObject( prop ), + optall = jQuery.speed( speed, easing, callback ), + doAnimation = function() { + + // Operate on a copy of prop so per-property easing won't be lost + var anim = Animation( this, jQuery.extend( {}, prop ), optall ); + + // Empty animations, or finishing resolves immediately + if ( empty || dataPriv.get( this, "finish" ) ) { + anim.stop( true ); + } + }; + + doAnimation.finish = doAnimation; + + return empty || optall.queue === false ? + this.each( doAnimation ) : + this.queue( optall.queue, doAnimation ); + }, + stop: function( type, clearQueue, gotoEnd ) { + var stopQueue = function( hooks ) { + var stop = hooks.stop; + delete hooks.stop; + stop( gotoEnd ); + }; + + if ( typeof type !== "string" ) { + gotoEnd = clearQueue; + clearQueue = type; + type = undefined; + } + if ( clearQueue ) { + this.queue( type || "fx", [] ); + } + + return this.each( function() { + var dequeue = true, + index = type != null && type + "queueHooks", + timers = jQuery.timers, + data = dataPriv.get( this ); + + if ( index ) { + if ( data[ index ] && data[ index ].stop ) { + stopQueue( data[ index ] ); + } + } else { + for ( index in data ) { + if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) { + stopQueue( data[ index ] ); + } + } + } + + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && + ( type == null || timers[ index ].queue === type ) ) { + + timers[ index ].anim.stop( gotoEnd ); + dequeue = false; + timers.splice( index, 1 ); + } + } + + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. + if ( dequeue || !gotoEnd ) { + jQuery.dequeue( this, type ); + } + } ); + }, + finish: function( type ) { + if ( type !== false ) { + type = type || "fx"; + } + return this.each( function() { + var index, + data = dataPriv.get( this ), + queue = data[ type + "queue" ], + hooks = data[ type + "queueHooks" ], + timers = jQuery.timers, + length = queue ? queue.length : 0; + + // Enable finishing flag on private data + data.finish = true; + + // Empty the queue first + jQuery.queue( this, type, [] ); + + if ( hooks && hooks.stop ) { + hooks.stop.call( this, true ); + } + + // Look for any active animations, and finish them + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && timers[ index ].queue === type ) { + timers[ index ].anim.stop( true ); + timers.splice( index, 1 ); + } + } + + // Look for any animations in the old queue and finish them + for ( index = 0; index < length; index++ ) { + if ( queue[ index ] && queue[ index ].finish ) { + queue[ index ].finish.call( this ); + } + } + + // Turn off finishing flag + delete data.finish; + } ); + } +} ); + +jQuery.each( [ "toggle", "show", "hide" ], function( _i, name ) { + var cssFn = jQuery.fn[ name ]; + jQuery.fn[ name ] = function( speed, easing, callback ) { + return speed == null || typeof speed === "boolean" ? + cssFn.apply( this, arguments ) : + this.animate( genFx( name, true ), speed, easing, callback ); + }; +} ); + +// Generate shortcuts for custom animations +jQuery.each( { + slideDown: genFx( "show" ), + slideUp: genFx( "hide" ), + slideToggle: genFx( "toggle" ), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" }, + fadeToggle: { opacity: "toggle" } +}, function( name, props ) { + jQuery.fn[ name ] = function( speed, easing, callback ) { + return this.animate( props, speed, easing, callback ); + }; +} ); + +jQuery.timers = []; +jQuery.fx.tick = function() { + var timer, + i = 0, + timers = jQuery.timers; + + fxNow = Date.now(); + + for ( ; i < timers.length; i++ ) { + timer = timers[ i ]; + + // Run the timer and safely remove it when done (allowing for external removal) + if ( !timer() && timers[ i ] === timer ) { + timers.splice( i--, 1 ); + } + } + + if ( !timers.length ) { + jQuery.fx.stop(); + } + fxNow = undefined; +}; + +jQuery.fx.timer = function( timer ) { + jQuery.timers.push( timer ); + jQuery.fx.start(); +}; + +jQuery.fx.interval = 13; +jQuery.fx.start = function() { + if ( inProgress ) { + return; + } + + inProgress = true; + schedule(); +}; + +jQuery.fx.stop = function() { + inProgress = null; +}; + +jQuery.fx.speeds = { + slow: 600, + fast: 200, + + // Default speed + _default: 400 +}; + + +// Based off of the plugin by Clint Helfers, with permission. +// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/ +jQuery.fn.delay = function( time, type ) { + time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time; + type = type || "fx"; + + return this.queue( type, function( next, hooks ) { + var timeout = window.setTimeout( next, time ); + hooks.stop = function() { + window.clearTimeout( timeout ); + }; + } ); +}; + + +( function() { + var input = document.createElement( "input" ), + select = document.createElement( "select" ), + opt = select.appendChild( document.createElement( "option" ) ); + + input.type = "checkbox"; + + // Support: Android <=4.3 only + // Default value for a checkbox should be "on" + support.checkOn = input.value !== ""; + + // Support: IE <=11 only + // Must access selectedIndex to make default options select + support.optSelected = opt.selected; + + // Support: IE <=11 only + // An input loses its value after becoming a radio + input = document.createElement( "input" ); + input.value = "t"; + input.type = "radio"; + support.radioValue = input.value === "t"; +} )(); + + +var boolHook, + attrHandle = jQuery.expr.attrHandle; + +jQuery.fn.extend( { + attr: function( name, value ) { + return access( this, jQuery.attr, name, value, arguments.length > 1 ); + }, + + removeAttr: function( name ) { + return this.each( function() { + jQuery.removeAttr( this, name ); + } ); + } +} ); + +jQuery.extend( { + attr: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set attributes on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + // Fallback to prop when attributes are not supported + if ( typeof elem.getAttribute === "undefined" ) { + return jQuery.prop( elem, name, value ); + } + + // Attribute hooks are determined by the lowercase version + // Grab necessary hook if one is defined + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + hooks = jQuery.attrHooks[ name.toLowerCase() ] || + ( jQuery.expr.match.bool.test( name ) ? boolHook : undefined ); + } + + if ( value !== undefined ) { + if ( value === null ) { + jQuery.removeAttr( elem, name ); + return; + } + + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + elem.setAttribute( name, value + "" ); + return value; + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + ret = jQuery.find.attr( elem, name ); + + // Non-existent attributes return null, we normalize to undefined + return ret == null ? undefined : ret; + }, + + attrHooks: { + type: { + set: function( elem, value ) { + if ( !support.radioValue && value === "radio" && + nodeName( elem, "input" ) ) { + var val = elem.value; + elem.setAttribute( "type", value ); + if ( val ) { + elem.value = val; + } + return value; + } + } + } + }, + + removeAttr: function( elem, value ) { + var name, + i = 0, + + // Attribute names can contain non-HTML whitespace characters + // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 + attrNames = value && value.match( rnothtmlwhite ); + + if ( attrNames && elem.nodeType === 1 ) { + while ( ( name = attrNames[ i++ ] ) ) { + elem.removeAttribute( name ); + } + } + } +} ); + +// Hooks for boolean attributes +boolHook = { + set: function( elem, value, name ) { + if ( value === false ) { + + // Remove boolean attributes when set to false + jQuery.removeAttr( elem, name ); + } else { + elem.setAttribute( name, name ); + } + return name; + } +}; + +jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( _i, name ) { + var getter = attrHandle[ name ] || jQuery.find.attr; + + attrHandle[ name ] = function( elem, name, isXML ) { + var ret, handle, + lowercaseName = name.toLowerCase(); + + if ( !isXML ) { + + // Avoid an infinite loop by temporarily removing this function from the getter + handle = attrHandle[ lowercaseName ]; + attrHandle[ lowercaseName ] = ret; + ret = getter( elem, name, isXML ) != null ? + lowercaseName : + null; + attrHandle[ lowercaseName ] = handle; + } + return ret; + }; +} ); + + + + +var rfocusable = /^(?:input|select|textarea|button)$/i, + rclickable = /^(?:a|area)$/i; + +jQuery.fn.extend( { + prop: function( name, value ) { + return access( this, jQuery.prop, name, value, arguments.length > 1 ); + }, + + removeProp: function( name ) { + return this.each( function() { + delete this[ jQuery.propFix[ name ] || name ]; + } ); + } +} ); + +jQuery.extend( { + prop: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set properties on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + + // Fix name and attach hooks + name = jQuery.propFix[ name ] || name; + hooks = jQuery.propHooks[ name ]; + } + + if ( value !== undefined ) { + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + return ( elem[ name ] = value ); + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + return elem[ name ]; + }, + + propHooks: { + tabIndex: { + get: function( elem ) { + + // Support: IE <=9 - 11 only + // elem.tabIndex doesn't always return the + // correct value when it hasn't been explicitly set + // https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + // Use proper attribute retrieval(#12072) + var tabindex = jQuery.find.attr( elem, "tabindex" ); + + if ( tabindex ) { + return parseInt( tabindex, 10 ); + } + + if ( + rfocusable.test( elem.nodeName ) || + rclickable.test( elem.nodeName ) && + elem.href + ) { + return 0; + } + + return -1; + } + } + }, + + propFix: { + "for": "htmlFor", + "class": "className" + } +} ); + +// Support: IE <=11 only +// Accessing the selectedIndex property +// forces the browser to respect setting selected +// on the option +// The getter ensures a default option is selected +// when in an optgroup +// eslint rule "no-unused-expressions" is disabled for this code +// since it considers such accessions noop +if ( !support.optSelected ) { + jQuery.propHooks.selected = { + get: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent && parent.parentNode ) { + parent.parentNode.selectedIndex; + } + return null; + }, + set: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent ) { + parent.selectedIndex; + + if ( parent.parentNode ) { + parent.parentNode.selectedIndex; + } + } + } + }; +} + +jQuery.each( [ + "tabIndex", + "readOnly", + "maxLength", + "cellSpacing", + "cellPadding", + "rowSpan", + "colSpan", + "useMap", + "frameBorder", + "contentEditable" +], function() { + jQuery.propFix[ this.toLowerCase() ] = this; +} ); + + + + + // Strip and collapse whitespace according to HTML spec + // https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace + function stripAndCollapse( value ) { + var tokens = value.match( rnothtmlwhite ) || []; + return tokens.join( " " ); + } + + +function getClass( elem ) { + return elem.getAttribute && elem.getAttribute( "class" ) || ""; +} + +function classesToArray( value ) { + if ( Array.isArray( value ) ) { + return value; + } + if ( typeof value === "string" ) { + return value.match( rnothtmlwhite ) || []; + } + return []; +} + +jQuery.fn.extend( { + addClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).addClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + if ( cur.indexOf( " " + clazz + " " ) < 0 ) { + cur += clazz + " "; + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + removeClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + if ( !arguments.length ) { + return this.attr( "class", "" ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + + // This expression is here for better compressibility (see addClass) + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + + // Remove *all* instances + while ( cur.indexOf( " " + clazz + " " ) > -1 ) { + cur = cur.replace( " " + clazz + " ", " " ); + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + toggleClass: function( value, stateVal ) { + var type = typeof value, + isValidValue = type === "string" || Array.isArray( value ); + + if ( typeof stateVal === "boolean" && isValidValue ) { + return stateVal ? this.addClass( value ) : this.removeClass( value ); + } + + if ( isFunction( value ) ) { + return this.each( function( i ) { + jQuery( this ).toggleClass( + value.call( this, i, getClass( this ), stateVal ), + stateVal + ); + } ); + } + + return this.each( function() { + var className, i, self, classNames; + + if ( isValidValue ) { + + // Toggle individual class names + i = 0; + self = jQuery( this ); + classNames = classesToArray( value ); + + while ( ( className = classNames[ i++ ] ) ) { + + // Check each className given, space separated list + if ( self.hasClass( className ) ) { + self.removeClass( className ); + } else { + self.addClass( className ); + } + } + + // Toggle whole class name + } else if ( value === undefined || type === "boolean" ) { + className = getClass( this ); + if ( className ) { + + // Store className if set + dataPriv.set( this, "__className__", className ); + } + + // If the element has a class name or if we're passed `false`, + // then remove the whole classname (if there was one, the above saved it). + // Otherwise bring back whatever was previously saved (if anything), + // falling back to the empty string if nothing was stored. + if ( this.setAttribute ) { + this.setAttribute( "class", + className || value === false ? + "" : + dataPriv.get( this, "__className__" ) || "" + ); + } + } + } ); + }, + + hasClass: function( selector ) { + var className, elem, + i = 0; + + className = " " + selector + " "; + while ( ( elem = this[ i++ ] ) ) { + if ( elem.nodeType === 1 && + ( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) { + return true; + } + } + + return false; + } +} ); + + + + +var rreturn = /\r/g; + +jQuery.fn.extend( { + val: function( value ) { + var hooks, ret, valueIsFunction, + elem = this[ 0 ]; + + if ( !arguments.length ) { + if ( elem ) { + hooks = jQuery.valHooks[ elem.type ] || + jQuery.valHooks[ elem.nodeName.toLowerCase() ]; + + if ( hooks && + "get" in hooks && + ( ret = hooks.get( elem, "value" ) ) !== undefined + ) { + return ret; + } + + ret = elem.value; + + // Handle most common string cases + if ( typeof ret === "string" ) { + return ret.replace( rreturn, "" ); + } + + // Handle cases where value is null/undef or number + return ret == null ? "" : ret; + } + + return; + } + + valueIsFunction = isFunction( value ); + + return this.each( function( i ) { + var val; + + if ( this.nodeType !== 1 ) { + return; + } + + if ( valueIsFunction ) { + val = value.call( this, i, jQuery( this ).val() ); + } else { + val = value; + } + + // Treat null/undefined as ""; convert numbers to string + if ( val == null ) { + val = ""; + + } else if ( typeof val === "number" ) { + val += ""; + + } else if ( Array.isArray( val ) ) { + val = jQuery.map( val, function( value ) { + return value == null ? "" : value + ""; + } ); + } + + hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ]; + + // If set returns undefined, fall back to normal setting + if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) { + this.value = val; + } + } ); + } +} ); + +jQuery.extend( { + valHooks: { + option: { + get: function( elem ) { + + var val = jQuery.find.attr( elem, "value" ); + return val != null ? + val : + + // Support: IE <=10 - 11 only + // option.text throws exceptions (#14686, #14858) + // Strip and collapse whitespace + // https://html.spec.whatwg.org/#strip-and-collapse-whitespace + stripAndCollapse( jQuery.text( elem ) ); + } + }, + select: { + get: function( elem ) { + var value, option, i, + options = elem.options, + index = elem.selectedIndex, + one = elem.type === "select-one", + values = one ? null : [], + max = one ? index + 1 : options.length; + + if ( index < 0 ) { + i = max; + + } else { + i = one ? index : 0; + } + + // Loop through all the selected options + for ( ; i < max; i++ ) { + option = options[ i ]; + + // Support: IE <=9 only + // IE8-9 doesn't update selected after form reset (#2551) + if ( ( option.selected || i === index ) && + + // Don't return options that are disabled or in a disabled optgroup + !option.disabled && + ( !option.parentNode.disabled || + !nodeName( option.parentNode, "optgroup" ) ) ) { + + // Get the specific value for the option + value = jQuery( option ).val(); + + // We don't need an array for one selects + if ( one ) { + return value; + } + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + }, + + set: function( elem, value ) { + var optionSet, option, + options = elem.options, + values = jQuery.makeArray( value ), + i = options.length; + + while ( i-- ) { + option = options[ i ]; + + /* eslint-disable no-cond-assign */ + + if ( option.selected = + jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1 + ) { + optionSet = true; + } + + /* eslint-enable no-cond-assign */ + } + + // Force browsers to behave consistently when non-matching value is set + if ( !optionSet ) { + elem.selectedIndex = -1; + } + return values; + } + } + } +} ); + +// Radios and checkboxes getter/setter +jQuery.each( [ "radio", "checkbox" ], function() { + jQuery.valHooks[ this ] = { + set: function( elem, value ) { + if ( Array.isArray( value ) ) { + return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 ); + } + } + }; + if ( !support.checkOn ) { + jQuery.valHooks[ this ].get = function( elem ) { + return elem.getAttribute( "value" ) === null ? "on" : elem.value; + }; + } +} ); + + + + +// Return jQuery for attributes-only inclusion + + +support.focusin = "onfocusin" in window; + + +var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/, + stopPropagationCallback = function( e ) { + e.stopPropagation(); + }; + +jQuery.extend( jQuery.event, { + + trigger: function( event, data, elem, onlyHandlers ) { + + var i, cur, tmp, bubbleType, ontype, handle, special, lastElement, + eventPath = [ elem || document ], + type = hasOwn.call( event, "type" ) ? event.type : event, + namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : []; + + cur = lastElement = tmp = elem = elem || document; + + // Don't do events on text and comment nodes + if ( elem.nodeType === 3 || elem.nodeType === 8 ) { + return; + } + + // focus/blur morphs to focusin/out; ensure we're not firing them right now + if ( rfocusMorph.test( type + jQuery.event.triggered ) ) { + return; + } + + if ( type.indexOf( "." ) > -1 ) { + + // Namespaced trigger; create a regexp to match event type in handle() + namespaces = type.split( "." ); + type = namespaces.shift(); + namespaces.sort(); + } + ontype = type.indexOf( ":" ) < 0 && "on" + type; + + // Caller can pass in a jQuery.Event object, Object, or just an event type string + event = event[ jQuery.expando ] ? + event : + new jQuery.Event( type, typeof event === "object" && event ); + + // Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true) + event.isTrigger = onlyHandlers ? 2 : 3; + event.namespace = namespaces.join( "." ); + event.rnamespace = event.namespace ? + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) : + null; + + // Clean up the event in case it is being reused + event.result = undefined; + if ( !event.target ) { + event.target = elem; + } + + // Clone any incoming data and prepend the event, creating the handler arg list + data = data == null ? + [ event ] : + jQuery.makeArray( data, [ event ] ); + + // Allow special events to draw outside the lines + special = jQuery.event.special[ type ] || {}; + if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) { + return; + } + + // Determine event propagation path in advance, per W3C events spec (#9951) + // Bubble up to document, then to window; watch for a global ownerDocument var (#9724) + if ( !onlyHandlers && !special.noBubble && !isWindow( elem ) ) { + + bubbleType = special.delegateType || type; + if ( !rfocusMorph.test( bubbleType + type ) ) { + cur = cur.parentNode; + } + for ( ; cur; cur = cur.parentNode ) { + eventPath.push( cur ); + tmp = cur; + } + + // Only add window if we got to document (e.g., not plain obj or detached DOM) + if ( tmp === ( elem.ownerDocument || document ) ) { + eventPath.push( tmp.defaultView || tmp.parentWindow || window ); + } + } + + // Fire handlers on the event path + i = 0; + while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) { + lastElement = cur; + event.type = i > 1 ? + bubbleType : + special.bindType || type; + + // jQuery handler + handle = ( dataPriv.get( cur, "events" ) || Object.create( null ) )[ event.type ] && + dataPriv.get( cur, "handle" ); + if ( handle ) { + handle.apply( cur, data ); + } + + // Native handler + handle = ontype && cur[ ontype ]; + if ( handle && handle.apply && acceptData( cur ) ) { + event.result = handle.apply( cur, data ); + if ( event.result === false ) { + event.preventDefault(); + } + } + } + event.type = type; + + // If nobody prevented the default action, do it now + if ( !onlyHandlers && !event.isDefaultPrevented() ) { + + if ( ( !special._default || + special._default.apply( eventPath.pop(), data ) === false ) && + acceptData( elem ) ) { + + // Call a native DOM method on the target with the same name as the event. + // Don't do default actions on window, that's where global variables be (#6170) + if ( ontype && isFunction( elem[ type ] ) && !isWindow( elem ) ) { + + // Don't re-trigger an onFOO event when we call its FOO() method + tmp = elem[ ontype ]; + + if ( tmp ) { + elem[ ontype ] = null; + } + + // Prevent re-triggering of the same event, since we already bubbled it above + jQuery.event.triggered = type; + + if ( event.isPropagationStopped() ) { + lastElement.addEventListener( type, stopPropagationCallback ); + } + + elem[ type ](); + + if ( event.isPropagationStopped() ) { + lastElement.removeEventListener( type, stopPropagationCallback ); + } + + jQuery.event.triggered = undefined; + + if ( tmp ) { + elem[ ontype ] = tmp; + } + } + } + } + + return event.result; + }, + + // Piggyback on a donor event to simulate a different one + // Used only for `focus(in | out)` events + simulate: function( type, elem, event ) { + var e = jQuery.extend( + new jQuery.Event(), + event, + { + type: type, + isSimulated: true + } + ); + + jQuery.event.trigger( e, null, elem ); + } + +} ); + +jQuery.fn.extend( { + + trigger: function( type, data ) { + return this.each( function() { + jQuery.event.trigger( type, data, this ); + } ); + }, + triggerHandler: function( type, data ) { + var elem = this[ 0 ]; + if ( elem ) { + return jQuery.event.trigger( type, data, elem, true ); + } + } +} ); + + +// Support: Firefox <=44 +// Firefox doesn't have focus(in | out) events +// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787 +// +// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1 +// focus(in | out) events fire after focus & blur events, +// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order +// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857 +if ( !support.focusin ) { + jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) { + + // Attach a single capturing handler on the document while someone wants focusin/focusout + var handler = function( event ) { + jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) ); + }; + + jQuery.event.special[ fix ] = { + setup: function() { + + // Handle: regular nodes (via `this.ownerDocument`), window + // (via `this.document`) & document (via `this`). + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ); + + if ( !attaches ) { + doc.addEventListener( orig, handler, true ); + } + dataPriv.access( doc, fix, ( attaches || 0 ) + 1 ); + }, + teardown: function() { + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ) - 1; + + if ( !attaches ) { + doc.removeEventListener( orig, handler, true ); + dataPriv.remove( doc, fix ); + + } else { + dataPriv.access( doc, fix, attaches ); + } + } + }; + } ); +} +var location = window.location; + +var nonce = { guid: Date.now() }; + +var rquery = ( /\?/ ); + + + +// Cross-browser xml parsing +jQuery.parseXML = function( data ) { + var xml, parserErrorElem; + if ( !data || typeof data !== "string" ) { + return null; + } + + // Support: IE 9 - 11 only + // IE throws on parseFromString with invalid input. + try { + xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" ); + } catch ( e ) {} + + parserErrorElem = xml && xml.getElementsByTagName( "parsererror" )[ 0 ]; + if ( !xml || parserErrorElem ) { + jQuery.error( "Invalid XML: " + ( + parserErrorElem ? + jQuery.map( parserErrorElem.childNodes, function( el ) { + return el.textContent; + } ).join( "\n" ) : + data + ) ); + } + return xml; +}; + + +var + rbracket = /\[\]$/, + rCRLF = /\r?\n/g, + rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i, + rsubmittable = /^(?:input|select|textarea|keygen)/i; + +function buildParams( prefix, obj, traditional, add ) { + var name; + + if ( Array.isArray( obj ) ) { + + // Serialize array item. + jQuery.each( obj, function( i, v ) { + if ( traditional || rbracket.test( prefix ) ) { + + // Treat each array item as a scalar. + add( prefix, v ); + + } else { + + // Item is non-scalar (array or object), encode its numeric index. + buildParams( + prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]", + v, + traditional, + add + ); + } + } ); + + } else if ( !traditional && toType( obj ) === "object" ) { + + // Serialize object item. + for ( name in obj ) { + buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add ); + } + + } else { + + // Serialize scalar item. + add( prefix, obj ); + } +} + +// Serialize an array of form elements or a set of +// key/values into a query string +jQuery.param = function( a, traditional ) { + var prefix, + s = [], + add = function( key, valueOrFunction ) { + + // If value is a function, invoke it and use its return value + var value = isFunction( valueOrFunction ) ? + valueOrFunction() : + valueOrFunction; + + s[ s.length ] = encodeURIComponent( key ) + "=" + + encodeURIComponent( value == null ? "" : value ); + }; + + if ( a == null ) { + return ""; + } + + // If an array was passed in, assume that it is an array of form elements. + if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) { + + // Serialize the form elements + jQuery.each( a, function() { + add( this.name, this.value ); + } ); + + } else { + + // If traditional, encode the "old" way (the way 1.3.2 or older + // did it), otherwise encode params recursively. + for ( prefix in a ) { + buildParams( prefix, a[ prefix ], traditional, add ); + } + } + + // Return the resulting serialization + return s.join( "&" ); +}; + +jQuery.fn.extend( { + serialize: function() { + return jQuery.param( this.serializeArray() ); + }, + serializeArray: function() { + return this.map( function() { + + // Can add propHook for "elements" to filter or add form elements + var elements = jQuery.prop( this, "elements" ); + return elements ? jQuery.makeArray( elements ) : this; + } ).filter( function() { + var type = this.type; + + // Use .is( ":disabled" ) so that fieldset[disabled] works + return this.name && !jQuery( this ).is( ":disabled" ) && + rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) && + ( this.checked || !rcheckableType.test( type ) ); + } ).map( function( _i, elem ) { + var val = jQuery( this ).val(); + + if ( val == null ) { + return null; + } + + if ( Array.isArray( val ) ) { + return jQuery.map( val, function( val ) { + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ); + } + + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ).get(); + } +} ); + + +var + r20 = /%20/g, + rhash = /#.*$/, + rantiCache = /([?&])_=[^&]*/, + rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg, + + // #7653, #8125, #8152: local protocol detection + rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/, + rnoContent = /^(?:GET|HEAD)$/, + rprotocol = /^\/\//, + + /* Prefilters + * 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example) + * 2) These are called: + * - BEFORE asking for a transport + * - AFTER param serialization (s.data is a string if s.processData is true) + * 3) key is the dataType + * 4) the catchall symbol "*" can be used + * 5) execution will start with transport dataType and THEN continue down to "*" if needed + */ + prefilters = {}, + + /* Transports bindings + * 1) key is the dataType + * 2) the catchall symbol "*" can be used + * 3) selection will start with transport dataType and THEN go to "*" if needed + */ + transports = {}, + + // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression + allTypes = "*/".concat( "*" ), + + // Anchor tag for parsing the document origin + originAnchor = document.createElement( "a" ); + +originAnchor.href = location.href; + +// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport +function addToPrefiltersOrTransports( structure ) { + + // dataTypeExpression is optional and defaults to "*" + return function( dataTypeExpression, func ) { + + if ( typeof dataTypeExpression !== "string" ) { + func = dataTypeExpression; + dataTypeExpression = "*"; + } + + var dataType, + i = 0, + dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || []; + + if ( isFunction( func ) ) { + + // For each dataType in the dataTypeExpression + while ( ( dataType = dataTypes[ i++ ] ) ) { + + // Prepend if requested + if ( dataType[ 0 ] === "+" ) { + dataType = dataType.slice( 1 ) || "*"; + ( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func ); + + // Otherwise append + } else { + ( structure[ dataType ] = structure[ dataType ] || [] ).push( func ); + } + } + } + }; +} + +// Base inspection function for prefilters and transports +function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) { + + var inspected = {}, + seekingTransport = ( structure === transports ); + + function inspect( dataType ) { + var selected; + inspected[ dataType ] = true; + jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) { + var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR ); + if ( typeof dataTypeOrTransport === "string" && + !seekingTransport && !inspected[ dataTypeOrTransport ] ) { + + options.dataTypes.unshift( dataTypeOrTransport ); + inspect( dataTypeOrTransport ); + return false; + } else if ( seekingTransport ) { + return !( selected = dataTypeOrTransport ); + } + } ); + return selected; + } + + return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" ); +} + +// A special extend for ajax options +// that takes "flat" options (not to be deep extended) +// Fixes #9887 +function ajaxExtend( target, src ) { + var key, deep, + flatOptions = jQuery.ajaxSettings.flatOptions || {}; + + for ( key in src ) { + if ( src[ key ] !== undefined ) { + ( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ]; + } + } + if ( deep ) { + jQuery.extend( true, target, deep ); + } + + return target; +} + +/* Handles responses to an ajax request: + * - finds the right dataType (mediates between content-type and expected dataType) + * - returns the corresponding response + */ +function ajaxHandleResponses( s, jqXHR, responses ) { + + var ct, type, finalDataType, firstDataType, + contents = s.contents, + dataTypes = s.dataTypes; + + // Remove auto dataType and get content-type in the process + while ( dataTypes[ 0 ] === "*" ) { + dataTypes.shift(); + if ( ct === undefined ) { + ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" ); + } + } + + // Check if we're dealing with a known content-type + if ( ct ) { + for ( type in contents ) { + if ( contents[ type ] && contents[ type ].test( ct ) ) { + dataTypes.unshift( type ); + break; + } + } + } + + // Check to see if we have a response for the expected dataType + if ( dataTypes[ 0 ] in responses ) { + finalDataType = dataTypes[ 0 ]; + } else { + + // Try convertible dataTypes + for ( type in responses ) { + if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) { + finalDataType = type; + break; + } + if ( !firstDataType ) { + firstDataType = type; + } + } + + // Or just use first one + finalDataType = finalDataType || firstDataType; + } + + // If we found a dataType + // We add the dataType to the list if needed + // and return the corresponding response + if ( finalDataType ) { + if ( finalDataType !== dataTypes[ 0 ] ) { + dataTypes.unshift( finalDataType ); + } + return responses[ finalDataType ]; + } +} + +/* Chain conversions given the request and the original response + * Also sets the responseXXX fields on the jqXHR instance + */ +function ajaxConvert( s, response, jqXHR, isSuccess ) { + var conv2, current, conv, tmp, prev, + converters = {}, + + // Work with a copy of dataTypes in case we need to modify it for conversion + dataTypes = s.dataTypes.slice(); + + // Create converters map with lowercased keys + if ( dataTypes[ 1 ] ) { + for ( conv in s.converters ) { + converters[ conv.toLowerCase() ] = s.converters[ conv ]; + } + } + + current = dataTypes.shift(); + + // Convert to each sequential dataType + while ( current ) { + + if ( s.responseFields[ current ] ) { + jqXHR[ s.responseFields[ current ] ] = response; + } + + // Apply the dataFilter if provided + if ( !prev && isSuccess && s.dataFilter ) { + response = s.dataFilter( response, s.dataType ); + } + + prev = current; + current = dataTypes.shift(); + + if ( current ) { + + // There's only work to do if current dataType is non-auto + if ( current === "*" ) { + + current = prev; + + // Convert response if prev dataType is non-auto and differs from current + } else if ( prev !== "*" && prev !== current ) { + + // Seek a direct converter + conv = converters[ prev + " " + current ] || converters[ "* " + current ]; + + // If none found, seek a pair + if ( !conv ) { + for ( conv2 in converters ) { + + // If conv2 outputs current + tmp = conv2.split( " " ); + if ( tmp[ 1 ] === current ) { + + // If prev can be converted to accepted input + conv = converters[ prev + " " + tmp[ 0 ] ] || + converters[ "* " + tmp[ 0 ] ]; + if ( conv ) { + + // Condense equivalence converters + if ( conv === true ) { + conv = converters[ conv2 ]; + + // Otherwise, insert the intermediate dataType + } else if ( converters[ conv2 ] !== true ) { + current = tmp[ 0 ]; + dataTypes.unshift( tmp[ 1 ] ); + } + break; + } + } + } + } + + // Apply converter (if not an equivalence) + if ( conv !== true ) { + + // Unless errors are allowed to bubble, catch and return them + if ( conv && s.throws ) { + response = conv( response ); + } else { + try { + response = conv( response ); + } catch ( e ) { + return { + state: "parsererror", + error: conv ? e : "No conversion from " + prev + " to " + current + }; + } + } + } + } + } + } + + return { state: "success", data: response }; +} + +jQuery.extend( { + + // Counter for holding the number of active queries + active: 0, + + // Last-Modified header cache for next request + lastModified: {}, + etag: {}, + + ajaxSettings: { + url: location.href, + type: "GET", + isLocal: rlocalProtocol.test( location.protocol ), + global: true, + processData: true, + async: true, + contentType: "application/x-www-form-urlencoded; charset=UTF-8", + + /* + timeout: 0, + data: null, + dataType: null, + username: null, + password: null, + cache: null, + throws: false, + traditional: false, + headers: {}, + */ + + accepts: { + "*": allTypes, + text: "text/plain", + html: "text/html", + xml: "application/xml, text/xml", + json: "application/json, text/javascript" + }, + + contents: { + xml: /\bxml\b/, + html: /\bhtml/, + json: /\bjson\b/ + }, + + responseFields: { + xml: "responseXML", + text: "responseText", + json: "responseJSON" + }, + + // Data converters + // Keys separate source (or catchall "*") and destination types with a single space + converters: { + + // Convert anything to text + "* text": String, + + // Text to html (true = no transformation) + "text html": true, + + // Evaluate text as a json expression + "text json": JSON.parse, + + // Parse text as xml + "text xml": jQuery.parseXML + }, + + // For options that shouldn't be deep extended: + // you can add your own custom options here if + // and when you create one that shouldn't be + // deep extended (see ajaxExtend) + flatOptions: { + url: true, + context: true + } + }, + + // Creates a full fledged settings object into target + // with both ajaxSettings and settings fields. + // If target is omitted, writes into ajaxSettings. + ajaxSetup: function( target, settings ) { + return settings ? + + // Building a settings object + ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) : + + // Extending ajaxSettings + ajaxExtend( jQuery.ajaxSettings, target ); + }, + + ajaxPrefilter: addToPrefiltersOrTransports( prefilters ), + ajaxTransport: addToPrefiltersOrTransports( transports ), + + // Main method + ajax: function( url, options ) { + + // If url is an object, simulate pre-1.5 signature + if ( typeof url === "object" ) { + options = url; + url = undefined; + } + + // Force options to be an object + options = options || {}; + + var transport, + + // URL without anti-cache param + cacheURL, + + // Response headers + responseHeadersString, + responseHeaders, + + // timeout handle + timeoutTimer, + + // Url cleanup var + urlAnchor, + + // Request state (becomes false upon send and true upon completion) + completed, + + // To know if global events are to be dispatched + fireGlobals, + + // Loop variable + i, + + // uncached part of the url + uncached, + + // Create the final options object + s = jQuery.ajaxSetup( {}, options ), + + // Callbacks context + callbackContext = s.context || s, + + // Context for global events is callbackContext if it is a DOM node or jQuery collection + globalEventContext = s.context && + ( callbackContext.nodeType || callbackContext.jquery ) ? + jQuery( callbackContext ) : + jQuery.event, + + // Deferreds + deferred = jQuery.Deferred(), + completeDeferred = jQuery.Callbacks( "once memory" ), + + // Status-dependent callbacks + statusCode = s.statusCode || {}, + + // Headers (they are sent all at once) + requestHeaders = {}, + requestHeadersNames = {}, + + // Default abort message + strAbort = "canceled", + + // Fake xhr + jqXHR = { + readyState: 0, + + // Builds headers hashtable if needed + getResponseHeader: function( key ) { + var match; + if ( completed ) { + if ( !responseHeaders ) { + responseHeaders = {}; + while ( ( match = rheaders.exec( responseHeadersString ) ) ) { + responseHeaders[ match[ 1 ].toLowerCase() + " " ] = + ( responseHeaders[ match[ 1 ].toLowerCase() + " " ] || [] ) + .concat( match[ 2 ] ); + } + } + match = responseHeaders[ key.toLowerCase() + " " ]; + } + return match == null ? null : match.join( ", " ); + }, + + // Raw string + getAllResponseHeaders: function() { + return completed ? responseHeadersString : null; + }, + + // Caches the header + setRequestHeader: function( name, value ) { + if ( completed == null ) { + name = requestHeadersNames[ name.toLowerCase() ] = + requestHeadersNames[ name.toLowerCase() ] || name; + requestHeaders[ name ] = value; + } + return this; + }, + + // Overrides response content-type header + overrideMimeType: function( type ) { + if ( completed == null ) { + s.mimeType = type; + } + return this; + }, + + // Status-dependent callbacks + statusCode: function( map ) { + var code; + if ( map ) { + if ( completed ) { + + // Execute the appropriate callbacks + jqXHR.always( map[ jqXHR.status ] ); + } else { + + // Lazy-add the new callbacks in a way that preserves old ones + for ( code in map ) { + statusCode[ code ] = [ statusCode[ code ], map[ code ] ]; + } + } + } + return this; + }, + + // Cancel the request + abort: function( statusText ) { + var finalText = statusText || strAbort; + if ( transport ) { + transport.abort( finalText ); + } + done( 0, finalText ); + return this; + } + }; + + // Attach deferreds + deferred.promise( jqXHR ); + + // Add protocol if not provided (prefilters might expect it) + // Handle falsy url in the settings object (#10093: consistency with old signature) + // We also use the url parameter if available + s.url = ( ( url || s.url || location.href ) + "" ) + .replace( rprotocol, location.protocol + "//" ); + + // Alias method option to type as per ticket #12004 + s.type = options.method || options.type || s.method || s.type; + + // Extract dataTypes list + s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ]; + + // A cross-domain request is in order when the origin doesn't match the current origin. + if ( s.crossDomain == null ) { + urlAnchor = document.createElement( "a" ); + + // Support: IE <=8 - 11, Edge 12 - 15 + // IE throws exception on accessing the href property if url is malformed, + // e.g. http://example.com:80x/ + try { + urlAnchor.href = s.url; + + // Support: IE <=8 - 11 only + // Anchor's host property isn't correctly set when s.url is relative + urlAnchor.href = urlAnchor.href; + s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !== + urlAnchor.protocol + "//" + urlAnchor.host; + } catch ( e ) { + + // If there is an error parsing the URL, assume it is crossDomain, + // it can be rejected by the transport if it is invalid + s.crossDomain = true; + } + } + + // Convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) { + s.data = jQuery.param( s.data, s.traditional ); + } + + // Apply prefilters + inspectPrefiltersOrTransports( prefilters, s, options, jqXHR ); + + // If request was aborted inside a prefilter, stop there + if ( completed ) { + return jqXHR; + } + + // We can fire global events as of now if asked to + // Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118) + fireGlobals = jQuery.event && s.global; + + // Watch for a new set of requests + if ( fireGlobals && jQuery.active++ === 0 ) { + jQuery.event.trigger( "ajaxStart" ); + } + + // Uppercase the type + s.type = s.type.toUpperCase(); + + // Determine if request has content + s.hasContent = !rnoContent.test( s.type ); + + // Save the URL in case we're toying with the If-Modified-Since + // and/or If-None-Match header later on + // Remove hash to simplify url manipulation + cacheURL = s.url.replace( rhash, "" ); + + // More options handling for requests with no content + if ( !s.hasContent ) { + + // Remember the hash so we can put it back + uncached = s.url.slice( cacheURL.length ); + + // If data is available and should be processed, append data to url + if ( s.data && ( s.processData || typeof s.data === "string" ) ) { + cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data; + + // #9682: remove data so that it's not used in an eventual retry + delete s.data; + } + + // Add or update anti-cache param if needed + if ( s.cache === false ) { + cacheURL = cacheURL.replace( rantiCache, "$1" ); + uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce.guid++ ) + + uncached; + } + + // Put hash and anti-cache on the URL that will be requested (gh-1732) + s.url = cacheURL + uncached; + + // Change '%20' to '+' if this is encoded form body content (gh-2658) + } else if ( s.data && s.processData && + ( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) { + s.data = s.data.replace( r20, "+" ); + } + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + if ( jQuery.lastModified[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] ); + } + if ( jQuery.etag[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] ); + } + } + + // Set the correct header, if data is being sent + if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) { + jqXHR.setRequestHeader( "Content-Type", s.contentType ); + } + + // Set the Accepts header for the server, depending on the dataType + jqXHR.setRequestHeader( + "Accept", + s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ? + s.accepts[ s.dataTypes[ 0 ] ] + + ( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) : + s.accepts[ "*" ] + ); + + // Check for headers option + for ( i in s.headers ) { + jqXHR.setRequestHeader( i, s.headers[ i ] ); + } + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && + ( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) { + + // Abort if not done already and return + return jqXHR.abort(); + } + + // Aborting is no longer a cancellation + strAbort = "abort"; + + // Install callbacks on deferreds + completeDeferred.add( s.complete ); + jqXHR.done( s.success ); + jqXHR.fail( s.error ); + + // Get transport + transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR ); + + // If no transport, we auto-abort + if ( !transport ) { + done( -1, "No Transport" ); + } else { + jqXHR.readyState = 1; + + // Send global event + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] ); + } + + // If request was aborted inside ajaxSend, stop there + if ( completed ) { + return jqXHR; + } + + // Timeout + if ( s.async && s.timeout > 0 ) { + timeoutTimer = window.setTimeout( function() { + jqXHR.abort( "timeout" ); + }, s.timeout ); + } + + try { + completed = false; + transport.send( requestHeaders, done ); + } catch ( e ) { + + // Rethrow post-completion exceptions + if ( completed ) { + throw e; + } + + // Propagate others as results + done( -1, e ); + } + } + + // Callback for when everything is done + function done( status, nativeStatusText, responses, headers ) { + var isSuccess, success, error, response, modified, + statusText = nativeStatusText; + + // Ignore repeat invocations + if ( completed ) { + return; + } + + completed = true; + + // Clear timeout if it exists + if ( timeoutTimer ) { + window.clearTimeout( timeoutTimer ); + } + + // Dereference transport for early garbage collection + // (no matter how long the jqXHR object will be used) + transport = undefined; + + // Cache response headers + responseHeadersString = headers || ""; + + // Set readyState + jqXHR.readyState = status > 0 ? 4 : 0; + + // Determine if successful + isSuccess = status >= 200 && status < 300 || status === 304; + + // Get response data + if ( responses ) { + response = ajaxHandleResponses( s, jqXHR, responses ); + } + + // Use a noop converter for missing script but not if jsonp + if ( !isSuccess && + jQuery.inArray( "script", s.dataTypes ) > -1 && + jQuery.inArray( "json", s.dataTypes ) < 0 ) { + s.converters[ "text script" ] = function() {}; + } + + // Convert no matter what (that way responseXXX fields are always set) + response = ajaxConvert( s, response, jqXHR, isSuccess ); + + // If successful, handle type chaining + if ( isSuccess ) { + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + modified = jqXHR.getResponseHeader( "Last-Modified" ); + if ( modified ) { + jQuery.lastModified[ cacheURL ] = modified; + } + modified = jqXHR.getResponseHeader( "etag" ); + if ( modified ) { + jQuery.etag[ cacheURL ] = modified; + } + } + + // if no content + if ( status === 204 || s.type === "HEAD" ) { + statusText = "nocontent"; + + // if not modified + } else if ( status === 304 ) { + statusText = "notmodified"; + + // If we have data, let's convert it + } else { + statusText = response.state; + success = response.data; + error = response.error; + isSuccess = !error; + } + } else { + + // Extract error from statusText and normalize for non-aborts + error = statusText; + if ( status || !statusText ) { + statusText = "error"; + if ( status < 0 ) { + status = 0; + } + } + } + + // Set data for the fake xhr object + jqXHR.status = status; + jqXHR.statusText = ( nativeStatusText || statusText ) + ""; + + // Success/Error + if ( isSuccess ) { + deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] ); + } else { + deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] ); + } + + // Status-dependent callbacks + jqXHR.statusCode( statusCode ); + statusCode = undefined; + + if ( fireGlobals ) { + globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError", + [ jqXHR, s, isSuccess ? success : error ] ); + } + + // Complete + completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] ); + + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] ); + + // Handle the global AJAX counter + if ( !( --jQuery.active ) ) { + jQuery.event.trigger( "ajaxStop" ); + } + } + } + + return jqXHR; + }, + + getJSON: function( url, data, callback ) { + return jQuery.get( url, data, callback, "json" ); + }, + + getScript: function( url, callback ) { + return jQuery.get( url, undefined, callback, "script" ); + } +} ); + +jQuery.each( [ "get", "post" ], function( _i, method ) { + jQuery[ method ] = function( url, data, callback, type ) { + + // Shift arguments if data argument was omitted + if ( isFunction( data ) ) { + type = type || callback; + callback = data; + data = undefined; + } + + // The url can be an options object (which then must have .url) + return jQuery.ajax( jQuery.extend( { + url: url, + type: method, + dataType: type, + data: data, + success: callback + }, jQuery.isPlainObject( url ) && url ) ); + }; +} ); + +jQuery.ajaxPrefilter( function( s ) { + var i; + for ( i in s.headers ) { + if ( i.toLowerCase() === "content-type" ) { + s.contentType = s.headers[ i ] || ""; + } + } +} ); + + +jQuery._evalUrl = function( url, options, doc ) { + return jQuery.ajax( { + url: url, + + // Make this explicit, since user can override this through ajaxSetup (#11264) + type: "GET", + dataType: "script", + cache: true, + async: false, + global: false, + + // Only evaluate the response if it is successful (gh-4126) + // dataFilter is not invoked for failure responses, so using it instead + // of the default converter is kludgy but it works. + converters: { + "text script": function() {} + }, + dataFilter: function( response ) { + jQuery.globalEval( response, options, doc ); + } + } ); +}; + + +jQuery.fn.extend( { + wrapAll: function( html ) { + var wrap; + + if ( this[ 0 ] ) { + if ( isFunction( html ) ) { + html = html.call( this[ 0 ] ); + } + + // The elements to wrap the target around + wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true ); + + if ( this[ 0 ].parentNode ) { + wrap.insertBefore( this[ 0 ] ); + } + + wrap.map( function() { + var elem = this; + + while ( elem.firstElementChild ) { + elem = elem.firstElementChild; + } + + return elem; + } ).append( this ); + } + + return this; + }, + + wrapInner: function( html ) { + if ( isFunction( html ) ) { + return this.each( function( i ) { + jQuery( this ).wrapInner( html.call( this, i ) ); + } ); + } + + return this.each( function() { + var self = jQuery( this ), + contents = self.contents(); + + if ( contents.length ) { + contents.wrapAll( html ); + + } else { + self.append( html ); + } + } ); + }, + + wrap: function( html ) { + var htmlIsFunction = isFunction( html ); + + return this.each( function( i ) { + jQuery( this ).wrapAll( htmlIsFunction ? html.call( this, i ) : html ); + } ); + }, + + unwrap: function( selector ) { + this.parent( selector ).not( "body" ).each( function() { + jQuery( this ).replaceWith( this.childNodes ); + } ); + return this; + } +} ); + + +jQuery.expr.pseudos.hidden = function( elem ) { + return !jQuery.expr.pseudos.visible( elem ); +}; +jQuery.expr.pseudos.visible = function( elem ) { + return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length ); +}; + + + + +jQuery.ajaxSettings.xhr = function() { + try { + return new window.XMLHttpRequest(); + } catch ( e ) {} +}; + +var xhrSuccessStatus = { + + // File protocol always yields status code 0, assume 200 + 0: 200, + + // Support: IE <=9 only + // #1450: sometimes IE returns 1223 when it should be 204 + 1223: 204 + }, + xhrSupported = jQuery.ajaxSettings.xhr(); + +support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported ); +support.ajax = xhrSupported = !!xhrSupported; + +jQuery.ajaxTransport( function( options ) { + var callback, errorCallback; + + // Cross domain only allowed if supported through XMLHttpRequest + if ( support.cors || xhrSupported && !options.crossDomain ) { + return { + send: function( headers, complete ) { + var i, + xhr = options.xhr(); + + xhr.open( + options.type, + options.url, + options.async, + options.username, + options.password + ); + + // Apply custom fields if provided + if ( options.xhrFields ) { + for ( i in options.xhrFields ) { + xhr[ i ] = options.xhrFields[ i ]; + } + } + + // Override mime type if needed + if ( options.mimeType && xhr.overrideMimeType ) { + xhr.overrideMimeType( options.mimeType ); + } + + // X-Requested-With header + // For cross-domain requests, seeing as conditions for a preflight are + // akin to a jigsaw puzzle, we simply never set it to be sure. + // (it can always be set on a per-request basis or even using ajaxSetup) + // For same-domain requests, won't change header if already provided. + if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) { + headers[ "X-Requested-With" ] = "XMLHttpRequest"; + } + + // Set headers + for ( i in headers ) { + xhr.setRequestHeader( i, headers[ i ] ); + } + + // Callback + callback = function( type ) { + return function() { + if ( callback ) { + callback = errorCallback = xhr.onload = + xhr.onerror = xhr.onabort = xhr.ontimeout = + xhr.onreadystatechange = null; + + if ( type === "abort" ) { + xhr.abort(); + } else if ( type === "error" ) { + + // Support: IE <=9 only + // On a manual native abort, IE9 throws + // errors on any property access that is not readyState + if ( typeof xhr.status !== "number" ) { + complete( 0, "error" ); + } else { + complete( + + // File: protocol always yields status 0; see #8605, #14207 + xhr.status, + xhr.statusText + ); + } + } else { + complete( + xhrSuccessStatus[ xhr.status ] || xhr.status, + xhr.statusText, + + // Support: IE <=9 only + // IE9 has no XHR2 but throws on binary (trac-11426) + // For XHR2 non-text, let the caller handle it (gh-2498) + ( xhr.responseType || "text" ) !== "text" || + typeof xhr.responseText !== "string" ? + { binary: xhr.response } : + { text: xhr.responseText }, + xhr.getAllResponseHeaders() + ); + } + } + }; + }; + + // Listen to events + xhr.onload = callback(); + errorCallback = xhr.onerror = xhr.ontimeout = callback( "error" ); + + // Support: IE 9 only + // Use onreadystatechange to replace onabort + // to handle uncaught aborts + if ( xhr.onabort !== undefined ) { + xhr.onabort = errorCallback; + } else { + xhr.onreadystatechange = function() { + + // Check readyState before timeout as it changes + if ( xhr.readyState === 4 ) { + + // Allow onerror to be called first, + // but that will not handle a native abort + // Also, save errorCallback to a variable + // as xhr.onerror cannot be accessed + window.setTimeout( function() { + if ( callback ) { + errorCallback(); + } + } ); + } + }; + } + + // Create the abort callback + callback = callback( "abort" ); + + try { + + // Do send the request (this may raise an exception) + xhr.send( options.hasContent && options.data || null ); + } catch ( e ) { + + // #14683: Only rethrow if this hasn't been notified as an error yet + if ( callback ) { + throw e; + } + } + }, + + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432) +jQuery.ajaxPrefilter( function( s ) { + if ( s.crossDomain ) { + s.contents.script = false; + } +} ); + +// Install script dataType +jQuery.ajaxSetup( { + accepts: { + script: "text/javascript, application/javascript, " + + "application/ecmascript, application/x-ecmascript" + }, + contents: { + script: /\b(?:java|ecma)script\b/ + }, + converters: { + "text script": function( text ) { + jQuery.globalEval( text ); + return text; + } + } +} ); + +// Handle cache's special case and crossDomain +jQuery.ajaxPrefilter( "script", function( s ) { + if ( s.cache === undefined ) { + s.cache = false; + } + if ( s.crossDomain ) { + s.type = "GET"; + } +} ); + +// Bind script tag hack transport +jQuery.ajaxTransport( "script", function( s ) { + + // This transport only deals with cross domain or forced-by-attrs requests + if ( s.crossDomain || s.scriptAttrs ) { + var script, callback; + return { + send: function( _, complete ) { + script = jQuery( " + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Binder

+
+

Questions

+
    +

  • Why sharing code alone may not be sufficient.

    • +

  • How to share a computational environment?

    • +

  • What is Binder?

    • +

  • How to binderize my Python repository?

    • +

  • How to publish my Python repository?

    • +
+
+
+

Objectives

+
    +

  • Learn about reproducible computational environments.

    • +

  • Learn to create and share custom computing environments with Binder.

    • +

  • Learn to get a DOI from Zenodo for a repository.

    • +
+
+
+

Why is it sometimes not enough to share your code?

+

Before we work in groups, +let’s take an example from geospatial +analysis where the first import in the code would be (please note that it is +not necessary to install any of the packages mentioned below):

+
from osgeo import ogr, osr, gdal
+
+
+

Depending on how you install this python package, it may be necessary to have +libgdal and its development headers already installed on your system; with +information on the version you have used, etc.

+
+

Exercise 1

+
+

Binder-1 (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+
+
+
+

Sharing a computing environment with Binder

+

Binder allows you to create +custom computing environments that can be shared and used by many remote users. +It uses repo2docker to +create a container image (docker image) of a +project using information contained in included configuration files.

+

Repo2docker is a standalone package that you can install locally on your laptop +but an online Binder service is freely available. +This is what we will be using in the tutorial.

+

The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder.

+https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png +

Credit: Juliette Taka, Logilab and the OpenDreamKit project (2017)

+
+

Binder exercise/demo

+

In an earlier episode (Data visualization with Matplotlib) we have created this notebook:

+
import pandas as pd
+import matplotlib.pyplot as plt
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+data_2007 = data[data["year"] == 2007]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xscale("log")
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
+
+

We will now first share it via GitHub “statically”, +then using Binder.

+
+

Exercise/demo: Making your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+
+
+
+

How can I get a DOI from Zenodo?

+

Zenodo is a general purpose open-access +repository built and operated by CERN and OpenAIRE that allows researchers to archive and get a +Digital Object Identifier (DOI) to data that they +share.

+
+

Binder-3 (optional)

+

Everything you deposit on Zenodo is meant to be kept (long-term archive). +Therefore we recommend to practice with the Zenodo “sandbox” (practice/test area) +instead: https://sandbox.zenodo.org

+
    +

  1. Link GitHub with Zenodo:

    2. +
+
+
    +

  • Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing).

    • +

  • Log in to Zenodo with your GitHub account. Be aware that you may need to +authorize Zenodo application (Zenodo will redirect you back to GitHub for +Authorization).

    • +

  • Choose the repository webhooks options.

    • +

  • From the drop-down menu next to your email address at the top of the page, select GitHub.

    • +

  • You will be presented with a list of all your Github repositories.

    • +
+
+
    +

  1. Archiving a repo:

    2. +
+
+
    +

  • Select a repository you want to archive on Zenodo.

    • +

  • Toggle the “on” button next to the repository ou need to archive.

    • +

  • Click on the Repo that you want to reserve.

    • +

  • Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release.

    • +
+
+
    +

  1. Trigger Zenodo to Archive your repository

    2. +
+
+
    +

  • Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI.

    • +

  • If this is the first release of your code then you should give it a +version number of v1.0.0. Add description for your release then click the +Publish release button.

    • +

  • Zenodo takes an archive of your GitHub repository each time you create a new Release.

    • +
+
+
    +

  1. To ensure that everything is working:

    2. +
+
+
    +

  • Go to https://zenodo.org/account/settings/github/ (or the corresponding +sandbox at https://sandbox.zenodo.org/account/settings/github/), or the +Upload page (https://zenodo.org/deposit), you will find your repo is +listed.

    • +

  • Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo.

    • +

  • You can edit the archive on Zenodo and/or publish a new version of your software.

    • +

  • It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata +manually, you can also add a .zenodo.json or a CITATION.cff file to your repo and Zenodo will infer the metadata from this file.

    • +

  • Your code is now published on a Github public repository and archived on Zenodo.

    • +

  • Update the README file in your repository with the newly created zenodo badge.

    • +
+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/data-formats.html b/branch/opengraph/data-formats.html new file mode 100644 index 00000000..56f61997 --- /dev/null +++ b/branch/opengraph/data-formats.html @@ -0,0 +1,915 @@ + + + + + + + + + + + + + Data formats with Pandas and Numpy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Data formats with Pandas and Numpy

+
+

Questions

+
    +

  • How do you store your data right now?

    • +

  • Are you doing data cleaning / preprocessing every time you load the data?

    • +
+
+
+

Objectives

+
    +

  • Learn the distinguishing characteristics of different data formats.

    • +

  • Learn how Pandas to read and write data in a variety of formats.

    • +
+
+
+

What is a data format?

+

Whenever you have data (e.g. measurement data, simulation results, analysis results), you’ll need a way to store it. +This applies both when

+
    +

  1. you’re storing the data in memory while you’re working on it;

    2. +

  2. you’re storing it to a disk for later work.

    3. +
+

Let’s consider this randomly generated dataset with various columns:

+
import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
+dataset.info()
+
+
+

This DataFrame already has a data format: it is in the tidy data format! +In tidy data format we have multiple columns of data that are collected in a Pandas DataFrame.

+_images/tidy_data.png +

Let’s consider another example:

+
n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+data_array
+
+
+

Here we have a different data format: we have a two-dimentional array of numbers! +This is different to Pandas DataFrame as data is stored as one contiguous block instead of individual columns. +This also means that the whole array must have one data type.

+
+https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png +
+

Source: Elegant Scipy

+
+
+

Now the question is: can we store these datasets in a file in a way that keeps our data format intact?

+

For this we need a file format that supports our chosen data format.

+

Pandas has support for many file formats for tidy data and Numpy has support for some file formats for array data. +However, there are many other file formats that can be used through other libraries.

+
+
+

What to look for in a file format?

+

When deciding which file format you should use for your program, you should remember the following:

+

There is no file format that is good for every use case.

+

Instead, there are various standard file formats for various use cases:

+
+https://imgs.xkcd.com/comics/standards.png +
+

Source: xkcd #927.

+
+
+

Usually, you’ll want to consider the following things when choosing a file format:

+
    +

  1. Is everybody else / leading authorities in my field using a certain format? +Maybe they have good reasons for using it.

    2. +

  2. Is the file format good for my data format (is it fast/space efficient/easy to use)?

    3. +

  3. Do I need a human-readable format or is it enought to work on it using programming languages?

    4. +

  4. Do I want to archive / share the data or do I just want to store it while I’m working?

    5. +
+
+ +
+

Exercise 1

+
+

Exercise

+
    +

  • Create the example dataframe dataset with:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Use the %timeit-magic to calculate how long it takes to save / load the dataset as a CSV-file.

    • +
+
+ +
+
+

Exercise 2

+
+

Exercise

+
    +

  • Save the dataset dataset using a binary format of your choice.

    • +

  • Use the %timeit-magic to calculate how long it takes to save / load the dataset.

    • +

  • Did you notice any difference in speed?

    • +
+
+ +
+
+

Exercise 3

+
+

Exercise

+
    +

  • Create a numpy array. Store it as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+ +
+
+

Benefits of binary file formats

+

Binary files come with various benefits compared to text files.

+
    +

  1. They can represent floating point numbers with full precision.

    2. +

  2. Storing data in binary format can potentially save lots of space. +This is because you do not need to write numbers as characters. +Additionally some file formats support compression of the data.

    3. +

  3. Data loading from binary files is usually much faster than loading from text files. +This is because memory can be allocated for the data before data is loaded as the type of data in columns is known.

    4. +

  4. You can often store multiple datasets and metadata to the same file.

    5. +

  5. Many binary formats allow for partial loading of the data. +This makes it possible to work with datasets that are larger than your computer’s memory.

    6. +
+

Performance when writing tidy dataset:

+

For the tidy dataset we had, we can test the performance of the different file formats:

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File format

File size [MB]

Write time [ms]

Read time [ms]

CSV

4.571760

0.296015

0.072096

Feather

2.202471

0.013013

0.007742

Parquet

1.820971

0.009052

0.009052

HDF5

4.892181

0.037609

0.033721

NetCDF4

6.894043

0.073829

0.010776

+

The relatively poor performance of HDF5-based formats in this case is due to the data being mostly one dimensional columns full of character strings.

+

Performance when writing data array:

+

For the array-shaped data_array we had, we can test the performance of the different file formats:

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File format

File size [MB]

Write time [ms]

Read time [ms]

CSV

23.841858

0.647893

0.639863

npy

7.629517

0.009885

0.002539

HDF5

7.631348

0.012877

0.002737

NetCDF4

7.637207

0.018905

0.009876

+

For this kind of a data, HDF5-based formats perform much better.

+
+
+

Things to remember

+
    +

  1. There is no file format that is good for every use case.

    2. +

  2. Usually, your research question determines which libraries you want to use to solve it. +Similarly, the data format you have determines file format you want to use.

    3. +

  3. However, if you’re using a previously existing framework or tools or you work in a specific field, you should prioritize using the formats that are used in said framework/tools/field.

    4. +

  4. When you’re starting your project, it’s a good idea to take your initial data, clean it, and store the results in a good binary format that works as a starting point for your future analysis. +If you’ve written the cleaning procedure as a script, you can always reproduce it.

    5. +

  5. Throughout your work, you should use code to turn important data to human-readable format (e.g. plots, averages, pandas.DataFrame.head()), not to keep your full data in a human-readable format.

    6. +

  6. Once you’ve finished, you should store the data in a format that can be easily shared to other people.

    7. +
+
+
+

Other file formats

+
+

Pickle

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: None (pickle-module is included with Python).

    • +

  • Space efficiency: Ok.

    • +

  • Good for sharing/archival: No! See warning below.

    • +
  • +
    Tidy data:
      +

    • Speed: Ok

      • +

    • Ease of use: Ok

      • +
    +
    +
    +
    • +
  • +
    Array data:
      +

    • Speed: Ok

      • +

    • Ease of use: Ok

      • +
    +
    +
    +
    • +

  • Best use cases: Saving Python objects for debugging.

    • +
+
+
+

Warning

+

Loading pickles that have been provided from untrusted sources is +risky as they can contain arbitrary executable code.

+
+

Pickle is Python’s own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:

+
import pickle
+
+with open('data_array.pickle', 'wb') as f:
+    pickle.dump(data_array, f)
+
+with open('data_array.pickle', 'rb') as f:
+    data_array_pickle = pickle.load(f)
+
+
+
+
+

JSON (JavaScript Object Notation)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: None (json-module is included with Python).

    • +

  • Space efficiency: Ok.

    • +

  • Good for sharing/archival: No! See warning below.

    • +
  • +
    Tidy data:
      +

    • Speed: Ok

      • +

    • Ease of use: Ok

      • +
    +
    +
    +
    • +
  • +
    Array data:
      +

    • Speed: Ok

      • +

    • Ease of use: Ok

      • +
    +
    +
    +
    • +

  • Best use cases: Saving Python objects for debugging.

    • +
+
+

JSON is another popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.). +However, when you’re working with big data, you rarely want to keep your data in this format.

+

Similarly to other popular files, Pandas can write and read json files with to_json()- and read_json()-functions:

+
dataset.to_json('dataset.json')
+dataset_json = pd.read_csv('dataset.json')
+
+
+

However, JSON is often used to represent hierarchical data with multiple layers or multiple connections. +For such data you might need to do a lot more processing.

+
+
+

Excel (binary)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: openpyxl

    • +

  • Space efficiency: Bad.

    • +

  • Good for sharing/archival: Maybe.

    • +
  • +
    Tidy data:
      +

    • Speed: Bad

      • +

    • Ease of use: Good

      • +
    +
    +
    +
    • +
  • +
    Array data:
      +

    • Speed: Bad

      • +

    • Ease of use: Ok

      • +
    +
    +
    +
    • +

  • Best use cases: Sharing data in many fields. Quick data analysis.

    • +
+
+

Excel is very popular in social sciences and economics. +However, it is not a good format for data science.

+

See Pandas’ documentation on working with Excel files.

+

Using Excel files with Pandas requires openpyxl-package to be installed.

+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pandas can read and write a variety of data formats.

    • +

  • There are many good, standard formats, and you don’t need to create your own.

    • +

  • There are plenty of other libraries dedicated to various formats.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/data-visualization.html b/branch/opengraph/data-visualization.html new file mode 100644 index 00000000..053f02f3 --- /dev/null +++ b/branch/opengraph/data-visualization.html @@ -0,0 +1,661 @@ + + + + + + + + + + + + + Data visualization with Matplotlib — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Data visualization with Matplotlib

+
+

Questions

+
    +

  • What happens if you can’t automatically produce plots?

    • +

  • When to use Matplotlib for data visualization?

    • +

  • When to prefer other libraries?

    • +
+
+
+

Objectives

+
    +

  • Be able to create simple plots with Matplotlib and tweak them

    • +

  • Know about object-oriented vs pyplot interfaces of Matplotlib

    • +

  • Be able to adapt gallery examples

    • +

  • Know how to look for help

    • +

  • Know that other tools exist

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • No manual post-processing. This will bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    +
      +

    • Matplotlib: +probably the most standard and most widely used

      • +

    • Seaborn: +high-level interface to Matplotlib, statistical functions built in

      • +

    • Altair: +declarative visualization (R users will be more at home), statistics built in

      • +

    • Plotly: +interactive graphs

      • +

    • Bokeh: +also here good for interactivity

      • +

    • plotnine: +implementation of a grammar of graphics in Python, it is based on ggplot2

      • +

    • ggplot: +R users will be more at home

      • +

    • PyNGL: +used in the weather forecast community

      • +

    • K3D: +Jupyter notebook extension for 3D visualization

      • +

    • …

      • +
    +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative +(using grammar of graphics).

    • +
+
+
+

Why are we starting with Matplotlib?

+
    +

  • Matplotlib is perhaps the most “standard” Python plotting library.

    • +

  • Many libraries build on top of Matplotlib.

    • +

  • MATLAB users will feel familiar.

    • +

  • Even if you choose to use another library (see above list), chances are high +that you need to adapt a Matplotlib plot of somebody else.

    • +

  • Libraries that are built on top of Matplotlib may need knowledge of Matplotlib +for custom adjustments.

    • +
+

However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code.

+

Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. Later we will also try other libraries.

+
+
+

Getting started with Matplotlib

+

We can start in a Jupyter notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK.

+

Let us create our first plot using +subplots(), +scatter, and some other methods on the +Axes object:

+
# this line tells Jupyter to display matplotlib figures in the notebook
+%matplotlib inline
+
+import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
+# uncomment the next line if you would like to save the figure to disk
+# fig.savefig("my-first-plot.png")
+
+
+
+Result of our first plot +
+

This is the result of our first plot.

+
+
+

When running a Matplotlib script on a remote server without a +“display” (e.g. compute cluster), you may need to add the +matplotlib.use call:

+
import matplotlib.pyplot as plt
+matplotlib.use("Agg")
+
+# ... rest of the script
+
+
+
+
+

Exercise: Matplotlib

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y*2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +
+
+ + +
+
+
+

Matplotlib has two different interfaces

+

When plotting with Matplotlib, it is useful to know and understand that +there are two approaches even though the reasons of this dual approach is +outside the scope of this lesson.

+
    +

  • The more modern option is an object-oriented interface (the +fig and ax objects +can be configured separately and passed around to functions):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
    +
    +
    • +

  • The more traditional option mimics MATLAB plotting and uses the +pyplot interface (:py:mod:plt <matplotlib.pyplot> carries +the global settings):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+plt.scatter(x=data_x, y=data_y, c="#E69F00")
+
+plt.xlabel("we should label the x axis")
+plt.ylabel("we should label the y axis")
+plt.title("some title")
+
    +
    +
    • +
+

When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, we +recommend to learn and use the object oriented interface.

+
+

Why do we emphasize this?

+

One day you may want to write functions which wrap +around Matplotlib function calls and then you can send Figure and Axes +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions.

+

When using the pyplot interface, settings are modified for the entire +matplotlib.pyplot package. The latter is acceptable for linear scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls.

+
+
+
+
+

Styling and customizing plots

+
    +

  • Do not customize “manually” using a graphical program (not easily repeatable/reproducible).

    • +

  • No manual post-processing. This will bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • Matplotlib and also all the other libraries allow to customize almost every aspect of a plot.

    • +

  • It is useful to study Matplotlib parts of a figure +so that we know what to search for to customize things.

    • +

  • Matplotlib cheatsheets: https://github.com/matplotlib/cheatsheets

    • +

  • You can also select among pre-defined themes/ +style +sheets +with use, for instance:

    +
    plt.style.use('ggplot')
+
    +
    +
    • +
+
+
+

Exercises: Styling and customization

+

Here are 3 exercises where we try to adapt existing scripts to either tweak +how the plot looks (exercises 1 and 2) or to modify the input data (example 3).

+

This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice:

+
    +

  • select an example that is close to what you have in mind

    • +

  • being able to adapt it to your needs

    • +

  • being able to search for help

    • +

  • being able to understand help request answers (not easy)

    • +
+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+
+data_2007 = data[data["year"] == 2007]
+
+data_2007
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+ +
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+ + + +
+
+

Discussion

+

After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on.

+
+
+
+

Keypoints

+
    +

  • Avoid manual post-processing, script everything.

    • +

  • Browse a number of example galleries to help you choose the library +that fits best your work/style.

    • +

  • Figures for presentation slides and figures for manuscripts have +different requirements.

    • +

  • Think about color-vision deficiencies when choosing colors. Use +existing solutions for this problem.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/dependencies.html b/branch/opengraph/dependencies.html new file mode 100644 index 00000000..f34fdd96 --- /dev/null +++ b/branch/opengraph/dependencies.html @@ -0,0 +1,519 @@ + + + + + + + + + + + + + Dependency management — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Dependency management

+
+

Questions

+
    +

  • Do you expect your code to work in one year? Five? What if it +uses numpy or tensorflow or random-github-package ?

    • +

  • How can my collaborators get the same results as me? What about +future me?

    • +

  • How can my collaborators easily install my codes with all the necessary dependencies?

    • +

  • How can I make it easy for my colleagues to reproduce my results?

    • +

  • How can I work on two (or more) projects with different and conflicting dependencies?

    • +
+
+
+

Objectives

+
    +

  • Learn how to record dependencies

    • +

  • Be able to communicate the dependencies as part of a report/thesis/publication

    • +

  • Learn how to use isolated environments for different projects

    • +

  • Simplify the use and reuse of scripts and projects

    • +
+
+
+

How do you track dependencies of your project?

+
    +

  • Dependency: Reliance on a external component. In this case, a +separately installed software package such as numpy.

    • +
+
+
+

Exercises 1

+
+

Dependencies-1 (15 min)

+

Please discuss in breakout rooms and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+
+
+

PyPI (The Python Package Index) and (Ana)conda

+
    +

  • PyPI (The Python Package Index) and Conda are popular packaging/dependency +management tools.

    • +

  • When you run pip install you typically install from PyPI but one can also pip install from a GitHub +repository and similar.

    • +

  • When you run conda install you typically install from Anaconda Cloud but there are many community-driven conda channels +and you can create your own.

    • +
+

Why are there two ecosystems?

+
    +

  • PyPI is traditionally for Python-only packages but it is no problem to also +distribute packages written in other languages as long as they provide a +Python interface.

    • +

  • Conda is more general and while it contains many Python packages and packages +with a Python interface, it is often used to also distribute packages which +do not contain any Python (e.g. C or C++ packages).

    • +

  • Many libraries and tools are distributed in both ecosystems.

    • +
+

In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages.

+
+
+

Creating isolated environments

+

Isolated environments solve a couple of problems:

+
    +

  • You can install specific, also older, versions into them.

    • +

  • You can create one for each project and no problem if the two projects +require different versions.

    • +

  • If you make some mistake and install something you did not want or need, you +can remove the environment and create a new one.

    • +
+
+
+

Exercises 2

+
+

Dependencies-2 (15 min)

+
+
+

Chloe just joined your team and will be working on her Master Thesis. She is +quite familiar with Python, still finishing some Python assignments (due in a +few weeks) and you give her a Python code for analyzing and plotting your +favorite data. The thing is that your Python code has been developed by +another Master Student (from last year) and requires a pretty old version of +Numpy (1.13.1) and Matplotlib (2.2.2) (otherwise the code fails). The code +could probably work with a recent version of Python but has been validated with +Python 3.6 only. Having no idea what the code does, she decides that the best +approach is to create an isolated environment with the same dependencies used +previously. This will give her a baseline for future upgrade and +developments.

+

For this first exercise, we will be using conda for creating an isolated environment.

+
    +

  1. Create a conda environment:

    +
    $ conda create --name python36-env python=3.6 numpy=1.13.1 matplotlib=2.2.2
+
    +
    +
    2. +
+

Conda environments can also be managed (create, update, delete) from the +anaconda-navigator. Check out the corresponding documentation here.

+
    +

  1. Activate the environment:

    +
    $ conda activate python36-env
+
    +
    +
    +

    conda activate versus source activate

    +

    If you do not have a recent version of Anaconda or anaconda has not been +setup properly, you may encounter an error. With older version of anaconda, +you can try:

    +
    $ source activate python36-env
+
    +
    +
    +
    2. +

  2. Open a Python console and check that you have effectively the right version for each package:

    +
    import numpy
+import matplotlib
+
+print('Numpy version: ', numpy.__version__)
+print('Matplotlib version: ', matplotlib.__version__)
+
    +
    +

    Or use the one-liner if you have access to a terminal like bash

    +

    python -c “import numpy; print(numpy.__version__)” +python -c “import matplotlib;print(matplotlib.__version__)”

    +
    3. +

  3. Deactivate the environment:

    +
    $ conda deactivate
+
    +
    +
    4. +

  4. Check Numpy and Matplotlib versions in the default environment to make +sure they are different from python36-env.

    5. +
+

There is no need to specify the conda environment when using deactivate. It +deactivates the current environment.

+
+

Remark

+
    +

  • Sometimes the package version you would need does not seem to be +available. You may have to select another conda channel +for instance conda-forge. Channels can then +be indicated when installing a package:

    +
    $ conda install -c conda-forge matplotlib=2.2.0
+
    +
    +
    • +

  • We will see below that rather than specifying the list of dependencies as +argument of conda create, it is recommended to record dependencies in +a file.

    • +
+
+
+
+
+

Exercises 3

+
+

Dependencies-3 (15 min, optional)

+

This is the same exercise as before but we use virtualenv rather than conda.

+
    +

  1. Create a venv:

    +
    $ python -m venv scicomp
+
    +
    +

    Here scicomp is the name of the virtual environment. It creates a new +folder called scicomp.

    +
    2. +

  2. Activate it. To activate your newly created virtual environment locate the +script called activate and execute it.

    +
      +

    • Linux/Mac-OSX: look at bin folder in the scicomp folder:

      +
      $ source scicomp/bin/activate
+
      +
      +
      • +

    • Windows: most likely you can find it in the Scripts folder.

      • +
    +
    3. +

  3. Install Numpy 1.13.1 and Matplotlib 2.2.2 into the virtual environment:

    +
    $ pip install numpy==1.13.1
+$ pip install matplotlib==2.2.2
+
    +
    +
    4. +

  4. Deactivate it:

    +
    $ deactivate
+
    +
    +
    5. +
+
+
+
+

Recording dependencies

+

There are two standard ways to record dependencies for Python projects.:

+

Using a requirements.txt (used by virtual environment) file which +looks like this:

+
numpy
+matplotlib
+pandas
+scipy
+
+
+

Or using an environments.yml (for conda) file which looks like this:

+
name: my-environment
+
+dependencies:
+  - numpy
+  - matplotlib
+  - pandas
+  - scipy
+
+
+

But all of these dependencies evolve so before publishing our work +it can be very useful for future generations and for the future you +to pin dependencies to versions.

+

Here are the two files again, but this time with versions pinned:

+

requirements.txt with versions:

+
numpy==1.19.2
+matplotlib==3.3.2
+pandas==1.1.2
+scipy==1.5.2
+
+
+

environments.yml with versions:

+
name: my-environment
+
+dependencies:
+  - python=3.6
+  - numpy=1.19.2
+  - matplotlib=3.3.2
+  - pandas=1.1.2
+  - scipy=1.5.2
+
+
+ +
+
+

Dependencies 4

+
+

Dependencies-4 (15 min)

+
    +

  • Create the file environment.yml or requirements.txt

    • +
  • +
    Create an environment based on these dependencies:
      +

    • Conda: $ conda create --name myenvironment --file requirements.txt

      • +

    • Virtual environment: First create and activate, then $ pip install -r requirements.txt

      • +
    +
    +
    +
    • +
  • +
    Freeze the environment:
      +

    • Conda: $ conda list --export > requirements.txt or $ conda env export > environment.yml

      • +

    • Virtual environment: $ pip freeze > requirements.txt

      • +
    +
    +
    +
    • +

  • Have a look at the generated (“frozen”) file.

    • +
+
+

Tip: instead of installing packages with $ pip install somepackage, what I do is +to add somepackage to requirements.txt or environment.yml and install +from the file, then you have a trace of all installed dependencies.

+
+
+

How to communicate the dependencies as part of a report/thesis/publication

+

Each notebook or script or project which depends on libraries should come with +either a requirements.txt or a environment.yml, unless you are creating +and distributing this project as Python package (see next section).

+
    +

  • Attach a requirements.txt or a environment.yml to your thesis.

    • +

  • Even better: put requirements.txt or a environment.yml in your Git repository along your code.

    • +

  • Even better: also binderize your analysis pipeline (more about that in a later session).

    • +
+
+
+

Version pinning for package creators

+

We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in setup.py or pyproject.toml +(PyPI) or meta.yaml (conda).

+

These dependencies will then be used by either other libraries (who in turn +write their own setup.py or pyproject.toml or meta.yaml) or by +people directly (filling out requirements.txt or a environment.yml).

+

Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from setup.py):

+
# ...
+install_requires=[
+   'numpy==1.19.2',
+   'matplotlib==3.3.2'
+   'pandas==1.1.2'
+   'scipy==1.5.2'
+]
+# ...
+
+
+

or you can define a range or keep them undefined like here (example taken from +setup.py):

+
# ...
+install_requires=[
+   'numpy',
+   'matplotlib'
+   'pandas'
+   'scipy'
+]
+# ...
+
+
+

Should we pin the versions here or not?

+
    +

  • Pinning versions here would be good for reproducibility.

    • +

  • However pinning versions may make it difficult for this library to be used in a project alongside other +libraries with conflicting version dependencies.

    • +

  • Therefore as library creator make the version requirements as wide as possible.

    +
      +

    • Set minimum version when you know of a reason: >=2.1

      • +

    • Sometimes set maximum version to next major version (<4) (when +you currently use 3.x.y) when you expect issues with next +major version.

      • +
    +
    • +

  • As the “end consumer” of libraries, define your dependencies as narrowly as possible.

    • +
+
+
+

See also

+

Other tools for dependency management:

+
    +

  • Poetry: dependency management and packaging

    • +

  • Pipenv: dependency management, alternative to Poetry

    • +

  • pyenv: if you need different Python versions for different projects

    • +

  • micropipenv: lightweight tool to “rule them all”

    • +
+

Other resources:

+ +
+

Keypoints

+
    +

  • Install dependencies by first recording them in requirements.txt or +environment.yml and install using these files, then you have a trace.

    • +

  • Use isolated environments and avoid installing packages system-wide.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/exercises.html b/branch/opengraph/exercises.html new file mode 100644 index 00000000..ae85cab1 --- /dev/null +++ b/branch/opengraph/exercises.html @@ -0,0 +1,1807 @@ + + + + + + + + + + + + + List of exercises — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

List of exercises

+
+

Full list

+

This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests.

+
+

Jupyter

+

In jupyter.ipynb:

+
+

Exercises: Jupyter-1

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are starting from the navigator, change to the directory you want to use.

      • +

    • If you are starting from the command line, you should navigate to the directory you want to use first.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+

In jupyter.ipynb:

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+

In jupyter.ipynb:

+ +

In jupyter.ipynb:

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

NumPy

+

In numpy.rst:

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-2

+ +
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+

In numpy.rst:

+ +
+
+

Advanced NumPy

+

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lession before continuing with this advanced lesson.

+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes as input:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

And produces as output the appropriate index in the 1D array. Use the image above as a +guide. Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the .strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its .shape and .strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+

In numpy-advanced.rst:

+ +
+
+

Pandas

+

In pandas.rst:

+
+

Exploring dataframes

+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+

In pandas.rst:

+ +

In pandas.rst:

+
+

Analyze the Titanic passenger list dataset

+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+

In pandas.rst:

+ +

In pandas.rst:

+
+

Analyze the Nobel prize dataset

+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries:

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below).

      • +

    • Then create the pivot table:

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y="year", x="bornCountry",inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+
+
+

Data visualization with Matplotlib

+

In data-visualization.md:

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y*2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+
+data_2007 = data[data["year"] == 2007]
+
+data_2007
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+ +

In data-visualization.md:

+ +
+
+

Data formats with Pandas and Numpy

+

In data-formats.rst:

+
+

Exercise

+
    +

  • Create the example dataframe dataset with:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Use the %timeit-magic to calculate how long it takes to save / load the dataset as a CSV-file.

    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Save the dataset dataset using a binary format of your choice.

    • +

  • Use the %timeit-magic to calculate how long it takes to save / load the dataset.

    • +

  • Did you notice any difference in speed?

    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create a numpy array. Store it as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+

In data-formats.rst:

+ +
+
+

Scripts

+

In scripts.rst:

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and the weather_data file and upload them to your jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Note: If you haven’t downloaded the file directly to your jupyterlab folder, it will be located in your Downloads folder or the folder you selected. In jupyterlab click on the ‘upload file’ button, navigate to the folder containing the file and select it to load it into your jupyterlab folder.

    +
    2. +

  2. Open a terminal in jupyter (File -> New -> Terminal).

    3. +

  3. Convert the jupyter script to a python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+

In scripts.rst:

+
+

Scripts-2 (optional)

+
    +

  1. Create weather_functions.py with the above function and add an additional function for plotting the dataset.

    2. +

  2. Update weather_observations.py to call it.

    3. +
+
+

In scripts.rst:

+ +

In scripts.rst:

+
+

Scripts-3

+
    +

  1. Take the python script we have written in the preceding exercise and use +argparse to specify the input and output files and allow the start and end dates to be set.

    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from Mai 2020 to October 2020). +Also use data for cairo (https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv)

    3. +
+
+

In scripts.rst:

+ +

In scripts.rst:

+
+

Scripts-4

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in jupyterlab. +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+

In scripts.rst:

+ +
+
+

SciPy

+

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+

In scipy.rst:

+ +

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+

In scipy.rst:

+ +
+
+

Library ecosystem

+

In libraries.rst:

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+

In libraries.rst:

+ +

In libraries.rst:

+
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+

In libraries.rst:

+ +
+
+

Parallel programming

+

In parallel.rst:

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+

In parallel.rst:

+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+

In parallel.rst:

+
+

Parallel-2, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+
+

In parallel.rst:

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+
+

Dependency management

+

In dependencies.rst:

+
+

Dependencies-1 (15 min)

+

Please discuss in breakout rooms and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+

In dependencies.rst:

+
+

Dependencies-2 (15 min)

+
+
+

Chloe just joined your team and will be working on her Master Thesis. She is +quite familiar with Python, still finishing some Python assignments (due in a +few weeks) and you give her a Python code for analyzing and plotting your +favorite data. The thing is that your Python code has been developed by +another Master Student (from last year) and requires a pretty old version of +Numpy (1.13.1) and Matplotlib (2.2.2) (otherwise the code fails). The code +could probably work with a recent version of Python but has been validated with +Python 3.6 only. Having no idea what the code does, she decides that the best +approach is to create an isolated environment with the same dependencies used +previously. This will give her a baseline for future upgrade and +developments.

+

For this first exercise, we will be using conda for creating an isolated environment.

+
    +

  1. Create a conda environment:

    +
    $ conda create --name python36-env python=3.6 numpy=1.13.1 matplotlib=2.2.2
+
    +
    +
    2. +
+

Conda environments can also be managed (create, update, delete) from the +anaconda-navigator. Check out the corresponding documentation here.

+
    +

  1. Activate the environment:

    +
    $ conda activate python36-env
+
    +
    +
    +

    conda activate versus source activate

    +

    If you do not have a recent version of Anaconda or anaconda has not been +setup properly, you may encounter an error. With older version of anaconda, +you can try:

    +
    $ source activate python36-env
+
    +
    +
    +
    2. +

  2. Open a Python console and check that you have effectively the right version for each package:

    +
    import numpy
+import matplotlib
+
+print('Numpy version: ', numpy.__version__)
+print('Matplotlib version: ', matplotlib.__version__)
+
    +
    +

    Or use the one-liner if you have access to a terminal like bash

    +

    python -c “import numpy; print(numpy.__version__)” +python -c “import matplotlib;print(matplotlib.__version__)”

    +
    3. +

  3. Deactivate the environment:

    +
    $ conda deactivate
+
    +
    +
    4. +

  4. Check Numpy and Matplotlib versions in the default environment to make +sure they are different from python36-env.

    5. +
+

There is no need to specify the conda environment when using deactivate. It +deactivates the current environment.

+
+

Remark

+
    +

  • Sometimes the package version you would need does not seem to be +available. You may have to select another conda channel +for instance conda-forge. Channels can then +be indicated when installing a package:

    +
    $ conda install -c conda-forge matplotlib=2.2.0
+
    +
    +
    • +

  • We will see below that rather than specifying the list of dependencies as +argument of conda create, it is recommended to record dependencies in +a file.

    • +
+
+
+

In dependencies.rst:

+
+

Dependencies-3 (15 min, optional)

+

This is the same exercise as before but we use virtualenv rather than conda.

+
    +

  1. Create a venv:

    +
    $ python -m venv scicomp
+
    +
    +

    Here scicomp is the name of the virtual environment. It creates a new +folder called scicomp.

    +
    2. +

  2. Activate it. To activate your newly created virtual environment locate the +script called activate and execute it.

    +
      +

    • Linux/Mac-OSX: look at bin folder in the scicomp folder:

      +
      $ source scicomp/bin/activate
+
      +
      +
      • +

    • Windows: most likely you can find it in the Scripts folder.

      • +
    +
    3. +

  3. Install Numpy 1.13.1 and Matplotlib 2.2.2 into the virtual environment:

    +
    $ pip install numpy==1.13.1
+$ pip install matplotlib==2.2.2
+
    +
    +
    4. +

  4. Deactivate it:

    +
    $ deactivate
+
    +
    +
    5. +
+
+

In dependencies.rst:

+
+

Dependencies-4 (15 min)

+
    +

  • Create the file environment.yml or requirements.txt

    • +
  • +
    Create an environment based on these dependencies:
      +

    • Conda: $ conda create --name myenvironment --file requirements.txt

      • +

    • Virtual environment: First create and activate, then $ pip install -r requirements.txt

      • +
    +
    +
    +
    • +
  • +
    Freeze the environment:
      +

    • Conda: $ conda list --export > requirements.txt or $ conda env export > environment.yml

      • +

    • Virtual environment: $ pip freeze > requirements.txt

      • +
    +
    +
    +
    • +

  • Have a look at the generated (“frozen”) file.

    • +
+
+
+
+

Binder

+

In binder.rst:

+
+

Binder-1 (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+

In binder.rst:

+
+

Exercise/demo: Making your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+

In binder.rst:

+
+

Binder-3 (optional)

+

Everything you deposit on Zenodo is meant to be kept (long-term archive). +Therefore we recommend to practice with the Zenodo “sandbox” (practice/test area) +instead: https://sandbox.zenodo.org

+
    +

  1. Link GitHub with Zenodo:

    2. +
+
+
    +

  • Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing).

    • +

  • Log in to Zenodo with your GitHub account. Be aware that you may need to +authorize Zenodo application (Zenodo will redirect you back to GitHub for +Authorization).

    • +

  • Choose the repository webhooks options.

    • +

  • From the drop-down menu next to your email address at the top of the page, select GitHub.

    • +

  • You will be presented with a list of all your Github repositories.

    • +
+
+
    +

  1. Archiving a repo:

    2. +
+
+
    +

  • Select a repository you want to archive on Zenodo.

    • +

  • Toggle the “on” button next to the repository ou need to archive.

    • +

  • Click on the Repo that you want to reserve.

    • +

  • Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release.

    • +
+
+
    +

  1. Trigger Zenodo to Archive your repository

    2. +
+
+
    +

  • Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI.

    • +

  • If this is the first release of your code then you should give it a +version number of v1.0.0. Add description for your release then click the +Publish release button.

    • +

  • Zenodo takes an archive of your GitHub repository each time you create a new Release.

    • +
+
+
    +

  1. To ensure that everything is working:

    2. +
+
+
    +

  • Go to https://zenodo.org/account/settings/github/ (or the corresponding +sandbox at https://sandbox.zenodo.org/account/settings/github/), or the +Upload page (https://zenodo.org/deposit), you will find your repo is +listed.

    • +

  • Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo.

    • +

  • You can edit the archive on Zenodo and/or publish a new version of your software.

    • +

  • It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata +manually, you can also add a .zenodo.json or a CITATION.cff file to your repo and Zenodo will infer the metadata from this file.

    • +

  • Your code is now published on a Github public repository and archived on Zenodo.

    • +

  • Update the README file in your repository with the newly created zenodo badge.

    • +
+
+
+

In binder.rst:

+
+

Binder-4 (10 min)

+

We will be using an existing Zenodo DOI 10.5281/zenodo.3886864 to start Binder:

+
+
    +

  • Go to https://mybinder.org and fill information using Zenodo DOI (as shown on the animation below):

    • +
+https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif +
    +

  • You can also get a Binder badge and update the README file in the +repository. It is good practice to add both the Zenodo badge and the +corresponding Binder badge.

    • +
+
+
+
+
+

Packaging

+

In packaging.rst:

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/genindex.html b/branch/opengraph/genindex.html new file mode 100644 index 00000000..671b4128 --- /dev/null +++ b/branch/opengraph/genindex.html @@ -0,0 +1,139 @@ + + + + + + Index — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ + +

Index

+ +
+ +
+ + +
+
+
+ +
+ +
+

© Copyright 2020, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/guide.html b/branch/opengraph/guide.html new file mode 100644 index 00000000..6076144c --- /dev/null +++ b/branch/opengraph/guide.html @@ -0,0 +1,253 @@ + + + + + + + + + + + + + Instructor’s guide — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Instructor’s guide

+
+

Learner personas

+

A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

+

A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

+

B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

+

Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren’t familiar.

+

Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter

+
+
+

About each section

+

In general, “Python for Scientific Computing could be a multi-year +course. We can’t even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path.

+
    +

  • Python intro: We can’t really replace a Python tutorial, but +here we try to outline some of the main points. We don’t go over +this in the course.

    • +

  • Jupyter: Jupyter is somewhat useful, but the main reason we go +over it is that it provides a convenient user interface for the +other programming lessons (it’s easier to spend a bit of time with +Jupyter than expect people to be able to use some +editor/IDE/shell/etc). So, we do start from the beginning, so that +people can do the other lessons, but also try to teach some advanced +tips and tricks.

    • +

  • Numpy: The basic of much of the rest of scipy, so we need to +cover it. We try to get the main principles out, but if someone +already knows it this can be a bit boring. We try to make sure +everyone comes out with an appreciation for vectorization and +broadcasting.

    • +

  • Pandas: A lot of similar goals to the Numpy section, especially +the concepts behind Dataframes that one needs to know in order to +read other documentation.

    • +

  • Visualization: Matplotlib is getting a bit old, but is still the +backbone of other plotting packages. We try to get forth the ideas +of the matplotlib API that can be seen in other packages and the +importance of scripted plots.

    • +

  • Data formats: Input/output/storage is a common task, and can +easily either be a bottleneck or a huge mess. This lessons tries to +show some best practices with data formats and, as usual, get the +idea to not “do it yourself”. Pandas is used as a common framework, +but we should point out there are plenty of other options.

    • +

  • Scripts: The most important lesson here is to break out of +Jupyter/run buttons of editors. If you can’t make actual programs +with an actual interface, you can’t scale up.

    +
      +

    • This is the first lesson to introduce the command line. We +recommend being as simple as possible: at least demonstrate the +JupyterLab terminal and discuss the bigger picture behind what it +means and why.

      • +

    • This is also the first lesson to use non-Jupyter code editor. We +recommend again being simple: use the JupyterLab code editor to +start off, and carefully explain what is going on.

      • +
    +
    • +

  • Scipy: We don’t cover much here (this is super short), but the +point is scipy exists and the concept of wrapping existing C/fortran +libraries and so on.

    • +

  • Library ecosystem: This was an overview of the types of packages +available in the “scipy ecosystem”, which is a large and ill-defined +thing. But there is another point: choosing what to use. Do you +trust a half-done thing published on someone’s personal webpage? If +it’s on Github? How do you make your code more reusable? When +coming from academic courses, you get a “build it yourself” idea, +which isn’t sustainable in research.

    • +

  • Parallel programming:

    • +

  • Dependencies: The main point here is environments, another thing +you often don’t learn in courses.

    +
      +

    • There is a lot of material here. Consider what you will demo, +what will be done as exercises, and what is advanced/optional. +However, it is the fourth-day lesson that is most interactive, so +it is OK if it take a while to go through everything.

      • +

    • If someone else installs Anaconda for a user (e.g. admin-managed +laptop), the conda environment creations (with --name, +possibly with --prefix too?) may not work. Be prepared for +this and mention it. You don’t need to solve the problem but +acknowledge that the lesson becomes a demo. The virtualenv part +should hopefully work for them.

      • +
    +
    • +

  • Binder: Binder exists and can help make code +reproducible/reusable by others.

    • +

  • Packaging: How to make your code reusable by others. By the +time we get here, people are tired and the topics get involved. We +more explicitly say “you might want to watch and take this as a +demo”.

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/index.html b/branch/opengraph/index.html new file mode 100644 index 00000000..62f98991 --- /dev/null +++ b/branch/opengraph/index.html @@ -0,0 +1,335 @@ + + + + + + + + + + + + + Python for Scientific Computing — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python for Scientific Computing

+
+

Attending the course 22-25.november.2022?

+

See the course page here. +Whether you are or aren’t, the course material is below.

+
+

Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing the main Python package for numerical +computing, NumPy, and discusses then SciPy toolbox for various +scientific computing tasks as well as visualization with the +Matplotlib package. In addition, it talks about how python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python.

+

This course (like any course) can’t teach you Python… it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to.

+
+

Prerequisites

+ +

These are not prerequisites:

+
    +

  • Any external libraries, e.g. numpy

    • +

  • Knowing how to make scripts or use Jupyter

    • +
+
+
+

Videos

+

Videos from the 2021 instance of this course can be found in +this YouTube playlist.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

(prereq)

Introduction to Python

30 min

Jupyter

60 min

NumPy or Advanced NumPy

60 min

Pandas

60 min

Data visualization with Matplotlib

30 min

Data formats with Pandas and Numpy

60 min

Scripts

15 min

SciPy

30 min

Library ecosystem

45 min

Parallel programming

30 min

Dependency management

30 min

Binder

60 min

Packaging

+
+
+
+

Reference

+ +
+
+

Who is the course for?

+

The course is targeted towards these learner personas:

+
    +

  • A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able +to do their research more efficiently and make sure that they are +using the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

    • +

  • A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

    • +

  • B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

    • +
+
+
+

Motivation

+
+

Why Python

+

Python has become popular, largely due to good reasons. It’s very easy +to get started, there’s lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities.

+
+
+

Why not Python for Scientific Computing

+

While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools.

+
    +

  • Implementing performance-critical kernels. Python is a very +slow language, which often doesn’t matter if you can offload the +heavy lifting to fast compiled code, e.g. by using Numpy array +operations. But if what you’re trying to do isn’t vectorizable +then you’re out of luck. An alternative to Python, albeit much less +mature and with a smaller ecosystem, but which provides very fast +generated code, is Julia.

    • +

  • Creating libraries that can be called from other languages. In this +case you’ll often want to create a library with a C interface, which +can then be called from most languages. Suitable languages for this +sort of task, depending on what you are doing, could be Rust, C, +C++, or Fortran.

    • +

  • You really like static typing, or functional programming +approaches. Haskell might be what you’re looking for.

    • +
+
+
+

Python 2 vs Python 3

+

Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard.

+

At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2.

+
+
+
+

Credits

+

This course was originally designed by Janne Blomqvist.

+

In 2020 it was completely redesigned by a team of the following:

+
    +

  • Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, …

    • +

  • Editor:

    • +

  • Testers and advisors: Enrico Glerean

    • +
+

We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

+
+
+

See also

+
    +

  • High Performance Data Analytics in Python +<https://enccs.github.io/HPDA-Python/> is a logical follow-up to +this lesson that goes more in-depth to tools of high-performance +and large-scale Python.

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/installation.html b/branch/opengraph/installation.html new file mode 100644 index 00000000..7c688054 --- /dev/null +++ b/branch/opengraph/installation.html @@ -0,0 +1,350 @@ + + + + + + + + + + + + + Software installation — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Software installation

+

This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or some other way access to it. For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line for some lessons).

+

If you need installation help, show this page to someone around you +and they can probably do all you need

+
+

Generic list of tools required

+

Note: The actual installation instructions are below. This is a +generic description which will help those who already understand all +of the tools.

+
    +

  • Python 3 (Anaconda is recommended, it will include everything)

    +
      +

    • With some extra packages installed. They are all included in +Aanconda, and are listed in the environment.yml file you can +find under miniconda below.

      • +
    +
    • +

  • Text editor (several lessons, can also be done through Jupyterlab)

    • +

  • Command-line shell (several lessons, can also be done through Jupyterlab)

    • +

  • git (not needed, this lesson is usually done as a demo)

    • +
+
+

Generic instructions with miniconda and an environment file (advanced)

+

This is the advanced, minimal method of installing the Python +packages. For most people, we recommend Anaconda (below). You +will actually learn about miniconda during the workshop. This +doesn’t provide the graphical Anaconda navigator, so you’ll need to +activate the miniconda environment using the command line.

+

You can read how to install miniconda from the CodeRefinery +installation instructions.

+

Then this environment file +contains all packages needed, and can be installed with:

+
$ conda env create -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml
+
+
+

Each time you start a new shell, you need to activate miniconda (if +you don’t do run conda init), and then you need to activate the +proper environment with conda activate python-for-scicomp.

+

We might have missed some packages, though, which can be later +installed with conda install.

+
+
+
+

Python

+

We expect you to have a working Python installation with some common +libraries. We recommend that you install the Anaconda python +distribution. The +Anaconda Navigator +provides a convenient way to access the software.

+
+

Other options

+

We recommend Anaconda, Anaconda Navigator, and JupyterLab in these +instructions because it is simple and can be used by everyone. As +you advance in your career, we +recommend that you explore other options as well, but +that can come later.

+

Any other Python distribution which you can install libraries into +would work, but because there are so many different ways to do this, +we don’t support them. You would need the extra libraries mentioned +in the Miniconda instructions above.

+
+
+

JupyterLab

+

We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). If you install the full +Anaconda distribution, this will be available and can be started +either through Anaconda Navigator or command line.

+
+
+

Verification of Python and JupyterLab

+
+

Watch the video

+

See this verification in video form - if you can do this, you are +ready to go for day one. Your exact steps may be a bit different.

+
+

You should be able to start JupyterLab. You can do this from the +Anaconda Navigator (recommended if you have it):

+
+_images/anaconda-navigator-jupyterlab.png +
+

Starting JupyterLab from the Anaconda Navigator.

+
+
+

… or you can start JupyterLab from the command line:

+
$ jupyter-lab
+(... Jupyter starts in a web browser)
+
+
+

Verify that you can start a Jupyter notebook. We will learn how to +do this in day 1, but you can try running print("Hello, world!") +if you want.

+
+_images/jupyterlab-notebook.png +
+

Starting a Jupyter Notebook from JupyterLab.

+
+
+
+
+
+

Text editor

+

For one portion of the course, you will need a text editor. If you +don’t know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.

+
+

Other editors

+

Because we need to be simple in our teaching, we only teach the +most basic editors. We encourage you to try out more advanced ones +yourself.

+

For other editors, see the CodeRefinery instructions. You don’t +exactly need a terminal editor - the graphical ones, such as VSCode or +whatever you use now, will work as well.

+
+
+
+

Command line

+

You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed. If you want to +test in advance:

+
    +

  • You can start it from JupyterLab (recommended):

    +
    +_images/jupyterlab-terminal.png +
    +

    From the JupyterLab launcher, select “Terminal”.

    +
    +
    +
    • +
+
+

Other ways to access the command line

+
    +

  • From the Anaconda Navigator:

    +
    +_images/anaconda-prompt.png +
    +

    From the Anaconda Navigator, you can select “environments” on the +left, then click on one, then the arrow, then “Open terminal”.

    +
    +
    +
    • +

  • From your operating system’s terminal applications, if you activate +Anaconda.

    • +
+
+
+

Verification of the command line

+

To verify command line usage, type the following commands (without the +$), and you should see the corresponding output that lists the +Python version:

+
$ python -V
+Python 3.8.3
+
+## Or python3...
+$ python3 -V
+Python 3.8.3
+
+
+

Any version of Python 3 through a recent Anaconda should work for the +course.

+
+
+
+

Zoom

+

If this is an online workshop, it might use Zoom. You can see +CodeRefinery instructions for it.

+
+
+

Need help?

+

If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up!

+
+
+

See also

+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/jupyter.html b/branch/opengraph/jupyter.html new file mode 100644 index 00000000..343d4585 --- /dev/null +++ b/branch/opengraph/jupyter.html @@ -0,0 +1,417 @@ + + + + + + + + + + + + + Jupyter — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Jupyter

+
+

Questions

+
    +

  • What is the purpose of a “Computational narrative”?

    • +

  • What role does Jupyter play in development?

    • +

  • When is Jupyter not a good tool?

    • +
+
+
+

Objectives

+

This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.

+
    +

  • Be able to use Jupyter to run examples for the rest of the course.

    • +

  • Be able to run Jupyter in a directory do your own work.

    • +

  • You won’t be a Jupyter expert after this, but should be able to do the rest of the course.

    • +
+
+
+

What is Jupyter?

+

Jupyter is a web-based interactive computing system. It is most well known for having the notebook file format and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a computational narrative.

+

Jupyter is good for data exploration and interactive work, and making

+

We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.

+
+
+

Getting started with Jupyter

+
    +

  • Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run jupyter-lab. You can also start in from Anaconda Navigator.

    • +
+

For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need.

+

Here, we see a tour of the JupyterLab interface:

+

Main UI tour

+
+
+

Exercises 1

+
+

Exercises: Jupyter-1

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are starting from the navigator, change to the directory you want to use.

      • +

    • If you are starting from the command line, you should navigate to the directory you want to use first.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+
+
+

Running code in Jupyter

+

A notebook is divided into cells. Each cell has some input, and when it is executed an output appears right below it.

+

There are different types of cells: primarily code cells and markdown cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving style to text - you can check out this reference. For example the previous sentence is:

+
Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/).
+
+
+

notebook UI

+

When using keyboard shortcuts, you can switch between edit mode and command mode with Enter and Esc.

+

You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:

+
    +

  • Ctrl-Enter: Run cell

    • +

  • Shift-Enter: Run cell and select cell below

    • +

  • Alt-Enter: Run cell and insert new cell below

    • +

  • a / b: insert new cell above/below

    • +

  • m / y: markdown cell / code cell

    • +

  • x: cut cell

    • +

  • c: copy cell

    • +

  • v: paste cell

    • +

  • d, d: delete cell

    • +
+

Now, let’s look at some code samples:

+
+
+
for i in range(3):
+    print(i)
+
+
+
+
+
0
+1
+2
+
+
+
+
+
+
+
print(sum(range(5)))
+
+
+
+
+
10
+
+
+
+
+

By convention, if the last thing in a cell is an object, that object gets printed:

+
+
+
sum(range(5))
+sum(range(10))
+
+
+
+
+
45
+
+
+
+
+

In addition to raw cells, there are magics, which exist outside of Python. They are a property of the runtime itself (in Python’s case, they come from IPython. For example, the following cell magic %%bash turns the cell into a shell script (may not work on all operating systems):

+
+
+
%%bash
+for x in $(seq 3) ; do
+    echo $x
+done
+
+
+
+
+
1
+2
+3
+
+
+
+
+
    +

  • A cell magic starts with %%, goes on the first line of a cell, and applies to the whole cell

    • +

  • A line magic starts with %, goes on any line, and applies to that line.

    • +
+
+
+

Exercises 2

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+ +
+
+

Why Jupyter?

+
    +

  • Being able to edit, check, re-edit quickly is great for prototyping and testing new ideas

    +
      +

    • Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.

      • +
    +
    • +

  • You can make a complete story - in one place. No more having code, figures, and description in different places.

    +
      +

    • Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.

      • +
    +
    • +

  • Notebook as an interactive publication itself - for example the discovery of gravitational waves data is released as a notebook.

    • +

  • Jupyter Notebooks display on Github - low-barrier way to share your analysis.

    • +

  • Teaching - great for getting difficult software distribution out of the way.

    • +
+
+
+

Why not Jupyter?

+

Jupyter is great for many things, but there are some problems if not used well:

+
    +

  • They don’t promote modularity, and once you get started in a +notebook it can be hard to migrate to modules.

    • +

  • They are difficult to test. There are things to run notebooks as +unit tests like nbval, but it’s not +perfect.

    • +

  • Notebooks can be version controlled +(nbdime helps with that), but +there are still limitations.

    • +

  • You can change code after you run it and run code out of order. +This can make debugging hard and results irreproducible if you +aren’t careful.

    • +

  • Notebooks aren’t named by default and tend to acquire a bunch of +unrelated stuff. Be careful with organization!

    • +

  • Once lots of code is in notebooks, it can be hard to change to +proper programs that can be scripted.

    • +
+

You can read more about these downsides https://scicomp.aalto.fi/scicomp/jupyter-pitfalls/.

+

But these downsides aren’t specific to Jupyter! They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.

+
+
+

Exercises 3

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Jupyter is powerful and can be used for interactive work

    • +

  • … but not the end solution when you need to scale up.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/libraries.html b/branch/opengraph/libraries.html new file mode 100644 index 00000000..1fa5efb2 --- /dev/null +++ b/branch/opengraph/libraries.html @@ -0,0 +1,486 @@ + + + + + + + + + + + + + Library ecosystem — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Library ecosystem

+
+

Questions

+
    +

  • What happens when you need some method Beyond what we discuss in this course, what is available?

    • +

  • How do you decide what to build on for your work?

    • +
+
+
+

Objectives

+
    +

  • Know of some other available packages, but don’t necessarily know +how to use them.

    • +

  • Be able to evaluate what you should reuse and what you should +develop yourself.

    • +
+
+

You can’t do everything yourself. In fact, once we heard a quote such +as this:

+
+

When you are a student, you are expected to do everything +yourself, and that is how you are evaluated. When you become a +researcher, you have to be able to reuse what others have done. +We don’t have much practice in doing this. +– A student

+
+

In this lesson, we’ll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types:

+
    +

  • Well-maintained libraries that are used by many others.

    • +

  • A wide variety of public code that might work but isn’t necessarily +well-maintained (for example, code from articles).

    • +
+

We’ll start with the first then go to the second.

+
+

Glossary

+
+
Library

A collection of code used by a program.

+
+
Package

A library that has been made easily installable and reusable. +Often published on public repositories such as the Python Package +Index

+
+
Dependency

A requirement of another program, not included in that program.

+
+
+
+
+

The Python/SciPy ecosystem

+

This section is nothing more than a tour of what exists in Python. +You aren’t expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work.

+

The “core” packages could be considered. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy):

+
    +

  • Python

    • +

  • Numpy - arrays, everything builds on this

    • +

  • Scipy - scientific functions (not necessarily a lot builds on this)

    • +

  • matplotlib - plotting, many other plotting tools build on this

    • +

  • pandas - data structures

    • +

  • IPython / Jupyter: interactive work

    • +
+
+

Core numerics libraries

+
    +

  • numpy - arrays and array math.

    • +

  • scipy - software +for math, science, and engineering.

    • +
+
+
+

Plotting

+
    +

  • matplotlib - base plotting package, +somewhat low level but almost everything builds on it.

    • +

  • seaborn - higher level plotting +interface; statistical graphics.

    • +

  • mayavi - 3D plotting

    • +

  • PIL - image manipulation. The +original PIL is no longer maintained, the new “Pillow” is a drop-in +replacement.

    • +
+
+
+

Data analysis and other important core packages

+ +
+
+

Interactive computing and human interface

+
    +

  • Interactive computing

    +
      +

    • IPython - nicer interactive interpreter

      • +

    • Jupyter (notebook, lab, hub, …) - +web-based interface to IPython and other languages

      • +
    +
    • +

  • Testing

    +
      +

    • pytest - automated testing interface

      • +
    +
    • +

  • Documentation

    +
      +

    • Sphinx - documentation generator +(also used for this lesson…)

      • +
    +
    • +

  • Development environments

    +
      +

    • Spyder - interactive Python +development environment.

      • +
    +
    • +

  • Binder - load any git repository in +Jupyter automatically, good for reproducible research

    • +
+
+
+

Speeding up code and parallelism

+
    +

  • PyMPI - Message +Passing Interface (MPI) in Python for parallelizing jobs.

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • numba - just in time compiling of +functions for speed-up

    • +

  • PyPy - Python written in Python so that +it can internally optimize more.

    • +

  • Dask - distributed array data structure for +distributed computation

    • +

  • Joblib - easy embarrassingly +parallel computing

    • +

  • IPyParallel - easy +parallel task engine

    • +

  • numexpr - Fast evaluation of +array expressions by automatically compiling the arithmetic.

    • +
+
+
+

Machine learning

+

If you need some machine learning, you probably already know what you +need and this list is short and irrelevant.

+ +
+
+
+

Connecting Python to other languages

+

As we discussed with Scipy, very many of the above packages aren’t +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things:

+
    +

  • Extending Python by writing your own modules in C.

    +
      +

    • It’s actually common to first have (or write) an analysis package +in C or C++, then make the Python interface. Then it can be +supported by other languages, too.

      • +

    • Or one starts an analysis package in Python, and slowly moves bits +of it to C over time as there is need.

      • +
    +
    • +

  • Embedding Python, where you have another primary application +that uses Python under the hood as an internal scripting language.

    • +
+

These features aren’t exactly unique to Python, but Python does +support them very well. Read more: Extending and embedding Python.

+
+

Tools for interfacing with other languages

+

These days, one rarely directly extends the Python interpreter, but uses

+
    +

  • cffi and ctypes - interface to C +and compatible libraries

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • f2py - interface to Fortran +code

    • +

  • swig - connect to a variety of programming languages.

    • +

  • Boost.python - Another Python/C++ interface

    • +

  • TODO: Julia modules for Python?

    • +
+
+
+
+

Evaluating Python packages for reuse

+

Above, we talked about well-maintained mainstream packages. Do you +trust random code you find online (for example included in a paper)?

+

Especially consider scientific results, which have to be correct. +Still, you also can’t build everything yourself, so you have to +carefully evaluate the situation.

+

Below are some things to consider:

+
    +

  • Are there releases? Have they been going on for a while?

    • +

  • Are releases installable without copy-paste?

    • +

  • Are dependencies handled well?

    • +

  • Does the code randomly change, so that it no longer works with your +code. Is this relevant?

    • +

  • Is there good documentation, that not just tells how to use it but +how it works?

    • +

  • Is there automated testing? What’s your evaluation of the risk of +undetectable scientific errors?

    • +

  • Is there a community, or is it one person? Is it backed by some +organization? Does it have a permanent home?

    • +

  • Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) +where a community could form?

    • +

  • Do others post issues and make contributions? Are these issues +dealt with in a timely manner? Can you search past bug reports?

    • +

  • Is the software citeable?

    • +
+
+
+

Is your work reuseable?

+

Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a CodeRefinery workshop will make +sure you have the tools to produce high-quality, reusable code.

+
+
+

What’s next?

+
    +

  • The CodeRefinery workshop mentioned +above will prepare you for others to reuse your code and for you to +contribute to other code.

    • +

  • The upcoming Dependency management lesson will teach you how to +record and manage dependencies so that anyone can seamlessly reuse +your code.

    • +
+
+
+

Exercises

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+ +
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • Almost everything you need can already be found, except your +incremental work.

    • +

  • When do you build on that other work, and when do you create +things yourself?

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/numpy-advanced.html b/branch/opengraph/numpy-advanced.html new file mode 100644 index 00000000..a08c7100 --- /dev/null +++ b/branch/opengraph/numpy-advanced.html @@ -0,0 +1,556 @@ + + + + + + + + + + + + + Advanced NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Advanced NumPy

+
+

Questions

+
    +

  • How can NumPy be so fast?

    • +

  • Why are some things fast and some things slow?

    • +

  • How can I control whether NumPy makes a copy or operates in-place?

    • +
+
+
+

Objectives

+
    +

  • Understand why NumPy has so many specialized functions for specific operations

    • +

  • Understand the underlying machinery of the Numpy ndarray object

    • +

  • Understand when and why NumPy makes a copy of the data rather than a view

    • +
+

This is intended as a follow-up to the basic NumPy lesson. The indended +audience for this advanced lesson is those who have used NumPy before and +now want to learn how to get the most out of this amazing package.

+
+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +Guide to NumPy by +Travis E. Oliphant, its initial creator.

+
+

NumPy can be really fast

+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast.

+

How fast can NumPy be? Let’s race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:

+
#include <stdlib.h>
+#include <stdio.h>
+#define N_ELEMENTS 100000000
+int main(int argc, char** argv) {
+    double* a = (double*) malloc(sizeof(double) * N_ELEMENTS);
+    int i;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        a[i] = (double) rand() / RAND_MAX;
+    }
+    double sum = 0;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        sum += a[i];
+    }
+    printf("%f", sum);
+    return 0;
+}
+
+
+
+
+

Exercise 1

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lession before continuing with this advanced lesson.

+
+ +
+
+

The library behind the curtain: BLAS

+

NumPy is fast because it outsources most of its heavy lifting to +Basic Linear Algebra Subprograms (BLAS). +BLAS for Fortran was published in 1979 +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as element-wise sum, matrix +multiplication, computing the vector length, etc.

+

The API of that software library was later standardized, and today there are +many modern implementations available. These libraries represent over 40 years +of optimizing efforts and make use of +specialized CPU instructions for manipulating arrays. +In other words, they are fast.

+

One of the functions inside the BLAS library is a +function +to compute the “norm” of a vector, which is the same as computing its length, using the +Pythagorean theorem: +\(\sqrt(a[0]^2 + a[1]^2 + \ldots)\).

+

Let’s race the BLAS function versus a naive “manual” version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:

+
import numpy as np
+rng = np.random.default_rng(seed=0)
+a = rng.random(100_000_000)
+
+
+

We now implement the Pythagorean theorem using basic NumPy functionality and +use %%timeit to record how long it takes to execute:

+
%%timeit
+l = np.sqrt(np.sum(a ** 2))
+print(l)
+
+
+

And here is the version using the specialized BLAS function:

+
%%timeit
+l = np.linalg.norm(a)
+print(l)
+
+
+
+
+

NumPy tries to avoid copying data

+

Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy’s +numpy.ndarray datastructure works behind the scenes.

+
+

The ndarray exposed

+

The first thing you need to know about numpy.ndarray is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector.

+_images/01_memory_layout.svg

NumPy is faking the second dimension behind the scenes! When we request the +element at say, [2, 3], NumPy converts this to the correct index in the +long 1D array [11].

+
+
    +

  • Converting [2, 3] → [11] is called “raveling”

    • +

  • The reverse, converting [11] → [2, 3] is called “unraveling”

    • +
+
+

The implications of this are many, so take let’s take some time to understand +it properly by writing our own ravel() function.

+
+
+
+

Exercise 2

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes as input:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

And produces as output the appropriate index in the 1D array. Use the image above as a +guide. Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+ +
+
+

Strides

+

As seen in the exercise, to get to the next row, we have to skip over +n_cols indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of “strides”:

+
np.zeros((4, 8)).strides           # (64, 8)
+np.zeros((4, 5, 6, 7, 8)).strides  # (13440, 2688, 448, 64, 8)
+
+
+

The .strides attribute contains for each dimension, the number of bytes (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes.

+
+

An example: matrix transpose

+

Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let’s see how long NumPy’s +transpose function takes, by transposing a huge (10 000 ✕ 20 000) matrix:

+
import numpy as np
+a = rng.rand(10_000, 20_000)
+print(f'Matrix `a` takes up {a.nbytes / 10**6} MB')
+
+
+

Let’s time the numpy.transpose() function:

+
%%timeit
+b = a.transpose()
+
+
+

It takes mere nanoseconds to transpose 1600 MB of data! NumPy avoided copying +any data by only modifying the .strides of the existing array in-place:

+
print(a.strides)  # (160000, 8)
+print(b.strides)  # (8, 160000)
+
+
+
+
+

Another example: reshaping

+

Modifying the shape of an array through numpy.reshape() is also +accomplished without any copying of data by modifying the .strides:

+
a = rng.rand(20_000, 10_000)
+print(f'{a.strides=}')  # (80000, 8)
+b = a.reshape(40_000, 5_000)
+print(f'{b.strides=}')  # (40000, 8)
+c = a.reshape(20_000, 5_000, 2)
+print(f'{c.strides=}')  # (80000, 16, 8)
+
+
+
+
+
+

Exercises 3

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the .strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its .shape and .strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+ +
+
+

A fast thing + a fast thing = a fast thing?

+

If numpy.transpose() is fast, and numpy.reshape() is fast, then +doing them both must be fast too, right?:

+
# Create a large array
+a = np.random.rand(10_000, 20_000)
+
+
+

Measuring the time it takes to first transpose and then reshape:

+
%%timeit -n 1 -r 1
+a.T.reshape(40_000, 5_000)
+
+
+

In this case, the data actually had to be copied and it’s super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the .strides:

+
a = np.array([[1, 2, 3], [4, 5, 6]])
+
+print('Original array:')
+print(a)
+
+print('\nTransposed:')
+print(a.T)
+
+print('\nTransposed and then reshaped:')
+print(a.T.reshape(2, 3))
+
+
+
+
+

Copy versus view

+

Whenever NumPy constructs a new array by modifying the .strides instead of +copying data, we way it created a “view”. This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +numpy.ndarray object will have a reference to the original array in +its .base attribute:

+
a = np.zeros((5, 5))
+print(a.base)  # None
+b = a[:2, :2]
+print(b.base.shape)  # (5, 5)
+
+
+
+

Warning

+

When you create a large array and select only a portion of it, the large +array will stay in memory if a view was created!

+
+

The new array b object has a pointer to the same memory buffer as the array +it has been derived from:

+
print(a.__array_interface__['data'])
+print(b.__array_interface__['data'])
+
+
+

Views are created by virtue of modifying the value of the .shape attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:

+
b = a[1:3, 1:3]   # This view does not start at the beginning
+offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0]
+print('Offset:' offset, 'bytes')  # Offset: 48 bytes
+
+
+_images/02_views.svg

Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:

+
b[0, 0] = 1.
+print(a)  # Original matrix was modified
+
+
+

Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:

+
c = a[[0, 2]]  # Select rows 0 and 2
+print(c.base)  # None. So not a view.
+
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • The best way to make your code more efficient is to learn more about the +NumPy API and use specialized functions whenever possible.

    • +

  • NumPy will avoid copying data whenever it can. Whether it can depends on +what kind of layout the data is currently in.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/numpy.html b/branch/opengraph/numpy.html new file mode 100644 index 00000000..3c5b586c --- /dev/null +++ b/branch/opengraph/numpy.html @@ -0,0 +1,637 @@ + + + + + + + + + + + + + NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

NumPy

+
+

Questions

+
    +

  • Why using NumPy instead of pure python?

    • +

  • How to use basic NumPy?

    • +

  • What is vectorization?

    • +
+
+
+

Objectives

+
    +

  • Understand the Numpy array object

    • +

  • Be able to use basic NumPy functionality

    • +

  • Understand enough of NumPy to seach for answers to the rest of your questions ;)

    • +
+

We expect most people to be able to do all the basic exercises +here. It is probably quite easy for many people; we have advanced +exercises at the end in that case.

+
+

So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible.

+
+

What is an array?

+

For example, consider [1, 2.5, 'asdf', False, [1.5, True]] - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately.

+

NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it.

+

An array is a ‘grid’ of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has:

+
    +

  • dtype - data type. Arrays always contain one type

    • +

  • shape - shape of the data, for example 3×2 or 3×2×500 or even +500 (one dimensional) or [] (zero dimensional).

    • +

  • data - raw data storage in memory. This can be passed to C or +Fortran code for efficient calculations.

    • +
+

To test the performance of pure Python vs NumPy we can write in our jupyter notebook:

+

Create one list and one ‘empty’ list, to store the result in

+
a = list(range(10000))
+b = [ 0 ] * 10000
+
+
+

In a new cell starting with %%timeit, loop through the list a and fill the second list b with a squared

+
%%timeit
+for i in range(len(a)):
+  b[i] = a[i]**2
+
+
+

That looks and feels quite fast. But let’s take a look at how NumPy performs for the same task.

+

So for the NumPy example, create one array and one ‘empty’ array to store the result in

+
import numpy as np
+a = np.arange(10000)
+b = np.zeros(10000)
+
+
+

In a new cell starting with %%timeit, fill b with a squared

+
%%timeit
+b = a ** 2
+
+
+

We see that compared to working with numpy arrays, working with traditional python lists is actually slow.

+
+
+

Creating arrays

+

There are different ways of creating arrays (numpy.array(), numpy.ndarray.shape, numpy.ndarray.size):

+
a = np.array([1,2,3])               # 1-dimensional array (rank 1)
+b = np.array([[1,2,3],[4,5,6]])     # 2-dimensional array (rank 2)
+
+b.shape                             # the shape (rows,columns)
+b.size                              # number of elements
+
+
+

In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (numpy.zeros(), numpy.ones(), numpy.full(), numpy.eye(), numpy.arange(), numpy.linspace()):

+
np.zeros((2, 3))             # 2x3 array with all elements 0
+np.ones((1,2))               # 1x2 array with all elements 1
+np.full((2,2),7)             # 2x2 array with all elements 7
+np.eye(2)                    # 2x2 identity matrix
+
+np.arange(10)                # Evenly spaced values in an interval
+np.linspace(0,9,10)          # same as above, see exercise
+
+c = np.ones((3,3))
+d = np.ones((3, 2), 'bool')  # 3x2 boolean array
+
+
+

Arrays can also be stored and read from a (.npy) file (numpy.save(), numpy.load()):

+
np.save('x.npy', a)           # save the array a to a .npy file
+x = np.load('x.npy')          # load an array from a .npy file and store it in variable x
+
+
+

In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (numpy.ndarray.dtype, numpy.ndarray.astype()):

+
d.dtype                    # datatype of the array
+d.astype('int')            # change datatype from boolean to integer
+
+
+

In the last example, .astype('int'), it will make a copy of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed.

+
+
+

Exercises 1

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+ +
+
+

Array maths and vectorization

+

Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do.

+

By default, basic arithmetic (+, -, *, /) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is “vectorized” +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop.

+

Note that unlike Matlab, where * means matrix multiplication, NumPy uses +* to perform element-by-element multiplication and uses the @ symbol to +perform matrix multiplication:

+
a = np.array([[1,2],[3,4]])
+b = np.array([[5,6],[7,8]])
+
+# Addition
+c = a + b
+d = np.add(a,b)
+
+# Matrix multiplication
+e = a @ b
+f = np.dot(a, b)
+
+
+

Other common mathematical operations include: - (numpy.subtract), * (numpy.multiply), / (numpy.divide), .T (numpy.transpose()), numpy.sqrt, numpy.sum(), numpy.mean(), …

+
+
+

Exercises 2

+
+

Exercises: Numpy-2

+ +
+ +
+
+

Indexing and Slicing

+
+

See also

+

Numpy basic indexing docs

+
+

NumPy has many ways to extract values out of arrays:

+
    +

  • You can select a single element

    • +

  • You can select rows or columns

    • +

  • You can select ranges where a condition is true.

    • +
+

Clever and efficient use of these operations is a key to NumPy’s +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C.

+
a = np.arange(16).reshape(4, 4)  # 4x4 matrix from 0 to 15
+a[0]                             # first row
+a[:,0]                           # first column
+a[1:3,1:3]                       # middle 2x2 array
+
+a[(0, 1), (1, 1)]                # second element of first and second row as array
+
+
+

Boolean indexing on above created array:

+
idx = (a > 0)      # creates boolean matrix of same size as a
+a[idx]             # array with matching values of above criterion
+
+a[a > 0]           # same as above in one line
+
+
+
+
+

Exercises 3

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+ +
+
+

Types of operations

+

There are different types of standard operations in NumPy:

+

ufuncs, “universal functions”: These are element-by-element +functions with standardized arguments:

+
    +

  • One, two, or three input arguments

    • +

  • For example, a + b is similar to np.add(a, b) but the ufunc +has more control.

    • +

  • out= output argument, store output in this array (rather than +make a new array) - saves copying data!

    • +

  • See the full reference

    • +

  • They also do broadcasting (ref). Can you add a 1-dimensional array of shape (3) +to an 2-dimensional array of shape (3, 2)? With broadcasting you +can!

    +
    a = np.array([[1, 2, 3],
+              [4, 5, 6]])
+b = np.array([10, 10, 10])
+a + b                       # array([[11, 12, 13],
+                            #        [14, 15, 16]])
+
    +
    +

    Broadcasting is smart and consistent about what it does, which I’m +not clever enough to explain quickly here: the manual page on +broadcasting. +The basic idea is that it expands dimensions of the smaller array so +that they are compatible in shape.

    +
    • +
+

Array methods do something to one array:

+
    +

  • Some of these are the same as ufuncs:

    +
    x = np.arange(12)
+x.shape = (3, 4)
+x                    #  array([[ 0,  1,  2,  3],
+                     #         [ 4,  5,  6,  7],
+                     #         [ 8,  9, 10, 11]])
+x.max()              #  11
+x.max(axis=0)        #  array([ 8,  9, 10, 11])
+x.max(axis=1)        #  array([ 3,  7, 11])
+
    +
    +
    • +
+

Other functions: there are countless other functions covering +linear algebra, scientific functions, etc.

+
+
+

Exercises 4

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+ +
+
+

Linear algebra and other advanced math

+

In general, you use arrays (n-dimensions), not matrixes +(specialized 2-dimensional) in NumPy.

+

Internally, NumPy doesn’t invent its own math routines: it relies on +BLAS +and LAPACK to do this kind +of math - the same as many other languages.

+
    +

  • Linear algebra in numpy

    • +

  • Many, many other array functions

    • +

  • Scipy has even +more functions

    • +

  • Many other libraries use NumPy arrays as the standard data +structure: they take data in this format, and return it similarly. +Thus, all the other packages you may want to use are compatible

    • +

  • If you need to write your own fast code in C, NumPy arrays can be +used to pass data. This is known as extending Python.

    • +
+
+
+

Additional exercises

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally.

    • +

  • Be aware of some NumPy specific peculiarities

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/objects.inv b/branch/opengraph/objects.inv new file mode 100644 index 00000000..2545df67 Binary files /dev/null and b/branch/opengraph/objects.inv differ diff --git a/branch/opengraph/packaging.html b/branch/opengraph/packaging.html new file mode 100644 index 00000000..13d61f45 --- /dev/null +++ b/branch/opengraph/packaging.html @@ -0,0 +1,500 @@ + + + + + + + + + + + + + Packaging — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Packaging

+
+

Questions

+
    +

  • How to organize Python projects larger than one script?

    • +

  • What is a good file and folder structure for Python projects?

    • +

  • How can you make your Python functions most usable by your collaborators?

    • +

  • How to prepare your code to make a Python package?

    • +

  • How to publish your Python package?

    • +
+
+
+

Objectives

+
    +

  • Learn to identify the components of a Python package

    • +

  • Learn to create a Python package

    • +

  • Learn to publish a Python package

    • +
+
+
+

Organizing Python projects

+

Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file.

+

In the Scripts episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further.

+

Recommendations:

+ +

To have a concrete example but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: scipy.

+

These are the 3 files:

+
+
adding.py
+
def add(x, y):
+    return x + y
+
+
+
+
+
subtracting.py
+
def subtract(x, y):
+    return x - y
+
+
+
+
+
integrating.py
+
from scipy import integrate
+
+
+def integral(function, lower_limit, upper_limit):
+    return integrate.quad(function, lower_limit, upper_limit)
+
+
+
+

We will add a fourth file:

+
+
__init__.py
+
"""
+Example calculator package.
+"""
+
+from .adding import add
+from .subtracting import subtract
+from .integrating import integral
+
+__version__ = "0.1.0"
+
+
+
+

This __init__.py file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using relative imports +(with the dot).

+

This is how we will arrange the files in the project folder/repository:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+└── README.md
+
+
+

Now we are ready to test the package. For this we need to be in the “root” +folder, what we have called the project-folder. We also need to have +scipy available in our environment:

+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+

The package is not yet pip-installable, though. We will make this possible in +the next section.

+
+
+

Testing a local pip install

+

To make our example package pip-installable we need to add one more file:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+├── README.md
+└── setup.py
+
+
+

This is how setup.py looks:

+
+
setup.py
+
import setuptools
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    # adapt "myname" to something unique
+    # if you want to test the upload to test-PyPI
+    name="calculator-myname",
+    version="0.1.0",
+    author="Firstname Lastname",
+    author_email="firstname.lastname@example.org",
+    description="A small example package",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://example.org",
+    packages=setuptools.find_packages(),
+    install_requires=[
+        "scipy",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.6',
+)
+
+
+
+

Note how our package requires scipy and we decided to not pin the version +here (see Version pinning for package creators).

+

Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see PyPI (The Python Package Index) and (Ana)conda)

+
+
+

Exercises 1

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Sharing packages via PyPI

+

Once we are able to pip-install the example package locally, we are ready for +upload.

+

We exercise by uploading to test-PyPI, not the +real PyPI, so that if we mess things up, nothing bad +happens.

+

We need two more things:

+
    +

  • We will do this using Twine so you need +to pip install that, too.

    • +

  • You need an account on test-PyPI.

    • +
+

Let’s try it out. First we create the distribution package:

+
$ python setup.py sdist
+
+
+

We need twine:

+
$ pip install twine
+
+
+

And use twine to upload the distribution files to test-PyPI:

+
$ twine upload -r testpypi dist/*
+
+Uploading distributions to https://test.pypi.org/legacy/
+Enter your username:
+Enter your password:
+
+
+

Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt “myname”):

+
$ pip install -i https://test.pypi.org/simple/ calculator-myname
+
+
+
+
+

Tools that simplify sharing via PyPI

+

The solution that we have used to create the example package (using +setuptools and twine) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using pyproject.toml as more general alternative to +setup.py.

+

There are at least two tools which try to make the packaging and PyPI interaction easier:

+ +
+
+

Building a conda package and share it

+
+

Demo

+

Most people will watch and observe this, due to speed which we will +move.

+
+
+

Prerequisites

+

To create a conda package, conda-build package is required. You may install it with Anaconda Navigator or from the command line:

+
$ conda install conda-build
+
+
+
+

The simplest way for creating a conda package for your python script is to +first publish it in PyPI following the steps explained +above.

+
+

Building a python package with conda skeleton pypi

+

Once build, the conda package can be installed locally. For this example, we +will use runtest. runtest is a numerically tolerant end-to-end test +library for research software.

+
    +

  1. Create pypi skeleton:

    +
    $ conda skeleton pypi runtest
+
    +
    +

    The command above will create a new folder called runtest containing a file meta.yaml, the conda recipe for runtest.

    +
    2. +

  2. Edit meta.yaml and update requirements:

    +
    requirements:
+  host:
+    - pip
+    - python
+    - flit
+  run:
+    - python
+    - flit
+
    +
    +

    In the requirements above, we specified what is required for the host and for running the package.

    +
    +

    Remark

    +

    For pure python recipes, this is all you need for building a python package with conda. +If your package needs to be built (for instance compilation), you would need additional files e.g. build.sh (to build on Linux/Mac-OSX) and bld.bat (to build on Windows systems). You can also add test scripts for testing your package. See documentation

    +
    +
    3. +

  3. Build your package with conda

    +

    Your package is now ready to be build with conda:

    +
    $ conda-build runtest
+
    +
    +
    +

    Conda package location

    +

    Look at the messages produced while building. The location of the local conda package is given (search for anaconda upload):

    +
    ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2
+
    +
    +

    The prefix ~/anaconda3/ may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder win-64 differs too (for instance linux-64 on Linux machines).

    +

    The conda package we have created is specific to your platform (here win-64). It can be converted to other platforms using conda convert.

    +
    +
    4. +

  4. Check within new environment

    +

    It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments.

    +
    $ conda create -n local-runtest --use-local runtest
+
    +
    +

    We can then check runtest has been successfully installed in local-runtest conda environment. Open a new Terminal with local-runtest environment (either from the command line:

    +
    $ conda activate local-runtest
+
    +
    +

    or via Anaconda Navigator (Open Terminal), import runtest and +check its version:

    +
    import runtest
+print(runtest.__version__)
+
    +
    +
    5. +
+
+

Building a conda package from scratch

+

It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the conda-build documentation for more information.

+
+

To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a conda channel (see below).

+
+
+

Publishing a python package

+
    +

  • Upload your package to Anaconda.org: see instructions here. +Please note that you will have to create an account on Anaconda.

    • +

  • Upload your package to conda-forge: +conda-forge is a conda channel: it contains community-led collection of +recipes, build infrastructure and distributions for the conda package +manager. Anyone can public conda packages to conda-forge if certain +guidelines are respected.

    • +

  • Upload your package to bioconda: bioconda is +a very popular channel for the conda package manager specializing in +bioinformatics software. As for conda-forge, you need to follow their +guidelines when +building conda recipes.

    • +
+

You can also create your own conda channel +for publishing your packages.

+
+

Keypoints

+
    +

  • Organize your code for publishing

    • +

  • Pypi

    • +

  • conda

    • +
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/pandas.html b/branch/opengraph/pandas.html new file mode 100644 index 00000000..1c941c3d --- /dev/null +++ b/branch/opengraph/pandas.html @@ -0,0 +1,597 @@ + + + + + + + + + + + + + Pandas — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Pandas

+
+

Questions

+
    +

  • How do I learn a new Python package?

    • +

  • How can I use pandas dataframes in my research?

    • +
+
+
+

Objectives

+
    +

  • Learn simple and some more advanced usage of pandas dataframes

    • +

  • Get a feeling for when pandas is useful and know where to find more information

    • +

  • Understand enough of pandas to be able to read its documentation.

    • +
+
+

Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including:

+ +

Let’s get a flavor of what we can do with pandas. We will be working with an +example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:

+
import pandas as pd
+
+
+

We can download the data from this GitHub repository +by visiting the page and saving it to disk, or by directly reading into +a dataframe:

+
url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv"
+titanic = pd.read_csv(url, index_col='Name')
+
+
+

We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:

+
# print the first 5 lines of the dataframe
+titanic.head()
+
+# print summary statistics for each column
+titanic.describe()
+
+
+

Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38% of passengers survived, etc.

+

Let’s say we’re interested in the survival probability of different age groups. With two one-liners, we can find the average age of those who survived or didn’t survive, and plot corresponding histograms of the age distribution:

+
print(titanic.groupby("Survived")["Age"].mean())
+
+
+
titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10),
+             layout=(2,1), zorder=2, sharex=True, rwidth=0.9);
+
+
+

Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let’s get back to basics.

+
+

Getting help

+

Series and DataFrames have a lot functionality, but +how can we find out what methods are available and how they work? One way is to visit +the API reference +and reading through the list. +Another way is to use the autocompletion feature in Jupyter and type e.g. +titanic["Age"]. in a notebook and then hit TAB twice - this should open +up a list menu of available methods and attributes.

+

Jupyter also offers quick access to help pages (docstrings) which can be +more efficient than searching the internet. Two ways exist:

+
    +

  • Write a function name followed by question mark and execute the cell, e.g. +write titanic.hist? and hit SHIFT + ENTER.

    • +

  • Write the function name and hit SHIFT + TAB.

    • +
+
+
+

What’s in a dataframe?

+

As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +DataFrame object +is composed of rows and columns:

+_images/01_table_dataframe.svg

Each column of a dataframe is a +series object +- a dataframe is thus a collection of series:

+
# print some information about the columns
+titanic.info()
+
+
+

Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type int64 or of type object.

+

Let’s inspect one column of the Titanic passanger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):

+
titanic["Age"]
+titanic.Age          # same as above
+type(titanic["Age"])
+
+
+

The columns have names. Here’s how to get them:

+
titanic.columns
+
+
+

However, the rows also have names! This is what Pandas calls the index:

+
titanic.index
+
+
+

We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and values. We can +refer to columns and rows either by number or by their name:

+
titanic.loc['Lam, Mr. Ali',"Age"]          # select single value by row and column
+titanic.loc[:'Lam, Mr. Ali',"Name":"Age"]  # slice the dataframe by row and column *names*
+titanic.iloc[0:2,3:6]                      # same slice as above by row and column *numbers*
+
+titanic.at['Lam, Mr. Ali',"Age"] = 42      # set single value by row and column *name* (fast)
+titanic.at['Lam, Mr. Ali',"Age"]           # select single value by row and column *name* (fast)
+titanic.at['Lam, Mr. Ali',"Age"] = 42      # set single value by row and column *name* (fast)
+titanic.iat[0,5]                           # select same value by row and column *number* (fast)
+
+titanic["foo"] = "bar"                     # set a whole column
+
+
+

Dataframes also support boolean indexing, just like we saw for numpy +arrays:

+
titanic[titanic["Age"] > 70]
+# ".str" creates a string object from a column
+titanic[titanic.index.str.contains("Margaret")]
+
+
+

What if your dataset has missing data? Pandas uses the value numpy.nan +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:

+
titanic.isna()                    # returns boolean mask of NaN values
+titanic.dropna()                  # drop missing values
+titanic.dropna(how="any")         # or how="all"
+titanic.dropna(subset=["Cabin"])  # only drop NaNs from one column
+titanic.fillna(0)                 # replace NaNs with zero
+titanic.fillna(method='ffill')    # forward-fill NaNs
+
+
+
+
+

Exercises 1

+
+

Exploring dataframes

+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+
+

Tidy data

+

The above analysis was rather straightforward thanks to the fact +that the dataset is tidy.

+_images/tidy_data.png +

In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data.

+

What would untidy data look like? Here’s an example from +some run time statistics from a 1500 m running event:

+
runners = pd.DataFrame([
+              {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240},
+              {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300},
+              {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360},
+          ])
+
+
+

What makes this data untidy is that the column names 400, 800, 1200, 1500 +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row.

+

To make untidy data tidy, a common operation is to “melt” it, +which is to convert it from wide form to a long form:

+
runners = pd.melt(runners, id_vars="Runner",
+              value_vars=[400, 800, 1200, 1500],
+              var_name="distance",
+              value_name="time"
+          )
+
+
+

In this form it’s easier to filter, group, join +and aggregate the data, and it’s also easier to model relationships +between variables.

+

The opposite of melting is to pivot data, which can be useful to +view data in different ways as we’ll see below.

+

For a detailed exposition of data tidying, have a look at +this article.

+
+
+

Working with dataframes

+

We saw above how we can read in data into a dataframe using the read_csv method. +Pandas also understands multiple other formats, for example using read_excel, +read_hdf, read_json, etc. (and corresponding methods to write to file: +to_csv, to_excel, to_hdf, to_json, etc.)

+

But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array:

+
dates = pd.date_range('20130101', periods=6)
+df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD'))
+
+
+

or a dictionary:

+
df = pd.DataFrame({'A': ['foo', 'bar', 'foo', 'bar', 'foo', 'bar', 'foo', 'foo'],
+                   'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'],
+                   'C': np.array([3] * 8, dtype='int32'),
+                   'D': np.random.randn(8),
+                   'E': np.random.randn(8)})
+
+
+

There are many ways to operate on dataframes. Let’s look at a +few examples in order to get a feeling of what’s possible +and what the use cases can be.

+

We can easily split and concatenate or append dataframes:

+
sub1, sub2, sub3 = df[:2], df[2:4], df[4:]
+pd.concat([sub1, sub2, sub3])
+sub1.append([sub2, sub3])      # same as above
+
+
+

When pulling data from multiple dataframes, a powerful pandas.DataFrame.merge method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:

+
age = pd.DataFrame([
+    {"Runner": "Runner 4", "Age": 18},
+    {"Runner": "Runner 2", "Age": 21},
+    {"Runner": "Runner 1", "Age": 23},
+    {"Runner": "Runner 3", "Age": 19},
+])
+
+
+

We now want to use this table to annotate the original runners table from +before with their age. Note that the runners and age dataframes have a +different ordering to it, and age has an entry for Dave which is not +present in the runners table. We can let Pandas deal with all of it using +the merge method:

+
# Add the age for each runner
+runners.merge(age, on="Runner")
+
+
+

In fact, much of what can be done in SQL +is also possible with pandas.

+

groupby is a powerful method which splits a dataframe and aggregates data +in groups. To see what’s possible, let’s return to the Titanic dataset. Let’s +test the old saying “Women and children first”. We start by creating a new +column Child to indicate whether a passenger was a child or not, based on +the existing Age column. For this example, let’s assume that you are a +child when you are younger than 12 years:

+
titanic["Child"] = titanic["Age"] < 12
+
+
+

Now we can test the saying by grouping the data on Sex and then creating further sub-groups based on Child:

+
titanic.groupby(["Sex", "Child"])["Survived"].mean()
+
+
+

Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +std, min, +max, cumsum, +median, skew, +var etc.

+
+
+

Exercises 2

+
+

Analyze the Titanic passenger list dataset

+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+
+

Time series superpowers

+

An introduction of pandas wouldn’t be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates:

+
nobel = pd.read_csv("http://api.nobelprize.org/v1/laureate.csv")
+nobel.head()
+
+
+

This dataset has three columns for time, “born”/”died” and “year”. +These are represented as strings and integers, respectively, and +need to be converted to datetime format:

+
# the errors='coerce' argument is needed because the dataset is a bit messy
+nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce')
+nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce')
+nobel["year"] = pd.to_datetime(nobel["year"], format="%Y")
+
+
+

Pandas knows a lot about dates:

+
print(nobel["born"].dt.day)
+print(nobel["born"].dt.year)
+print(nobel["born"].dt.weekday)
+
+
+

We can add a column containing the (approximate) lifespan in years rounded +to one decimal:

+
nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1)
+
+
+

and then plot a histogram of lifespans:

+
nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9)
+
+
+

Finally, let’s see one more example of an informative plot +produced by a single line of code:

+
nobel.boxplot(column="lifespan", by="category")
+
+
+
+
+

Exercises 3

+
+

Analyze the Nobel prize dataset

+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries:

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below).

      • +

    • Then create the pivot table:

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y="year", x="bornCountry",inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+
+
+

Beyond the basics

+

There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its API. And when there is not, you can always +apply your own functions to the data using apply:

+
from functools import lru_cache
+
+@lru_cache
+def fib(x):
+    """Compute Fibonacci numbers. The @lru_cache remembers values we
+    computed before, which speeds up this function a lot."""
+    if x < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif x < 2:
+        return x
+    else:
+        return fib(x - 2) + fib(x - 1)
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = df['Generation'].apply(fib)
+
+
+
+

Keypoints

+
    +

  • pandas dataframes are a good data structure for tabular data

    • +

  • Dataframes allow both simple and advanced analysis in very compact form

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/parallel-pi-multiprocessing.html b/branch/opengraph/parallel-pi-multiprocessing.html new file mode 100644 index 00000000..f915a22f --- /dev/null +++ b/branch/opengraph/parallel-pi-multiprocessing.html @@ -0,0 +1,355 @@ + + + + + + + + + + + + + Python multithreading solution — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python multithreading solution

+

Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare).

+
+
+
import random
+
+
+
+
+
+
+
def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+    
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+
+
+
+
+
%%timeit
+# Do it just for timing
+n, n_inside_circle = sample(10**6)
+
+
+
+
+
474 ms ± 3.75 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do the actual calculation (the previous result doesn't get saved)
+n, n_inside_circle = sample(10**6)
+
+
+
+
+

This is the “calculate answer” phase.

+
+
+
pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+
+
+
3.141252
+
+
+
+
+
+

Do it in parallel with multiprocessing

+

This divides the calculation into 10 tasks and runs sample on each of them. Then it re-combines the results.

+
+
+
import multiprocessing.pool
+pool = multiprocessing.pool.Pool()
+# The default pool makes one process per CPU
+
+
+
+
+
+
+
%%timeit
+# Do it once to time it
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
305 ms ± 5.52 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
pool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.141344
+
+
+
+
+
+
+

Do it in “parallel” with threads

+

To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process.

+
+
+
threadpool = multiprocessing.pool.ThreadPool()
+
+
+
+
+
+
+
%%timeit -o
+# Do it once to time it
+threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
498 ms ± 5.34 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
<TimeitResult : 498 ms ± 5.34 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)>
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
threadpool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.14156
+
+
+
+
+
+
+

Future ideas

+

You could make a separate calculate function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.

+

Notice the similarity to split-apply-combine or map-reduce which is a specialization of split-apply-combine.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/parallel.html b/branch/opengraph/parallel.html new file mode 100644 index 00000000..4cb0b208 --- /dev/null +++ b/branch/opengraph/parallel.html @@ -0,0 +1,559 @@ + + + + + + + + + + + + + Parallel programming — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Parallel programming

+
+

Questions

+
    +

  • When you need more than one processor, what do you do?

    • +

  • How can we use more than one processor/core in Python?

    • +
+
+
+

Objectives

+
    +

  • Understand the major strategies of parallelizing code

    • +

  • Understand mechanics of the multiprocessing package

    • +

  • Know when to use more advanced packages or approaches

    • +
+
+
+

Modes of parallelism

+

You realize you do have more computation to do than you can on one processor? +What do you do?

+
    +

  1. Profile your code, identify the actual slow spots.

    2. +

  2. Can you improve your code in those areas? Use an existing library?

    3. +

  3. Are there are any low-effort optimizations that you can make?

    4. +

  4. Think about parallelizing.

    5. +
+

Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers).

+

Parallel computing is when many different tasks are carried out +simultaneously. There are three main models:

+
    +

  • Embarrassingly parallel: the code does not need to synchronize/communicate +with other instances, and you can run +multiple instances of the code separately, and combine the results +later. If you can do this, great! (array jobs, task queues)

    • +

  • Shared memory parallelism: Parallel threads need to communicate and do so via +the same memory (variables, state, etc). (OpenMP)

    • +

  • Message passing: Different processes manage their own memory segments. They share data +by communicating (passing messages) as needed. (Message Passing Interface (MPI)).

    • +
+

Programming shared memory or message passing is beyond the scope of +this course, but the simpler strategies are most often used anyway.

+
+

Warning

+

Parallel programming is not magic, but many things can go wrong and +you can get unexpected results or difficult to debug problems. +Parallel programming is a fascinating world to get involved in, but +make sure you invest enough time to do it well.

+

See the video by Raymond Hettinger (“See Also” at bottom +of page) for an entertaining take on this.

+
+
+
+

Multithreading and the GIL

+

The designers of the Python language made the choice +that only one thread in a process can run actual Python code +by using the so-called global interpreter lock (GIL). +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python without being a bit careful. +At first glance, this is bad for parallelism. But it’s not all bad!:

+
    +

  • External libraries (NumPy, SciPy, Pandas, etc), written in C or other +languages, can release the lock and run multi-threaded. Also, most +input/output releases the GIL, and input/output is slow.

    • +

  • If speed is important enough you need things parallel, you usually +wouldn’t use pure Python.

    • +
+

We won’t cover threading in this course.

+
+

See also

+ +
+
+
+

multiprocessing

+

As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +multiprocessing module.

+
    +

  • The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock.

    • +

  • There are low-level functions which have a lot of the same risks and +difficulties as when using threading.

    • +
+

To show an example, +the split-apply-combine +or map-reduce paradigm is +quite useful for many scientific workflows. Consider you have this:

+
def square(x):
+    return x*x
+
+
+

You can apply the function to every element in a list using the +map() function:

+
>>> list(map(square, [1, 2, 3, 4, 5, 6]))
+[1, 4, 9, 16, 25, 36]
+
+
+

The multiprocessing.pool.Pool class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list:

+
>>> from multiprocessing import Pool
+>>> with Pool() as pool:
+...     pool.map(square, [1, 2, 3, 4, 5, 6])
+[1, 4, 9, 16, 25, 36]
+
+
+
+
+

Exercises, multiprocessing

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+
+
+

MPI

+

The message passing interface (MPI) approach to parallelization +is that:

+
    +

  • Tasks (cores) have a rank and are numbered 0, 1, 2, 3, …

    • +

  • Each task (core) manages its own memory

    • +

  • Tasks communicate and share data by sending messages

    • +

  • Many higher-level functions exist to distribute information to other tasks +and gather information from other tasks

    • +

  • All tasks typically run the entire code and we have to be careful to avoid +that all tasks do the same thing

    • +
+

Introductory MPI lessons where Python is included:

+ +

These blog posts are good for gentle MPI/mpi4py introduction:

+ +

Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together.

+

Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work:

+
import random
+import time
+from mpi4py import MPI
+
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x ** 2 + y ** 2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+comm = MPI.COMM_WORLD
+size = comm.Get_size()
+rank = comm.Get_rank()
+
+n = 10 ** 7
+
+if size > 1:
+    n_task = int(n / size)
+else:
+    n_task = n
+
+t0 = time.perf_counter()
+_, n_inside_circle = sample(n_task)
+t = time.perf_counter() - t0
+
+print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+n_inside_circle = comm.gather(n_inside_circle, root=0)
+print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+
+if rank == 0:
+    pi_estimate = 4.0 * sum(n_inside_circle) / n
+    print(
+        f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds"
+    )
+
+
+
+
+

Exercises, MPI

+
+

Parallel-2, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+
+
+
+

Coupling to other languages

+

As mentioned further up in “Multithreading and the GIL”, Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP “directly”.

+

However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don’t +need parallelism, but need to make an optimized algorithm for a small part of the code.

+

Two strategies are common:

+
    +

  • Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization:

    +
    +
      +

    • C: use the cffi package (C foreign function interface). ctypes is a similar but slightly more primitive module that is in the standard library.

      • +

    • C++: use pybind11

      • +

    • Fortran: create a C interface using iso_c_binding and then couple the C layer to Python +using cffi

      • +

    • Rust: use PyO3

      • +
    +
    +
    • +

  • Let compiled languages do the shared-memory parallelization part (as in above +point) and let Python do the MPI work and distribute tasks across nodes using +an mpi4py layer.

    • +
+

Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course.

+

Before you take this route, profile the application first to be sure where +the bottleneck is.

+

Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason.

+
+
+

Dask and task queues

+

There are other strategies that go completely beyond the manual +parallelization methods above. We won’t go into much detail.

+
+

Dask

+

Dask is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs.

+

Dask is very popular for data analysis and is used by a number of high-level python library:

+
    +

  • Dask arrays scale Numpy (see also xarray

    • +

  • Dask dataframes scale Pandas workflows

    • +

  • Dask-ML scales Scikit-Learn

    • +
+

Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block.

+
+

Example from dask.org

+
# Arrays implement the Numpy API
+import dask.array as da
+x = da.random.random(size=(10000, 10000),
+                     chunks=(1000, 1000))
+x + x.T - x.mean(axis=0)
+# It runs using multiple threads on your machine.
+# It could also be distributed to multiple machines
+
+
+
+
+
+
+

Exercises, Dask

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+

Task queues

+

A task queue has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for embarrassingly parallel jobs.

+

There are different descriptions of task queues in Python. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant.

+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pure Python is not very good for highly parallel code.

    • +

  • Luckily it interfaces to many things which are good, and give +you the full control you need.

    • +

  • Combining vectorized functions (numpy, scipy, pandas, etc.) with +the parallel strategies listed here will get you very far.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/python.html b/branch/opengraph/python.html new file mode 100644 index 00000000..001b99d8 --- /dev/null +++ b/branch/opengraph/python.html @@ -0,0 +1,303 @@ + + + + + + + + + + + + + Introduction to Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Introduction to Python

+
+

Questions

+
    +

  • What are the basic blocks of Python language?

    • +

  • How are functions and classes defined in Python?

    • +
+
+
+

Objectives

+
    +

  • Get a very short introduction to Python types and syntax

    • +

  • Be able to follow the rest of the examples in the course, even if you don’t understand everything perfectly.

    • +
+

We expect everyone to be able to know the following basic material +to follow the course (though it is not everything you need to +know about Python).

+
+

If you are not familiar with Python, here is a very short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise.

+
+

See also

+

This page contains an overview of the basics of Python. You can +also refer to This Python overview from a different lesson +which is slightly more engaging.

+
+
+

Scalars

+

Scalar types, that is, single elements of various types:

+
i = 42       # integer
+i = 2**77    # Integers have arbitrary precision
+g = 3.14     # floating point number
+c = 2 - 3j   # Complex number
+b = True     # boolean
+s = "Hello!" # String (Unicode)
+q = b'Hello' # bytes (8-bit values)
+
+
+

Read more: int, float, complex, +bool, str, bytes.

+
+
+

Collections

+

Collections are data structures capable of storing multiple values.

+
l = [1, 2, 3]                      # list
+l[1]                               # lists are indexed by int
+l[1] = True                        # list elements can be any type
+d = {"Janne": 123, "Richard": 456} # dictionary
+d["Janne"]
+s = set(("apple", "cherry", "banana", "apple")) # Set of unique values
+s
+
+
+

Read more: list, tuple, dict, set.

+
+
+

Control structures

+

Python has the usual control structures, that is conditional +statements and loops. For example, the The if statement statement:

+
x = 2
+if x == 3:
+    print('x is 3')
+elif x == 2:
+    print('x is 2')
+else:
+    print('x is something else')
+
+
+

While loops loop until some condition is met:

+
x = 0
+while x < 42:
+    print('x is ', x)
+    x += 0.2
+
+
+

For loops loop over some collection of values:

+
xs = [1, 2, 3, 4]
+for x in xs:
+    print(x)
+
+
+

Often you want to loop over a sequence of integers, in that case the +range() function is useful:

+
for x in range(9):
+    print(x)
+
+
+

Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the enumerate() +function:

+
xs = [1, 'hello', 'world']
+for ii, x in enumerate(xs):
+    print(ii, x)
+
+
+
+
+

Functions and classes

+

Python functions are defined by the Function definitions keyword. They take a +number of arguments, and return a number of return values.

+
def hello(name):
+    """Say hello to the person given by the argument"""
+    print('Hello', name)
+    return 'Hello ' + name
+
+hello("Anne")
+
+
+

Classes are defined by the Class definitions keyword:

+
class Hello:
+    def __init__(self, name):
+        self._name = name
+    def say(self):
+        print('Hello', self._name)
+
+h = Hello("Richard")
+h.say()
+
+
+
+
+

Python type system

+

Python is strongly and dynamically typed.

+

Strong here means, roughly, that it’s not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior).

+
x = 42
+type(x)
+x + "hello"
+
+
+

Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type:

+
x = 42
+x = "hello"
+
+
+

Jargon: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation.

+

??? (lesson here)

+
+

Keypoints

+
    +

  • Python offers a nice set of basic types as many other programming languages

    • +

  • Python is strongly typed and dynamically typed

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/quick-reference.html b/branch/opengraph/quick-reference.html new file mode 100644 index 00000000..dc0f0c9c --- /dev/null +++ b/branch/opengraph/quick-reference.html @@ -0,0 +1,158 @@ + + + + + + + + + + + + + Quick reference — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/scipy.html b/branch/opengraph/scipy.html new file mode 100644 index 00000000..606b0dc6 --- /dev/null +++ b/branch/opengraph/scipy.html @@ -0,0 +1,316 @@ + + + + + + + + + + + + + SciPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

SciPy

+
+

Questions

+
    +

  • When you need more advanced mathematical functions, where do you +look?

    • +
+
+
+

Objectives

+
    +

  • Understand that SciPy exists and what kinds of things it has.

    • +

  • Understand the importance of using external libraries and how to +use them.

    • +

  • Understand the purpose of wrapping existing C/Fortran code.

    • +

  • Non-objective: know details of everything (or anything) in SciPy.

    • +
+
+
+

See also

+ +
+

SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms.

+
+

What’s in SciPy?

+

Briefly, it contains functionality for

+
    +

  • Special functions (Bessel, Gamma, etc.)

    • +

  • Numerical integration

    • +

  • Optimization

    • +

  • Interpolation

    • +

  • Fast Fourier Transform (FFT)

    • +

  • Signal processing

    • +

  • Linear algebra (more complete than in NumPy)

    • +

  • Sparse matrices

    • +

  • Statistics

    • +

  • More I/O routine, e.g. Matrix Market format for sparse matrices, +MATLAB files (.mat), etc.

    • +
+

Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages.

+

Most functions are documented ridiculously well from a scientific +standpoint: you aren’t just using some unknown function, but have a +full scientific description and citation to the method and +implementation.

+
+
+

Exercises: use SciPy

+

These exercises do not exist because you might need these +functions someday. They are because you will need to read +documentation and understand documentation of an an external library +eventually.

+
+

1: Numerical integration

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+ +
+
+

2: Sparse matrices

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+ +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • When you need advance math or scientific functions, let’s just +admit it: you do a web search first.

    • +

  • But when you see something in SciPy come up, you know your +solutions are in good hands.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/scripts.html b/branch/opengraph/scripts.html new file mode 100644 index 00000000..6bd4447f --- /dev/null +++ b/branch/opengraph/scripts.html @@ -0,0 +1,613 @@ + + + + + + + + + + + + + Scripts — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Scripts

+
+

Questions

+
    +

  • Why are command line programs useful, compared to Jupyter +notebooks and similar?

    • +

  • How to create a python script?

    • +

  • How to generalize a python script?

    • +
+
+
+

Objectives

+
    +

  • Learn how to streamline your python notebooks by creating repeatable python scripts

    • +

  • Learn how to import other python files

    • +

  • Learn to parse command line arguments in python

    • +
+
+
+

Why scripts?

+

So far we have been learning python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype python code so we may think that is more than enough for your day to day work.

+

But after several weeks of hard work with python, you may end up:

+
    +

  • either with 10 different notebooks (so that you can run them concurrently)

    • +

  • or with a very long notebook which is becoming hardly readable!

    • +
+

Let’s imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks?

+

In this episode, we will learn how to automate your work using python scripts so that

+
    +

  • you do not need to manually configure your notebooks to be able to run with different parameters

    • +

  • can easily run you work via other tools, such as on computing clusters.

    • +
+
+
+

From jupyter notebooks to python scripts

+
+
+

Save as python script

+

Jupyter notebooks can be parameterized for instance using papermill. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate python scripts. This will also force you to modularize your code. See CodeRefinery’s lesson on Modular code development.

+

Within JupyterLab, you can export any jupyter notebook to a python script:

+
+https://jupyterlab.readthedocs.io/en/stable/_images/exporting_menu.png +
+

Select File (top menu bar) → Export Notebook as → Export notebook to Executable Script.

+
+
+

Actually, you could also export your notebook in many other formats. +Check the JupyterLab documentation for more information. +If you keep working in the jupyterlab folder, you can also convert files in the terminal (File -> New -> Terminal) by running:

+
$ jupyter nbconvert --to script your_notebook_name.ipynb
+
+
+
+
+

Exercises 1

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and the weather_data file and upload them to your jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Note: If you haven’t downloaded the file directly to your jupyterlab folder, it will be located in your Downloads folder or the folder you selected. In jupyterlab click on the ‘upload file’ button, navigate to the folder containing the file and select it to load it into your jupyterlab folder.

    +
    2. +

  2. Open a terminal in jupyter (File -> New -> Terminal).

    3. +

  3. Convert the jupyter script to a python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+
+
+

Importing other python files

+

We have a very short notebook that loads and plots data. But even in this script, we have to do a bit of processing (changing the format of the dates). We also extract a subset of our data for a +given date range.

+

In general, it is good practice to separate processing from plotting. The reason is that you often need to generate multiple plots using the data while pre-processing data once only. +When data preprocessing is expensive this is even more important.

+

For example, we can create a new python file (weather_functions.py) containing a function to adjust the dates in our dataset:

+
import pandas as pd
+
+def preprocess(dataset, start_date, end_date):
+  dataset['Local time'] = pd.to_datetime(dataset['Local time'],dayfirst=True)
+  dataset = dataset[dataset['Local time'].between(start_date,end_date)]
+  return dataset
+
+
+

and modify the weather_observations.py file to

+
import pandas as pd
+import weather_functions
+
+url = "https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv"
+# read the data skipping comment lines
+weather = pd.read_csv(url,comment='#')
+# set start and end time
+start_date=pd.to_datetime('01/06/2021',dayfirst=True)
+end_date=pd.to_datetime('01/10/2021',dayfirst=True)
+# preprocess the data
+weather = weather_functions.preprocess(weather, start_date, end_date)
+...
+
+
+
+
+

Exercises 2

+
+

Scripts-2 (optional)

+
    +

  1. Create weather_functions.py with the above function and add an additional function for plotting the dataset.

    2. +

  2. Update weather_observations.py to call it.

    3. +
+
+ +
+
+

Command line arguments with sys.argv

+

We now have a better organized code but it still cannot easily process time ranges or a +specified output file name. To achieve this, rather than copying the same code several times for +different time ranges or output file names, we can update the main code to take the +start/end time and output file name from the command line

+

Example: We modify the weather_observations.py script such that we allow start +and end times as well as the output file to be passed in as arguments to the function:

+
import sys
+import pandas as pd
+import weather_functions
+
+# set start and end time
+start_date = pd.to_datetime(sys.argv[1],dayfirst=True)
+end_date = pd.to_datetime(sys.argv[2],dayfirst=True)
+
+output_file_name = sys.argv[3]
+
+...
+
+# preprocess the data
+weather = weather_functions.preprocess(weather, start_date, end_date)
+
+...
+
+fig.savefig(output_file_name)
+
+
+

We can try it out:

+
$ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png
+
+
+
+

Discussion

+
    +

  • Does it work?

    • +

  • Why is this better than modifying the script every time I want it to +plot data for a different period?

    • +

  • What problems do you expect when using this approach (using sys.argv)?

    • +
+
+

This approach is brittle and more robust solutions exist that allow to fully +customize your scripts and generate help texts at the same time:

+
    +

  • argparse: +built-in to Python, this is the one that we will show below.

    • +

  • doctopt: you write the help text and this generates a parser for you.

    • +

  • click: another nice +library for command line interfaces - very easy to use.

    • +
+
+
+

Parsing command line arguments with argparse

+

This example not only gives you descriptive command line +arguments, it also automatically generates a --help option for you:

+
import argparse
+import pandas as pd
+import weather_functions
+
+parser = argparse.ArgumentParser()
+# set start and end time
+parser.add_argument('-o', '--output', type=str, default="Out.png"
+                 help="end time")
+parser.add_argument('-s', '--start', type=str, default="1/1/2019"
+                 help="start time")
+parser.add_argument('-e', '--end', type=str, default="1/1/2021"
+                 help="output filename")
+
+args = parser.parse_args()
+
+start_date = pd.to_datetime(args.start,dayfirst=True)
+end_date = pd.to_datetime(args.end,dayfirst=True)
+
+...
+
+# preprocess the data
+weather = weather_functions.preprocess(weather, start_date, end_date)
+
+...
+
+fig.savefig(args.output)
+
+
+
+
+

Exercises 3

+
+

Scripts-3

+
    +

  1. Take the python script we have written in the preceding exercise and use +argparse to specify the input and output files and allow the start and end dates to be set.

    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from Mai 2020 to October 2020). +Also use data for cairo (https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv)

    3. +
+
+ +
+

Discussion

+

What was the point of doing this?

+

Now you can do this:

+
$ python weather_observations.py --help
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png
+$ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png
+$ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output temperature_cairo.png
+
+
+
    +

  • We can now process different input files without changing the script.

    • +

  • We can select multiple time ranges without modifying the script.

    • +

  • This way we can also loop over file patterns (using shell loops or similar) or use +the script in a workflow management system and process many files in parallel.

    • +

  • By changing from sys.argv to argparse we made the script more robust against +user input errors and also got a help text (accessible via --help).

    • +
+
+
+
+

Load larger option lists using config files

+

In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line:

+
$ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021
+
+
+

This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple Parameter = Value +format, and parse it yourself, or you can use e.g. the JSON or YAML formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won’t go into the details of the formats, and will only give +a short example using YAML here.

+

The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a python module (yaml) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the json package).

+

The python module optionsparser.py provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values.

+

In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation …), set the labels and titles explicitly etc.

+

In the YAML format, names and values are separated by :. Our above example would therefore translate to the following YAML file:

+
input:        https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv
+output:       rain_in_cairo.png
+xlabel:       Days in June
+ylabel:       Rainfall in mm
+title:        Rainfall in Cairo
+data_column:  RRR
+start:        01/06/2021
+end:          30/06/2021
+
+
+
+
+

Exercises 4 (optional)

+
+

Scripts-4

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in jupyterlab. +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+ +
+

Further reading

+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/opengraph/search.html b/branch/opengraph/search.html new file mode 100644 index 00000000..c7ed94f6 --- /dev/null +++ b/branch/opengraph/search.html @@ -0,0 +1,153 @@ + + + + + + Search — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+
+ +
+ +
+

© Copyright 2020, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/branch/opengraph/searchindex.js b/branch/opengraph/searchindex.js new file mode 100644 index 00000000..834aa6e2 --- /dev/null +++ b/branch/opengraph/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"docnames": ["binder", "data-formats", "data-visualization", "dependencies", "exercises", "guide", "index", "installation", "jupyter", "libraries", "numpy", "numpy-advanced", "packaging", "pandas", "parallel", "parallel-pi-multiprocessing", "python", "quick-reference", "scipy", "scripts"], "filenames": ["binder.rst", "data-formats.rst", "data-visualization.md", "dependencies.rst", "exercises.md", "guide.rst", "index.rst", "installation.rst", "jupyter.ipynb", "libraries.rst", "numpy.rst", "numpy-advanced.rst", "packaging.rst", "pandas.rst", "parallel.rst", "parallel-pi-multiprocessing.ipynb", "python.rst", "quick-reference.rst", "scipy.rst", "scripts.rst"], "titles": ["Binder", "Data formats with Pandas and Numpy", "Data visualization with Matplotlib", "Dependency management", "List of exercises", "Instructor\u2019s guide", "Python for Scientific Computing", "Software installation", "Jupyter", "Library ecosystem", "NumPy", "Advanced NumPy", "Packaging", "Pandas", "Parallel programming", "Python multithreading solution", "Introduction to Python", "Quick reference", "SciPy", "Scripts"], "terms": {"alon": 0, "mai": [0, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 19], "suffici": [0, 4], "what": [0, 2, 3, 4, 5, 6, 7, 11, 12, 14, 16, 19], "my": [0, 1, 2, 3, 4, 9, 10, 13], "python": [0, 1, 2, 4, 5, 8, 10, 11, 13, 14, 18], "repositori": [0, 3, 4, 9, 12, 13], "publish": [0, 3, 4, 5, 9, 11], "learn": [0, 1, 2, 3, 4, 5, 6, 7, 11, 12, 13, 14, 17, 19], "about": [0, 2, 3, 4, 6, 7, 8, 9, 10, 11, 13, 14, 16, 18, 19], "custom": [0, 9, 19], "befor": [0, 1, 2, 3, 4, 7, 10, 11, 12, 13, 14], "we": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "work": [0, 1, 2, 3, 5, 7, 8, 10, 11, 14, 19], "group": [0, 2, 4, 8, 9, 13], "let": [0, 1, 2, 4, 6, 8, 10, 11, 12, 13, 14, 18, 19], "": [0, 1, 2, 4, 6, 7, 8, 10, 11, 12, 14, 15, 16, 19], "take": [0, 1, 4, 5, 8, 10, 11, 12, 13, 14, 15, 16, 18, 19], "an": [0, 1, 3, 5, 6, 8, 9, 12, 13, 14, 15, 16, 18, 19], "exampl": [0, 1, 3, 6, 7, 8, 9, 10, 12, 13, 16, 18, 19], "geospati": 0, "analysi": [0, 1, 2, 3, 8, 11, 13, 14], "where": [0, 1, 2, 4, 5, 6, 9, 10, 13, 14, 18], "first": [0, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 18, 19], "import": [0, 1, 2, 3, 4, 5, 8, 10, 11, 12, 13, 14, 15, 18], "would": [0, 2, 3, 4, 7, 9, 10, 11, 12, 13, 14, 16, 19], "pleas": [0, 3, 4, 7, 12], "note": [0, 2, 4, 7, 10, 12, 13, 14, 19], "necessari": [0, 3, 11, 12, 14], "instal": [0, 1, 2, 3, 4, 5, 6, 9, 13, 14], "ani": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 19], "packag": [0, 1, 2, 5, 6, 7, 10, 11, 13, 14, 19], "mention": [0, 1, 5, 7, 9, 13, 14], "below": [0, 1, 2, 3, 4, 6, 7, 8, 9, 11, 12, 13, 14, 18, 19], "osgeo": 0, "ogr": 0, "osr": 0, "gdal": 0, "depend": [0, 5, 6, 9, 10, 11, 12], "you": [0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "thi": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "have": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "libgdal": 0, "its": [0, 1, 2, 4, 10, 11, 12, 13, 14], "develop": [0, 3, 4, 6, 8, 9, 11, 13, 19], "header": 0, "alreadi": [0, 1, 4, 5, 7, 9, 10, 13, 19], "system": [0, 3, 4, 7, 8, 12, 14, 19], "inform": [0, 4, 9, 12, 13, 14, 18, 19], "version": [0, 4, 6, 7, 8, 11, 12, 14], "us": [0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], "etc": [0, 1, 4, 5, 6, 9, 10, 11, 13, 14, 18, 19], "lea": [0, 4], "phd": [0, 4, 5, 6], "student": [0, 3, 4, 5, 6, 9], "biologi": [0, 4], "after": [0, 2, 4, 8, 10, 11, 14, 19], "2": [0, 12, 15, 16], "year": [0, 2, 3, 4, 5, 6, 9, 11, 13], "intens": [0, 4], "she": [0, 3, 4], "final": [0, 2, 4, 6, 10, 11, 13, 14, 15], "readi": [0, 2, 4, 7, 12], "her": [0, 3, 4], "paper": [0, 4, 9, 10], "The": [0, 1, 2, 4, 5, 6, 7, 8, 10, 12, 13, 14, 15, 16, 18, 19], "ha": [0, 1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 18], "analyz": [0, 3], "data": [0, 3, 5, 6, 8, 10, 14, 16, 19], "avail": [0, 3, 4, 5, 7, 9, 11, 12, 13, 18, 19], "github": [0, 2, 3, 4, 5, 6, 8, 9, 13, 14], "supervisor": [0, 4], "who": [0, 2, 3, 4, 5, 7, 9, 11, 13, 14], "advoc": [0, 4], "open": [0, 1, 3, 4, 6, 7, 9, 12, 13, 18, 19], "scienc": [0, 1, 4, 6, 9, 13, 14], "told": [0, 4], "possibli": [0, 4, 5, 6], "just": [0, 1, 2, 3, 4, 6, 9, 10, 11, 13, 14, 15, 18], "problem": [0, 1, 2, 3, 4, 5, 8, 14, 19], "anticip": [0, 4], "5": [0, 2, 3, 6, 8, 11, 13, 14, 15, 18], "now": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 19], "form": [0, 4, 6, 7, 9, 13], "small": [0, 1, 2, 4, 5, 9, 10, 11, 12, 14], "person": [0, 2, 4, 5, 9, 16], "discuss": [0, 3, 4, 5, 6, 8, 9], "If": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 14, 16, 19], "workshop": [0, 4, 7, 9], "onlin": [0, 4, 7, 9], "each": [0, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 15, 18], "join": [0, 3, 4, 13], "breakout": [0, 3, 4], "room": [0, 3, 4], "possibl": [0, 1, 2, 3, 4, 5, 8, 10, 11, 12, 13, 14, 16], "practic": [0, 2, 3, 4, 5, 6, 8, 9, 12, 19], "document": [0, 1, 3, 4, 5, 8, 9, 12, 13, 14, 18, 19], "collabor": [0, 3, 4, 6, 12], "write": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 19], "summari": [0, 4, 13], "bullet": [0, 4, 8], "point": [0, 1, 2, 4, 5, 6, 8, 9, 10, 11, 14, 15, 16, 19], "provid": [0, 1, 2, 3, 4, 5, 6, 7, 10, 13, 14, 19], "instructor": [0, 4, 6], "allow": [0, 1, 2, 4, 11, 13, 14, 18, 19], "mani": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "remot": [0, 2, 7], "user": [0, 2, 4, 5, 13, 14, 19], "It": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 12, 14, 16, 18, 19], "repo2dock": 0, "contain": [0, 1, 3, 4, 7, 8, 10, 11, 12, 13, 16, 18, 19], "imag": [0, 4, 9, 11], "docker": 0, "project": [0, 1, 2, 4, 6, 9], "includ": [0, 1, 4, 7, 9, 10, 11, 13, 14, 18], "configur": [0, 2, 19], "file": [0, 3, 4, 6, 8, 9, 10, 12, 13, 18], "standalon": 0, "local": [0, 4, 19], "laptop": [0, 5], "servic": 0, "freeli": 0, "tutori": [0, 5, 13, 14], "main": [0, 2, 4, 5, 6, 8, 11, 14, 18, 19], "fork": 0, "add": [0, 1, 2, 3, 4, 8, 10, 11, 12, 13, 19], "requir": [0, 1, 2, 3, 4, 9, 12, 13, 14, 19], "credit": 0, "juliett": 0, "taka": 0, "logilab": 0, "opendreamkit": 0, "2017": 0, "In": [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 16, 19], "earlier": 0, "episod": [0, 3, 12, 19], "visual": [0, 1, 5, 6, 13], "matplotlib": [0, 3, 5, 6, 9, 17, 19], "panda": [0, 2, 3, 5, 6, 9, 14, 17, 19], "pd": [0, 1, 2, 4, 13, 19], "pyplot": [0, 2, 4, 19], "plt": [0, 2, 4, 19], "url": [0, 2, 4, 12, 13, 19], "http": [0, 2, 3, 4, 6, 7, 8, 9, 12, 13, 14, 19], "raw": [0, 2, 4, 7, 8, 10, 13, 19], "githubusercont": [0, 2, 4, 7, 13, 19], "com": [0, 2, 4, 7, 9, 13, 19], "plotli": [0, 2, 4], "dataset": [0, 1, 2, 19], "master": [0, 2, 3, 4, 7, 11, 13, 19], "gapminder_with_cod": [0, 2, 4], "csv": [0, 2, 4, 13, 19], "read_csv": [0, 1, 2, 4, 13, 19], "data_2007": [0, 2, 4], "2007": [0, 2, 4], "fig": [0, 2, 4, 19], "ax": [0, 2, 4, 19], "subplot": [0, 2, 4, 19], "scatter": [0, 2, 4], "x": [0, 1, 2, 3, 4, 8, 10, 12, 13, 14, 15, 16, 18, 19], "gdppercap": [0, 2, 4], "y": [0, 1, 2, 3, 4, 8, 10, 12, 13, 14, 15, 19], "lifeexp": [0, 2, 4], "alpha": [0, 2, 4, 13], "0": [0, 1, 2, 3, 4, 6, 8, 10, 11, 12, 13, 14, 15, 16, 18], "set_xscal": [0, 2, 4], "log": 0, "set_xlabel": [0, 2, 4, 19], "gdp": [0, 2, 4], "usd": [0, 2, 4, 13], "per": [0, 2, 4, 8, 14, 15], "capita": [0, 2, 4], "set_ylabel": [0, 2, 4, 19], "life": [0, 2, 4], "expect": [0, 2, 3, 4, 5, 6, 7, 9, 10, 16, 19], "via": [0, 3, 4, 9, 14, 17, 19], "static": [0, 4, 6, 16], "demonstr": [0, 2, 4, 5], "upload": [0, 4, 12, 19], "Then": [0, 2, 4, 7, 9, 13, 14, 15, 18], "look": [0, 2, 3, 4, 6, 8, 9, 10, 11, 12, 13, 14, 18], "render": [0, 4], "txt": [0, 3, 4], "which": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "commit": [0, 4], "push": [0, 4, 8], "also": [0, 2, 4, 5, 12, 13, 16, 19], "visit": [0, 4, 13], "mybind": [0, 4, 14], "org": [0, 2, 4, 6, 8, 9, 12, 13, 17], "copi": [0, 4, 8, 9, 10, 14, 19], "past": [0, 4, 8, 9], "under": [0, 4, 7, 9, 13, 14], "text": [0, 1, 4, 6, 8, 12, 13, 19], "readm": [0, 3, 4, 12], "md": [0, 4, 8, 12], "check": [0, 1, 3, 4, 8, 9, 10, 12, 14, 18, 19], "launch": [0, 4], "badg": [0, 4], "try": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 19], "click": [0, 4, 7, 19], "button": [0, 4, 5, 8, 19], "see": [0, 2, 4, 12, 13, 19], "minut": [0, 4, 13], "two": [0, 1, 3, 4, 8, 9, 10, 12, 13, 14], "expor": [0, 4], "execut": [0, 1, 3, 4, 8, 10, 11, 13, 19], "cloud": [0, 3, 4], "enjoi": [0, 4], "being": [0, 1, 2, 4, 5, 10, 11, 14], "fulli": [0, 4, 19], "gener": [0, 1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 18, 19], "purpos": [0, 8, 18], "access": [0, 3, 4, 13, 15, 19], "built": [0, 2, 4, 12, 19], "oper": [0, 4, 6, 7, 8, 11, 12, 13, 14], "cern": 0, "openair": 0, "research": [0, 1, 3, 5, 6, 7, 9, 12, 13, 19], "archiv": [0, 1, 4], "digit": 0, "identifi": [0, 12, 14], "thei": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18], "everyth": [0, 2, 4, 5, 6, 7, 8, 9, 14, 15, 16, 18, 19], "deposit": [0, 4], "meant": [0, 4, 6], "kept": [0, 4], "long": [0, 1, 3, 4, 7, 9, 11, 13, 18, 19], "term": [0, 1, 2, 4], "therefor": [0, 3, 4, 19], "recommend": [0, 2, 3, 4, 5, 7, 11, 12, 14, 19], "sandbox": [0, 4], "test": [0, 1, 2, 4, 6, 7, 8, 9, 10, 11, 13, 14, 18], "area": [0, 4, 6, 14], "instead": [0, 1, 3, 4, 8, 10, 11, 13, 14, 18, 19], "go": [0, 2, 4, 5, 6, 7, 9, 12, 14, 19], "real": [0, 2, 4, 12], "later": [0, 1, 2, 3, 4, 7, 11, 14], "account": [0, 4, 12], "Be": [0, 2, 3, 4, 5, 8, 9, 10, 16], "awar": [0, 4, 10, 14], "need": [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "author": [0, 1, 4, 6, 9, 12], "applic": [0, 1, 4, 7, 9, 14], "redirect": [0, 4], "back": [0, 1, 4, 9, 11, 13], "choos": [0, 1, 2, 4, 5], "webhook": [0, 4], "drop": [0, 4, 9, 13], "down": [0, 4, 8, 14], "menu": [0, 4, 8, 13, 19], "next": [0, 2, 3, 4, 8, 10, 11, 12, 14], "email": [0, 4], "address": [0, 4], "top": [0, 2, 4, 10, 18, 19], "page": [0, 4, 6, 7, 8, 10, 13, 14, 16, 18, 19], "select": [0, 2, 3, 4, 7, 8, 10, 11, 13, 19], "present": [0, 1, 2, 4, 6, 13], "list": [0, 2, 3, 6, 8, 9, 10, 11, 14, 15, 16], "all": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 19], "repo": [0, 4], "want": [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 16, 19], "toggl": [0, 4], "ou": [0, 4], "reserv": [0, 4], "releas": [0, 4, 8, 9, 14], "trigger": [0, 4], "automat": [0, 2, 4, 9, 14, 19], "download": [0, 4, 6, 13, 19], "zip": [0, 4], "ball": [0, 4], "new": [0, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19], "regist": [0, 4], "should": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 15], "give": [0, 2, 3, 4, 8, 10, 11, 13, 14, 19], "number": [0, 1, 2, 4, 8, 10, 11, 13, 14, 16, 18, 19], "v1": [0, 4, 13], "descript": [0, 4, 7, 8, 12, 14, 18, 19], "time": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 14, 15, 16, 18, 19], "To": [0, 2, 3, 4, 7, 10, 11, 12, 13, 14, 15, 19], "ensur": [0, 4, 5, 6], "set": [0, 2, 3, 4, 7, 11, 13, 16, 19], "correspond": [0, 3, 4, 7, 13], "find": [0, 2, 3, 4, 6, 7, 8, 9, 13, 14, 19], "ad": [0, 4, 12, 13], "edit": [0, 4, 6, 7, 8, 12], "softwar": [0, 3, 4, 6, 8, 9, 11, 12], "fill": [0, 3, 4, 10, 11, 13], "other": [0, 2, 3, 4, 5, 6, 8, 11, 12, 13, 16], "metadata": [0, 1, 4], "manual": [0, 2, 4, 7, 10, 11, 14, 19], "json": [0, 4, 19], "citat": [0, 4, 18], "cff": [0, 4], "infer": [0, 4], "public": [0, 8, 9, 12], "updat": [0, 3, 4, 12, 19], "newli": [0, 3, 4], "rather": [0, 3, 4, 10, 11, 13, 19], "than": [0, 1, 3, 4, 5, 9, 10, 11, 12, 13, 14, 16, 18, 19], "specifi": [0, 3, 4, 12, 14, 19], "when": [0, 1, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 18, 19], "exist": [0, 1, 2, 4, 5, 6, 8, 9, 11, 13, 14, 18, 19], "5281": [0, 4], "3886864": [0, 4], "start": [0, 1, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 19], "shown": [0, 4], "anim": [0, 4], "good": [0, 1, 2, 3, 4, 6, 8, 9, 10, 12, 13, 14, 18, 19], "both": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 13, 14, 15, 19], "how": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "do": [1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "store": [1, 4, 10, 11, 16, 18, 19], "your": [1, 2, 5, 6, 7, 8, 10, 11, 12, 13, 14, 18, 19], "right": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 14], "ar": [1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "clean": 1, "preprocess": [1, 4, 19], "everi": [1, 2, 9, 10, 14, 19], "load": [1, 4, 9, 10, 13, 14], "distinguish": 1, "characterist": 1, "differ": [1, 3, 4, 6, 7, 8, 10, 12, 13, 14, 16, 18, 19], "read": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 16, 18], "varieti": [1, 4, 9, 18, 19], "whenev": [1, 11], "e": [1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 18, 19], "g": [1, 2, 3, 4, 5, 6, 10, 12, 13, 14, 16, 18, 19], "measur": [1, 4, 11, 13, 18], "simul": 1, "result": [1, 2, 3, 4, 8, 9, 10, 11, 14, 15, 18], "ll": [1, 4, 6, 7, 9, 13, 19], "wai": [1, 3, 4, 8, 10, 11, 12, 13, 14, 18, 19], "appli": [1, 8, 11, 13, 14, 15], "re": [1, 4, 6, 8, 9, 10, 13, 15, 19], "memori": [1, 4, 10, 11, 14], "while": [1, 3, 4, 5, 6, 9, 10, 11, 12, 13, 16, 19], "disk": [1, 2, 4, 9, 13], "consid": [1, 4, 5, 9, 10, 14], "randomli": [1, 9], "variou": [1, 2, 4, 6, 12, 16], "column": [1, 4, 10, 11, 13], "np": [1, 2, 4, 10, 11, 13], "n_row": [1, 4, 11], "100000": [1, 4], "datafram": [1, 2, 5, 14], "string": [1, 4, 12, 13, 16, 19], "random": [1, 2, 3, 4, 9, 10, 11, 13, 14, 15, 18], "choic": [1, 3, 4, 6, 13, 14], "appl": [1, 4, 16], "banana": [1, 4, 16], "carrot": [1, 4], "size": [1, 2, 4, 10, 13, 14, 18], "timestamp": [1, 4], "date_rang": [1, 4, 13], "20130101": [1, 4, 13], "period": [1, 4, 13, 19], "freq": [1, 4], "integ": [1, 4, 10, 11, 13, 16], "rang": [1, 3, 4, 8, 10, 14, 15, 16, 19], "10": [1, 2, 8, 9, 10, 11, 13, 14, 15, 18, 19], "float": [1, 4, 10, 11, 16], "uniform": [1, 4], "info": [1, 13], "tidi": 1, "multipl": [1, 4, 10, 11, 13, 14, 15, 16, 19], "collect": [1, 9, 11, 12, 13], "anoth": [1, 2, 3, 4, 5, 9, 10, 12, 13, 16, 19], "n": [1, 2, 4, 8, 10, 11, 12, 14, 15], "1000": [1, 14, 19], "data_arrai": 1, "here": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19], "diment": 1, "one": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19], "contigu": 1, "block": [1, 4, 12, 14, 16, 18], "individu": [1, 7], "mean": [1, 4, 5, 6, 8, 10, 11, 13, 14, 15, 16], "whole": [1, 2, 4, 8, 13, 18], "must": [1, 11], "type": [1, 2, 4, 5, 6, 7, 8, 9, 13, 18, 19], "sourc": [1, 6, 8, 9, 12, 13, 18], "eleg": 1, "scipi": [1, 3, 5, 6, 10, 12, 14], "can": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 18, 19], "keep": [1, 3, 4, 9, 10, 19], "our": [1, 2, 3, 4, 7, 10, 11, 12, 13, 14, 15, 19], "intact": 1, "For": [1, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 16, 18, 19], "support": [1, 4, 7, 9, 13, 14, 18], "chosen": 1, "howev": [1, 2, 3, 5, 13, 14], "through": [1, 4, 5, 7, 10, 11, 13, 14], "librari": [1, 2, 3, 5, 6, 7, 10, 12, 13, 14, 18, 19], "decid": [1, 3, 4, 9, 10, 12], "program": [1, 2, 5, 6, 8, 9, 11, 12, 16, 19], "follow": [1, 3, 4, 6, 7, 8, 11, 12, 13, 14, 16, 18, 19], "There": [1, 2, 3, 4, 5, 8, 10, 12, 13, 14, 19], "case": [1, 3, 4, 6, 8, 10, 11, 13, 14, 16], "standard": [1, 2, 3, 4, 6, 7, 10, 11, 14], "xkcd": 1, "927": 1, "usual": [1, 4, 5, 7, 8, 14, 16], "everybodi": 1, "els": [1, 2, 4, 5, 13, 14, 16], "lead": [1, 19], "field": 1, "certain": [1, 12], "mayb": [1, 4, 10], "reason": [1, 2, 3, 5, 6, 14, 19], "fast": [1, 4, 6, 9, 10, 13, 18], "space": [1, 6, 10], "effici": [1, 5, 6, 10, 11, 13], "easi": [1, 2, 3, 6, 8, 9, 10, 13, 19], "human": 1, "readabl": [1, 19], "enought": 1, "languag": [1, 2, 3, 6, 8, 10, 11, 12, 16, 18], "share": [1, 3, 4, 8, 11, 14], "m": [1, 2, 3, 4, 8, 10, 13, 15], "bad": [1, 4, 9, 11, 12, 14], "ye": [1, 3, 4, 11], "speed": [1, 4, 10, 11, 12, 13, 14], "eas": 1, "great": [1, 2, 4, 8, 9, 14], "ok": [1, 2, 5, 13], "dimension": [1, 2, 4, 10], "anyth": [1, 4, 9, 18], "higher": [1, 9, 14], "best": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 18], "far": [1, 14, 19], "easili": [1, 2, 3, 5, 8, 9, 13, 16, 19], "shareabl": 1, "big": [1, 4, 9, 11], "veri": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 19], "nice": [1, 4, 13, 16, 19], "interfac": [1, 3, 4, 5, 6, 8, 12, 14, 18, 19], "to_csv": [1, 4, 13], "function": [1, 2, 4, 6, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19], "index": [1, 2, 4, 9, 11, 12, 13, 16], "fals": [1, 4, 10], "dataset_csv": [1, 4], "routin": [1, 10, 18], "save": [1, 2, 4, 8, 10, 13, 15], "well": [1, 6, 7, 8, 9, 14, 18, 19], "savetxt": 1, "data_array_csv": 1, "loadtxt": 1, "care": [1, 8, 14], "enough": [1, 4, 5, 6, 10, 13, 14, 16, 19], "decim": [1, 4, 10, 13], "place": [1, 3, 4, 8, 10, 11], "so": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19], "won": [1, 8, 14, 19], "t": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 18, 19], "lose": 1, "precis": [1, 11, 16], "doubl": [1, 11], "16": [1, 4, 10, 11, 14, 19], "normal": [1, 2, 4, 18], "test_numb": 1, "sqrt": [1, 10, 11], "test_fil": 1, "sqrt2": 1, "w": [1, 4], "f": [1, 4, 7, 10, 11, 14, 18], "close": [1, 2, 4, 8, 15], "from": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 16, 18], "r": [1, 2, 3, 4, 10, 11, 12], "test_number2": 1, "float64": [1, 4, 10], "readlin": 1, "calcul": [1, 4, 10, 12, 14, 15, 18], "distanc": [1, 13], "between": [1, 4, 8, 10, 13, 19], "print": [1, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 16, 18], "ab": 1, "avoid": [1, 2, 3, 4, 10, 12, 14], "even": [1, 2, 3, 4, 5, 9, 10, 14, 15, 16, 19], "infal": 1, "whether": [1, 4, 6, 11, 13, 18], "written": [1, 3, 4, 9, 10, 14, 18, 19], "match": [1, 4, 10], "compar": [1, 4, 10, 14, 15, 18, 19], "row": [1, 4, 10, 11, 13], "origin": [1, 4, 6, 9, 10, 11, 13, 19], "last": [1, 3, 4, 8, 10], "sometim": [1, 3, 4, 13, 14], "round": [1, 4, 10, 13], "due": [1, 3, 4, 6, 10, 12], "complex": [1, 16, 19], "technic": [1, 7], "storag": [1, 5, 10], "high": [1, 2, 4, 5, 6, 9, 10, 13, 14], "ineffici": 1, "wise": [1, 11], "repres": [1, 4, 11, 13, 18], "nativ": 1, "suffer": 1, "pyarrow": 1, "pip": [1, 3, 4], "demo": [1, 5, 7, 14], "No": [1, 2, 8], "temporari": 1, "frame": 1, "quickli": [1, 4, 8, 10], "julia": [1, 6, 9], "to_feath": 1, "read_feath": 1, "dataset_feath": 1, "complic": 1, "said": 1, "columnar": [1, 9], "commonli": 1, "machin": [1, 6, 12, 14], "usabl": [1, 4, 9, 12], "c": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 16, 18], "java": 1, "matlab": [1, 2, 10, 18], "to_parquet": 1, "read_parquet": 1, "dataset_parquet": 1, "arbitrari": [1, 11, 16], "bit": [1, 2, 4, 5, 6, 7, 9, 13, 14, 16, 19], "more": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "pytabl": [1, 9], "h5py": [1, 9], "numer": [1, 6, 12, 13], "name": [1, 2, 3, 4, 5, 8, 12, 13, 16, 18, 19], "perform": [1, 4, 6, 10, 11, 13, 14, 18], "larg": [1, 4, 5, 6, 9, 11, 19], "amount": [1, 6, 11], "singl": [1, 4, 6, 10, 11, 12, 13, 16, 19], "especi": [1, 5, 9, 10], "multidimension": [1, 10], "physic": [1, 4, 13], "tabl": [1, 4, 13], "creat": [1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 18, 19], "to_hdf": [1, 4, 13], "h5": [1, 4], "mode": [1, 4, 8], "dataset_hdf5": [1, 4], "read_hdf": [1, 4, 13], "come": [1, 2, 3, 5, 7, 8, 11, 18], "default": [1, 3, 4, 8, 10, 13, 14, 15, 19], "anaconda": [1, 2, 3, 4, 5, 6, 7, 8, 12], "h5_file": 1, "create_dataset": 1, "again": [1, 3, 4, 5, 8, 10, 15], "full": [1, 7, 10, 14, 18], "data_array_h5": 1, "h5netcdf": 1, "often": [1, 2, 3, 4, 5, 6, 9, 10, 12, 13, 14, 16, 19], "faster": [1, 4, 10, 11, 14, 15], "offici": 1, "A": [1, 2, 4, 5, 6, 8, 9, 10, 12, 13, 14], "xarrai": [1, 14], "spatial": 1, "tempor": 1, "dimens": [1, 10, 11], "those": [1, 4, 7, 10, 11, 13, 14], "structur": [1, 2, 4, 9, 10, 12, 13, 19], "relat": [1, 6, 12], "make": [1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19], "to_xarrai": 1, "to_netcdf": 1, "nc": 1, "engin": [1, 9], "xr": 1, "dataset_xarrai": 1, "open_dataset": 1, "dataset_netcdf4": 1, "to_panda": 1, "dataarrai": 1, "data_array_xarrai": 1, "open_dataarrai": 1, "data_array_netcdf4": 1, "to_numpi": 1, "advantag": [1, 11], "z": [1, 4, 10], "tell": [1, 2, 4, 9, 11, 13], "grid": [1, 10], "situat": [1, 4, 9, 14], "As": [1, 3, 7, 9, 11, 12, 13, 14], "further": [1, 6, 12, 13, 14], "temporarili": 1, "data_array_npi": 1, "savez": 1, "npz": 1, "data_array0": 1, "data_array1": 1, "idea": [1, 3, 4, 5, 8, 9, 10, 13, 14], "timeit": [1, 4, 8, 10, 11, 14, 15, 18], "magic": [1, 4, 8, 14, 15], "did": [1, 3, 4, 8, 14], "notic": [1, 4, 9, 10, 14, 15], "doe": [1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 18, 19], "my_arrai": [1, 4], "my_array_npi": [1, 4], "potenti": 1, "lot": [1, 4, 5, 6, 8, 9, 13, 14, 18, 19], "becaus": [1, 4, 7, 8, 10, 11, 13, 14, 15, 18], "charact": 1, "addition": 1, "compress": 1, "much": [1, 2, 4, 5, 6, 8, 9, 12, 13, 14], "alloc": [1, 10], "known": [1, 4, 8, 10, 11], "same": [1, 3, 4, 8, 10, 11, 13, 14, 15, 16, 19], "partial": 1, "larger": [1, 2, 4, 12], "comput": [1, 2, 3, 4, 5, 7, 8, 10, 11, 13, 14, 15, 18, 19], "had": [1, 4, 5, 6, 9, 11], "mb": [1, 11], "571760": 1, "296015": 1, "072096": 1, "202471": 1, "013013": 1, "007742": 1, "820971": 1, "009052": 1, "892181": 1, "037609": 1, "033721": 1, "6": [1, 2, 3, 4, 10, 11, 12, 13, 14, 15], "894043": 1, "073829": 1, "010776": 1, "rel": [1, 2, 4, 9, 12], "poor": [1, 4, 13], "base": [1, 2, 3, 4, 8, 9, 11, 13], "mostli": 1, "shape": [1, 4, 10, 11], "23": [1, 13], "841858": 1, "647893": 1, "639863": 1, "7": [1, 2, 4, 8, 10, 11, 13, 14, 15], "629517": 1, "009885": 1, "002539": 1, "631348": 1, "012877": 1, "002737": 1, "637207": 1, "018905": 1, "009876": 1, "kind": [1, 4, 10, 11, 13, 18], "better": [1, 3, 4, 6, 8, 9, 18, 19], "determin": [1, 16], "solv": [1, 3, 4, 5, 8], "similarli": [1, 10, 13], "previous": [1, 3, 4], "framework": [1, 5, 6, 10], "tool": [1, 2, 3, 5, 6, 8, 10, 13, 14, 19], "specif": [1, 3, 8, 10, 11, 12, 14, 18, 19], "priorit": 1, "initi": [1, 4, 10, 11], "futur": [1, 3, 4, 8, 9, 14], "ve": [1, 4, 14], "procedur": [1, 2], "script": [1, 2, 3, 5, 6, 8, 9, 11, 12], "alwai": [1, 4, 10, 11, 13], "reproduc": [1, 3, 5, 6, 9, 19], "throughout": 1, "code": [1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 18, 19], "turn": [1, 3, 8], "plot": [1, 3, 5, 8, 13, 19], "averag": [1, 4, 13], "head": [1, 4, 8, 13], "onc": [1, 4, 8, 9, 12, 15, 19], "finish": [1, 3, 4, 14], "peopl": [1, 2, 3, 4, 5, 7, 8, 10, 12, 13], "none": [1, 11], "modul": [1, 4, 8, 9, 11, 12, 14, 18, 19], "warn": 1, "debug": [1, 8, 14], "been": [1, 3, 4, 5, 6, 9, 11, 12, 14, 19], "untrust": 1, "riski": 1, "own": [1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 19], "serial": 1, "suit": 1, "variabl": [1, 2, 4, 8, 10, 13, 14, 16, 18], "inspect": [1, 13], "wb": 1, "dump": 1, "rb": 1, "data_array_pickl": 1, "deal": [1, 13], "web": [1, 2, 4, 7, 8, 9, 12, 18], "rest": [1, 2, 4, 5, 8, 10, 16], "api": [1, 4, 5, 11, 13, 14], "rare": [1, 9], "to_json": [1, 13], "read_json": [1, 13], "dataset_json": 1, "layer": [1, 14], "connect": 1, "might": [1, 5, 6, 7, 9, 12, 18], "process": [1, 2, 4, 9, 11, 14, 15, 18, 19], "openpyxl": 1, "quick": [1, 2, 4, 6, 13, 18], "social": 1, "econom": 1, "io": [1, 3, 6, 14], "comparison": [1, 12], "notebook": [1, 2, 3, 7, 8, 9, 10, 12, 13, 14], "don": [1, 4, 5, 6, 7, 8, 9, 13, 14, 16], "plenti": [1, 5], "dedic": 1, "happen": [2, 4, 8, 9, 10, 11, 12, 14], "produc": [2, 4, 9, 11, 12, 13], "prefer": [2, 4, 9], "abl": [2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 16, 19], "simpl": [2, 4, 5, 7, 8, 9, 12, 13, 14, 15, 19], "tweak": 2, "them": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 18, 19], "know": [2, 3, 4, 5, 6, 7, 9, 10, 11, 13, 14, 16, 18], "orient": [2, 4, 6], "v": [2, 4, 7, 8, 10, 18], "help": [2, 4, 5, 8, 19], "clau": 2, "o": [2, 4, 10, 12, 15, 18, 19], "wilk": 2, "fundament": 2, "One": [2, 4, 10, 11, 13, 19], "thing": [2, 3, 4, 5, 6, 8, 9, 10, 12, 14, 18], "i": [2, 3, 4, 5, 7, 11, 12, 13, 14, 15, 16, 18, 19], "over": [2, 4, 5, 9, 10, 11, 13, 16, 19], "autom": [2, 4, 9, 12, 19], "friend": 2, "think": [2, 14, 19], "figur": [2, 4, 8, 18, 19], "autogener": 2, "part": [2, 4, 5, 8, 10, 11, 14], "pipelin": [2, 3], "out": [2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 18, 19], "sent": 2, "printer": 2, "post": [2, 9, 14], "bite": 2, "regener": 2, "50": 2, "dai": [2, 4, 5, 7, 9, 13, 19], "submiss": 2, "deadlin": 2, "left": [2, 4, 6, 7, 8, 10, 11], "perfect": [2, 4, 8, 9], "within": [2, 12, 19], "probabl": [2, 3, 4, 7, 9, 10, 13, 14, 18], "most": [2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 14, 18], "wide": [2, 3, 4, 9, 13], "seaborn": [2, 4, 9, 13], "level": [2, 4, 5, 6, 9, 10, 14], "statist": [2, 4, 9, 13, 18], "altair": [2, 4], "declar": [2, 4], "home": [2, 4, 7, 9], "interact": [2, 4, 5, 8, 12, 14], "graph": [2, 4, 9], "bokeh": [2, 4], "plotnin": [2, 4], "implement": [2, 4, 6, 10, 11, 14, 18], "grammar": [2, 4], "graphic": [2, 4, 7, 9], "ggplot2": [2, 4], "ggplot": [2, 4], "pyngl": [2, 4], "weather": [2, 4, 19], "forecast": [2, 4], "commun": [2, 4, 6, 9, 12, 13, 14], "k3d": [2, 4], "jupyt": [2, 5, 6, 7, 9, 10, 12, 13, 14], "extens": [2, 4, 8, 9, 14], "3d": [2, 4, 9], "famili": [2, 4, 13], "perhap": [2, 9], "build": [2, 5, 9, 11, 18], "feel": [2, 4, 9, 10, 13], "familiar": [2, 3, 4, 5, 6, 16], "abov": [2, 4, 7, 8, 9, 10, 11, 12, 13, 14, 15, 19], "chanc": [2, 10, 13], "somebodi": 2, "knowledg": [2, 11], "adjust": [2, 4, 10, 19], "low": [2, 4, 8, 9, 13, 14], "draw": 2, "abstract": 2, "qualiti": [2, 9], "some": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 16, 18, 19], "line": [2, 4, 5, 6, 8, 10, 12, 13, 14, 18], "strength": 2, "matter": [2, 6], "sinc": [2, 4, 10, 11, 15], "typic": [2, 3, 5, 14, 16], "fit": [2, 14], "But": [2, 3, 4, 5, 6, 8, 9, 10, 13, 14, 18, 19], "run": [2, 3, 5, 7, 11, 12, 13, 15, 19], "u": [2, 4, 11, 13, 14, 18, 19], "method": [2, 4, 7, 9, 10, 13, 14, 18], "displai": [2, 4, 8], "inlin": [2, 4, 8], "en": [2, 4], "wikipedia": [2, 4, 19], "wiki": [2, 4], "anscomb": [2, 4], "27s_quartet": [2, 4], "data_x": [2, 4], "8": [2, 4, 7, 10, 11, 13, 16, 19], "13": [2, 3, 4, 10], "9": [2, 4, 10, 13, 14, 16], "11": [2, 4, 10, 11, 14], "14": [2, 4, 10, 16], "4": [2, 11, 13, 14, 15, 16, 18], "12": [2, 4, 10, 13, 14, 19], "data_i": [2, 4], "04": [2, 4], "95": [2, 4], "58": [2, 4], "81": [2, 4], "33": [2, 4], "96": [2, 4, 13], "24": [2, 4], "26": [2, 4], "84": [2, 4], "82": [2, 4], "68": [2, 4], "e69f00": [2, 4], "label": [2, 4, 19], "axi": [2, 4, 10, 14], "set_titl": [2, 4, 19], "titl": [2, 4, 8, 19], "uncom": [2, 4], "like": [2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 19], "savefig": [2, 4, 19], "png": [2, 4, 19], "server": [2, 7], "without": [2, 4, 6, 7, 9, 10, 11, 12, 13, 14, 15, 16, 19], "cluster": [2, 19], "call": [2, 3, 4, 6, 8, 11, 12, 13, 14, 19], "agg": 2, "valu": [2, 4, 10, 11, 13, 14, 16, 19], "56b4e9": [2, 4], "data2_i": [2, 4], "74": [2, 4], "77": [2, 4, 16], "009e73": [2, 4], "second": [2, 4, 9, 10, 11, 14], "multipli": [2, 4, 10, 11, 18], "element": [2, 4, 10, 11, 14, 16, 18], "data2_y_sc": [2, 4], "legend": [2, 4], "search": [2, 4, 9, 12, 13, 18], "clue": [2, 4], "At": [2, 4, 6, 14], "end": [2, 3, 4, 8, 10, 12, 14, 19], "qualit": 2, "palett": [2, 4], "opim": 2, "vision": 2, "defici": 2, "clauswilk": 2, "dataviz": 2, "pitfal": [2, 8], "html": [2, 4, 6], "okab": 2, "k": 2, "ito": 2, "2008": [2, 6], "univers": [2, 6, 10], "design": [2, 4, 6, 14, 15], "cud": 2, "That": [2, 4, 10], "friendli": 2, "colorblind": 2, "understand": [2, 4, 7, 10, 11, 13, 14, 16, 18, 19], "approach": [2, 3, 4, 6, 12, 14, 19], "though": [2, 4, 7, 12, 14, 15, 16], "dual": 2, "outsid": [2, 4, 8, 12], "scope": [2, 14], "lesson": [2, 4, 5, 6, 7, 8, 9, 11, 13, 14, 16, 19], "modern": [2, 6, 11], "option": [2, 5, 8, 10, 13, 18], "separ": [2, 3, 10, 13, 14, 15, 19], "pass": [2, 4, 9, 10, 14, 19], "around": [2, 4, 7, 11, 13, 14, 18], "tradit": [2, 10], "mimic": 2, "py": [2, 3, 4, 8, 12, 14, 19], "mod": 2, "carri": [2, 10, 14], "global": [2, 4, 14, 18], "xlabel": [2, 4, 19], "ylabel": [2, 4, 19], "internet": [2, 13], "mix": 2, "although": 2, "compact": [2, 13], "wrap": [2, 5, 18], "send": [2, 8, 14], "less": [2, 4, 6, 8, 10, 11], "risk": [2, 9, 14], "chang": [2, 4, 6, 8, 9, 10, 11, 13, 19], "unrel": [2, 8], "modifi": [2, 4, 11, 18, 19], "entir": [2, 14], "latter": 2, "accept": 2, "linear": [2, 4, 11, 18], "yield": 2, "surpris": 2, "introduc": [2, 5, 6], "enhanc": 2, "almost": [2, 6, 9], "aspect": 2, "studi": [2, 8], "cheatsheet": [2, 13, 17], "among": [2, 4, 13], "pre": [2, 19], "defin": [2, 3, 4, 5, 11, 13, 16, 18, 19], "theme": 2, "sheet": 2, "instanc": [2, 3, 4, 6, 12, 14, 16, 19], "either": [2, 3, 4, 5, 7, 8, 12, 13, 14, 19], "input": [2, 4, 5, 8, 10, 11, 14, 15, 19], "imposs": [2, 4, 8], "rememb": [2, 9, 13], "strategi": [2, 4, 8, 14], "mind": 2, "request": [2, 4, 9, 11, 14], "answer": [2, 3, 4, 10, 14, 15], "fetch": [2, 4], "snippet": [2, 4], "overview": [2, 4, 5, 13, 16], "realiz": [2, 4, 14], "ideal": [2, 4], "task": [2, 4, 5, 6, 9, 10, 15, 19], "switch": [2, 4, 8], "arriv": [2, 4], "transpar": [2, 4], "slide": [2, 4], "screen": [2, 4], "onli": [2, 3, 4, 6, 7, 11, 12, 13, 14, 19], "few": [2, 3, 4, 10, 13, 14, 19], "centimet": [2, 4], "inch": [2, 4], "font": [2, 4], "tickmark": [2, 4], "too": [2, 4, 5, 8, 9, 11, 12, 14], "fontsiz": [2, 4], "tick_param": [2, 4], "major": [2, 3, 4, 14], "length": [2, 4, 11], "minor": [2, 4], "labels": [2, 4], "doubt": [2, 4], "brows": [2, 4, 8], "link": [2, 4, 9, 19], "recent": [2, 3, 4, 7, 12], "simpli": [2, 4], "interest": [2, 4, 12, 13, 14], "numpi": [2, 3, 5, 6, 9, 13, 14, 17, 18], "arrai": [2, 4, 6, 9, 11, 13, 14, 18], "dictionari": [2, 4, 13, 16, 19], "feed": [2, 4], "simplifi": [2, 3, 4], "kei": [2, 4, 8, 10], "imagin": [2, 4, 6, 12, 19], "were": [2, 4, 6, 9], "pydata": [2, 4, 17], "And": [2, 4, 6, 11, 12, 13], "caught": [2, 4], "ey": [2, 4, 10], "simple_violinplot": [2, 4], "d": [2, 4, 8, 10, 13, 16, 18], "seem": [2, 3, 4, 9, 18], "sn": [2, 4, 13], "violinplot": [2, 4, 13], "set_them": [2, 4], "across": [2, 4, 14], "sever": [2, 4, 6, 7, 9, 19], "default_rng": [2, 4, 11], "p": [2, 4], "40": [2, 4, 11], "arang": [2, 4, 10, 13], "show": [2, 4, 5, 6, 7, 9, 12, 13, 14, 19], "distribut": [2, 3, 4, 6, 7, 8, 9, 12, 13, 14], "violin": [2, 4], "light": [2, 4], "inner": [2, 4, 13], "h": [2, 4, 11, 16], "reveal": [2, 4], "25146044": [2, 4], "27005437": [2, 4], "78778386": [2, 4], "27832843": [2, 4], "88147169": [2, 4], "76439276": [2, 4], "87844934": [2, 4], "49695422": [2, 4], "59252953": [2, 4], "00342116": [2, 4], "26038963": [2, 4], "15118015": [2, 4], "69725111": [2, 4], "60361933": [2, 4], "22137264": [2, 4], "86174242": [2, 4], "45950762": [2, 4], "32352988": [2, 4], "56724895": [2, 4], "42215312": [2, 4], "34419915": [2, 4], "46123886": [2, 4], "56953795": [2, 4], "95292133": [2, 4], "clutter": [2, 4], "remov": [2, 3, 4], "l1": [2, 4], "l2": [2, 4], "focu": [2, 4], "set_yticklabel": [2, 4], "clarifi": 2, "move": [2, 9, 11, 12], "manuscript": 2, "five": 3, "tensorflow": [3, 9], "get": [3, 4, 5, 6, 7, 9, 10, 11, 14, 15, 16, 18, 19], "me": 3, "colleagu": [3, 7], "conflict": 3, "reus": [3, 4, 14], "relianc": 3, "extern": [3, 5, 6, 12, 14, 18], "compon": [3, 12], "Into": [3, 4], "yml": [3, 4, 7], "why": [3, 4, 5, 10, 11, 14], "ever": [3, 4], "experienc": [3, 4], "popular": [3, 6, 12, 14], "similar": [3, 5, 9, 10, 14, 15, 19], "driven": 3, "channel": [3, 4, 12], "ecosystem": [3, 5, 6], "tradition": 3, "meet": 3, "coupl": 3, "older": [3, 4, 9], "mistak": 3, "someth": [3, 10, 12, 14, 16, 18], "chloe": [3, 4], "team": [3, 4, 6], "quit": [3, 4, 10, 11, 14, 19], "still": [3, 4, 5, 6, 8, 9, 10, 12, 19], "assign": [3, 4, 8], "week": [3, 4, 19], "favorit": [3, 4], "pretti": [3, 4, 9, 18], "old": [3, 4, 5, 6, 8, 9, 13], "otherwis": [3, 4, 16], "fail": [3, 4], "could": [3, 4, 5, 6, 7, 9, 10, 14, 15, 19], "valid": [3, 4], "baselin": [3, 4, 5, 6], "upgrad": [3, 4, 6], "python36": [3, 4], "env": [3, 4, 7, 19], "delet": [3, 4, 8], "navig": [3, 4, 7, 8, 12, 19], "setup": [3, 4, 12], "properli": [3, 4, 11], "encount": [3, 4], "error": [3, 4, 9, 10, 13, 19], "With": [3, 4, 7, 10, 13], "consol": [3, 4], "effect": [3, 4], "__version__": [3, 4, 12], "Or": [3, 4, 7, 9], "liner": [3, 4, 13], "termin": [3, 4, 5, 7, 12, 19], "bash": [3, 4, 8], "deactiv": [3, 4], "sure": [3, 4, 5, 6, 7, 9, 14], "current": [3, 4, 11], "forg": [3, 4, 12], "indic": [3, 4, 10, 11, 13], "argument": [3, 4, 10, 13, 14, 15, 16, 18], "virtualenv": [3, 4, 5], "venv": [3, 4], "scicomp": [3, 4, 7, 8, 19], "virtual": [3, 4, 12], "folder": [3, 4, 12, 19], "locat": [3, 4, 9, 19], "linux": [3, 4, 12], "mac": [3, 4, 12], "osx": [3, 4, 12], "bin": [3, 4, 13, 19], "window": [3, 4, 12], "evolv": 3, "19": [3, 4, 11, 13], "refer": [3, 4, 8, 10, 11, 13, 16], "section": [3, 4, 8, 9, 12], "coderefineri": [3, 7, 8, 9, 19], "03": [3, 19], "myenviron": [3, 4], "freez": [3, 4], "export": [3, 4, 19], "frozen": [3, 4], "tip": [3, 5], "somepackag": 3, "trace": 3, "unless": [3, 4, 8, 9, 10, 14], "attach": 3, "put": [3, 4, 9, 10, 19], "git": [3, 7, 9], "along": [3, 8, 11, 16, 19], "binder": [3, 5, 6, 9], "session": [3, 4, 7, 8, 14], "talk": [3, 6, 9], "express": [3, 9], "pyproject": [3, 12], "toml": [3, 12], "meta": [3, 12], "yaml": [3, 12, 19], "These": [3, 4, 6, 9, 10, 11, 12, 13, 14, 18], "directli": [3, 4, 9, 10, 11, 13, 14, 19], "difficult": [3, 8, 14], "narrowli": 3, "taken": [3, 4, 14], "install_requir": [3, 12], "undefin": [3, 16], "alongsid": 3, "minimum": 3, "maximum": [3, 13], "issu": [3, 9], "consum": 3, "poetri": [3, 12], "pipenv": 3, "altern": [3, 6, 12], "pyenv": 3, "micropipenv": 3, "lightweight": [3, 8], "rule": [3, 4, 11, 18], "resourc": [3, 4, 9, 19], "aalto": [3, 8], "fi": [3, 8], "mainli": 4, "helper": 4, "teach": [4, 5, 6, 7, 8, 9], "event": [4, 13], "cover": [4, 5, 6, 10, 13, 14], "subset": [4, 13, 19], "ipynb": [4, 19], "directori": [4, 8], "cours": [4, 5, 7, 8, 9, 10, 14, 16], "command": [4, 5, 6, 8, 12, 13], "stuff": [4, 8], "done": [4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15], "browser": [4, 7, 8], "non": [4, 5, 8, 10, 18], "editor": [4, 5, 6, 8], "begin": [4, 5, 8, 11], "independ": [4, 8, 12], "trivial": [4, 8, 11], "slightli": [4, 6, 8, 14, 16, 19], "ten": [4, 8], "fibonacci": [4, 8, 13], "markdown": [4, 8, 12], "cell": [4, 8, 10, 13, 14, 15], "bold": [4, 8], "ital": [4, 8], "fastest": [4, 8], "sum": [4, 8, 10, 11, 13, 14, 15], "1000000": [4, 8], "tab": [4, 8, 13], "hint": [4, 8, 13], "thin": [4, 8], "sidebar": [4, 8], "shut": [4, 8], "kernel": [4, 6, 8], "b": [4, 5, 6, 8, 10, 11, 13, 16], "repeat": [4, 8, 10, 11, 19], "increment": [4, 8, 9], "tupl": [4, 8, 10, 16], "new_a": [4, 8], "new_b": [4, 8], "statement": [4, 8, 14, 16], "hand": [4, 8, 18], "comment": [4, 8, 19], "output": [4, 5, 7, 8, 10, 11, 14, 19], "relet": [4, 8], "395": [4, 8], "loop": [4, 8, 10, 15, 16, 19], "std": [4, 8, 13, 15], "dev": [4, 8, 13, 15], "becam": [4, 6, 8], "maintain": [4, 8, 9], "spread": [4, 8], "order": [4, 5, 8, 10, 13], "On": [4, 8], "success": [4, 8], "prevent": [4, 8, 14], "rst": 4, "datatyp": [4, 10], "linspac": [4, 10], "3x2": [4, 10], "int": [4, 10, 11, 14, 16], "astyp": [4, 10], "reshap": [4, 10], "numpyi": [4, 10], "npy": [4, 10], "dtype": [4, 10, 13], "int64": [4, 10, 13], "eg": [4, 10], "zero": [4, 10, 11, 13, 18], "cast": [4, 10], "randint": [4, 10], "matrix": [4, 10, 18], "dot": [4, 10, 12, 18], "leav": [4, 10], "paramet": [4, 10, 13, 19], "elementwis": [4, 10], "enabl": [4, 10, 13], "given": [4, 10, 12, 16, 19], "view": [4, 10, 13], "mere": [4, 10, 11], "henc": [4, 10, 13], "addit": [4, 6, 8, 11, 12, 19], "itself": [4, 8, 10], "ufunc": [4, 10, 11], "id": [4, 5, 10], "third": [4, 10], "return": [4, 10, 11, 12, 13, 14, 15, 16, 18, 19], "wa": [4, 5, 6, 9, 10, 11, 13, 19], "actual": [4, 5, 7, 9, 10, 11, 14, 15, 19], "slower": [4, 10], "10000": [4, 10, 14, 18], "squar": [4, 10, 14, 15], "extra": [4, 7, 10], "revers": [4, 10, 11], "vector": [4, 5, 11, 14, 18], "becom": [4, 5, 6, 9, 10, 11, 19], "2d": [4, 10, 11], "border": [4, 10], "insid": [4, 10, 11], "ceil": [4, 10], "floor": [4, 10], "trunc": [4, 10], "particular": [4, 10, 18], "behav": [4, 10], "neg": [4, 10, 13], "recal": [4, 10], "ident": [4, 10, 14], "sin": [4, 10], "co": [4, 10], "4x4": [4, 10], "equal": [4, 10], "allclos": [4, 10], "1d": [4, 10, 11], "sort": [4, 6, 9, 10], "np_arrai": [4, 10], "question": 4, "indirect": [4, 10], "ones": [4, 7, 10, 11], "combin": [4, 8, 10, 13, 14, 15], "8x4": [4, 10], "content": [4, 8, 10], "bottom": [4, 10, 14], "4x8": [4, 10], "rand": [4, 10, 11, 18], "100": [4, 10, 11, 13], "exactli": [4, 7, 9, 10], "halfwai": [4, 10], "nearest": [4, 10], "posit": [4, 10], "75": [4, 10, 15], "trun": [4, 10], "oo": [4, 10], "s2c2": [4, 10], "argsort": [4, 10], "concaten": [4, 10, 11, 13], "slow": [4, 6, 8, 10, 11, 14, 18], "million": [4, 11], "100000000": [4, 11], "togeth": [4, 6, 11, 14, 17], "beat": [4, 11], "troubl": [4, 11], "complet": [4, 6, 8, 11, 13, 14, 18], "basic": [4, 5, 6, 7, 10, 11, 14, 15, 16, 18], "lession": [4, 11], "continu": [4, 11], "100_000_000": [4, 11], "ravel": [4, 11], "col": [4, 11, 13], "total": [4, 11], "n_col": [4, 11], "appropri": [4, 11], "guid": [4, 6, 11, 13], "desir": [4, 11], "3_465": [4, 11], "18_923": [4, 11], "10_000": [4, 11], "20_000": [4, 11], "69_318_923": [4, 11], "def": [4, 11, 12, 13, 14, 15, 16, 18, 19], "littl": [4, 5, 6, 9, 11], "featur": [4, 9, 11, 13], "stride_trick": [4, 11], "stride": 4, "attribut": [4, 11, 13], "plai": [4, 8, 11, 13], "educ": [4, 6, 11], "transpos": [4, 10], "lib": [4, 11], "as_strid": [4, 11], "000": [4, 11], "obtain": [4, 11, 19], "By": [4, 5, 8, 10, 11, 14, 15, 19], "infinit": [4, 11], "100_000_000_000": [4, 11], "autocomplet": [4, 13], "docstr": [4, 12, 13], "piqu": [4, 13], "ag": [4, 13], "slice": [4, 13], "boolean": [4, 10, 13, 16], "surviv": [4, 13], "rate": [4, 13], "iloc": [4, 13], "loc": [4, 13], "df": [4, 13], "investig": [4, 13], "sibsp": [4, 13], "uniqu": [4, 9, 12, 13, 16], "largest": [4, 13], "histogram": [4, 13], "split": [4, 13, 14, 15], "fare": [4, 13], "lambda": [4, 12, 13], "hist": [4, 13], "fly": [4, 13], "rich": [4, 13], "member": [4, 13], "rwidth": [4, 13], "countri": [4, 13], "receiv": [4, 13], "describ": [4, 6, 12, 13], "borncountrycod": [4, 13], "laureat": [4, 13], "step": [4, 7, 12, 13, 14], "lifespan": [4, 13], "extract": [4, 10, 13, 19], "country1": [4, 13], "country2": [4, 13], "country3": [4, 13], "country4": [4, 13], "borncountri": [4, 13], "isin": [4, 13], "groupbi": [4, 13], "categori": [4, 13], "pivot": [4, 13], "spreadsheet": [4, 13], "count": [4, 13], "pivot_t": [4, 13], "aggfunc": [4, 13], "heatmap": [4, 13], "linewidth": [4, 13], "stick": [4, 13], "swarmplot": [4, 13], "subset_physchem": [4, 13], "chemistri": [4, 13], "catplot": [4, 13], "swarm": [4, 13], "color": 4, "binari": 4, "weather_observ": [4, 19], "weather_data": [4, 19], "jupyterlab": [4, 5, 8, 17, 19], "temperatur": [4, 19], "tapiola": [4, 19], "espoo": [4, 19], "rp5": [4, 19], "kz": [4, 19], "lectur": [4, 19], "haven": [4, 19], "convert": [4, 11, 12, 13, 18, 19], "nbconvert": [4, 19], "python3": [4, 7, 19], "weather_funct": [4, 19], "usr": [4, 19], "utf": [4, 19], "aaltoscicomp": [4, 7, 19], "weather_tapiola": [4, 19], "start_dat": [4, 19], "to_datetim": [4, 13, 19], "01": [4, 18, 19], "06": [4, 19], "2021": [4, 6, 19], "dayfirst": [4, 19], "true": [4, 10, 13, 16, 19], "end_dat": [4, 19], "plot_data": [4, 19], "date": [4, 9, 13, 19], "nto": [4, 19], "observ": [4, 12, 13, 19], "celsiu": [4, 19], "tick": [4, 19], "autofmt_xd": [4, 19], "preced": [4, 19], "argpars": 4, "interv": [4, 10, 18, 19], "januari": [4, 19], "2019": [4, 14, 19], "june": [4, 19], "2020": [4, 6, 10, 19], "octob": [4, 19], "cairo": [4, 19], "weather_cairo": [4, 19], "parser": [4, 19], "argumentpars": [4, 19], "add_argu": [4, 19], "str": [4, 13, 16, 19], "dd": [4, 19], "mm": [4, 19], "yyyi": [4, 19], "arg": [4, 19], "parse_arg": [4, 19], "optionspars": [4, 19], "config": 4, "sy": 4, "argv": [4, 11], "get_paramet": [4, 19], "confg": [4, 19], "data_column": [4, 19], "pars": 4, "relev": [4, 9, 18], "integr": [4, 8, 12], "quad": [4, 12, 18], "vari": [4, 18], "myfunct": [4, 18], "fortran": [4, 5, 6, 9, 10, 11, 14, 18], "quadpack": [4, 18], "assum": [4, 6, 13, 18], "scientif": [4, 5, 9, 10, 14, 18], "doc": [4, 6, 10, 13, 18], "spars": 4, "05": [4, 18, 19], "algebra": [4, 11, 18], "product": [4, 18], "macro": [4, 18], "dens": [4, 18], "thumb": [4, 18], "worth": [4, 11, 18], "represent": [4, 18], "densiti": [4, 18], "csc": [4, 18], "spare": [4, 18], "bsr": [4, 18], "coo": [4, 18], "csr": [4, 18], "matric": 4, "fairli": [4, 18], "lil": [4, 18], "dok": [4, 18], "sai": [4, 5, 9, 10, 11, 13, 16, 18], "insert": [4, 8, 18], "7m": [4, 18], "42m": [4, 18], "1600m": [4, 18], "toarrai": [4, 18], "64m": [4, 18], "time_spars": [4, 18], "matrix2": [4, 18], "time_ful": [4, 18], "3f": [4, 18], "made": [4, 9, 14, 19], "wish": [4, 9], "hackmd": [4, 9], "networkx": [4, 9], "webpag": [4, 5, 9], "footnot": [4, 9], "rkdarst": [4, 9], "pcd": [4, 9], "dftlib": [4, 9], "numgrid": [4, 9], "dynbench": [4, 9], "vpython": [4, 9], "doesn": [4, 6, 7, 9, 10, 14, 15], "fine": [4, 9], "action": [4, 9], "workflow": [4, 9, 14, 19], "green": [4, 9], "correct": [4, 9, 11], "minim": [4, 7, 8, 9, 10], "miss": [4, 5, 7, 9, 13], "clearli": [4, 9, 10, 13], "anymor": [4, 9], "ancient": [4, 9], "pull": [4, 9, 13], "websit": [4, 9], "disappear": [4, 9], "goe": [4, 6, 8, 9, 10, 12, 14], "everyon": [4, 5, 7, 8, 9, 16], "somewher": [4, 9, 11, 13], "improv": [4, 9, 14], "isn": [4, 5, 6, 9], "pi": [4, 14, 15], "stochast": [4, 14, 15], "algorithm": [4, 11, 14, 18], "realli": [4, 5, 6, 14], "worri": [4, 14], "1x1": [4, 14], "fall": [4, 14], "circl": [4, 14], "highlight": [4, 14], "sampl": [4, 8, 14, 15], "trial": [4, 14, 15], "number_in_circl": [4, 14, 15], "n_inside_circl": [4, 14, 15], "up": [4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 18, 19], "pool": [4, 14, 15], "threadpool": [4, 14, 15], "thread": [4, 14], "multithread": 4, "longer": [4, 9, 11, 14], "pure": [4, 10, 12, 14], "simultan": [4, 14], "cpu": [4, 10, 11, 14, 15], "node": [4, 14], "schedul": [4, 14], "permiss": [4, 14], "upset": [4, 14], "slurm": [4, 14], "environ": [4, 5, 8, 9, 12, 14], "slurm_cpus_per_task": [4, 14], "whatev": [4, 7, 8, 13, 14], "hood": [4, 9, 14], "experi": [4, 14, 19], "mpi4pi": [4, 14], "openmpi": [4, 14], "core": [4, 14], "mpiexec": [4, 14], "guess": [4, 14], "comm": [4, 14], "gather": [4, 14], "rank": [4, 10, 14], "_": [4, 14], "n_task": [4, 14], "illustr": [4, 11, 14], "usag": [4, 7, 10, 13, 14], "pypi": [4, 9], "track": 4, "record": [4, 9, 11], "thesi": 4, "isol": [4, 12], "zenodo": 4, "doi": 4, "path": [4, 5, 9, 12], "subtract": [4, 10, 12], "earli": [5, 6], "career": [5, 6, 7], "theoret": [5, 6], "themselv": [5, 6], "aren": [5, 6, 8, 9, 15, 18], "direct": [5, 6], "a2": [5, 6], "hasn": [5, 6], "comprehens": [5, 6, 9], "introduct": [5, 6, 11, 13, 14, 18], "mid": [5, 6], "late": [5, 6], "undergradu": [5, 6], "class": [5, 6, 10, 11, 14], "syntax": [5, 6, 16, 19], "manner": [5, 6, 9], "prerequisit": 5, "watch": [5, 6, 12], "crash": [5, 6], "Not": [5, 13], "multi": [5, 14], "pretend": 5, "fraction": 5, "academ": 5, "intro": [5, 13], "replac": [5, 9, 13], "outlin": 5, "somewhat": [5, 9], "conveni": [5, 7, 19], "easier": [5, 6, 12, 13, 19], "spend": 5, "shell": [5, 7, 8, 19], "advanc": [5, 6, 8, 13, 18], "trick": [5, 11], "principl": 5, "someon": [5, 7], "bore": 5, "appreci": 5, "broadcast": [5, 10], "goal": 5, "concept": [5, 10, 11], "behind": 5, "backbon": 5, "forth": 5, "seen": [5, 11], "format": [5, 6, 8, 9, 10, 13, 18, 19], "common": [5, 7, 9, 10, 11, 13, 14, 16, 18], "bottleneck": [5, 14], "huge": [5, 6, 11], "mess": [5, 12], "tri": 5, "yourself": [5, 6, 7, 9, 11, 19], "break": 5, "scale": [5, 6, 8, 14], "least": [5, 12, 16], "bigger": 5, "pictur": 5, "off": [5, 11], "carefulli": [5, 9], "explain": [5, 10, 12], "super": [5, 11], "short": [5, 6, 9, 13, 16, 19], "ill": 5, "trust": [5, 9], "half": 5, "reusabl": [5, 9], "sustain": 5, "parallel": [5, 6, 19], "materi": [5, 6, 13, 16], "exercis": [5, 6], "fourth": [5, 12], "admin": 5, "manag": [5, 6, 9, 11, 12, 14, 19], "conda": [5, 7], "creation": 5, "prefix": [5, 12], "prepar": [5, 6, 9, 12], "acknowledg": 5, "hopefulli": 5, "tire": 5, "topic": [5, 9, 11], "involv": [5, 11, 14], "explicitli": [5, 19], "object": 6, "util": 6, "toolbox": 6, "broader": [6, 9], "expert": [6, 8], "found": [6, 9], "youtub": 6, "playlist": 6, "prereq": 6, "30": [6, 19], "min": [6, 13], "60": 6, "15": [6, 10, 11], "45": [6, 8], "target": 6, "toward": [6, 12], "learner": [6, 14], "persona": 6, "particularli": [6, 9], "basi": 6, "excel": [6, 13], "glue": 6, "battl": [6, 18], "deep": 6, "embrac": 6, "anybodi": 6, "bother": 6, "acquir": [6, 8], "licens": [6, 12], "extrem": 6, "todai": [6, 11], "certainli": 6, "critic": 6, "offload": 6, "heavi": [6, 11], "lift": [6, 11], "compil": [6, 9, 12, 14, 16, 18], "vectoriz": 6, "luck": 6, "albeit": 6, "matur": 6, "smaller": [6, 10, 11], "suitabl": 6, "rust": [6, 14], "haskel": 6, "came": 6, "septemb": 6, "ignor": 6, "until": [6, 14, 16], "reduc": [6, 14, 15], "transit": 6, "plan": 6, "adopt": 6, "unsupport": 6, "defacto": 6, "activ": [6, 7, 8, 9, 12], "unmaintain": 6, "compat": [6, 9, 10], "jann": [6, 16], "blomqvist": 6, "redesign": 6, "radovan": 6, "bast": 6, "richard": [6, 16], "darst": 6, "ann": [6, 16], "fouilloux": 6, "thor": 6, "wikfeldt": 6, "tester": 6, "advisor": [6, 8], "enrico": 6, "glerean": 6, "carpentri": 6, "conduct": 6, "topic_fold": 6, "polici": 6, "analyt": 6, "encc": 6, "hpda": 6, "logic": 6, "depth": 6, "3": [7, 12, 14, 15, 16, 18], "aanconda": 7, "dure": [7, 16], "init": 7, "proper": [7, 8, 11], "explor": [7, 8, 10, 14], "exact": 7, "lab": [7, 8, 9], "verifi": [7, 11], "1": [7, 15, 16], "hello": [7, 16], "world": [7, 14, 16], "portion": [7, 11], "encourag": 7, "vscode": 7, "launcher": 7, "arrow": 7, "ask": [7, 14], "definit": [7, 11, 16], "hour": 7, "narr": 8, "role": [8, 10], "interleav": 8, "tour": [8, 9], "divid": [8, 10, 14, 15], "appear": 8, "primarili": 8, "bar": [8, 13, 19], "style": [8, 19], "previou": [8, 12, 15, 19], "sentenc": 8, "commonmark": 8, "keyboard": 8, "shortcut": 8, "enter": [8, 12, 13], "esc": 8, "ctrl": 8, "shift": [8, 13], "alt": 8, "cut": 8, "convent": 8, "properti": 8, "runtim": [8, 16], "ipython": [8, 9], "seq": 8, "echo": 8, "Being": 8, "prototyp": [8, 19], "tend": 8, "phase": [8, 15], "stori": 8, "discoveri": 8, "gravit": 8, "wave": 8, "barrier": 8, "promot": 8, "modular": [8, 19], "hard": [8, 11, 19], "migrat": 8, "unit": 8, "nbval": 8, "control": [8, 10, 11, 14], "nbdime": 8, "limit": 8, "irreproduc": 8, "bunch": 8, "organ": [8, 9, 19], "downsid": 8, "balanc": 8, "power": [8, 10, 13], "beyond": [9, 14], "necessarili": 9, "fact": [9, 13], "heard": 9, "quot": 9, "classifi": [9, 12], "articl": [9, 13, 18], "noth": [9, 12], "conform": 9, "math": [9, 18], "mayavi": 9, "pil": 9, "manipul": [9, 11], "pillow": 9, "statsmodel": 9, "sympi": 9, "symbol": [9, 10], "network": 9, "hdf5": 9, "dateutil": 9, "pytz": 9, "arithmet": [9, 10], "handl": [9, 10, 13, 14], "timezon": 9, "databas": 9, "convers": [9, 19], "nicer": 9, "interpret": [9, 11, 14], "hub": 9, "pytest": 9, "sphinx": 9, "spyder": 9, "pympi": 9, "messag": [9, 12, 14], "mpi": 9, "job": [9, 14], "cython": 9, "numba": 9, "intern": [9, 10], "optim": [9, 11, 14, 18], "dask": 9, "joblib": 9, "embarrassingli": [9, 14], "ipyparallel": 9, "numexpr": 9, "irrelev": 9, "pytorch": 9, "nltk": 9, "natur": [9, 10], "scikit": [9, 14, 17], "predict": 9, "thu": [9, 10, 13, 18], "contribut": [9, 13], "extend": [9, 10], "slowli": 9, "embed": 9, "primari": 9, "cffi": [9, 14], "ctype": [9, 14], "f2py": 9, "swig": 9, "boost": 9, "todo": 9, "mainstream": 9, "undetect": 9, "perman": 9, "host": [9, 12], "site": 9, "gitlab": 9, "bitbucket": 9, "dealt": 9, "bug": [9, 19], "report": [9, 19], "citeabl": 9, "upcom": 9, "anyon": [9, 12], "seamlessli": 9, "detail": [9, 12, 13, 14, 18, 19], "except": 9, "seach": 10, "flexibl": 10, "asdf": 10, "background": [10, 14], "500": 10, "empti": 10, "len": 10, "ndarrai": 10, "2x3": 10, "1x2": 10, "2x2": 10, "evenli": 10, "bool": [10, 16], "occas": 10, "special": [10, 11, 12, 13, 15, 18], "instruct": [10, 11, 12], "greatli": 10, "outperform": 10, "regular": 10, "unlik": [10, 13], "mathemat": [10, 11, 18], "condit": [10, 16], "clever": [10, 11], "cleverli": 10, "selector": 10, "benefit": [10, 19], "middl": [10, 11], "idx": 10, "criterion": 10, "three": [10, 13, 14], "ref": 10, "smart": 10, "consist": [10, 11, 12], "expand": 10, "max": [10, 13], "countless": 10, "invent": 10, "reli": 10, "bla": 10, "lapack": 10, "scientist": 10, "peculiar": 10, "underli": 11, "machineri": 11, "intend": 11, "indend": 11, "audienc": 11, "amaz": 11, "impract": 11, "seriou": 11, "yet": [11, 12], "dive": 11, "scene": 11, "serv": [11, 14], "travi": 11, "oliph": 11, "creator": [11, 12], "race": 11, "against": [11, 19], "contest": 11, "stdlib": 11, "stdio": 11, "n_element": 11, "argc": 11, "char": 11, "malloc": 11, "sizeof": 11, "rand_max": 11, "printf": 11, "outsourc": 11, "subprogram": 11, "1979": 11, "effort": [11, 14], "word": 11, "norm": 11, "pythagorean": 11, "theorem": 11, "ldot": 11, "naiv": 11, "decent": 11, "rng": 11, "seed": 11, "l": [11, 16], "linalg": 11, "expens": [11, 19], "cheap": 11, "surprisingli": 11, "closer": 11, "datastructur": 11, "flat": 11, "fake": 11, "unravel": 11, "implic": 11, "skip": [11, 19], "64": [11, 12, 13], "13440": 11, "2688": 11, "448": 11, "byte": [11, 16], "ahead": 11, "boi": 11, "diagon": 11, "20": 11, "nbyte": 11, "nanosecond": 11, "1600": 11, "160000": 11, "accomplish": 11, "80000": 11, "40_000": 11, "5_000": 11, "40000": 11, "laid": 11, "inevit": 11, "transposit": 11, "ntranspos": 11, "construct": 11, "stai": 11, "pointer": 11, "buffer": 11, "deriv": [11, 19], "__array_interface__": 11, "virtu": 11, "offset": 11, "48": 11, "affect": 11, "attempt": 11, "succe": 11, "layout": [11, 13], "25": [11, 13, 14], "grow": 12, "cake": 12, "concret": 12, "lower_limit": 12, "upper_limit": 12, "__init__": [12, 16], "hold": 12, "arrang": 12, "root": [12, 14], "setuptool": 12, "fh": 12, "long_descript": 12, "adapt": [12, 19], "mynam": 12, "firstnam": 12, "lastnam": 12, "author_email": 12, "long_description_content_typ": 12, "find_packag": 12, "osi": 12, "approv": 12, "mit": 12, "python_requir": 12, "pin": 12, "ana": 12, "twine": 12, "sdist": 12, "testpypi": 12, "dist": 12, "legaci": 12, "usernam": 12, "password": 12, "solut": 12, "achiev": [12, 19], "confus": 12, "trend": 12, "flit": 12, "simplest": 12, "runtest": 12, "toler": 12, "recip": 12, "sh": 12, "bld": 12, "bat": 12, "anaconda3": 12, "win": 12, "py38_0": 12, "tar": 12, "bz2": 12, "sub": [12, 13], "platform": 12, "successfulli": 12, "anywher": 12, "led": 12, "infrastructur": 12, "guidelin": 12, "respect": [12, 13], "bioconda": 12, "bioinformat": 12, "brief": 13, "train": 13, "flash": 13, "thorough": 13, "cookbook": 13, "flavor": 13, "kaggl": 13, "competit": 13, "index_col": 13, "ticket": 13, "sibl": 13, "spous": 13, "29": 13, "price": 13, "512": 13, "38": 13, "didn": 13, "figsiz": 13, "zorder": 13, "sharex": 13, "hit": 13, "twice": 13, "offer": [13, 16], "mark": 13, "saw": 13, "tabular": 13, "compos": 13, "passang": 13, "datafil": 13, "lam": 13, "mr": 13, "ali": 13, "42": [13, 16], "iat": 13, "foo": 13, "70": 13, "margaret": 13, "nan": 13, "forward": 13, "backward": 13, "isna": 13, "mask": 13, "dropna": 13, "cabin": 13, "fillna": 13, "ffill": 13, "straightforward": 13, "thank": 13, "untidi": 13, "1500": 13, "runner": [13, 14], "400": 13, "800": 13, "128": 13, "1200": 13, "192": 13, "240": 13, "80": 13, "160": 13, "300": 13, "288": 13, "360": 13, "ran": 13, "pair": 13, "melt": 13, "id_var": 13, "value_var": 13, "var_nam": 13, "value_nam": 13, "filter": 13, "aggreg": 13, "model": [13, 14], "relationship": 13, "opposit": 13, "exposit": 13, "read_excel": 13, "to_excel": 13, "scratch": 13, "randn": 13, "abcd": 13, "int32": 13, "append": 13, "sub1": 13, "sub2": 13, "sub3": 13, "concat": 13, "merg": 13, "act": 13, "sql": 13, "athlet": 13, "18": 13, "21": 13, "annot": 13, "entri": 13, "dave": 13, "women": 13, "children": 13, "child": 13, "younger": 13, "sex": 13, "chose": 13, "summar": 13, "cumsum": 13, "median": 13, "skew": 13, "var": 13, "wouldn": [13, 14], "abil": 13, "nobelpr": 13, "born": 13, "di": 13, "datetim": 13, "coerc": 13, "messi": 13, "dt": 13, "weekdai": 13, "approxim": [13, 14], "365": 13, "boxplot": 13, "functool": 13, "lru_cach": 13, "fib": 13, "rais": 13, "notimplementederror": 13, "elif": [13, 16], "rabbit": 13, "processor": 14, "mechan": 14, "profil": 14, "spot": 14, "hardwar": 14, "supercomput": 14, "synchron": 14, "state": 14, "openmp": 14, "segment": 14, "simpler": 14, "anywai": 14, "wrong": 14, "unexpect": 14, "fascin": 14, "invest": 14, "video": 14, "raymond": 14, "hetting": 14, "entertain": 14, "lock": 14, "glanc": 14, "shouldn": 14, "unix": 14, "embark": 14, "oppos": 14, "difficulti": 14, "map": [14, 15], "paradigm": 14, "36": 14, "equival": 14, "introductori": 14, "rantahar": 14, "pdc": 14, "blog": 14, "gentl": 14, "www": 14, "kth": 14, "se": 14, "08": 14, "comm_world": 14, "get_siz": 14, "get_rank": 14, "t0": 14, "perf_count": 14, "pi_estim": 14, "nnumber": 14, "dart": 14, "estim": 14, "spent": 14, "workaround": 14, "foreign": 14, "primit": 14, "pybind11": 14, "iso_c_bind": 14, "pyo3": 14, "rout": 14, "Of": 14, "overcom": 14, "ml": 14, "piec": 14, "chunk": 14, "delai": 14, "lazi": 14, "proce": 14, "stream": 14, "fashion": 14, "da": 14, "redund": 14, "concurr": [14, 19], "safe": 14, "highli": 14, "luckili": 14, "474": 15, "141252": 15, "305": 15, "52": 15, "n_sum": 15, "n_inside_circle_sum": 15, "141344": 15, "498": 15, "34": 15, "timeitresult": 15, "14156": 15, "regardless": 15, "perfectli": 16, "engag": 16, "3j": 16, "unicod": 16, "q": 16, "capabl": 16, "123": 16, "456": 16, "cherri": 16, "dict": [16, 19], "met": 16, "sequenc": 16, "iter": 16, "enumer": 16, "ii": 16, "keyword": 16, "self": 16, "_name": 16, "strongli": [16, 19], "dynam": 16, "strong": 16, "roughli": 16, "circumv": 16, "invok": 16, "behavior": 16, "redefin": 16, "jargon": 16, "associ": 16, "rvalu": 16, "lvalu": 16, "reifi": 16, "datacamp": 17, "briefli": 18, "bessel": 18, "gamma": 18, "interpol": 18, "fourier": 18, "transform": 18, "fft": 18, "signal": 18, "market": 18, "mat": 18, "ridicul": 18, "standpoint": 18, "unknown": 18, "somedai": 18, "eventu": 18, "admit": 18, "streamlin": 19, "hardli": 19, "willing": 19, "suppos": 19, "rerun": 19, "parameter": 19, "papermil": 19, "attract": 19, "soon": 19, "forc": 19, "your_notebook_nam": 19, "cannot": 19, "output_file_nam": 19, "31": 19, "spring_in_tapiola": 19, "brittl": 19, "robust": 19, "doctopt": 19, "filenam": 19, "temperature_tapiola": 19, "temperature_tapiola_dec": 19, "28": 19, "temperature_tapiola_feb": 19, "temperature_cairo": 19, "pattern": 19, "got": 19, "rain_in_tapiola": 19, "rainfal": 19, "rrr": 19, "scroll": 19, "inconveni": 19, "unnecessari": 19, "precipit": 19, "translat": 19, "rain_in_cairo": 19, "jupytext": 19}, "objects": {}, "objtypes": {}, "objnames": {}, "titleterms": {"binder": [0, 4], "question": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "object": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "why": [0, 2, 6, 8, 19], "i": [0, 1, 6, 8, 9, 10], "sometim": 0, "enough": 0, "share": [0, 12], "your": [0, 3, 4, 9], "code": [0, 8, 9], "exercis": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 18, 19], "1": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 18, 19], "10": [0, 4], "min": [0, 2, 3, 4], "comput": [0, 6, 9], "environ": [0, 3, 7], "demo": [0, 4, 12], "make": [0, 4], "notebook": [0, 4, 19], "reproduc": [0, 2, 4], "anyon": [0, 4], "15": [0, 2, 3, 4], "how": [0, 3], "can": [0, 11], "get": [0, 2, 8, 13], "doi": 0, "from": [0, 12, 14, 19], "zenodo": 0, "3": [0, 1, 2, 3, 4, 6, 8, 10, 11, 13, 19], "option": [0, 3, 4, 7, 14, 19], "creat": [0, 3, 10], "link": 0, "4": [0, 1, 3, 4, 10, 19], "keypoint": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 18], "data": [1, 2, 4, 9, 11, 13], "format": [1, 4], "panda": [1, 4, 13], "numpi": [1, 4, 10, 11], "what": [1, 8, 9, 10, 13, 18], "look": 1, "file": [1, 7, 19], "us": [1, 18, 19], "some": 1, "most": 1, "popular": 1, "csv": 1, "comma": 1, "separ": 1, "valu": 1, "kei": 1, "featur": 1, "feather": 1, "parquet": 1, "hdf5": 1, "hierarch": 1, "version": [1, 3], "5": [1, 4, 10], "netcdf4": 1, "network": 1, "common": 1, "form": 1, "npy": 1, "arrai": [1, 10], "solut": [1, 2, 4, 8, 10, 11, 13, 14, 15, 18, 19], "2": [1, 2, 3, 4, 6, 8, 9, 10, 11, 13, 14, 18, 19], "benefit": 1, "binari": 1, "thing": [1, 11], "rememb": 1, "other": [1, 7, 9, 10, 14, 19], "pickl": 1, "json": 1, "javascript": 1, "notat": 1, "excel": 1, "see": [1, 3, 6, 7, 8, 9, 10, 11, 14, 18], "also": [1, 3, 6, 7, 8, 9, 10, 11, 14, 18], "visual": [2, 4], "matplotlib": [2, 4], "repeat": 2, "ar": 2, "we": 2, "start": [2, 8], "extend": [2, 4], "previou": [2, 4], "exampl": [2, 4, 11, 14], "color": 2, "ha": 2, "two": 2, "differ": 2, "interfac": [2, 9], "do": [2, 3, 15], "emphas": 2, "thi": 2, "style": 2, "custom": [2, 4], "plot": [2, 4, 9], "log": [2, 4], "scale": [2, 4], "prepar": [2, 4], "public": [2, 3, 4], "adapt": [2, 4], "galleri": [2, 4], "an": [2, 4, 7, 10, 11], "explor": [2, 4, 13], "discuss": [2, 19], "depend": [3, 4], "manag": [3, 4], "you": 3, "track": 3, "project": [3, 12], "pypi": [3, 12], "The": [3, 9, 11], "python": [3, 6, 7, 9, 12, 15, 16, 19], "packag": [3, 4, 9, 12], "index": [3, 10], "ana": 3, "conda": [3, 4, 12], "isol": 3, "activ": [3, 4], "versu": [3, 4, 11], "sourc": [3, 4], "remark": [3, 4, 12], "record": 3, "commun": 3, "part": 3, "report": 3, "thesi": 3, "pin": 3, "creator": 3, "list": [4, 7, 13, 19], "full": 4, "jupyt": [4, 8, 19], "advanc": [4, 7, 10, 11, 14], "datafram": [4, 13], "analyz": [4, 13], "titan": [4, 13], "passeng": [4, 13], "dataset": [4, 13], "nobel": [4, 13], "prize": [4, 13], "script": [4, 19], "scipi": [4, 9, 18], "librari": [4, 9, 11], "ecosystem": [4, 9], "work": [4, 9, 13], "evalu": [4, 9], "parallel": [4, 9, 14, 15], "program": [4, 14], "multiprocess": [4, 14, 15], "run": [4, 8, 14], "cluster": [4, 14], "mpi": [4, 14], "dask": [4, 14], "instructor": 5, "": [5, 9, 13, 18], "guid": 5, "learner": 5, "persona": 5, "about": 5, "each": 5, "section": 5, "scientif": 6, "attend": 6, "cours": 6, "22": 6, "25": 6, "novemb": 6, "2022": 6, "prerequisit": [6, 12], "video": [6, 7], "refer": [6, 17], "who": 6, "motiv": 6, "v": 6, "credit": 6, "softwar": 7, "instal": [7, 12], "gener": 7, "tool": [7, 9, 12], "requir": 7, "instruct": 7, "miniconda": 7, "jupyterlab": 7, "verif": 7, "watch": 7, "text": 7, "editor": 7, "command": [7, 19], "line": [7, 19], "wai": 7, "access": 7, "zoom": 7, "need": 7, "help": [7, 13], "glossari": 9, "core": 9, "numer": [9, 18], "analysi": 9, "import": [9, 19], "interact": 9, "human": 9, "speed": 9, "up": 9, "machin": 9, "learn": 9, "connect": 9, "languag": [9, 14], "reus": 9, "reuseabl": 9, "next": 9, "math": 10, "vector": 10, "slice": 10, "type": [10, 16], "oper": 10, "linear": 10, "algebra": 10, "addit": 10, "realli": 11, "fast": 11, "behind": 11, "curtain": 11, "bla": 11, "tri": 11, "avoid": 11, "copi": 11, "ndarrai": 11, "expos": 11, "stride": 11, "matrix": 11, "transpos": 11, "anoth": 11, "reshap": 11, "A": 11, "view": 11, "organ": 12, "test": 12, "local": 12, "pip": 12, "via": 12, "simplifi": 12, "build": 12, "skeleton": 12, "locat": 12, "scratch": 12, "publish": 12, "tidi": 13, "time": 13, "seri": 13, "superpow": 13, "beyond": 13, "basic": 13, "mode": 14, "multithread": [14, 15], "gil": 14, "coupl": 14, "task": 14, "queue": 14, "org": 14, "thread": 15, "futur": 15, "idea": 15, "introduct": 16, "scalar": 16, "collect": 16, "control": 16, "structur": 16, "function": 16, "class": 16, "system": 16, "quick": 17, "integr": 18, "spars": 18, "matric": 18, "save": 19, "argument": 19, "sy": 19, "argv": 19, "pars": 19, "argpars": 19, "load": 19, "larger": 19, "config": 19, "further": 19, "read": 19}, "envversion": {"sphinx.domains.c": 2, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 8, "sphinx.domains.index": 1, "sphinx.domains.javascript": 2, "sphinx.domains.math": 2, "sphinx.domains.python": 3, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.todo": 2, "sphinx.ext.intersphinx": 1, "sphinx": 57}, "alltitles": {"Binder": [[0, "binder"], [4, "binder"]], "Questions": [[0, "questions-0"], [1, "questions-0"], [2, "questions-0"], [3, "questions-0"], [8, "questions-0"], [9, "questions-0"], [10, "questions-0"], [11, "questions-0"], [12, "questions-0"], [13, "questions-0"], [14, "questions-0"], [16, "questions-0"], [18, "questions-0"], [19, "questions-0"]], "Objectives": [[0, "objectives-0"], [1, "objectives-0"], [2, "objectives-0"], [3, "objectives-0"], [8, "objectives-0"], [9, "objectives-0"], [10, "objectives-0"], [11, "objectives-0"], [12, "objectives-0"], [13, "objectives-0"], [14, "objectives-0"], [16, "objectives-0"], [18, "objectives-0"], [19, "objectives-0"]], "Why is it sometimes not enough to share your code?": [[0, "why-is-it-sometimes-not-enough-to-share-your-code"]], "Exercise 1": [[0, "exercise-1"], [1, "exercise-1"], [11, "exercise-1"]], "Binder-1 (10 min)": [[0, "exercise-0"], [4, "exercise-0"]], "Sharing a computing environment with Binder": [[0, "sharing-a-computing-environment-with-binder"]], "Binder exercise/demo": [[0, "binder-exercise-demo"]], "Exercise/demo: Making your notebooks reproducible by anyone (15 min)": [[0, "exercise-1"], [4, "exercise-1"]], "How can I get a DOI from Zenodo?": [[0, "how-can-i-get-a-doi-from-zenodo"]], "Binder-3 (optional)": [[0, "exercise-2"], [4, "exercise-2"]], "Create a Binder link for your Zenodo DOI": [[0, "create-a-binder-link-for-your-zenodo-doi"]], "Binder-4 (10 min)": [[0, "exercise-3"], [4, "exercise-3"]], "Keypoints": [[0, "keypoints-0"], [1, "keypoints-0"], [2, "keypoints-0"], [3, "keypoints-0"], [8, "keypoints-0"], [9, "keypoints-0"], [10, "keypoints-0"], [11, "keypoints-0"], [12, "keypoints-0"], [13, "keypoints-0"], [14, "keypoints-0"], [16, "keypoints-0"], [18, "keypoints-0"]], "Data formats with Pandas and Numpy": [[1, "data-formats-with-pandas-and-numpy"], [4, "data-formats-with-pandas-and-numpy"]], "What is a data format?": [[1, "what-is-a-data-format"]], "What to look for in a file format?": [[1, "what-to-look-for-in-a-file-format"]], "Using some of the most popular file formats": [[1, "using-some-of-the-most-popular-file-formats"]], "CSV (comma-separated values)": [[1, "csv-comma-separated-values"]], "Key features": [[1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null]], "Feather": [[1, "feather"]], "Parquet": [[1, "parquet"]], "HDF5 (Hierarchical Data Format version 5)": [[1, "hdf5-hierarchical-data-format-version-5"]], "NetCDF4 (Network Common Data Form version 4)": [[1, "netcdf4-network-common-data-form-version-4"]], "npy (numpy array format)": [[1, "npy-numpy-array-format"]], "Exercise": [[1, "exercise-0"], [1, "exercise-1"], [1, "exercise-2"], [4, "exercise-0"], [4, "exercise-1"], [4, "exercise-2"], [4, "exercise-0"], [4, "exercise-1"], [18, "exercise-0"], [18, "exercise-1"]], "Solution": [[1, "solution-0"], [1, "solution-1"], [1, "solution-2"], [2, "solution-0"], [2, "solution-1"], [2, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [13, "solution-0"], [13, "solution-1"], [14, "solution-0"], [14, "solution-1"], [18, "solution-0"], [18, "solution-1"], [19, "solution-0"], [19, "solution-1"], [19, "solution-2"]], "Exercise 2": [[1, "exercise-2"], [11, "exercise-2"]], "Exercise 3": [[1, "exercise-3"]], "Benefits of binary file formats": [[1, "benefits-of-binary-file-formats"]], "Things to remember": [[1, "things-to-remember"]], "Other file formats": [[1, "other-file-formats"]], "Pickle": [[1, "pickle"]], "JSON (JavaScript Object Notation)": [[1, "json-javascript-object-notation"]], "Excel (binary)": [[1, "excel-binary"]], "See also": [[1, "see-also"], [3, "see-also"], [6, "see-also"], [7, "see-also"], [8, "see-also"], [9, "see-also"], [10, "see-also"], [11, "see-also"], [14, "see-also"], [18, "see-also"]], "Data visualization with Matplotlib": [[2, "data-visualization-with-matplotlib"], [4, "data-visualization-with-matplotlib"]], "Repeatability/reproducibility": [[2, "repeatability-reproducibility"]], "Why are we starting with Matplotlib?": [[2, "why-are-we-starting-with-matplotlib"]], "Getting started with Matplotlib": [[2, "getting-started-with-matplotlib"]], "Exercise: Matplotlib": [[2, "exercise-matplotlib"]], "Exercise Matplotlib-1: extend the previous example (15 min)": [[2, "exercise-0"], [4, "exercise-0"]], "Why these colors?": [[2, "discussion-0"]], "Matplotlib has two different interfaces": [[2, "matplotlib-has-two-different-interfaces"]], "Why do we emphasize this?": [[2, "discussion-1"]], "Styling and customizing plots": [[2, "styling-and-customizing-plots"]], "Exercises: Styling and customization": [[2, "exercises-styling-and-customization"]], "Exercise Customization-1: log scale in Matplotlib (15 min)": [[2, "exercise-1"], [4, "exercise-1"]], "Exercise Customization-2: preparing a plot for publication (15 min)": [[2, "exercise-2"], [4, "exercise-2"]], "Exercise Customization-3: adapting a gallery example": [[2, "exercise-3"], [4, "exercise-3"]], "An example exploration": [[2, "solution-3"], [4, "solution-3"]], "Discussion": [[2, "discussion-2"], [19, "discussion-0"], [19, "discussion-1"]], "Dependency management": [[3, "dependency-management"], [4, "dependency-management"]], "How do you track dependencies of your project?": [[3, "how-do-you-track-dependencies-of-your-project"]], "Exercises 1": [[3, "exercises-1"], [8, "exercises-1"], [10, "exercises-1"], [12, "exercises-1"], [13, "exercises-1"], [19, "exercises-1"]], "Dependencies-1 (15 min)": [[3, "exercise-0"], [4, "exercise-0"]], "PyPI (The Python Package Index) and (Ana)conda": [[3, "pypi-the-python-package-index-and-ana-conda"]], "Creating isolated environments": [[3, "creating-isolated-environments"]], "Exercises 2": [[3, "exercises-2"], [8, "exercises-2"], [10, "exercises-2"], [13, "exercises-2"], [19, "exercises-2"]], "Dependencies-2 (15 min)": [[3, "exercise-1"], [4, "exercise-1"]], "conda activate versus source activate": [[3, "callout-0"], [4, "callout-0"]], "Remark": [[3, "callout-1"], [4, "callout-1"], [12, "callout-1"]], "Exercises 3": [[3, "exercises-3"], [8, "exercises-3"], [10, "exercises-3"], [11, "exercises-3"], [13, "exercises-3"], [19, "exercises-3"]], "Dependencies-3 (15 min, optional)": [[3, "exercise-2"], [4, "exercise-2"]], "Recording dependencies": [[3, "recording-dependencies"]], "Dependencies 4": [[3, "dependencies-4"]], "Dependencies-4 (15 min)": [[3, "exercise-3"], [4, "exercise-3"]], "How to communicate the dependencies as part of a report/thesis/publication": [[3, "how-to-communicate-the-dependencies-as-part-of-a-report-thesis-publication"]], "Version pinning for package creators": [[3, "version-pinning-for-package-creators"]], "List of exercises": [[4, "list-of-exercises"]], "Full list": [[4, "full-list"]], "Jupyter": [[4, "jupyter"], [8, "jupyter"]], "Exercises: Jupyter-1": [[4, "exercise-0"], [8, "exercise-0"]], "Exercises: Jupyter-2": [[4, "exercise-1"], [8, "exercise-1"]], "Solutions: Jupyter-2": [[4, "solution-0"], [8, "solution-0"]], "Exercises: Jupyter-3": [[4, "exercise-2"], [8, "exercise-2"]], "NumPy": [[4, "numpy"], [10, "numpy"]], "Exercises: Numpy-1": [[4, "exercise-0"], [10, "exercise-0"]], "Solutions: Numpy-1": [[4, "solution-0"], [10, "solution-0"]], "Exercises: Numpy-2": [[4, "exercise-1"], [10, "exercise-1"]], "Solutions: Numpy-2": [[4, "solution-1"], [10, "solution-1"]], "Exercise: Numpy-3": [[4, "exercise-2"], [10, "exercise-2"]], "Solution: Numpy-3": [[4, "solution-2"], [10, "solution-2"]], "Exercises: Numpy-4": [[4, "exercise-3"], [10, "exercise-3"]], "Solution: Numpy-4": [[4, "solution-3"], [10, "solution-3"]], "Numpy-5": [[4, "exercise-4"], [10, "exercise-4"]], "Solution Numpy-5": [[4, "solution-4"], [10, "solution-4"]], "Advanced NumPy": [[4, "advanced-numpy"], [11, "advanced-numpy"]], "Exercises: Numpy-Advanced-1": [[4, "exercise-0"], [11, "exercise-0"]], "Solutions: Numpy-Advanced-2": [[4, "solution-0"], [4, "solution-1"], [11, "solution-0"], [11, "solution-1"]], "Exercises: Numpy-Advanced-2": [[4, "exercise-1"], [11, "exercise-1"]], "Exercises: Numpy-Advanced-3": [[4, "exercise-2"], [11, "exercise-2"]], "Solutions: Numpy-Advanced-3": [[4, "solution-2"], [11, "solution-2"]], "Pandas": [[4, "pandas"], [13, "pandas"]], "Exploring dataframes": [[4, "exercise-0"], [13, "exercise-0"]], "Analyze the Titanic passenger list dataset": [[4, "exercise-1"], [13, "exercise-1"]], "Analyze the Nobel prize dataset": [[4, "exercise-2"], [13, "exercise-2"]], "Scripts": [[4, "scripts"], [19, "scripts"]], "Scripts-1": [[4, "exercise-0"], [19, "exercise-0"]], "Scripts-2 (optional)": [[4, "exercise-1"], [19, "exercise-1"]], "Scripts-3": [[4, "exercise-2"], [19, "exercise-2"]], "Scripts-4": [[4, "exercise-3"], [19, "exercise-3"]], "SciPy": [[4, "scipy"], [18, "scipy"]], "Library ecosystem": [[4, "library-ecosystem"], [9, "library-ecosystem"]], "Libraries 1.1: Libraries in your work": [[4, "exercise-0"], [9, "exercise-0"]], "Libraries 1.1": [[4, "solution-0"], [9, "solution-0"]], "Libraries 1.2: Evaluating packages": [[4, "exercise-1"], [9, "exercise-1"]], "Libraries 1.2": [[4, "solution-1"], [9, "solution-1"]], "Parallel programming": [[4, "parallel-programming"], [14, "parallel-programming"]], "Parallel-1, multiprocessing": [[4, "exercise-0"], [14, "exercise-0"]], "(advanced) Parallel-2 Running on a cluster": [[4, "exercise-1"], [14, "exercise-1"]], "Parallel-2, MPI": [[4, "exercise-2"], [14, "exercise-2"]], "Dask-Examples (optional)": [[4, "exercise-3"], [14, "exercise-3"]], "Packaging": [[4, "packaging"], [12, "packaging"]], "Packaging-1": [[4, "exercise-0"], [12, "exercise-0"]], "Instructor\u2019s guide": [[5, "instructor-s-guide"]], "Learner personas": [[5, "learner-personas"]], "About each section": [[5, "about-each-section"]], "Python for Scientific Computing": [[6, "python-for-scientific-computing"]], "Attending the course 22-25.november.2022?": [[6, null]], "Prerequisites": [[6, "prerequisites-0"], [12, "callout-0"]], "Videos": [[6, null]], "Reference": [[6, null]], "Who is the course for?": [[6, "who-is-the-course-for"]], "Motivation": [[6, "motivation"]], "Why Python": [[6, "why-python"]], "Why not Python for Scientific Computing": [[6, "why-not-python-for-scientific-computing"]], "Python 2 vs Python 3": [[6, "python-2-vs-python-3"]], "Credits": [[6, "credits"]], "Software installation": [[7, "software-installation"]], "Generic list of tools required": [[7, "generic-list-of-tools-required"]], "Generic instructions with miniconda and an environment file (advanced)": [[7, null]], "Python": [[7, "python"]], "Other options": [[7, null]], "JupyterLab": [[7, "jupyterlab"]], "Verification of Python and JupyterLab": [[7, "verification-of-python-and-jupyterlab"]], "Watch the video": [[7, null]], "Text editor": [[7, "text-editor"]], "Other editors": [[7, null]], "Command line": [[7, "command-line"]], "Other ways to access the command line": [[7, null]], "Verification of the command line": [[7, "verification-of-the-command-line"]], "Zoom": [[7, "zoom"]], "Need help?": [[7, "need-help"]], "What is Jupyter?": [[8, "what-is-jupyter"]], "Getting started with Jupyter": [[8, "getting-started-with-jupyter"]], "Running code in Jupyter": [[8, "running-code-in-jupyter"]], "Why Jupyter?": [[8, "why-jupyter"]], "Why not Jupyter?": [[8, "why-not-jupyter"]], "Glossary": [[9, "glossary"]], "The Python/SciPy ecosystem": [[9, "the-python-scipy-ecosystem"]], "Core numerics libraries": [[9, "core-numerics-libraries"]], "Plotting": [[9, "plotting"]], "Data analysis and other important core packages": [[9, "data-analysis-and-other-important-core-packages"]], "Interactive computing and human interface": [[9, "interactive-computing-and-human-interface"]], "Speeding up code and parallelism": [[9, "speeding-up-code-and-parallelism"]], "Machine learning": [[9, "machine-learning"]], "Connecting Python to other languages": [[9, "connecting-python-to-other-languages"]], "Tools for interfacing with other languages": [[9, "tools-for-interfacing-with-other-languages"]], "Evaluating Python packages for reuse": [[9, "evaluating-python-packages-for-reuse"]], "Is your work reuseable?": [[9, "is-your-work-reuseable"]], "What\u2019s next?": [[9, "what-s-next"]], "Exercises": [[9, "exercises"]], "What is an array?": [[10, "what-is-an-array"]], "Creating arrays": [[10, "creating-arrays"]], "Array maths and vectorization": [[10, "array-maths-and-vectorization"]], "Indexing and Slicing": [[10, "indexing-and-slicing"]], "Types of operations": [[10, "types-of-operations"]], "Exercises 4": [[10, "exercises-4"]], "Linear algebra and other advanced math": [[10, "linear-algebra-and-other-advanced-math"]], "Additional exercises": [[10, "additional-exercises"]], "NumPy can be really fast": [[11, "numpy-can-be-really-fast"]], "The library behind the curtain: BLAS": [[11, "the-library-behind-the-curtain-blas"]], "NumPy tries to avoid copying data": [[11, "numpy-tries-to-avoid-copying-data"]], "The ndarray exposed": [[11, "the-ndarray-exposed"]], "Strides": [[11, "strides"]], "An example: matrix transpose": [[11, "an-example-matrix-transpose"]], "Another example: reshaping": [[11, "another-example-reshaping"]], "A fast thing + a fast thing = a fast thing?": [[11, "a-fast-thing-a-fast-thing-a-fast-thing"]], "Copy versus view": [[11, "copy-versus-view"]], "Organizing Python projects": [[12, "organizing-python-projects"]], "Testing a local pip install": [[12, "testing-a-local-pip-install"]], "Sharing packages via PyPI": [[12, "sharing-packages-via-pypi"]], "Tools that simplify sharing via PyPI": [[12, "tools-that-simplify-sharing-via-pypi"]], "Building a conda package and share it": [[12, "building-a-conda-package-and-share-it"]], "Demo": [[12, "demo-0"]], "Building a python package with conda skeleton pypi": [[12, "building-a-python-package-with-conda-skeleton-pypi"]], "Conda package location": [[12, "callout-2"]], "Building a conda package from scratch": [[12, "callout-3"]], "Publishing a python package": [[12, "publishing-a-python-package"]], "Getting help": [[13, "callout-0"]], "What\u2019s in a dataframe?": [[13, "what-s-in-a-dataframe"]], "Tidy data": [[13, "tidy-data"]], "Working with dataframes": [[13, "working-with-dataframes"]], "Time series superpowers": [[13, "time-series-superpowers"]], "Beyond the basics": [[13, "beyond-the-basics"]], "Modes of parallelism": [[14, "modes-of-parallelism"]], "Multithreading and the GIL": [[14, "multithreading-and-the-gil"]], "multiprocessing": [[14, "multiprocessing"]], "Exercises, multiprocessing": [[14, "exercises-multiprocessing"]], "MPI": [[14, "mpi"]], "Exercises, MPI": [[14, "exercises-mpi"]], "Coupling to other languages": [[14, "coupling-to-other-languages"]], "Dask and task queues": [[14, "dask-and-task-queues"]], "Dask": [[14, "dask"]], "Example from dask.org": [[14, "discussion-0"]], "Exercises, Dask": [[14, "exercises-dask"]], "Task queues": [[14, "task-queues"]], "Python multithreading solution": [[15, "python-multithreading-solution"]], "Do it in parallel with multiprocessing": [[15, "do-it-in-parallel-with-multiprocessing"]], "Do it in \u201cparallel\u201d with threads": [[15, "do-it-in-parallel-with-threads"]], "Future ideas": [[15, "future-ideas"]], "Introduction to Python": [[16, "introduction-to-python"]], "Scalars": [[16, "scalars"]], "Collections": [[16, "collections"]], "Control structures": [[16, "control-structures"]], "Functions and classes": [[16, "functions-and-classes"]], "Python type system": [[16, "python-type-system"]], "Quick reference": [[17, "quick-reference"]], "What\u2019s in SciPy?": [[18, "what-s-in-scipy"]], "Exercises: use SciPy": [[18, "exercises-use-scipy"]], "1: Numerical integration": [[18, "numerical-integration"]], "2: Sparse matrices": [[18, "sparse-matrices"]], "Why scripts?": [[19, "why-scripts"]], "From jupyter notebooks to python scripts": [[19, "from-jupyter-notebooks-to-python-scripts"]], "Save as python script": [[19, "save-as-python-script"]], "Importing other python files": [[19, "importing-other-python-files"]], "Command line arguments with sys.argv": [[19, "command-line-arguments-with-sys-argv"]], "Parsing command line arguments with argparse": [[19, "parsing-command-line-arguments-with-argparse"]], "Load larger option lists using config files": [[19, "load-larger-option-lists-using-config-files"]], "Exercises 4 (optional)": [[19, "exercises-4-optional"]], "Further reading": [[19, null]]}, "indexentries": {}}) \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/397ee019b6b388442dffa61ae3629d85/lint_example.py b/branch/rkdarst--dependengi-exercise-time/_downloads/397ee019b6b388442dffa61ae3629d85/lint_example.py new file mode 100644 index 00000000..df2cfc2a --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/397ee019b6b388442dffa61ae3629d85/lint_example.py @@ -0,0 +1,9 @@ +import numpy +import matplotlib.pyplot as plt + +x = np.linspace(0, np.pi, 100)) +y = np.sin(x) + +plt.plot(x, y) + +plt.show() diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb b/branch/rkdarst--dependengi-exercise-time/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb new file mode 100644 index 00000000..3c1ecd2a --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb @@ -0,0 +1,96 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "url = \"https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv\"\n", + "weather = pd.read_csv(url,comment='#')\n", + "\n", + "# define the start and end time for the plot \n", + "start_date=pd.to_datetime('01/06/2021', dayfirst=True)\n", + "end_date=pd.to_datetime('01/10/2021', dayfirst=True)\n", + "\n", + "# The date format in the file is in a day-first format, which matplotlib does nto understand.\n", + "# so we need to convert it.\n", + "weather['Local time'] = pd.to_datetime(weather['Local time'], dayfirst=True)\n", + "# select the data\n", + "weather = weather[weather['Local time'].between(start_date,end_date)]\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, we have the data loaded, and adapted to our needs. So lets get plotting" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYUAAAEcCAYAAAAoSqjDAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAABtDElEQVR4nO2dd7gcVdnAf+/evSU9pBcggRCE0CHSpSNKERQbKkX9wM+GYPsQsWBFUSwgIgLSwYIoItKbhBJCS0JNgJBCSC83N7lt93x/zJzZs7Nnd2f7bHJ+z3Ofuzs7O/vu7Mx5z1vO+4pSCofD4XA4ABKNFsDhcDgc8cEpBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA4HA5HgFMKDkcDEZHJIqJEJNloWUpBRD4pIvc2Wg5H9XFKwWFFRDYYf2kR2WQ8/2Sj5SsHEVkgIkfV+TOnicgdIrJORDpF5CERObCeMlSKTXEppW5SSr23kXI5aoNTCg4rSqnB+g9YCJxgbLup0fKFqcdMu9TPEJEpwAxgDrAdMAG4HbhXRA6ovoR55RARcfe6IxLuQnGUhIgkROQ8EXldRFaJyF9EZIT/mp5RflpEFonIGhH5XxF5t4jMFpG1InKZcawzRGSGiFzmz6RfEZEjjdeHicjVIrJURJaIyI9EpCX03l+JyCrg+yIyRUQe9OVaKSI3ichwf/8bgG2Bf/nWzjdF5DARWRz6foE1ISLfF5G/iciNIrIeOKOQTBa+DzyhlPq2Umq1UqpTKfVb4AbgZ6F9PyMib/vH/bohz74iMktE1ovIMhG5xHhtfxF53D+vL4jIYcZrD4vIj0VkBrAR+IaIzAp913NF5A7/8XEi8pz/OYtE5PvGro/6/9f65+4A//w/ZhzrQBF52v8dnzatIV+WH/q/V6eI3Csio/zXOvzzu8r/Hk+LyNg859NRD5RS7s/9FfwDFgBH+Y+/AjwJbA20A38AbvFfmwwo4AqgA3gv0A38AxgDTASWA4f6+58B9APnAq3Ax4B1wAj/9dv94w/y3z8T+FzovV8GksAAYAfgaF+u0XiD2a9t38N/fhiwuMB3/T7QB5yEN4EaUEgmy3l7B/i0ZfvhQMo/nj5nt/jH3A1YYcjwBHCq/3gwsL//eCKwCjjWl+1o//lo//WH8Sy8XfzzMwzoBKYacjwNfNw4F7v5x9odWAacFPpdk8Z7zwAe8x+PANYAp/qfdYr/fKQhy+vAjv53fhi4yH/tc8C/gIFAC7APMLTR1/yW/OcsBUep/C/wbaXUYqVUD97A+eGQa+WHSqlupdS9QBee0liulFoC/BfYy9h3Od7A3aeU+jPwKnCcP1s8FjhHKdWllFoO/Ar4uPHet5VSlyql+pVSm5RS85VS9ymlepRSK4BLgEMr/L5PKKX+oZRKA0MjyGQyClhq2b4Ub/AdYWy70D/mHOBPeAMreEppBxEZpZTaoJR60t/+KeAupdRdSqm0Uuo+YJYvn+ZapdSL/vlZB/xTH1dEpgI7AXcAKKUeVkrN8Y81G09JRT13xwHzlFI3+J91C/AKcIKxz5+UUq8ppTYBfwH2NL7fSGAHpVRKKfWMUmp9xM911ACnFBylMgm43Tf11wIv4816TZN/mfF4k+X5YOP5EqWUWZXxLTzf+yQ862Gp8Vl/wJudaxaZgonIWBG51XfrrAduxBuYK8H8jCgymawExlu2jwfSeLNp2+focwDwWbwZ9iu+a+V4Q5aPaDl8WQ4OfV7W+QFuJqNsPgH8Qym1EUBE9hMvCL5CRNbhKf+o526CL7PJW3jWjOYd4/FGMtfADcA9wK2+++znItIa8XMdNcApBUepLALer5Qabvx1+FZAOUwUETGebwu87X9ODzDK+JyhSqldjH3DJX5/4m/bTSk1FG82LQX278JzWwDgxwZGh/Yx3xNFJpP7gY9Ytn8UzwLZaGzbxniszwFKqXlKqVPwFM/PgL+JyCBflhtCv8MgpdRFBb7vfcBoEdkTTzncbLx2M57VsI1SahieC1Cfu2KllN/GU1Im2wJFrwnfQrxQKTUNOBA4Hjit2PsctcMpBUepXAH8WEQmAYjIaBE5sYLjjQHOFpFWEfkIsDOeW2QpcC/wSxEZKl6Ae4qIFHJpDAE2AOtEZCLwjdDry4DtjeevAR1+kLUVuAAvHmGlDJkuBA70A74jRGSIiHwZb9D7v9C+3xGRgSKyC/Bp4M8AIvIpERntu6/W+vum8aygE0TkGBFp8QO2h4nI1gXk7wP+ClyM57q6z3h5CLBaKdUtIvviWRKaFf5nmufO5C5gRxH5hIgkReRjwDTgznyyaETkcBHZzVfI6/HcSeli73PUDqcUHKXyG7wZ5b0i0okXdN6vguM9BUzFc7X8GPiwUmqV/9ppQBvwEp6r5W/Y3TGaC4G98YLV/wb+Hnr9p8AFvrvl676f/QvAVXiz2i5gMYWJLJNSah6eS2cPvAD2UuBk4Bil1IzQ7o8A84EHgF/48RiA9wEvisgGvHP/cT9+sgg4ETgfb9BehKcEi93TNwNHAX9VSvUb278A/MD/Tb+L5/fX32Mj3m8zwz93+4e+5yq8Gf7X8ILd3wSOV0qtLCILwDi8c7gezxX5CJ5LydEgJNud63DUDxE5A/gfpdTBjZbF4XB4OEvB4XA4HAFOKTgcDocjwLmPHA6HwxHgLAWHw+FwBDRVud4wo0aNUpMnT260GA6Hw9FUPPPMMyuVUuE1OUCTK4XJkycza9as4js6HA6HI0BEwivQA5z7yOFwOBwBTik4HA6HI8ApBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA0HU++sYrnFq4pvqPD4SiZpl6n4Ngy+fiVXkfKBRcd12BJHI7ND2cpOBwOhyOg7krB7xA1U0ReEJEXReRCf/t2IvKUiMwXkT+LSFu9ZXM4HI4tnUZYCj3AEUqpPYA9gff5nZx+BvxKKbUDXkerzzZANofD4diiqbtSUB4b/Ket/p8CjsBrywdwHXBSvWVrVv40401+dOdLjRbD4XBsBjQkpuA3Gn8eWI7XPPx1YK3RM3YxMDHPe88SkVkiMmvFihV1kTfuXPivl7jqsTcbLYbD4dgMaIhSUEqllFJ7AlsD+wI7lfDeK5VS05VS00ePtlZ+dWyGvLWqixnzo/SBdzgcldDQlFSl1FoReQg4ABguIknfWtgaWNJI2Rzx4tCLHwZcGqrDUWsakX00WkSG+48HAEcDLwMPAR/2dzsd+Ge9ZXM4HI4tnUa4j8YDD4nIbOBp4D6l1J3A/wFfFZH5wEjg6gbI1nQ0e4/t+cs7uWvO0sj796fSweNX3+nkvpeW1UIsh2OLpe7uI6XUbGAvy/Y38OILjhJIGzohlVa0JKRxwpTBBy6bwcbeFG/85FgSEWTf2JcKHh/z60cB51JyOKqJW9Hc5PQZM+fe/nSBPePJxl5vkF/e2RNp//Wb+nK2Nbu15HDECacUmpyUYSr09KcK7BlPRg1uB2DJ2o2R9u/s7s/Z1tXbfN/b4YgrTik0Of0pUyk0n6XQnvQuwa6e3IF9fXcfk8/7N3+dtSjYtmZjb85+6yzWg8PhKA+nFJqUnv4Ui1ZvpC+dUQTdfc03Y25t8eIImyyyL169CYCrjYV5y9fnupnWbXRKweGoFk4pNCnf/Nts3vPzh+jqybhT+tPN51vXgXGbQhNL3HnZ+u6cbc3oNnM44opTCk3Kw696JT5MH3szBlyTCe8StCkF/XXMr2ULSKeb8Hs7HHHFKYUmRWdv9hrZR/98/m3e8/MHSTeRxaAthU2WYHF/OjdGsmpDrlIw4yq1ZPbitVmBfYdjc8QphSbFNphe+uB8Fq3eRFdvboZOXMnEFHIVgA6cKzIDsS37KFUHS+H5RWv5wGUz+P3D82v+WQ5HI3FKoUlJ+A73jZYZti1oG1dE8geabesubPtZDIqq8846L5Yxe/G62n+Yw9FAnFJoUrSlsNFiFdhcMXFFu2N6LIO9DiCbhoBNCdrcTNVGu+uc98ixudPQKqmO8tGWgk0B2HL+44pekd1niQtYLQXL961loHljb39gJdT6sxyOOOAshSYlYynY3EfNE1PQSsE22NoW4220fLdUDQ2FL938HEf88hHeWuWtuHZKwbG545RCkxIEmi1ulxffXl9vccpGr60opBTMV2yWQqqG7qMHX1kOwDv++gjnPnJs7jil0KRoH7ctpvDdf75YZ2k8+lNpPnj5DB55LXqb1D5/4LeletqsCJtlVEtLQbPBz3pqxrUgDkcpOKXQJOhBM51WKKWs2UeD2loA2G+7EfUXEFi7qY/nFq7l3D8/H/k9fYGlkPua/s6mwrAqhToM1Bv8lePNVprc4SgVpxSagDdXdjHl/Lv49+ylbH/+XXzr73Os6xR0sFZXHi2Xfz6/hLfXbir5fXps7iuhMJ9ummNbcJfJTCp8vHos1gtcWc5QcGzmOKXQBDz+utew/pHXPP/2rU8vsloKenVzJatue/vTfOXW5znwogcjv+eGJxZw5C8fzmQSpdOs29TH/OWdRd+rFZktpqC/R7F1F2bNp9/cP4+P/uGJyLJHpRrn1uFoBlxKahOgZ+0Thg8ItulicbaaQZVkyJRTXO47fgxDp5D2pRQf/v3jzFu+oWhXNK1Iwi6g9d19kZWCaSn86v7XShM+Ir3+eemtRwDD4WggzlJoAvS6g8HtuTq82+KqqUQp2NYLREWXoEilFfOWb4j4ebnuowdeXsbu37+XmW+uBop3lKtHTEHL0Izd7RyOUnBKoQnQVoGtNLZtJfDTC9Yw+bx/s2h1tG5mJpUMems35TbAKUQqrYIAs/nVdPbSCxFLStSjZLhWln3OUnBs5tRdKYjINiLykIi8JCIvishX/O3fF5ElIvK8/3dsvWWLK4KnFfotA5JtgZfuRPb0gtUlf1Y5SiHpB73XWJrdFErhNAdYc7avA8u6WF4xbIFm27mqBC2rsxQcmzuNsBT6ga8ppaYB+wNfFJFp/mu/Ukrt6f/d1QDZYkmikKVQYJAa0tFa8mf1pjKWR9Sc/Da/peZaS6vMQoFZ8/uk04rfPTSft9duotv33ycjKgXbZ9jcapWQiZc4peDYvKm7UlBKLVVKPes/7gReBibWW45mQruPzAFJb7O5jzRDOkrPIzCVjBlUfW1ZJ3OX2N05GaWQaynYFNmm3hSTz/s3f3z0jWDb/OUbuPieV/n8Tc8GlkLC1nqN3I5sKzf0MPm8f3P7c4uDbdVuTdrjYgqOLYSylYKITBGRdv/xYSJytogML/EYk4G9gKf8TV8Skdkico2IbJXnPWeJyCwRmbViRfSVs9Vk+fpuDrroQd5YES2YWim6vLQtX7+QpZCMsNDqV/e9xgX/mBM8Nwc9cw3Ee3/1KMdf+pj1GG0t3mW0xmIp2JSCXgj2mwfmBdu0wuvq6Q8yoPIN7K2J7Mv2jRVdAPz2gUyvg2orBa0ge+vU0MfhaBSVWAq3ASkR2QG4EtgGuDnqm0VksH+Mc5RS64HfA1OAPYGlwC9t71NKXamUmq6Umj569OgKxC+fu+YsZcnaTVz3+IK6fJ6eGdvSIQulkEaJv/7mgXnc+ORC7/j96azso+4ii8Y07a3eZbTOYin09ae54B9z+OusRcE2m7vHVEZakeT7/LBbSdclMvtVR5U9KpmYQvNUoHU4yqESpZBWSvUDHwQuVUp9Axgf5Y0i0oqnEG5SSv0dQCm1TCmVUkqlgT8C+1YgW02p+1zR/0CrpVBg8CulTs+cxevY8YL/8MDLy4JtOrX18fkrC763kKWwvLOHG59cyDf+NjvYZvPLd/lWiWAsWsvTFyJsAS1d563jGGy4y6puKRhrMByOzZlKFq/1icgpwOnACf62opFN8XwhVwMvK6UuMbaPV0ot9Z9+EJhbgWw14bzbZrNyQw8HThkFZNw6tUYPkjZLobtCS0Fzv68MHjMUgFYKr6/sKvjetqRXc8mWfbS6K6MolFLMemsNIwe15eynZ/kihb8vQGtL9lzGXjm18sHbzGoK1im4QLNjM6cSS+HTwAHAj5VSb4rIdsANEd53EHAqcEQo/fTnIjJHRGYDhwPnViBbTbj16UXc//Lyun+uHptMV1FQZ6jAzLUUS2GZ74IZYQzY+u260F6+FNF2P9CsU2FNzIykO154m49c8QR/fWZxzn5ZmUhF5A67j/RAbVpN1VjQ1pfOdWml0ipQON19Kc798/NZTXgcjmanbEtBKfUScLbx/E3gZxHe9xhgG11cCmoe9CBp+t2jTISL7WPOhPVqZDPjR4+rxWbd2ptjcx+tNrYtXuO5eQr1exCk6OclQ4FmrRjNMuKVWgr3vvgOA9vst0dfKk1LooX7XlrG7c8tobc/ze8+uXdFn+dwxIWylYKIvInFva6U2r4iiRw5BNVCDaUQpbFMsRm36QrRfY7NOkP6/fYGOClueWohB+0wKphF21JSzW3aotjQnbufRqS4iyZssejzYxYH7C/i++/pT/Hoays5aucxVjfgWTc8k/e9vak0Ha0tgRxu7YJjc6KSmMJ043EH8BGgMYX8a8zKDT0M9F0oUP9Asx6Us5VCcSmKKQVzMNODqOmf1+/Xu5mH+91Dr/NbP6V05/FD836G6VJqb/XOYaEe0qm0Klq2Itli93r2ZFlShY/xpZuf476XlnHfuYcwdeyQgvuG0aXBtcVSjzIbDke9qMR9tCq06dci8gzw3cpEih/Tf3Q/O4wZHDzXvvo6xZnLVgqFxkWlVJY7Ss+yTReMfrv2z5uHW2MEkAuVlDCP1+4P5ht6srvFtSUTgSy2Jjphoqy/KDZQP+rXVyq0ziMf2pJJOkvBsRlSifvIdKIm8CyHzbYU93xL1U+xhkaqT5CN019aIDXfbHnhqo0ccvFD/PRDuwXb9OBtWgpa+enYgxm4HjesI3hcaAA2B3kdKO8KtRBtN5RCZ3dfsEI6H8VeN2XOR6He0MUUbl+/97qOvxRzVTkczUQlg7i5uKwfWAB8tCJpHFb0GGUunErlGYhaEplAbb6x7YXFawG41FhRrAPNZkzh7bXdjBzUbh0kTXfayg09eWU3lYzuuxA+XnuyhU68z1/f3c+A1hYKUQ1LQctg28/W99pE14fScZj+CPEdh6NZqMR9dHg1BXHkJ20JNJuDWUIyCqAjmQgWginl9XPuS6ms2bVOPzV982t937+pFE67ZiZtLQm++b535chkWi1aodgo1iAHMgHoqO8JZx/ZiBKIB7tFUcyF1duvy2hn/3c4NgdKVgoi8iml1I0i8lXb6+aCtM0V7XGIElO4/6VlbD96ENuPHlx85zykrCmpmYGoLZkIyjq0t7YESiGt4Cd3vcwf//smr//kWOYuWUdnd3/Qp6CjNTO46sVj4fIQval0MKs2h76ofvQoMYL21tKWy0SpnhrVzW+zgrp6ilkK2RVTnaXg2Jwox1IY5P8vLWWjSSllAZiN/7l+FkDRtpSFyCxes1sKrS0ZpdBhzLqVUtz0lFfXqLO7jxN/NwOAHcd6CspUAIUCrrb4RdRqobYBNjw7b08WdhdpWluEvpTKm31kEnWgtimFfJZKW0uC3lQ6owx0f2mnExybESUrBaXUH/z/F1ZfnPhRKOhYbL5aqULRpG2BZsNl0Z5M0KkfG/74tIKO1hY29qaConGQSQmNWh8oE2j2Zscbe1KRq4XaLIWwAgq7j/KRTCToS6VojRBTiNqS1Kbw8hXTa096SsGVvHBszlRSOvvnIjJURFpF5AERWSEin6qmcHHA5i9WEVcqVGvQyCxeMzN5Msc2awGZA2xaqSBo+/SCNcF2nf0TVSmYX+N7d7zIHj+4t6iLRRNOP4Xc4G5kpeC7jaK4j6JmBNmUfr4eFdrN1RuyFOIWUXj0tRVByq3DUSqV1D56r1/y+ni8zKMdgG9UQ6g40VfAN1AsprCxwCKtUsisLM5sMxWOGUTuyLIUVDCQvfZOZ7B9gx8YjtqdzJxN6yqqs95aY903nC4aRXl0FMk20mjlZ7qP2vK4kiJbCtaubXmUgu/minsXttOumclp18xstBiOJqUSpaBdT8cBf1VKReuy3mTYZpzFxptnF67hhEsfY2YZPZJtFBvgzIHRDB4rRWApmGmj/RZ3VMHPNwbOYQO8Qrjv+OWqwwxqyx7gowSaB7VHUwo6FdV0H+WzMkxrpKunP2/arFUpFHAfAcxdso6P/uEJOv1yHdVyE67p6uWDl89g0eqNZR+jWrI4tlwqUQp3isgrwD7AAyIyGtjsykXaVusWu+3+M2cpc5as4/6XlhXZMxrFFlNlu4+yLQU9C1+1IbdYXeTPNwaaoM6RpSIqwKD20nMXJg4fEGk/rRRajJTUfJlL5jk75tePMv1H91v3syncfG41bQVd+uB8Zr65Oq+1VC53zn6b5xau5YpHXi/7GKa7zikIRzmUrRSUUucBBwLTlVJ9QBdwYrUEiwu2uIAecPL1U9D+/nJKKNgoVtEi231kxhTslkLJn28IEPjR88g0uAylsPVWAyPtp91GZpw5X+aSqRR0dVYbtsVreS2FkJsraiwkKvq7VHLdmDGwKFaawxGmnHUKH7JsM5/+vRKB4obNfVTMl6zr+q8vUA20FEpxH5mD5Nf/+gJ7bjMcqEwp9GcphcLffUBbNFeQyTYj8lsKOg0UMgFms7x3voE5aulsu/soX0wh+7N0sb/wzzN3yTp2mTC05CZM2uqppGuc+X16+9MMai/7UI4tlHLWKZxQ4DXF5qYULIFmrRTy3fI6S2hDgZW+pVBsgMtnKQA8v2gt4JWPKJesaqpFex2UXg9q6pj8S16SLYKe8Lb6biNzQXN49q6JqhTSSrGpN5WlzPLN1MNKYaXvkjPPzwuL1nLi72bwjWPexRcP3yGSDBqt3CuxFMwJRKEkCYcjH+WsU/h0LQSJK7aU1GIB2g1+1lHYv1vqzPGuOUuZNn5oUUvBHNDyNYapBHPQK5ZN1GJRCmYVVBtbbzWA0w6YxOD2JJc/nO1PN4+XSUXNbMtXHK+Q8jJ97W+t2sjO372bn35oN07Zd1sgvyUYdlVp68t0Mep033tefKdkpdAfpB6XP5ib37saLUkdWx6VrFMYKyJXi8h//OfTROSz1RMtHtjcR8WUwqY+b2AwawKVc6N/4aZnOfKSR4qumDVnsFEzeUrBlL2riJ/aphSKFbgTEX5w4q7sM2mrnNfMILq2QrJjCvndR/OXd7J4TW4mjzlWLvD7T//juSXBtnxKIWyF6QZC5v5a35QT2NfXVT4X3RdvepbPXPu09TWlFI+/vtIa/3E4SqGSSNm1wD3ABP/5a8A5FcoTO2yBZj1I5pvB69LKnUZMIWrQL5VWrDL8/6m0Klom23TZ1MZSiD64mJlBehY/MGKcIWFRKOZ3aw0CzYalkGedQldvP0dd8iifuuqprO0rOnuyZtBaXtOPn2/RYTIh2Lxj5vnRx0kkvHLrZ9/yHOs29vH5G58p2stZf24+g/Lfc5by4Cv2HuF/f3YJn/jjU/x11qJgm2v+4yiHSpTCKKXUX4A0gFKqH2jKdIcn31jFvS++Y33NNmvTN2++mKt+vdNwtURdAfy7h+azz4/uZ3lnZgAppRNZtTNiINNpLArJhARrFYZ2eGsaoioFWzwiy1JoybUUbIoEMhlHC1ZlLIXl67t594/v55L7Xgu2aavOrHeklXqYhEiWPJn9M+dHZy61iHDm9bO444W3ueyhefxn7jtcfM+r1uNqtKVQTp+ON32LZ6GxxiFqpViHw6SSEaRLREbip+2LyP5AUy5g+/iVT+btyWsbkINCaPksBV8pmC9HKSENMNuvYDpj/krj8wrf3MkIi7nClBLeKGXlbkKE+792KM9ccBSDfVdWVOulxSKUWdJC+/TN2Ey+wLYtyK9jPOY6AB3/MS25vN9X7DEM07IILAWRYKDW7rNiZU8CpVDkt3n1nU4mn/dvnluYWSehr1PTinIlvR3lUIlS+CpwBzBFRGYA1wNfLvYmEdlGRB4SkZdE5EUR+Yq/fYSI3Cci8/z/uQ7mOvLi29mrVk36Aksh+6bTg4DNlxs1zXDsUC+HcHVX5nOL+YbNgSp6xdHoP30pNZySCWH8sAGMHNweLGQbO7SD1hZhu1GDGDW4Le97bbN+M0ahffrmwJfIM4Laai7ZlLi24FYb7UXzKYWEiFXpmvvrEhlZ38WXsZjFle88L1vfnWVp/neeV9fon8+/HWyzTRziFmhesnZTVv0uRzypZPHas8CheAvYPgfsopSaHeGt/cDXlFLTgP2BL4rINOA84AGl1FTgAf95XTEH7h/86yVmvrmaJ9/ILVWhB4H/zM24nJ54fRWH/+Jh/vbMYuugctecd/j37KVFZdCDtSlLsdRCXXoCorWqhPy+eBtRymHosdkcxLVSGDmojbkXHsODXzuUySMH2d6e81792LYGwxxv830Nm6VgmznrwXZjb4rH5q3kpqfeyjvDFuxKN60yA7DpPgoT1VIIs99PHuB0o5aRPq9mhzibRRun2kw9/SkOuuhBvvm3KEOEo5GUrBRE5FMicip4cQSl1ItKqbnAx0XkE8Xer5Ra6isUlFKdwMvARLzV0Nf5u10HnFSqbJVizhaHdHg33jpLOQc9aJjtMXUM4Hv/nGu9+a945HW+ePOzeT978nn/5pt/eyFwh2Td8EUsBVMpRCWq8oBomVN6DUGWUvBjCW3JBO3JFkQkbwwAsmf9+jjmOoTAUrAojzDW6qyW82ju96mrn+Lbt8/l9RXZ/bi1WAmRnAwkjR6AtTI3dYKuulpMufZaLFC9ANIsqaFjNF1GwUVtBZmutafeXM3k8/4drFVpJFpJu+qt8accS+HLwO2W7X8HvlbKgURkMrAX8BQwVimlp9LvAGPzvOcsEZklIrNWrKjuBWaa6Ho2ZgZ8NWbMoLc/zezFaxnqD8xdvamig/iarl4WrspNlfzLrMVB0Nic6RaLKQw1lEJUN1VrhPLTpRxTD85Ji6VguqoKrW3LyjTyHw9ozbUURGCncUP4yD5bB9lD4e9jc/vp3som5m8+xJc3PIgGqbCJ3IquegzWA3omLpCRRyueYpZC0DfauH50cTyz0KA+9oaefr59+xy+9fc5wUTFVEY6ecKMTzUKnZ5dLD3Z0XjKUQqtSqkN4Y1KqS4g8pRVRAYDtwHn+CW4zWMp8tSdU0pdqZSarpSaPnr06NIkL4KZg6/dz+s32dwQmSYrn73uaT5w2QxWrO/Jed1GT3+Kw37xMIdc/BDg3djmYirdq8HMXOor4hs2LYVCAW1beqeNsGspiqWQGTgzn6HrILUm88cAzKfZC9U8GcxBRPvzBeHucw7h4o/sgdYFYZltloLte5h1jnbbepjlm5k9oSVHKQzyg+g6XqAHdvMa0EHsYpaCfq+pPPT1N6Qj8xvr4yjgpqcWcsvMhUGmkRk20d83X9ylnmilELVMuqNxlKMUBohIjmNYRIYA+aOI2fu24imEm5RSuizGMhEZ778+HrAnZNeQjcZAogdXW2As07A9zX/nebOwFcbagkIzwg3d/YFLav7yTnb93j38ddbi4HXdUc2cwRazFEylMKFAxVHzhiwUUwg3senuS+WUxA7T0pJrKeiso3bjs8LunnxBY30cc7W2lt9scqSVUGvIHWbTo7ZB2ZY5FMZcNBd2H+nFgvqa0GtKTKUQWAoRlUKfRSbzN9HHMX+mzGro3EZM5ZQeqTbacnNKIf6UoxSuBv4mIpP0Bt8NdKv/WkHEs32vBl5WSl1ivHQHcLr/+HTgn2XIVhFdvSmO+dWj/PSul9nUq5VC/tpH5sCzdmMmHlHIfWQOQnf7gWqz74K+uU1/cSkxhfdOG8vNZ+5n3c8c0Ap1LwtbEd19qaIlsW2WgsZ8r3Z9tFrWHNhKWnQkcy0F83wEPRYiBM5tg7Lpv8+3wFDLIpItDxiWQigeYH5WVwXuIz05MZW4HvjN8xUOdJv7mUp0eWc3LzQgxrA+sBTsv9Pxl/6Xb/19Tj1FcuShZKWglPoF3oD9qIisEpFVwCPAnUqpiyMc4iDgVOAIEXne/zsWuAg4WkTmAUf5z+tCixHcfXVZJ3949I3ghrINJDb30JqNfQVfD14zFka9scJLYR01OFPKUgcMN2S5jzLHs3kChg1o5Y4vHcRtnz8QEeHdk0dYP9ucdetB1Aw46zEm7J/v7ktblYItWyiZNVClsz4LMrNb25qDLKVgCVzrWaZpOdmylPJNjIsNynktBWMldXimO7A9ew2CbbbfVcR9lE4rb6W1xcooZCmYlpXNUtD7mROM826bw4m/m1F0dXW10d+pL6X4/I3P8EYomD93yXpumbmw6p+rlGL5+s2uzUtNKasmglLqCuAK32Wks4iivvcx8hcYPbIceSqlrSXBpnQqeyBO6ZlX7kBhm7lnWQoFYgBmsPNtv3uZmeGUsRSys49E8vcwGDagNcttFPYhtycT9PSnGdia+bn1QN3ekilW19ri7ZdMhCyF/pS1plJLQoJBUL/HNlCZA5p+vaM1wYae7MHcZilklcn2Z5lmjEW/biq3ZIu9AF8x900+S6E1kZElvE5BxzyiWAr5Jgu/eWAev3lgHkfsNMZ7r7GfthTM8iH62KYVq92O5jZtNZjXks6smr98A+OGdVjlqQV6sjNnyTrmLFnH0nXd/OOLB9X8c391/zx++8A8Zp5/JGOG1u/7NjMV1URQSnWWohDiih5slq0zS0vk3nga24zTtBQK0WtYClq5rDeUgr65zc/oT6tg8LFp03AZifBMeZAl4KsHUXPA1gO0uR94ysi2KtnMxU9aYgp6gDQHe20ZaEvBnHknsyyFTMaPRiuylNV9lPs9whQtZGgoBfN4ZhmRsMLXCxa1BagHP/P307GqfJaIdiPqqqtZ7iNfJlOe3mDWbV4j/vVqfIbNBaqvI1sgvpboa0HHpvRCtrvn2svLVIvbnvHidfX+vs1M9QvlNCF6EHnbVAqWmZfGNuMzLYVCmIOFPs7aTZn3Bi6E0OfaUvku/+Te3HzmfjklucPPtdLIKlbXkuue0cHa1kTuZWEGmvVbkhb3UYsxeH1gD69W4v7bjzT28/5rRZwvzqEVgK2khelO0zGMbEvBbogWcx9tNAZUU7EkDUtBy3X2EV5Z7PfvOj7r2P2B+ygzsOsByXTj2OTSVo+5RiWz7iHznWyDvf4Mc5tNebQ3WCloK29FZw8X/ecV/vfGZ5j5Zu4C0WpRSXOpLRWnFMj46U0/a28oxdBk2frcC21tREsh21/sPTbdR7a0RMjMqM3BYdywDg6cMqroZ+pgqDmI60F0pVHiuVDQ1owp6NdNBRAsXjPkO3CHUSy46DimjB4cbAvcPS1aKZiWQq4rybR6RgzyktvMstQtkitzvqBz1OwfsCsZEThkR+98H7LjaBZcdBzH7uYphSD5wD+GLYDdm0pbs9nCcq3v7g+26WvEjKPo68U8lr7+rJatsU1ngkUt0FgttAVlfo/X/ZhaLWXpKXAfO+xUVGdZRA4EJpvHUUpdX6FMdUdbBSs6M4N9qf0P8jWyD2PeoNpfbCoUm08a7FkbhVINj542lvteWgZkgqHmgD3csgq6NY/7yPv87HTWnv501vESlkCzjXC8w/xeNpeNub/u5Wz2SNCKyZzZt+aRoZQaTllKIYiXwIl7TmTf7UYwftiArP30jN42+Jgup66eVE6pDNuMfnVXL+OGdQTXiOl6WuNbpWamUWZbrtLpybIU/MWRdbcUvP/m6ekzYlm1xhUHjE4lTXZuAH4BHAy82/+bXiW56oq+ac21BqUW7oo6E7Hlxa+3WArhi7jDElMotCjp0lP2Ch7rhU8tFkvBJIgzWNxHNivDln5arHyGfo8+52aKZ5Yry3DZfO3oHZk8ciCTRw1EhKyOZi15As02/masBymGebzWwFLw/muFABm33hl/eppl67uLXgf2mkzZq6Eh4/bIKAVTAeRaCmv8Aoo2pdDbn2buknVZ+3dWqVVsVGw9QcK9t2uJra2uw04llsJ0YJpSRTrANAH6RjZrH22K2BSnVGyWgrmSWl+84bhFxn2U2VboZjKzZIb6dZzMsV4f58tH7MClD873jmcJ2mpMy0nP7ExFoR8VVQr+jpNGDGT+8g2csMeE4DWbC0gEvnzkVL585FQA3vzpcVnHa7G4vPKV8HjDDwpHISumYMgSxrR0Hnl1RdGGSLc+vZAJwwdw8t5bc8E/5nL+sTsF14St7Wm3xVLQ16mpKPQAa7Nwl63v5vhLH+PEPScEn9HTn+KWmQtpa0lw8j5bF5S5uy+FSPQKvDbSFmVpU4a1wlkK0alEKcwFxgHFS3/GHNssoljbyXIxb4Cevlx/px4XwlkuepDyGrDoNND8SsGMPWhLwZZKa1obgfvIMtM2ByXtXrIVsCvmCtAz+0kjBzH3wmOyAtimpaDdHLZqo1nHs7itquGOyFpbkcj9vpoBIfmLWQq6B3V7MsFtzy4mIRhKIfPeniCmkNvvYaXv5rS6iiwDrHYVPfjycnYcNwTwrgW9WMymFLr7Ulz/xAI+fdB27PSduxkzpJ2Z3z6q4HcrhO286O8dtSthJRSrCuDIUMndMwp4SUTuEZE79F+1BKsn9exla8sOMcnXLcs2A49a02bogKR/7Mz3/Mj0bdhqYCsf2ntisE3PsE33ywF+5pD5+VpBZa0/sGQB2dDvaW0RBrcn8zbMaS/gojLRSsOWuVQJ7Zbva5PEzApLtkjexkthdOB+fXefsfAsHVgj+jrRFqtZ06rTkmmksQ2+2uro7OkPZufF3Ck3PvkWP7nrFa57fAEAyzsry+KxyaVlMbOtaoVrTRqdSiyF71dLiEailKrrBVOs4mi+AHcw2JruI4vv38aIgV7WTn9a0Zb0FnZtN3IQz333vVn7BaucjQH2tAMm8cQbq/jU/pOCpi5B9pGZkmpJU7Wh1zvYBm5TQZgVUQuRsMzi87nV9HePQpYS1ArKIkw4eyrqBEOXZjd9+739KQa1JdnQ0x/4/00XUZio38VMhdXXn7leZvbitey+9fCs92il9dLbWbUqy8bmVtObamWVm8Spt0TcKVspKKUeqaYgjaLWEZFkQrKUTjGlsN5S8hnsM/CWiAE6ncrZn05z91few9+eWczwgbnZR7pm/wNGc/h9Jm3F/B+/P8t60LK0WNxHxdAz8GKzeVuXNRtJi1KwrbOA0nzX9kBz7n7todTVfJbC4PZkVsaPPl+mUuhLKYZ0ePtpZRC1jWshzM/VmW7rjLUx85ZtyFEK2gLqqtIs3mYp6HO1qYaWQkKymyA5ilOynS0ij/n/O0VkvfHXKSLVmVbUkSiXStQBz0Z41losgG0r1Q2Z/HLzaMX87d96/0588fApwYKl/pRi+9GD+eb7dspZ4GZijmsikpPNY7MU9KBcTMlqBTmgrfClZ+uyZsMWU6hGNkurNdCce1xzmyow+ITLhOjZu7lwsS+VDhYaZiyFVM6K9Sh85qDtrNv19fegofhtbsygEmuVKqzaAs16S75FfdVAy+8CzdEppyDewf7/IUqpocbfEKXU0OqLWDu+9pcXuOaxN4vuZxt8ozapCbt4is381uRZGW2zFIoNfp87dArfOGanYDYbdbZkprPaBoVM7MGiFIocWwf8ilkKZu+EQujPNQfnUrrK5cO+ornwe/rTafKNPYNCZUL0AjRzIV5/WgXuNZ2EsLqrl10mlH5bTRo50Lpdz/yz1gsYSmFFZw+ru3qDtQ1hS+1jf3giUlvZMIXcR7WMKejrwqWkRmeLXtF827OL+fFdLxfdz5bKGTU9LzyoFlMK+fLHbX7tqF2sgpLTEZWCuQLZrhDzu4+KWQq9/qhZVCn47iNVRM1oxWTuFy5al49CPSXM/gz6exZTUN+/48WsFq0mOoagWeZX7gxn3miL4qf/eZln3lrD8s4e9pk0ouDn2shnXRTrM/HuH9/P3j+8L9hmWmB9qTRPvbm6YFvZfNgshcB9VKGLLJVW1uNDRpGHu9n99K6X875nS2eLVgpRMWf72l8ddeAJB16jtssMo2eQps86asMSvV9Un7o5gInxNW/7/AF8dPrWwazXzAzSj4sN4npWWmhA9l73XV5FblxbzKEtosK2WXv6dzUbAyWKWArfev9OgFcy5Mk3Vlu/m9k5DeDttZusx+oIqq4qTv7944AX1ymVUtw+hUpjmL/xxgrcPIUshULB9ChMOf8uTv/TzKxtj7y2gvnLO4Prw7SGvnLrc/zh0Td4aWnTebvrglMKETDvLz0zjeqiKDWmkI+t/MCweQNHvfFHDfYCzflcU2GGGgOYaQ3sM2kEP//wHlY/vv6axSZfn9hvWwAOnlq4ZpNeC1FsNmc7BzaFbTtVtpXPet1BtmvM+58vDHPinhOznrdbSpLotGBNPqVgy97acexgy56FiZIFNaDAZCFo5GP2mvbdPMUUug1b8o9e92pOlMpdC6s7IGpOv2YmR13yaKAUzMmFji+4NFU7FSkFEZkkIkf5jwfo/grNQCnZCNnNX7zH0S2F0mIK+dhqYKROp1bG+WUZ8i0SuuXM/bnlzP2D56alYHNR6XHCnKUfsfNYAPYMZbGE2XvbrVhw0XEF24ZCZuApduMGv42xm01h29xVmcV6RjzCUnNJf0a+4HxY8dvO2ZD2bEshX3C1JXS9tCcTQc0nk2IDczGLDTxXVWuLFAw0m6d/nZ+5VE4g35aVlakoa1YOrnygNhWL/snMxWva+nEZSXbKTkkVkTOBs4ARwBRga+AKGtQop1RKceOYN2rQnKaIi0Kvbg3PZMs1lcM+6VIY7Oec7zrRHrA8YIq3QO2WM/fn2YVrrG4hk8BSMAaHY3YZy8l7T7T2XSgH/fsUO89W95FRhkMPPG1+o6Hs/STYvy+l+xbkZhplgtl2GcIpsOYq50FtLXT1pnJ+v748gc/wWD9l9GCrNTS4I5lVliXM8btP4Nm31tKWTHDDk29Z9xnQ1sLG3lSgAMyBM1MlOLNNp0uX0/PZNgDbij/2p9O0lTBXtR13vRGX07JmWdi++PUor9GMVHIHfxHYF3gKQCk1T0TGVEWqOlDKjN28UfVAaHMRZL/HUwrhG6hcSyGRyAxM5VjYD339sGC9Qj4OmDIyUBAFZdGriI3BMCFSNYUAsMof8EYWkVlbBeZNr624jtaWIEffNrPW7qPWZAJ6U1nvtfWOzrdmIjxzNov8DfCVwtBQVdp87p2wApiax3U0flhHQaUwsK2Fn314dy5/eH7efQa0ttCWTAQzddN6eWaht2bFtNRe8X3w5WR3FVrRbFoHff0KSjCKbfeT2dtEK3mb27UeK6mbkUrcRz1KqeDsi0iSaGn/saAUSyFrtWzEQLNWBrmWQvbnRvXPJkS46X/246GvHRZp/zDbjRrEMEu57HLIZGBlZK9ONru3ghoyN/GYoe2Fdg9iLeYAmbHmchfcmbQalkJ4P3P8179/vgly2DXVYVoKvpU2ONTjOl/zl7Di2WG0XSlsvVV+95tIxtIpdH0NH9hGm9G6tLMns3DytXe8hormYP7IayuA7J7iUbG5j/RvnNV4qsTUUdvAbvYn0fehed9lmhnVfiV1M1LJ1O4RETkfGCAiRwNfAP5VHbFqT7lKIcjRL1JiQgfoclJSQxfi0AHJrEY3+WWAg3Yo3lCnWvzuE3vn9R3r72ZmP0Wtw1SMCz+wCxd+YBdWd/UypD0ZNLHJh461rLHMDos13tGuqWIlLQL3UR7VF85iGmIoAO02GtDm+e/1rHjpOnsz+fB53Da03mCvbYfz3MK1WXGGcPkOMzhcaFY/fdJWvL12U/BeW48F01LQE/rRQ0pXCtaCeJYqqaXWITMzopat7+ampxZykGHtpizBbH1PbupN8ezCNbz2Ticf33fbkj53c6YSpfB/wP8Ac4DPAXcBVxV7k4hcAxwPLFdK7epv+z5wJrDC3+18pdRdFchWlHJ9+0HzF+NeM292TYtlgddA34drMnJQe0SlkDnOC999b9ESzZVy3O75B+NEoBQSOdsqRc9wRw5u51vH7lx0/7F+M/aJwwfwij+7zVRxzexnSz/Vvn9bsb/sQLP3P18Ji3AA2rQK9ORhcHuSViN2kY+wNTIu1Gz+L587gLfXbuK2Z5cE24YPaGV5Z0+gHMw4UCFLYfLIQbQlE7y+sosnXl+Vda3q60s3agKzblLp947t3OlN2YHm0o5tuo++cutzPPnG6qw1GtpqsN3v3f0pPnS5l/brlEKGstxHItICvKyU+qNS6iNKqQ/7j6OMVNcC77Ns/5VSak//r6YKAXKzWgqld5oKwFprx3LjtVj87kM7WukM1TYaOTiaA9Ucd4YNbC0aH6gl+iuZKZ1S1pVUOaOHtHPjZ/fjko/tGWxrswSLbb+RzhIq6j7S2SoFLu+9th0ePB5sBJW1i2TU4PZIGWRh5TpumKcUPrjXRLYdMZDWlgSTRg7K6i6nj6sHQ1tDJBsD2loY2NbCC4vWcsofn8xqAGSbsdvcPVEplOlTiVIw91+02kvzNSdeWhmYloKtkdVm0BamapR1KyulUsCrIlKyelVKPQqsLudzq0m4RHXB3gQUHlysSsESUxg7tD0rMwKi+2erNROvBmZ7Sk0j5Tt46qiseImtNpMtBqTdX+ZrrTZLQYqvmbjpf/YLHps9Inr8wWjEoLZoE4DQaZzop+7+6mN78ug3Dw+2mwp5mB9XGdia23bVphT0MaeOHZyVHNBpuI9sqcA9FVgKhcZ6c3DuT6uSjp/V6tSPL9jiNd3GMbX1YGZbVbqAbnOikvndVsCLIvJAlfopfElEZovINSKSdwmniJwlIrNEZNaKFSvy7VaUsLsnMxjk7mtbvGaLM5jYGs+PCbkCwG4p2GSoVmGyahDMpo0RLA7iTfBn1bbf0mop2NxHRvaRjgfoc18orX1gWzIIercbsZZdJg4DPKUQZQJgXlffPnbnvK1FzWtuvP+9g0G9yPc+Zd9tePrbR7HTuKFZrq7Zi9YWlC2wFCIM2nfOfpul6zIL9Ar1mTCPd+vMRex4wX9YtHpj3v1NTAtEZ32ttPR+0JZCfyoduBlNhbLzd+/mb89Eb9e6OVOJUvgOXmzgB8Avjb9y+D3eWoc98Tq55T2OUupKpdR0pdT00aNHl/lxueZxMogB2FbDGgogketesPYXsCx4sqVX2gYKe6+B3O/QKNosaZtxsGTu+sp7+PfZBwcDZsIyYzZdRQP8mIhNKYgID339MO4555DMqtgiro1tRnjBX9Py+NnJu3H7Fw5k9JB2timQMaRJCJxx4GT23nY4Zx6yfd79zGtkz22GA5kB0rRorM2ZEhIEi03/+1VFikMGMQXjPMxdso4p59+VtUK7pz/Fl25+jk9e9RQAb6zYwO3PLSEfpgvoz08vBGBhRKVg3sf6u9gshaCFaVbnw+z4ztf/+gILSmjZurkSi34KSqkgmiUifwTurNax8xGumqhdItZy1BZLwZw1mj2L9Y1pq6wZTksEu6JobcldaBWHQVdjW+AVB4YPbGP4wLZglmnOToMGQslEMKhZYwpGP+ZRg9sZNbidmW+uAmBFkYQA7dtva0lwxaf2ZurYIQxsS7LXtp7he+AOo7juCftCMk1ChO9/YJei39UMCn90+jYkRFi/qY9f3vda1gy4vUC8C6LXzwK7pXDr0wtJpRX3v7yM0w6YDGTWO7zjZ1j9o4BCgGwl0xVaL1IM01IY6BcTXLY+Vyk889YaNvb2ZykCM3XVJku9+cldL3PUzmPZd7sRDZMBKrAUQv0UukUkVW4/BRExU10+iNf/uaaELYXM7DJ3X3NAfm2ZZ3o++lrGdZW05LvbOoLpomhmUHKQRVHYXEVxUgqZqqul12GqB3qhmOki1JlS5mCjB8Tsjm+5rjGd/rl4TeHZq65w2t6a4H27js+qNgtw1M5j8/Y50ERVtNn9HoTTD5wcNE5KFbEUzN+qlFIPZvbRg68sY+abq4Pr16zuq9t/Fur5bdJncUdFLXdhrmvQSv5t322l70ftBtzQ3Z816NuUQiO58tE3+Ogfnmi0GOUrBbOfAjAAOBm4vNj7ROQW4AngXSKyWEQ+C/xcROaIyGzgcODccuWKSo6lYHE5BDIbj4+z5M3ri89abtl484hB3k07PCsomvt5tm0xGnMzdYlSuTPxOKDrDJm/sV6TYFMKJrZBdN/tRrDdqEGcfeTUgp+rg7b50kBbEsJ3T5hWMCMo6u9sXiP6mm0LlLVdKWhL1aYEo2Aqhc9cO4uP/uEJBvvfucsIUmsF0dqS4OWl65m5wMsrue3zBwb7mPeFTQF05ylBHiYVClJDJtVVTw50gccuo6QHZJTCZw/OKOpGte2MUxnvqtQl8FNR/yEi3wPOK7LvKZbNV1dDjlIIZ1cE9WuKWArH7T4hxwVguo80ZmmE+849hPXd/cxf7lkZ5ie3JBLcetb+tLYkglLJZuaSnsnFyVWjB5q4drPSmUjeIO25EoKS2IYi0IFmZXEzmdsGtSd56OuHRf7cYr9VoYE/qkVoKuGWkFLIt9+wAa1s6OnHnHOcsu+23Pr0IqaOGcy85RsKfqa+ZXqMgXNge65SyJQWEd7/m/8CsMuEoUFAHPT6HO+3sblswv7+fJj3cfYkRYIYw2BDRlMJrvWVghnXy9cjvdbEqWJrJQXxPmQ8TQDTAfsyzRiS6z7SboMMuqCaeZ/aJoHaysi6UY1A89SxXvFYPRjst91IHn51RXC8/bcfGVqan3F16JzrOFkK+nv2p9Nc9om9Ijf7qRfbjBjA147ekeP3mMDhv3gYyFhx5qCg5TbvRz2wFsqWyccn9tuW9Zv6OHLnwiXACg38UX/nrLpTCe2+LGz5jB/WwZK1m7LcR3tsM5w3f3oszy9aywf9hVzFMGfTWsH0GSdxvX8tm5bzhOEDslylxToXdvelue2ZxUwYPqBgPS7T/WXK1ZFsCVyG2n3kKa6MDPOXeUpw6piMm6+nQampcarYWomlcILxuB9YAJxYkTR1JGwmZjp9ZWhtSdCfToVmfsIZB05mx7FDOP/2Od5+Ce07zexnCzTvte1WPPKNwxg+sI2f3f0KkKnAaloZ+jjZSiE+WiFjKaQ5fvcJDZYmFxHhyyFXj3bpmBVM9QzSFpAux4swZfRgLv7IHkX3K/RbRrUIbW4fWyVd05U1YfgAeGtNTuVbEbFWo7WtwIfsgoxdltcfm+/1Nhg7tIO3VnlxmHFDO7JWwBeLQW3qS/Gtv3v314KLjsu7n+kizAqwtyaC76TdSBt7U1nZhZ2+5bCHn70FmT4S9SZO7UIrUQpXKaVmmBtE5CBgeZ79Y0VYMwc3WVZWkbCpL5x6SZAdEiiFZK6lEFQ1DX3upJGDskxtW+G8pJEpk/ncOCqF+MxuiqFlNnsl68BwltshWJNQu+9W6KeM+jPbqvSOG5a7DsZUHvr7FjueVgYD25JFi8bZCtItXuMFes1J0qjB7da+1/nIV5vsrOtnsee2w/nCYTsA2fexmTLc1pIILHitLC99cB5vr812Zuw8fmgQoIcGuo9idC9VEh28NOK2WNKXoxR8/7KxTbd1tFXMNLFlWSQN91EY23oGeyOfzE0cI50QlCYuVtY6TugByszL14Fmc2BJWmIK1cbWuU4TVfnbguQ2pWArCmgbgEzloQOzhZSIRqefmqdr3Sbv+ljZmUnhHTm4LeteiGIp2Lj3pWX8/O5XAVjR2ZP1XUxLoTelgliLVgrPLlzLO+uzlcJuE4dlnSMXUyjDUhCRA4ADgdEi8lXjpaFAvJzLBQgvRLKZ422WjCQJWQ1plfHvtkac2WeX4s4dIJKG+0gTp5RPnWUTpfdCXGi1uI+00jVN98AKquFNGvSjaJGcwSDqz9xhcfcMaU/y4X22ZvvRg4JtprWpz4Etw0afi2RCgoVe244YGLh/8qGDyuYx1/od2sxFZOG6T/naqOpBWXd5y8c9L77D5254hj22HhZsMxVEKp0pDDioQJ+PXSZkN56KGuCuNnGKKZRjKbQBg/EUyhDjbz3w4eqJVlvCsyVbgFEP8rYuXJDxSbclcwd2fQPa3BDFVj4HgeYaVCGtBh/aayJ/Pmt/PrBH/OIJ+bBZc/r8mgOz9nvbcuerhf75beXXo1sKtlXvwi8+skfgWgG7UrBl++j9WlsS/PRDuzF1zGB2mzgsd79QpkWXTSn4gWbdKOmsQ7bnmF3GZr3P9j1NhV2sn/hCX1m97JesgNz4gj7PhZo/TfRXmd/+BS9dtnGWQhPHFPyVzI+IyLVKqcLLM2NMeIamZ+UqK6aQm5FkXss7jRvKzAWrA7+rrRCZbQaQVUvJMjBkAs1mv4ICX6bOJBLCfts3h5Xw0NcP47VlncEgYvq59W9u5q4HzexrmK8uhqWQ77ViRF2J3NqSYOzQdsYO7Qi+u819pL/36QdO5uR9tubkfbbmN/fPy9lvSEcyGOwhE2jW51AplTPLP2aXsXlrOGV9p2QL4L13rXGMhas28ot7X+XnH9492Bbcv8ZX6UupoIx9Kq0CxVPIDTZykJeOuq1foqSWsaRCxMlSqCTQvFFELgZ2AQJnplLqiIqlqgNh95EtxztTW99ITzVUxG9P2YvLHprHmCEdXoqpcT8Hq34tN2Ax36reZs4G47ROoZnYbtQgths1iGtn6Lo+mfM42s9Pnz55q6BImlbEtVzElLEUyl+kWEp5isf+z7slf//w64D9u7UlE8z78futZbd1n2nwYgNZSiFkKWzsTdGbSmf1GNExChPb9Wxe72aNokMufgggyzINlJChFfpTaYZ0tLK6q5d+oz+6aYEAbD9qEG/4NY5GDfHcWnpy1p9SzFm8jjdWbuDEPSfmyFgr4hRTqCTQfBPwCrAdcCFeSurTVZCpLuQLNOdzHw0NFiZl3jNuWAc/Omm3YNGSebO1F7AUTGyzRW3uxq0KaTNjCyCPGdrB/V89lO8en6k11GaxHqqNrcd1+LVi2NxH+WhtSQR/kN8Kam1JhHpQeI/NK3hsqNKvVgr3v7ycB19ZxqlXe0XwdhqX8dWb/alP3X8SZ+Up9GcqOlv2UZeR6bSxTyuj7ECzDiqn0ir4LgNDSuHK06Zz9enTec/UUYGloJti9afTnHDZY3zl1uetMtaKzSX7aKRS6mqgTyn1iFLqM0BTWAmQ20+hcKAZdvcDWp3duSl4elGOufAlU3Kg8OBisxR0ipx5E8QpptCM5Bvsdxgz2FoltZa+Zf1b2mtcRTuGLdBcDD3I9/VHG4AyNa4U0ydtBeQWdTSv0c9cO4tnF64Fsjv3mSmfPzxpV87P01HPXG1uC/iavUi6Lamy/WkVuMF2nTA0WFhnnqs7vnQQO4wZzJE7j+WGz+6XkwnWqBl7nGIKlSgF7fRbKiLHichewIgqyFQX8gWazY5mmZIHcMlH9+QLh01hb6OYnUbfKGa9lkxmSxFLwTIK6EwNcz2DUwqVMdSfQYabHIXRA2dNLYVE9meZj6O6CcML0KJgLjosZf90WgX9wcOTp64ee7bOrhOGcekpe3HpKXtZF8bZpO8wjm1rerPeWPVvWz+RSiveNW4IXzhsCleeNt2a7m02YzLR92GqzjP27r4UP7zzJZaujU8xiEpiCj8SkWHA1/DWJwylDoXsqkV44ZW+UbYa2BY0VQ+CxUoxYlAb33zfTtZjaZN1k3GhthWIKZjYZou6WYt5wzmdUBnar93Z3YdIdkKBSRB8rmlMIXewakl4Pvha/s4f2GMC/3rhbT53qN19E8YssGdbOwOZlFSTc4/akYOnjipZviz3kWVl8XqjlW2+dQzJRCK4T7WCNedl+ZSC/i1qmYps476XlnH1Y2/y4CvxWfNblqXg92ieqpRap5Saq5Q6XCm1j1LqjirLVzPC7qNJI73c7nOOypRHCNJKi1woej/TytCDS7H1BVal4B/HvOHKmRk6Mmi/9vrufp46/0j+/oUDrfsVyuWvFvqXtBW1q6VFOHxgG3/93wODUuDFMFM537frOAA++u5tsvYJW1R/+dwBfOWowtVk82GeD2tMwbgf8rn3zCQnfcuYccIhlqA3eArEU8z1deO8tcoLeK81UnC7+1K8aqTa1puylILfo9lW7bRpCM8IthrYxoKLjuO9u4wLtpk+1UKM8btYnbJvpmV1Ju+7dKWwna+gzCJ5TidUxtZ+PvrR08YyZkgHe/uNb8JM8PsXv3faOOvr1UAslkKm/0bNPrZkhhjxg6ljh7DgouOs7lOzKYytkZSNsO7zFoJm7jOb+2hTb2ZbvomabQ2QmexRaJKWTAidhjVSy1Xtmk1Bm9DMZ512zUyO+fWjDSvjXYn7aIaIXAb8GQh62Cmlnq1YqjrQn0pnuRFsEzRtzhb7cSaPGsTz3z2a4QPbuOAfXn8grRSK5WfbMlB0L+fJIweywM+vz2f2OqIxfGAbs7//3qD+fz5GDW7nhe+9N2tArBXmtWFbxNhobA2gbPKZcYaoSiGMWSYe7JaCWWcp33oCU77vnbALHckWjp421rpvmGRCWLfJ/AwoMqerGJ2cssH4bjPf9PpPbOjuD7wG9aSSK39P//8PjG2KJslA6k8r2oy2l7YJhE77i5IuNnyg/ccrxVIY3J706t0nhPu/eihbDWxlnx/dDxRelemIhi1fXnP2kVN5eel6oPYKWP/iZpJBog7uo1IZbKm6aqO1JcHQjiTru/utlVoL0dbitUdNiGQN9Db3kKko8t2S5gLSsUM7uORje0aWpSUhWW6cvlSalkRtK/fo2IlNx23o6Wfh6o1MHjmIYQPrNymspEfz4dUUpN70pxRtSbMXsmUxjV7IVEa6mDZvi3UkMweGoR2eUhC8VEnwUug2FalU6aicrx69Y90/096UKfr7p40fyivvrK+2WAFRraXWFm8S8/CrKyLPbPXY3e73zG5JSNHKqWZwOZ9rpxL3W7IlkbWSuh7pqYX6NyxZu4mPX/kkR08byx9Pm15zWTSVNNkZC/wEmKCUer+ITAMO8NcuxJ7+dJr2ZAIdzinoPoqY1519/GhKwbQUhg5o5e113VkB5t23Hl7yZzuaA3PhYjmB5ju/fHDVZTLJF5S95KN7MGP+Km57djHgVRMeM7QjJwgdhfbWBJ093vcOrzwOY8YZ8i0KrSQhI5mQrGB2uOpBLegukPo8w+9LoUuR14tK1ilcC9wD6LXnrwHnVChP3ehLqaziXrabMSiOVsbFoW+oSSMKZ3qYs6Mff3BXdho3JKfhu2PzpM0aU4j+/kRCapqVlm+Q/tDeW/OLj2TqEBVzkRZCp7gmpHjpjiz3Ub5AcwXut2RCsj6jPpZCfi/Ayg2eK6ve7c8r+bhRSqm/AGkApVQ/0DR+jlRaZa1ktV1KA3w/fjk56wfvMIrffWJvvvG+dxXcz7QU9pk0grvPOaTojMmxeWDrlxGnmALAf77yHqtFIiLBpClcOTUKuoSLrlTbkhBG5InLaUz3Ub6U1HxKctTgdg7dcXTB47e0SNbM3RZL7Eulg+KKS9dtsjYZCvP22k15XcCFLAXtMdjUm+KR11bw+RufKZoeXw0qUQpdIjISvzSKiOwPrIvyRhG5RkSWi8hcY9sIEblPROb5/+05g1Wgpz/FwtUbs5WC5VrSi8jKqUvSkvCW+ttWc5rEKdvEUV/M668cS6Ee7Dx+KLtaSmhDZmZvKyYZFX1/tCSEc47ekS8enl01YOzQ9uBxdxSlkOcEzrrgKK77zL4FZUkmElmDd18qnTMIX/ivFznk4odY09XLAT99kNOunlnwmAAHXvQgn7nWXhaukKWg3VfdfWm+cutz/GfuO9z69KKin1cplSiFrwJ3AFNEZAZwPfDliO+9FnhfaNt5wANKqanAA/7zmnD9428xf/mGrIU3tmtJ12wpry5JzO5uR2zQFTqzS6jHL/uoGLrOUDmWgo6nmIX9Brcn+cYxO2Vl2n3n+GnBY3PAztdLuRJXSzIhWSupr/rvG2x//l1Z64UeeNlbebzaz1Ka9daagsfUAfEn3lhlfb2QpaDdV5v6Uozz09Qfea32K58ryT56VkQOBd6FNwK+qpQq3C4p895HRWRyaPOJwGH+4+uAh4H/K1e+QuhyuWYdHNuMXaeZltOLuInubUeDMK8r07feLOj1CQPLWJugu6FlmlFlXusI9YvWmANovqydSpRqS0KyUkOve+ItwHMT6TRlnTa7JGLwt5jrOYqlsLG3n1Vd3vd6Z31P3v2rRdl6VUQ6gLOBH+KVzv6iv61cxiqllvqP3wGsK05E5CwRmSUis1asWFHWB43y6+ibBbZsl5IuohYuvRuF4W6xmSMPB/gNisxeANq33ozuxHLuDx030wFjc42CGXAe0JpROKZlb7qPLjguU3W1EqUQLmOvD2UW39Nj/KI1hduUamwrs00KVePVlkJ3X5oVnZ4yeGHRWn5450s1bcpTifvoerwGO5cCl/mPb6iGUMqzuazfWil1pVJqulJq+ujRhQNH+dA11M3sAtvNuO2IQXxor4nc8aWDSv6MEU3U1N5RXw7fybtuzVmpnnU3k/tI3z6DylAK+j06s8/03ZtKJp/C6elPsc2IAZy6/ySmGX2WKzl/4XLk+ljmgjbtDlq4OppSMN1cvf1prnz09azj9fSlGJlnrAhnPW4/yit/c/Vjb3LBP+ZE+vxyqEQp7KqU+qxS6iH/70w8xVAuy0RkPID/v2bOs0kjBzJ55EDOPSqzYMl2KbUlE1zysT3ZYcyQkj+jGWd8jvrQZpRkD7Y1oftIz+4HlLHaXruc9OzfnPgOMCyF9jzNhHr60+w0big/PGnXrDIblcQUwqux9U+xpquPuUvWsXJDT2DF5Ct1PXvxWlZ3mYN+ZmC/7vEF/OSuV7hlZiZY3N2fDvpEhwknuJy8z9bB41tmLsqKdVSTSpTCs37GEQAish8wq4Lj3QGc7j8+HfhnBccqyKD2JA9/4/Csao7mDOM9ZZT91dx9znu45cz9i+/o2GLRHf1Ml0kzWgpa/HLcR+/3q67qYnpmMseAIN4geYPYvf3pYE2CWT+sknUbr4Qqk2pPwsa+FMdf+hgn//7xwO21qsvu2//AZTM48XePBc+1pdCSEF5d5h3fHMx7+lJBscYw4aKdU8cMZsFFx3H5J/cGvFTXWlBJQZ19gMdFZKH/fFvgVRGZg+cB2j3fG0XkFryg8igRWQx8D7gI+IuIfBZ4C/hoBbKVjHkvXl8kda0QZhtCh8NGYCkY27RSaCKdYFgKpSuF90wdzRs/OZY75yzl+ifeygq6a0tBkILprloXmLGASpSqrTcEwKoNngJ4a9VGdh4/1N/Wm7VPXyodWBaLVmcGax1TaEkIC/ysM3Mw7+5PM2FYPkvB3kdeN+Fas7E35z3VoBKlEE4pjYxSKl/Z7SPLPWalmJeSc/04aom+ubPdR7mKIu7okhBbFVl0lo9EQoJuaylLTKE3lS6Y7qoVgK0vRVny5HnvW6sy8QPdh2WloRT+8dwSzvnz88EM3kRbCsmEBGmsnd19nHfbbB6bv5JUWmX1sDbJ1x1yq0He/mu6YuY+Ukq9BawHhgEj9Z9S6i3/tabCKQJHvcj4wDM3va7gum5jbW70WqBTurctUsqlELbSFgPbM9sKWgoF+lKUw5eP2MG6Xc/sE5JJIzbdR7pr2pwluWt3A0tBJMh27OpNcevTi4KaRh154ibhQHN7nSyFSlJSfwjMBn4L/NL/+0WV5Ko7Tic46oWe2ZqzY10VVy9sawZ0n4KtKijrbFMKZonzQgUltTJoNWMKFdzH//Mee5tSHQNIq8xAbVp5Ol1U/zcxMxz1cbpCbqp8VQ/C1ZnbWrz9hg9s5QN7TGCbCpRxISpxH30UmKKUqo26qjNOJzjqxUE7jOKIncZwwXE789CrjwBw0l4TeWzeSv43Yv/kOHDZJ/aiqydVkZVtmyWb/SwKWQr6Y7OqzdYgfctcz2QrjjnXtxCWW5SCTrXt6u0PMqwWrspOZx2eR6nmcx+1J1v47Sl7RZS+dCpRCnOB4dQwdbSe1Nt9NOO8I1yfhC2UjtYWrjnj3VnbBrcnueLUfRokUXm0J1uK1vYqhs1SMJVCoR4LQfaRoRRqcR+b2UK2Omid/sx/+fpMmuqm3hRvrNwQBOPNRKLOkKWQb8YfrqTQXkGNqVKo5FN+CjwnIveIyB36r1qC1Zt654dPHD4gcBk4HFsq4QVjkK0URIRff2xPa4XTINCcqE6gGeChrx/GN47JrmzcZUzeCpWtMN1HX//bCxz328dy1hKY7UpP3ttbd6B7socJ11yrpPBgKVTyKdcBP8NLJf2l8deUuJiCw1F/bOms4TagJ+01kR3H5k6gdFC5Jct9VJk8240axEl7Tcz7eqGKyauMRWtPveH1WTYXsgFMGJ6pBPTDk3Zh9vffm7dbXSqP+6jWVPIpG5VSv/VXMz+i/6omWd1xWsHhqDe2cjC2xXA2N5W27k1LoRruo9YCboNNfamssh75elJrMVaG1jPsMiFThnxgWzIIqn/T0nclHGgeXEbhwXKoRCn8V0R+KiIHiMje+q9qktWZZiov4HBsLtgCwzaXki0grd9ra2taCcki5sZ+fkFDgMPeNca6jw4w64Vvmn0m2dvEfOGwHfjRSbtmbQtbJcU601WLSlSPDn+bNR0UcEQFx2wYbp2Cw9EYfvPxPbN6KNjWGtgtBV3mwlynULk8xTKYRg+2N/4x0VlKYffRiEFtXHDczllF/DThxXP1aAdqo5J+CodXU5BG41SCw9EYTtwzvw9fM3ZYblV+PYiaE7pq1I4q1nPaTCE996gd6e5L0duf5qk3VwfbdbntcGC6JSF510Pk00X7Th7BAVNG2l+sAZUsXhsrIleLyH/859P8ukVNiTMUHI74stc2w3O22QbRaqxTSFrMjW1GZOoTjTIshWkThnLDZ/dj1JD2rP31LL831C+hUIptPoV285n7ce7RO1pfqwWVGFvXAvcAE/znrwHnVChPw2im6pQOx5aGLchqUwDVuI9tA/f2owYH/aJtqeT5ekqEF7sVUlr5RK/32FSyUhAR/euMUkr9BUgDKKX6gaZdjeV0gsMRX2xBVlscsBoDaCIhweCtlVFLQjhyZ6+sh2k1aAbm6SkRXoBms0KCz80je73HpnJiCjOBvYEuERmJX9XL762QWxGqSTBNQoejXjx1/pF0djdPEbx68dDXD8vy7ZureVtbhL6Usq5JqFaZi9YWIZVWnLDHeB59bSVnHzmVaeOHcvzu461Nt/L1lAi7jwrJZ9MXIvVPgilHKWgJv4rXGGeKiMwARgMfrpZg9cYpBUcjGDu0g7FDK2ltvnmy3ajsVb5mRlIykaAvlbLOrKuVWt6aSNBNmonDBzDjvExC5YFTvAZcV58+nQnDMxbDYe8aw+UPv55znLD7KNwHOus1i1ZohFu7HKUwWkS+6j++HbgLT1H0AEfhVU5tGiYOH8CStZtqUkjL4XBUn2SLQF/2rDuZEPrTqqLS2SZ6lXRLHnePdiVp9t1uBOccNZX+lOKyh+YH23tKsBRstY0aMSyVoxRagMHkZnHWpo5rjfn32QfT2W3vuORwOOJHsGjNGDE7WlvY0NNftZl1poFP9OOdc9SOvPpOZ5ZSyLEUCozytjIWjVg/VY5SWKqU+kHVJWkQwwe2MbzMzlEOh6P+BIvWjKBCezLBhp7qrGg2KXUVcbjsRSnZRzal0AhLoZyUVOdncTgcDcO2klkP3tVY0Qyg/JLXlSqF3HUK+QUstGq7npRzChvWR9nhcGy5nHXI9px/7E5B1pGpFNr92kjVGkR1Imm+Vpn5GNyezFrxHE5JLT2m0ARKQSm1uvheDofDUV3OP3ZnzjpkitFcx3QfebPsaiWM6HabtuJ8hRAR9t42U/QuXOai1JhCswSaa4qILAA68RbC9SulpjdWIofDESfEEgTWM/pqj6HlVCbdeqvcxW2aki2FBmiF2CkFn8OVUisbLYTD4YgfemA100X1jD6cAlouetZeqvsIYPyw/Eqh0DoFu6XQBO4jh8PhaCRaKWStePYH73ylrEtluN8StJxuZ/l6JkDhQHObZYl2s2Qf1RoF3Csiz4jIWeEXReQsEZklIrNWrFjRAPEcDkcj0QNl0mIpdPdVx1IY7Vc9Led47568FT87eTerq6hQ97T2iPWdak0clcLBSqm9gfcDXxSRQ8wXlVJXKqWmK6Wmjx6d28zb4XBs3mTcR5kBc/pkb3Y+blh1ytX88qN7cOr+k9hr2+Elv1dE+Ni7t2WcpXxJIXdUXCyF2MUUlFJL/P/LReR2YF/g0cZK5XA44oK2EEz30WcP3o4Dp4yydjQrh/HDBvDDUHvMUrFZCoVm/ub3EfEyoKQBy8JiZSmIyCARGaIfA+8F5jZWKofDESf0bNtMSRWRqimEalEo/dSGqTAG+aW4W5Mu+2gscLt/cpLAzUqpuxsrksPhiBPB6uWY11YoJ0itGdjm1XKyuZRqTayUglLqDWCPRsvhcDjii1YKPVUKKteK7UcP4pV3Ost676D2JHT20NoApRAr95HD4XAUQy/yqtaahFoxeeSg4jvlYahfQ6kSa6NcnFJwOBxNxYBWnX4a7+6/lQzoQwe0Ft+pRsTKfeRwOBzFOO/YnUgpxft3G9doUQpSietnmK8UwgX16oFTCg6Ho6kYM6SD33x8r0aLUZRwg55SivVllEL9XWTOfeRwOBw1IFzSohyl0O+UgsPhcGwehC2FI941JvJ7hzr3kcPhcGxe6MV1yYRw31cPZfyw3LIX+Wik+8gpBYfD4agB5orm7UZFS09tSybo7U+zzVYDAVjV1VsT2Qrh3EcOh8NRA8rJPhriV1GdNNJTCql0/d1HTik4HA5HDdBKoZRhXVd7bU8m+OR+23LVafVvPOncRw6Hw1EDCnVZy8evPrYnzy9ay5ihHfz4g7vVQKriOEvB4XA4akA4+ygKA9uSHDhlVA2kiY5TCg6Hw1EDCrXejDPNKbXD4XDEHO0+Uqr+weJKcErB4XA4akAjeiFUg+aU2uFwOGKOzj5qQFZpRTil4HA4HDVgSEdzJnc6peBwOBw1YFgDeyJUglMKDofDUQMa2SinEpxScDgcjhrQiP7K1SBWUovI+0TkVRGZLyLnNVoeh8PhqISJwwfwuUO3b7QYJRGbSIiItAC/A44GFgNPi8gdSqmXGiuZw+FwlMeM845otAglEydLYV9gvlLqDaVUL3ArcGKDZXI4HI4tijgphYnAIuP5Yn9bFiJylojMEpFZK1asqJtwDofDsSUQJ6UQCaXUlUqp6Uqp6aNHj260OA6Hw7FZESelsATYxni+tb/N4XA4HHUiTkrhaWCqiGwnIm3Ax4E7GiyTw+FwbFHEJvtIKdUvIl8C7gFagGuUUi82WCyHw+HYooiNUgBQSt0F3NVoORwOh2NLRZqt1reJiKwA3irz7aOAlVUUpxLiJIuNOMkXJ1mKERdZ4yJHFOIka5xksVGJfJOUUtZMnaZWCpUgIrOUUvXvim0hTrLYiJN8cZKlGHGRNS5yRCFOssZJFhu1ki9OgWaHw+FwNBinFBwOh8MRsCUrhSsbLYBBnGSxESf54iRLMeIia1zkiEKcZI2TLDZqIt8WG1NwOBwORy5bsqXgcDgcjhBOKTgcDocjwCkFh8PhcAQ4pVAnRORDIrJVo+VoBty5Kh0ROUJEBjVajmbCXWd2NkulICJnisjlIjIlBrJ8SkSeBA4GuhstTxh3rkrH7+nxQxEZEANZPikizwCHA32Nlicf7jqLTqPPVaxqH1WCiAiekvsw8E1gKbCfiCxRStX9h/flOQO4CjhQKfVUvWXIhztXpePLmAT+B/g/vMHkXuC/DZInCZwDfBt4v1LqyUbIUQh3nUUnTudqs7AURKRDeaSAZ4H9gN8DhwA7N0Im5eX6Pg3cAvSISEJETheRhsijceeqdESkzT9nfXjnbGfgD8CnRWRkI2RSSvUD84AbgbdEpE1EThaRCY2QJ4y7zqITt3PV9EpBRL4D3C0iXxaRXZRS85RSq4G/AQK8p15+QxG5UESOMzbNxysFfifwAnAAcI2I/NTfv67n352r0hGR7wE3i8gZIjJCKfWUUmoT3k27NXBUvWQTkfNFZD9j0xN4BSH/gzeYfBC4TkS+7e/fqHPmrrPo8sXmXAUopZr2D/gM8DCeZv0B8A9gsvH6e4HrgCND75MqyzECb3XhGrwLrdV4bWvgAmCK/3wHPNNwgjtX8TxXhjzn4rmIjgRuAH4DjDdePwX4J7B9jeUYD9wGrAXmhV47APgJsLX/fFf/3I5s0Dlz11mTnavwX9NaCr4PbhvgcuX5Bn8OzAV+qvdRSt0LLAB2E5HjROSL/vZqL+PuAv6hlNoKr4XoV43X3gZ+ppR63f/s+cDjwKQqy5AXd65KR0RagL2AC5VSDwA/BDbi+fHx5bsFWA8cKiLvFpFP1kicdcBflVLDgbUiYp6zp30ZF/syzQXuxiurXFfcdRadmJ2rbOqpGWugab8H3Gk8Hw3MBA4zth0ALMe7EM6toSyD/f/vxjNRx1v2GQD8GngIGObOVWzPlS7/cjHwJ/9xwpf3DmAfY9+jgU3AIuCzNZRpiP//YGAV0KblMvZpBS4F/g101OMcxeE6KyBLLK6zOJ2rSPLW40OqcFKPAMaFTzLQDrwEHKK3A2cDPzFO8n+Bq4GBtZDF9uP7n3dV6LXD8GYjv66WLHlk+ASwh3E+GnmusmSJ27kyPm+48dgcZKcC9+ErAf8cXYA/+OO5HZ4E/ljFc2aVJXTO/o7XrtZ87URgVh3PWUse2RpxnbUUeK3h1xkwwJSnkecqkrz1+qAyT+aBwIvA9cAOoROb9B9/EXjKeO2LwNeMk14V32oRWRL+Yy3TaOAVf1A5ANgdGApMrOG5Osq/gJYDZzT4XBWSpeHnypDn/cAjwE3At4ztLf7/Nrz0wD8br/2WjFIYQZ4JQhVlSRiDiD5nY4HVeC6iXYBt8fzkk+twzo7DC9L+BDjIPGcNuM4KydLw6wwvJvA43qD+SWN7st7nqiS56/2BJZzQFuBPwCdC282Z3Hj//4PARXim9T3ANxohC4Y2xwtKpoHngXfX6BwJnvn7F7yA1THA5cAX9MVXr3NVqiz1PlcWefcFngI+ABwK/BXYNbTPaF/W+/HWA0zxz9npDZKlw3h+lX/Ongam1emc7YPn3jgW+DheIPeM0D71uicjydKo68z/vZ4ETsLzLtyBoezrea5Klr2RH17kpG4FXAsMx5uxnYpnrnf4r1+Cp4UnA9sD/4s30/p2g2R5FM93KcDxwJvAN+t0rk40Hn8KeMJ4nsQLYtXrXEWRpWHnypDlXOBi//H2wK14Sk3PMC/Hyywahzcb/zGee+a7DZDld3iZKdPwLIdT8QKQdR088Bbt/dJ/PAAvY+ZZfJcX8Ms6XmdRZGnIdeZ/3q7AH4xt0/Csu9H+87qNXyXL32gBjJN2Np5vVpvmI/0f9VD/5vwL8Ge8RUOD8Mz4rULHaIuDLHgm6rA6nKszQ9tbgIPwZpHb+Nve5V+AtT5XZclS63OVT05gN7yslEuBxf7vey3wHTz3zPWWc9YeB1mA6Rixhzqes32B14AR/vPv4AVov+/fI7+u13VWqix1uCdPB442nk8G5mC4f4Ar8FJMh+BZLTU5VxV/l0YL4J+MM/BMrffhacsL8LT/RXhZAx/19xuCl3mxh/HevEGmBsiSrKYsEeX7FkaePJ6v9Gn8bJXQe2t9rkqRpebnqoCc38Gz+rYCfgWc4O83DS/wt2Mdz1kpsjTynH0bGIOnuO7Eixn9Cc9NeAWGwqzDOStFlpqeM/93+xveOofZ5nfHU+bXGc9H+PfDNrU6V9X4i8s6hSPx8obvBr4GdABfAL6LN/gOAVBKdQI3482eEBFR3tLwuMjSX2VZosjXjuemwZdrNl5dno9puQz5an2uSpGlHucqn5ytwJeVUmvwZpBv+fu9AszA/41FJFGHc1aKLI08Zx3AaUqpL+PdDz9QSn0a6MGb4fb4ctbrnowqS03Pmf+73YtXjuIZvHFC8yXgWBF5t/98A/AcoAz5qn2uKqahSsFYUv4cns8PpdQs4DE8P+544BvAMSJygohcgOeSeMnfV22OspQo35PARBE52N9P8IJVA/yLTlVbvjjJUqacjwOTRGQaXpDvKhEZiDcD3RVvzQFKqfTmKEuZcs4AdhSR9yilFiql7vP3OxZ4Q7+/TtdZ3WXJI5/4D69XSq3Fi0N9SEQm+Z+/HrgQ+I6InI7nddgF6KyHfOVSd6Vg1hYxLvQZQEJEDvGfz8W7GfZRSl2PZxIejJd6d7zyV29uTrJUKN/beEpLX2hjgK4a3aANl6VKci4GdlJKXQK8iucCmAZ8SCm1fHOTpUpyvo0XeEdEDhGRR/Csmys2R1kiyKcnOd3+/6fx6lD92NjnMrz4xj54K6Y/opRaV0sZK6UupbNFZF9gf6XUb80Zj28Sp/GqPb4IfExEZiilFovIGLwfGaXUgyLycDVmS3GSpYryjcMrwaD5ulKqd3OSpQZyjsULfAN8Fi91ce3mJEuN5NS/7QK8dOMXNydZSpRPL0Qzx4LLgL+IyC7ASrx42oMi8kgcXUU2am4piMg5wO3ABSLyfn9bC2TNBDrxgkXtwC9EpBUvgLNCH6dKCiE2stRAvlWGfNVQCLGRpYZyLtMyVkkhxEaWGsq50t9vYZUUQmxkKUM+pZRKi8gAERmsZfH3n4MXFB/qb28KhQDUPvsIb/n9XsDJwCOW1y/EW6yzE57b4Vo83/QfqH4WQ2xkibt8cZKlWeSMkyzNImecZClTvu/hlR3Z3X9+Cl6ywM8xKrM2018tTuIJeFH3/f3nLf5fB3AXcLa/PYGXn30zfglbY3tOCmOzyxJ3+eIkS7PIGSdZmkXOOMlSI/n2B7ar9W9a0+uliidzPPAvPDPvO8DLwDH+a7p2y5F4tc1HWd6f2Bxlibt8cZKlWeSMkyzNImecZKmRfLFbb1D2uajiST0BYwk58Dng9vAPi2f2Xeg/39c86ZujLHGXL06yNIuccZKlWeSMkyzNKF89/yo9kafhlZ9tBwaS3ZXqI2RKwJqF47bBW9C0Dq/eR1VOaJxkibt8cZKlWeSMkyzNImecZGlG+Rr1V3JKqp+GNQ7Pl5YGXgfOBL6ilFoqIq3Ka3A+Hi9DAOVF6AWvyuSf8PKOz1FKzSn18+MqS9zli5MszSJnnGRpFjnjJEszyhcLStSsus78jsCNehteDZK/h/b5F3CU/1gXrRoDHF4NbRYnWeIuX5xkaRY54yRLs8gZJ1maUb64/EWyFPy83B8CLSJyF17ubQq8/FsR+QrwtogcqpR6RETa8PL6XxORHwPHi8jhyludWdEKzTjJEnf54iRLs8gZJ1maRc44ydKM8sWNoovXRORQvEJPW+FVCf0h0AccLt5KP5S3yOT7eDnF4KVvnQE8gFfQ6yil1OpKhY2TLHGXL06yNIuccZKlWeSMkyzNKF8siWByvQc41Xh+OfB5vJP2jL8tgeen+wteW8B98crG7llNsyZOssRdvjjJ0ixyxkmWZpEzTrI0o3xx/ItyUgfiRee1r+2TwE/9x8/jlf0Fr/HHrTX+gWMjS9zli5MszSJnnGRpFjnjJEszyhfHv6LuI6XURqVUj8rU7jiaTB2gTwM7i8idwC14ZppZUraqxEmWuMsXJ1maRc44ydIscsZJlmaUL45ETkn1gzUKr6nMHf7mTuB8vLrvbyqllkBd6pjHRpa4yxcnWQoRJznjJEsh4iRnnGRpRvniRClVUtN4XaJWArv72vU7QFop9Zg+oXUiTrLYiJN8cZKlEHGSM06yFCJOcsZJFhtxly8+lOJrwiv2lMbrRvbZRvq94iRL3OWLkyzNImecZGkWOeMkSzPKF5c/XegpEiKyNXAqcIny+6A2ijjJYiNO8sVJlkLESc44yVKIOMkZJ1lsxF2+uFCSUnA4HA7H5k3dezQ7HA6HI744peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwqOWCIiKRF5XkReFJEXRORrIlLwehWRySLyiSrKcLaIvCwiN0Xc/wwRuaxan18uInKSiEwznv9ARI5qpEyO5qHkzmsOR53YpJTaE0BExuB1yhoKfK/AeyYDn/D3rQZfwCubvLhKxysZEUkqpfpLfNtJwJ3ASwBKqe9WWy7H5ouzFByxR3nNTc4CviQek0XkvyLyrP93oL/rRcB7fAvjXBFpEZGLReRpEZktIp+zHV9Evioic/2/c/xtVwDbA/8RkXND+3eIyJ9EZI6IPCcihxsvbyMiD4vIPBH5nr//IBH5t2/xzBWRj/nb9xGRR0TkGRG5R0TG+9sfFpFfi8gs4Nsi8pa2kvxjLRKRVhE50/9uL4jIbSIy0D8XHwAu9s/DFBG5VkQ+7L//SF/mOSJyjYi0+9sXiMiF/vmcIyI7VfzDOZqTRi+pdn/uz/YHbLBsW4tX0Gwg0OFvmwrM8h8fBtxp7H8WcIH/uB2YBWwXOuY+wBxgEDAYeBHYy39tATDKIsfXgGv8xzsBC8k0ZlkKjAQGAHPxSjKfDPzReP8wvDo8jwOj/W0fM475MHC5sf8/8dtA+vtd5T8eaezzIzJloK8FPmy8di3wYV/GRcCO/vbr8XoN6++q3/8F/Rnub8v7c5aCoxlpBf4oInOAvwLT8uz3XuA0EXkeeApvsJ4a2udg4HalVJdSagPwd7zGLIU4GLgRQCn1CvAWXt9fgPuUUquUUpv8Yx2Mp3SOFpGfich7lFLrgHfhVee8z5fvArwGL5o/hx5/zH/8ceO1XX2LaQ5en4Bdisj9LrxqoK/5z68DDjFe/7v//xk8V5xjC8TFFBxNgYhsj9dXdzleXGEZsAeeC7Q739vwZr/31EVIj3DdGKWUek1E9gaOBX4kIg8AtwMvKqUOyHOcLuPxHcBPRGQEnmXzoL/9WuAkpdQLInIGnqVUCboeUAo3NmyxOEvBEXtEZDRwBXCZUkrhuV+WKq+37qlAi79rJ15PXc09wOdFpNU/zo4iMih0+P8CJ/n++EHAB/1thfgv3swcEdkR2BZ41X/taBEZISID8AK+M0RkArBRKXUjcDGwt7//aBE5wD9Oq4hYZ/q+BfM08Bs895huGDMEWOp/v08abwmfB82rwGQR2cF/firwSJHv6tjCcLMBR1wZ4LtVWoF+4AbgEv+1y4HbROQ04G4ys+rZQEpEXsCbRf8Gzw3yrIgIXsetk8wPUUo9KyLXAjP9TVcppZ4rItvlwO99t00/cIZSqsf7CGYCt+G5gm5USs0SkWPwAr9pvKbxn1dK9frB39+KyDC8e/HXeDENG3/Gc5UdZmz7Dp5bbIX/XyuCW/Hca2fjxRL0d+0WkU8DfxWRJJ6iuaLId3VsYbgqqQ6Hw+EIcO4jh8PhcAQ4peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwoOh8PhCHBKweFwOBwB/w9rIgmvO/MuNQAAAABJRU5ErkJggg==\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "# start the figure.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(weather['Local time'], weather['T'])\n", + "# label the axes\n", + "ax.set_xlabel(\"Date of observation\")\n", + "ax.set_ylabel(\"Temperature in Celsius\")\n", + "ax.set_title(\"Temperature Observations\")\n", + "# adjust the date labels, so that they look nicer\n", + "fig.autofmt_xdate()\n", + "# save the figure\n", + "fig.savefig('weather.png')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/747df499c1e18239511ea006e0433951/exercise1.py b/branch/rkdarst--dependengi-exercise-time/_downloads/747df499c1e18239511ea006e0433951/exercise1.py new file mode 100644 index 00000000..c2d285e8 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/747df499c1e18239511ea006e0433951/exercise1.py @@ -0,0 +1,47 @@ +""" +pylint exercise 1 +""" +import numpy as np +import pandas as pd +import matplotlib.pyplot as plt +from sklearn import linear_model + + +def f(x): + """ + Example function: + + f(x) = x/2 + 2 + """" + return 0.5*x + 2 + + +# Create example data +x_data = np.linspace(0, 10, 100) +err = 2 * np.random.random(x_data.shape[0]) +y_data = f(x_data) + err + +# Put data into dataframe +df = pd.DataFrame({'x': x_data, 'y': y_data}) + +# Create linear model and fit data +reg = linear_model.LinearRegression(fit_intercept=True) + +reg.fit(df[['x'], df[['y']]) + +slope = reg.coef_[0][0] +intercept = reg.intercept_[0] + +df['pred'] = reg.predict(df[['x']]) + +fig, ax = plt.subplots() + +ax.scater(df[['x']], df[['y']], alpha=0.5) +ax.plot(df[['x']], df[['pred']] + color='black', linestyle='--', + label=f'Prediction with slope {slope:.2f} and intercept {intercept:.2f}') +ax.set_ylabel('y') +ax.set_xlabel('x') +ax.legend() + +plt.show() diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py b/branch/rkdarst--dependengi-exercise-time/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py new file mode 100644 index 00000000..8742b5f6 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py @@ -0,0 +1,38 @@ +import yaml + +def get_parameters(config_file, required, defaults): + ''' + Parameters: + Optionfile: FileName of the yaml file containing the options + required: Dict of required argument names and their object types. + defaults: Dict of default parameters mapping to their default values + + Returns: An object with fields named according to required and optional values. + ''' + f = open(config_file) + options = yaml.safe_load(f) + # create a parameters object that allows setting attributes. + parameters = type('Options', (), {})() + # check required arguments + for arg in required: + if not arg in options: + raise Exception("Could not find required Argument " + arg + " aborting...") + else: + if not isinstance(options[arg],required[arg]): + raise Exception("Expected input of type " + str(required[arg]) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + # check the default values. + for arg in defaults: + if arg in options: + if not isinstance(options[arg],type(defaults[arg])): + #Wrong type for the parameter + raise Exception("Expected input of type " + str(type(defaults[arg])) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + else: + print( arg + " not found in option file. Using default: " +str(defaults[arg])) + setattr(parameters,arg,defaults[arg]) + return parameters + + diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/a99f82e01864794e5780d2697d273d9e/code_style_example.py b/branch/rkdarst--dependengi-exercise-time/_downloads/a99f82e01864794e5780d2697d273d9e/code_style_example.py new file mode 100644 index 00000000..89e55460 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/a99f82e01864794e5780d2697d273d9e/code_style_example.py @@ -0,0 +1,18 @@ +import numpy as np + +def PI_estimate(n): + """This function calculates an estimate of pi with dart thrower algorithm. + """ + + pi_Numbers = np.random.random(size = 2*n) + x = pi_Numbers[ :n ] + y = pi_Numbers[ n: ] + + return 4*np.sum((x * x + y*y ) < 1)/n + + +for number in range(1,8): + + n = 10** number + + print(f'Estimate for PI with {n:8d} dart throws: {PI_estimate( n )}') diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/b1df8a26f353860c500cc194df1641aa/exercise2_solution.py b/branch/rkdarst--dependengi-exercise-time/_downloads/b1df8a26f353860c500cc194df1641aa/exercise2_solution.py new file mode 100644 index 00000000..a8596fff --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/b1df8a26f353860c500cc194df1641aa/exercise2_solution.py @@ -0,0 +1,30 @@ +import numpy as np +import matplotlib.pyplot as plt + + +def dice_toss(n, m): + """Throw n dice m times and the total value together.""" + dice_rolls = np.random.randint(1, 6, size=(m, n)) + + roll_averages = np.sum(dice_rolls, axis=-1) + + return roll_averages + + +fig, ax = plt.subplots() + +n = int(input("Number of dices to toss:\n")) + +bins = np.arange(1, 6 * n + 1) + +m = 1000 + +ax.hist(dice_toss(n, m), bins=bins) + +ax.set_title(f"Histogram of {n} dice tosses") + +ax.set_xlabel("Total value") + +ax.set_ylabel("Number of instances") + +plt.show() diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/bd9ea3f34382e553b2a8efaca3708746/exercise1_solution.py b/branch/rkdarst--dependengi-exercise-time/_downloads/bd9ea3f34382e553b2a8efaca3708746/exercise1_solution.py new file mode 100644 index 00000000..09d1e9ed --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/bd9ea3f34382e553b2a8efaca3708746/exercise1_solution.py @@ -0,0 +1,47 @@ +""" +pylint exercise 1 +""" +import numpy as np +import pandas as pd +import matplotlib.pyplot as plt +from sklearn import linear_model + + +def f(x): + """ + Example function: + + f(x) = x/2 + 2 + """ + return 0.5*x + 2 + + +# Create example data +x_data = np.linspace(0, 10, 100) +err = 2 * np.random.random(x_data.shape[0]) +y_data = f(x_data) + err + +# Put data into dataframe +df = pd.DataFrame({'x': x_data, 'y': y_data}) + +# Create linear model and fit data +reg = linear_model.LinearRegression(fit_intercept=True) + +reg.fit(df[['x']], df[['y']]) + +slope = reg.coef_[0][0] +intercept = reg.intercept_[0] + +df['pred'] = reg.predict(df[['x']]) + +fig, ax = plt.subplots() + +ax.scatter(df[['x']], df[['y']], alpha=0.5) +ax.plot(df[['x']], df[['pred']], + color='black', linestyle='--', + label=f'Prediction with slope {slope:.2f} and intercept {intercept:.2f}') +ax.set_ylabel('y') +ax.set_xlabel('x') +ax.legend() + +plt.show() diff --git a/branch/rkdarst--dependengi-exercise-time/_downloads/c0ff880c08336404fab105236689d632/exercise2.py b/branch/rkdarst--dependengi-exercise-time/_downloads/c0ff880c08336404fab105236689d632/exercise2.py new file mode 100644 index 00000000..4f4ef02b --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_downloads/c0ff880c08336404fab105236689d632/exercise2.py @@ -0,0 +1,28 @@ +import numpy as np +import matplotlib.pyplot as plt + +def dice_toss(n,m): + + """Throw n dice m times and the total value together.""" + dice_rolls = np.random.randint(1,6,size=(m, n)) + + roll_averages = np.sum(dice_rolls,axis = -1) + + return roll_averages +fig,ax = plt.subplots( ) + +n = int( input('Number of dices to toss:\n')) + +bins = np.arange(1, 6 * n+1) + +m = 1000 + +ax.hist(dice_toss(n,m), bins = bins) + +ax.set_title(f'Histogram of {n} dice tosses') + +ax.set_xlabel('Total value' ) + +ax.set_ylabel('Number of instances') + +plt.show() diff --git a/branch/rkdarst--dependengi-exercise-time/_images/01_memory_layout.svg b/branch/rkdarst--dependengi-exercise-time/_images/01_memory_layout.svg new file mode 100644 index 00000000..93da7c68 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_images/01_memory_layout.svg @@ -0,0 +1,584 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How you see a matrix: + How NumPy sees a matrix: + [0,] + [1,] + [2,] + [3,] + [,0] + [,1] + [,2] + [,3] + [0] + [1] + [2] + [3] + [4] + [5] + [6] + [7] + [8] + [9] + [10] + [11] + [12] + [13] + [14] + [15] + + + + diff --git a/branch/rkdarst--dependengi-exercise-time/_images/01_table_dataframe.svg b/branch/rkdarst--dependengi-exercise-time/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/branch/rkdarst--dependengi-exercise-time/_images/02_views.svg b/branch/rkdarst--dependengi-exercise-time/_images/02_views.svg new file mode 100644 index 00000000..925354e0 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_images/02_views.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + array "a" + array "b" + .shape.strides + .shape.strides + + + + + data pointer + data pointer + memory buffer + + diff --git a/branch/rkdarst--dependengi-exercise-time/_images/anaconda-navigator-jupyterlab.png b/branch/rkdarst--dependengi-exercise-time/_images/anaconda-navigator-jupyterlab.png new file mode 100644 index 00000000..4ea0854f Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/anaconda-navigator-jupyterlab.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/anaconda-prompt.png b/branch/rkdarst--dependengi-exercise-time/_images/anaconda-prompt.png new file mode 100644 index 00000000..e4fcf79b Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/anaconda-prompt.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/binder.jpg b/branch/rkdarst--dependengi-exercise-time/_images/binder.jpg new file mode 100644 index 00000000..d04c467d Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/binder.jpg differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/exercise.png b/branch/rkdarst--dependengi-exercise-time/_images/exercise.png new file mode 100644 index 00000000..6bfedfb4 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/exercise.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/gapminder-larger-font.png b/branch/rkdarst--dependengi-exercise-time/_images/gapminder-larger-font.png new file mode 100644 index 00000000..cf7270ef Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/gapminder-larger-font.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/gapminder-linear.png b/branch/rkdarst--dependengi-exercise-time/_images/gapminder-linear.png new file mode 100644 index 00000000..78b30e77 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/gapminder-linear.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/gapminder-log.png b/branch/rkdarst--dependengi-exercise-time/_images/gapminder-log.png new file mode 100644 index 00000000..7b6c3208 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/gapminder-log.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/getting-started.png b/branch/rkdarst--dependengi-exercise-time/_images/getting-started.png new file mode 100644 index 00000000..8690a86f Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/getting-started.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/jupyterlab-notebook.png b/branch/rkdarst--dependengi-exercise-time/_images/jupyterlab-notebook.png new file mode 100644 index 00000000..900fdfd9 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/jupyterlab-notebook.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/jupyterlab-terminal.png b/branch/rkdarst--dependengi-exercise-time/_images/jupyterlab-terminal.png new file mode 100644 index 00000000..33a6b02a Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/jupyterlab-terminal.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/main-ui.png b/branch/rkdarst--dependengi-exercise-time/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/main-ui.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/notebook-ui.png b/branch/rkdarst--dependengi-exercise-time/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/notebook-ui.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/python_unmasked.jpg b/branch/rkdarst--dependengi-exercise-time/_images/python_unmasked.jpg new file mode 100644 index 00000000..57e3cc47 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/python_unmasked.jpg differ diff --git a/branch/rkdarst--dependengi-exercise-time/_images/tidy_data.png b/branch/rkdarst--dependengi-exercise-time/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_images/tidy_data.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/binder.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/binder.rst.txt new file mode 100644 index 00000000..099cf169 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/binder.rst.txt @@ -0,0 +1,196 @@ +Binder +====== + +.. questions:: + + - Why sharing code alone may not be sufficient. + - How to share a computational environment? + - What is Binder? + - How to binderize my Python repository? + - How to publish my Python repository? + +.. objectives:: + + - Learn about reproducible computational environments. + - Learn to create and share custom computing environments with Binder. + - Learn to get a DOI from Zenodo for a repository. + + +Why is it sometimes not enough to share your code? +-------------------------------------------------- + +.. image:: img/binder/python_unmasked.jpg + + +Exercise 1 +~~~~~~~~~~ + +.. challenge:: Binder-1: Discuss better strategies than only code sharing (10 min) + + Lea is a PhD student in computational biology and after 2 years of intensive + work, she is finally ready to publish her first paper. The code she has used + for analyzing her data is available on GitHub but her supervisor who is an + advocate of open science told her that sharing code is not sufficient. + + **Why is it possibly not enough to share "just" your code? + What problems can you anticipate 2-5 years from now?** + + We form small groups (4-5 persons) and discuss in groups. If the workshop is + online, each group will join a breakout room. + If joining a group is not possible or practical, we use the shared document + to discuss this collaboratively. + + Each group write a summary (bullet points) of the discussion in the workshop + shared document (the link will be provided by your instructors). + + +Sharing a computing environment with Binder +------------------------------------------- + +`Binder `__ allows you to create +custom computing environments that can be shared and used by many remote users. +It uses `repo2docker `__ to +create a container image (`docker `__ image) of a +project using information contained in included configuration files. + +Repo2docker is a standalone package that you can install locally on your laptop +but an `online Binder `__ service is freely available. +This is what we will be using in the tutorial. + +The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder. + +.. image:: https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png + +Credit: `Juliette Taka, Logilab and the OpenDreamKit project (2017) `_ + + +Binder exercise/demo +~~~~~~~~~~~~~~~~~~~~ + +In an earlier episode (Data visualization with Matplotlib) we have created this notebook: + +.. code-block:: python + + import pandas as pd + import matplotlib.pyplot as plt + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + data_2007 = data[data["year"] == 2007] + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xscale("log") + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + +We will now first share it via `GitHub `__ "statically", +then using `Binder `__. + +.. challenge:: Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min) + + Instructor demonstrates this: + + - Creates a GitHub repository + - Uploads the notebook file + - Then we look at the statically rendered version of the notebook on GitHub + - Create a ``requirements.txt`` file which contains: + + .. code-block:: none + + pandas==1.2.3 + matplotlib==3.4.2 + + - Commit and push also this file to your notebook repository. + - Visit https://mybinder.org and copy paste the code under "Copy the text below ..." into your `README.md`: + + .. image:: img/binder/binder.jpg + + - Check that your notebook repository now has a "launch binder" + badge in your `README.md` file on GitHub. + - Try clicking the button and see how your repository is launched + on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud. + - Enjoy being fully reproducible! + + +How can I get a DOI from Zenodo? +--------------------------------- + +`Zenodo `__ is a general purpose open-access +repository built and operated by `CERN `__ and `OpenAIRE +`__ that allows researchers to archive and get a +`Digital Object Identifier (DOI) `__ to data that they +share. + +.. challenge:: Binder-3: Link a Github repository with Zenodo (optional) + + **Everything you deposit on Zenodo is meant to be kept (long-term archive). + Therefore we recommend to practice with the Zenodo "sandbox" (practice/test area) + instead:** https://sandbox.zenodo.org + + 1. **Link GitHub with Zenodo**: + + - Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing). + - Log in to Zenodo with your GitHub account. Be aware that you may need to + authorize Zenodo application (Zenodo will redirect you back to GitHub for + Authorization). + - Choose the repository webhooks options. + - From the drop-down menu next to your email address at the top of the page, select GitHub. + - You will be presented with a list of all your Github repositories. + + 2. **Archiving a repo**: + + - Select a repository you want to archive on Zenodo. + - Toggle the "on" button next to the repository ou need to archive. + - Click on the Repo that you want to reserve. + - Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release. + + 3. **Trigger Zenodo to Archive your repository** + + - Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI. + - If this is the first release of your code then you should give it a + version number of v1.0.0. Add description for your release then click the + Publish release button. + - Zenodo takes an archive of your GitHub repository each time you create a new Release. + + 4. **To ensure that everything is working**: + + - Go to https://zenodo.org/account/settings/github/ (or the corresponding + sandbox at https://sandbox.zenodo.org/account/settings/github/), or the + Upload page (https://zenodo.org/deposit), you will find your repo is + listed. + - Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo. + - You can edit the archive on Zenodo and/or publish a new version of your software. + - It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata + manually, you can also add a ``.zenodo.json`` or a ``CITATION.cff`` file to your repo and Zenodo will infer the metadata from this file. + - Your code is now published on a Github public repository and archived on Zenodo. + - Update the README file in your repository with the newly created zenodo badge. + + +Create a Binder link for your Zenodo DOI +---------------------------------------- + +Rather than specifying a GitHub repository when launching binder, you can instead use a Zenodo DOI. + +.. challenge:: Binder-4: Link Binder with Zenodo (10 min) + + We will be using an existing Zenodo DOI `10.5281/zenodo.3886864 `_ to start Binder: + + - Go to `https://mybinder.org `__ and fill information using Zenodo DOI (as shown on the animation below): + + .. image:: https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif + + - You can also get a Binder badge and update the README file in the + repository. It is good practice to add both the Zenodo badge and the + corresponding Binder badge. + +.. keypoints:: + + - It is easy to sharing reproducible computational environments + - Binder provides a way for anyone to test and run code - without + you needing to set up a dedicated server for it. + - Zenodo provides permanent archives and a DOI. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/data-formats.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/data-formats.rst.txt new file mode 100644 index 00000000..b106651f --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/data-formats.rst.txt @@ -0,0 +1,818 @@ +Data formats with Pandas and Numpy +================================== + +.. questions:: + + - How do you store your data right now? + - Are you doing data cleaning / preprocessing every time you load the data? + +.. objectives:: + + - Learn the distinguishing characteristics of different data formats. + - Learn how you can read and write data in a variety of formats. + +What is a data format? +---------------------- + +Data format can mean two different things + +1. `data structure `__ or how you're storing the data in memory while you're working on it; +2. `file format `__ or the way you're storing the data in the disk. + +Let's consider this randomly generated DataFrame with various columns:: + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.info() + +This DataFrame is structured in the tidy data format. +In tidy data format we have multiple columns of data that are collected in a Pandas DataFrame. + +.. image:: img/pandas/tidy_data.png + +Let's consider another example:: + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + np.info(data_array) + + +Here we have a different data structure: we have a two-dimentional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block instead of individual columns. +This also means that the whole array must have one data type. + + +.. figure:: https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png + + Source: `Elegant Scipy `__ + +Now the question is: **Can the data be saved to the disk without changing the data format?** + +For this we need a **file format** that can easily store our **data structure**. + +.. admonition:: Data type vs. data structure vs. file format + :class: dropdown + + - **Data type:** Type of a single piece of data (integer, string, float, ...). + - **Data structure:** How the data is organized in memory (individual columns, 2D-array, nested dictionaries, ...). + - **File format:** How the data is organized when it is saved to the disk (columns of strings, block of binary data, ...). + + For example, a black and white image stored as a .png-file (**file format**) + might be stored in memory as an NxM array (**data structure**) of integers (**data type**). + +What to look for in a file format? +---------------------------------- + +When deciding which file format you should use for your program, you should remember the following: + +**There is no file format that is good for every use case.** + +Instead, there are various standard file formats for various use cases: + +.. figure:: https://imgs.xkcd.com/comics/standards.png + + Source: `xkcd #927 `__. + +Usually, you'll want to consider the following things when choosing a file format: + +1. Is the file format good for my data structure (is it fast/space efficient/easy to use)? +2. Is everybody else / leading authorities in my field recommending a certain format? +3. Do I need a human-readable format or is it enought to work on it using code? +4. Do I want to archive / share the data or do I just want to store it while I'm working? + +Pandas supports `many file formats `__ for tidy data and Numpy supports `some file formats `__ for array data. +However, there are many other file formats that can be used through other libraries. + +Table below describes some data formats: + +.. list-table:: + :header-rows: 1 + + * - | Name: + - | Human + | readable: + - | Space + | efficiency: + - | Arbitrary + | data: + - | Tidy + | data: + - | Array + | data: + - | Long term + | storage/sharing: + + * - :ref:`Pickle ` + - ❌ + - 🟨 + - ✅ + - 🟨 + - 🟨 + - ❌ + + * - :ref:`CSV ` + - ✅ + - ❌ + - ❌ + - ✅ + - 🟨 + - ✅ + + * - :ref:`Feather ` + - ❌ + - ✅ + - ❌ + - ✅ + - ❌ + - ❌ + + * - :ref:`Parquet ` + - ❌ + - ✅ + - 🟨 + - ✅ + - 🟨 + - ✅ + + * - :ref:`npy ` + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + - ❌ + + * - :ref:`HDF5 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`NetCDF4 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`JSON ` + - ✅ + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + + * - :ref:`Excel ` + - ❌ + - ❌ + - ❌ + - 🟨 + - ❌ + - ✅ + + * - :ref:`Graph formats ` + - 🟨 + - 🟨 + - ❌ + - ❌ + - ❌ + - 🟨 + +.. important:: + + - ✅ : Good + - 🟨 : Ok / depends on a case + - ❌ : Bad + + +Storing arbitrary Python objects +-------------------------------- + + +.. _pickle: + +Pickle +****** + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** None (:mod:`pickle`-module is included with Python). + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** 🟨 + - **Array data:** 🟨 + - **Long term archival/sharing:** ❌! See warning below. + - **Best use cases:** Saving Python objects for debugging. + +.. warning:: + + Loading pickles that you have not created is + risky as they can contain arbitrary executable code. + + Do not unpickle objects from sources that you do not trust! + +:mod:`Pickle ` is Python's own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:: + + import pickle + + with open('data_array.pickle', 'wb') as f: + pickle.dump(data_array, f) + + with open('data_array.pickle', 'rb') as f: + data_array_pickle = pickle.load(f) + + +Exercise 1 +---------- + +.. challenge:: + + - Create an arbitrary python object (for example, a string or a list). Pickle it. + + Read the pickled object back in and check if it matches the original one. + +.. solution:: + + .. code-block:: python + + import pickle + + my_object=['test', 1, 2, 3] + + with open('string.pickle', 'wb') as f: + pickle.dump(my_object, f) + + + with open('string.pickle', 'rb') as f: + my_pickled_object = pickle.load(f) + + print(my_object, my_pickled_object) + print(my_object == my_pickled_object) + + +Storing tidy data +----------------- + +.. _csv: + +CSV (comma-separated values) +**************************** + +.. admonition:: Key features + + - **Type:** Text format + - **Packages needed:** numpy, pandas + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data. Small data. Data that needs to be human-readable. + +CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you're working with big data. + +Pandas has a very nice interface for writing and reading CSV files with `to_csv `__- and `read_csv `__-functions:: + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + +Numpy has `routines `__ for saving and loading arrays as CSV files as well:: + + np.savetxt('data_array.csv', data_array) + + data_array_csv = np.loadtxt('data_array.csv') + +.. admonition:: Storing data in CSVs can reduce data precision + :class: dropdown + + When working with floating point numbers you should be careful to save the data with enough decimal places so that you won't lose precision. + + For example, double-precision floating point numbers have `~16 decimal places of precision `__, but if you use normal Python to write these numbers, you can easily lose some of that precision. + Let's consider the following example: + + .. code-block:: python + + import numpy as np + test_number = np.sqrt(2) + # Write the number in a file + test_file = open('sqrt2.csv', 'w') + test_file.write('%f' % test_number) + test_file.close() + # Read the number from a file + test_file = open('sqrt2.csv', 'r') + test_number2 = np.float64(test_file.readline()) + test_file.close() + # Calculate the distance between these numbers + print(np.abs(test_number - test_number2)) + + CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. + We can check whether our written data matches the generated data: + + .. code-block:: python + + dataset.compare(dataset_csv) + + np.all(data_array == data_array_csv) + + In our case some rows of ``dataset_csv`` loaded from CSV do not match the original ``dataset`` as the last decimal can sometimes be rounded due to `complex technical reasons `__. + + Storage of these high-precision CSV files is usually very inefficient storage-wise. + + Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems. + + +.. _feather: + + +Feather +******* + +.. admonition:: Requires additional packages + :class: dropdown + + + Using Feather requires `pyarrow-package `__ to be installed. + + You can try installing pyarrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** ❌ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Temporary storage of tidy data. + +`Feather `__ is a file format for storing data frames quickly. +There are libraries for Python, R and Julia. + +We can work with Feather files with :external+pandas:ref:`to_feather- and read_feather-functions `:: + + dataset.to_feather('dataset.feather') + dataset_feather = pd.read_feather('dataset.feather') + +Feather is not a good format for storing array data, so we won't present an example of that here. + + +.. _parquet: + + +Parquet +******* + +.. admonition:: Requires additional packages + :class: dropdown + + Using Parquet requires `pyarrow-package `__ to be installed. + + You can try installing PyArrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** 🟨 + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in tidy data format. Archival of said data. + +`Parquet `__ is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.). + +We can work with Parquet files with :external+pandas:ref:`to_parquet- and read_parquet-functions `:: + + dataset.to_parquet('dataset.parquet') + dataset_parquet = pd.read_parquet('dataset.parquet') + +Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won't do that here. + + +Exercise 2 +---------- + +.. challenge:: + + - Create the example ``dataset``: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + - Save the dataset ``dataset`` as CSV. Load the dataset into a variable ``dataset_csv``. + - Use ``dataset.compare(dataset_csv)`` to check if loaded dataset matches the original one. + +.. solution:: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + + print(dataset.compare(dataset_csv)) + + Dataset might not be completely the same. Sometimes the CSV format cannot + fully represent a floating point value, which will result in rounding errors. + +Storing array data +------------------ + + +.. _npy: + + +npy (numpy array format) +************************ + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** numpy + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Saving numpy arrays temporarily. + +If you want to temporarily store numpy arrays, you can use the :func:`numpy.save`- and :func:`numpy.load`-functions:: + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + +There also exists :func:`numpy.savez`-function for storing multiple datasets in a single file:: + + np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array) + data_arrays = np.load('data_arrays.npz') + data_arrays['data_array0'] + +For big arrays it's good idea to check other binary formats such as HDF5 or NetCDF4. + +``np.save``- and ``np.savez``-functions work with +`sparse matrices `__, +but one can also use dedicated +`scipy.sparse.save_npz `__- and +`scipy.sparse.load_npz `__-functions. +Storing sparse matrices using these functions can give huge storage savings. + + +.. _hdf5: + + +HDF5 (Hierarchical Data Format version 5) +***************************************** + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** numpy, pandas, PyTables, h5py + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. + +HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences. + +Pandas allows you to store tables as HDF5 with `PyTables `_, which uses HDF5 to write the files. +You can create a HDF5 file with :external+pandas:ref:`to_hdf- and read_parquet-functions `:: + + dataset.to_hdf('dataset.h5', key='dataset', mode='w') + dataset_hdf5 = pd.read_hdf('dataset.h5') + +PyTables comes installed with the default Anaconda installation. + +For writing data that is not a table, you can use the excellent `h5py-package `__:: + + import h5py + + # Writing: + + # Open HDF5 file + h5_file = h5py.File('data_array.h5', 'w') + # Write dataset + h5_file.create_dataset('data_array', data=data_array) + # Close file and write data to disk. Important! + h5_file.close() + + # Reading: + + # Open HDF5 file again + h5_file = h5py.File('data_array.h5', 'r') + # Read the full dataset + data_array_h5 = h5_file['data_array'][()] + # Close file + h5_file.close() + +h5py comes with Anaconda as well. + + +.. _netcdf4: + + +NetCDF4 (Network Common Data Form version 4) +******************************************** + +.. admonition:: Requires additional packages + :class: dropdown + + Using NetCDF4 requires `netCDF4 `__- or `h5netcdf `__-package to be installed. + h5netcdf is often mentioned as being faster to the official netCDF4-package, so we'll be using it in the example. + + A great NetCDF4 interface is provided by a `xarray-package `__. + + You can try installing these packages with + + .. code-block:: bash + + !pip install h5netcdf xarray + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** pandas, netCDF4/h5netcdf, xarray + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets. + +NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs. + +NetCDF4 is a common format for storing large data from big simulations in physical sciences. + +Using interface provided by ``xarray``:: + + # Write tidy data as NetCDF4 + dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf') + # Read tidy data from NetCDF4 + import xarray as xr + dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf') + dataset_netcdf4 = dataset_xarray.to_pandas() + dataset_xarray.close() + +Working with array data is easy as well:: + + # Write array data as NetCDF4 + xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf') + # Read array data from NetCDF4 + data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf') + data_array_netcdf4 = data_array_xarray.to_numpy() + data_array_xarray.close() + +The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (``x``, ``y``, ``z``) or timestamps (``t``) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis. + +Exercise 3 +---------- + +.. challenge:: + + - Create an example numpy array: + + .. code-block:: python + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + - Store the array as a npy. + - Read the dataframe back in and compare it to the original one. Does the data match? + +.. solution:: + + .. code-block:: python + + import numpy as np + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + np.all(data_array == data_array_npy) + + +Other file formats +------------------ + + +.. _json: + +JSON (JavaScript Object Notation) +********************************* + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** None (:mod:`json`-module is included with Python). + - **Space efficiency:** ❌ + - **Arbitrary data:** 🟨 + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Saving nested/relational data, storing web requests. + +JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.). + +You rarely want to keep your data in this format, unless you're working with +nested data with multiple layers or lots of interconnections. + +Similarly to other popular files, Pandas can write and read json files with :meth:`~pandas.DataFrame.to_json`- and :func:`~pandas.read_json`-functions:: + + dataset.to_json('dataset.json') + dataset_json = pd.read_json('dataset.json') + + +.. _excel: + +Excel +***** + +.. admonition:: Requires additional packages + :class: dropdown + + Using Excel files with Pandas requires `openpyxl `__-package to be installed. + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** `openpyxl `__ + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** 🟨 + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data in many fields. Quick data analysis. + +Excel is very popular in social sciences and economics. +However, it is `not a good format `__ for data science. + +See Pandas' documentation on :external+pandas:ref:`working with Excel files `. + + +.. _graph: + +Graph formats (adjency lists, gt, GraphML etc.) +*********************************************** + +.. admonition:: Key features + + - **Type**: Many different formats + - **Packages needed:** Depends on a format. + - **Space efficiency:** 🟨 + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** 🟨 + - **Best use cases:** Saving graphs or data that can be represented as a graph. + +There are plenty of data formats for storing graphs. +We won't list them here as optimal data format depends heavily on the graph structure. + +One can use functions in libraries such as +`networkx `__, +`graph-tool `__, +`igraph `__ +to read and write graphs. + + + +Benefits of binary file formats +------------------------------- + +Binary files come with various benefits compared to text files. + +1. They can represent floating point numbers with full precision. +2. Storing data in binary format can potentially save lots of space. + This is because you do not need to write numbers as characters. + Additionally some file formats support compression of the data. +3. Data loading from binary files is usually much faster than loading from text files. + This is because memory can be allocated for the data before data is loaded as the type of data in columns is known. +4. You can often store multiple datasets and metadata to the same file. +5. Many binary formats allow for partial loading of the data. + This makes it possible to work with datasets that are larger than your computer's memory. + +**Performance with tidy dataset:** + +For the tidy ``dataset`` we had, we can test the performance of the different file formats: + +.. csv-table:: + :file: format_comparison_tidy.csv + :header-rows: 1 + +The relatively poor performance of HDF5-based formats in this case is due to the data being mostly one dimensional columns full of character strings. + + +**Performance with data array:** + +For the array-shaped ``data_array`` we had, we can test the performance of the different file formats: + + +.. csv-table:: + :file: format_comparison_array.csv + :header-rows: 1 + +For this kind of a data, HDF5-based formats perform much better. + + +Things to remember +------------------ + +1. **There is no file format that is good for every use case.** +2. Usually, your research question determines which libraries you want to use to solve it. + Similarly, the data format you have determines file format you want to use. +3. However, if you're using a previously existing framework or tools or you work in a specific field, you should prioritize using the formats that are used in said framework/tools/field. +4. When you're starting your project, it's a good idea to take your initial data, clean it, and store the results in a good binary format that works as a starting point for your future analysis. + If you've written the cleaning procedure as a script, you can always reproduce it. +5. Throughout your work, you should use code to turn important data to human-readable format (e.g. plots, averages, :meth:`pandas.DataFrame.head`), not to keep your full data in a human-readable format. +6. Once you've finished, you should store the data in a format that can be easily shared to other people. + + +See also +-------- + +- `Pandas' IO tools `__ +- `Tidy data comparison notebook `__ +- `Array data comparison notebook `__ + + +.. keypoints:: + + - Pandas can read and write a variety of data formats. + - There are many good, standard formats, and you don't need to create your own. + - There are plenty of other libraries dedicated to various formats. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/data-visualization.md.txt b/branch/rkdarst--dependengi-exercise-time/_sources/data-visualization.md.txt new file mode 100644 index 00000000..7b2c490d --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/data-visualization.md.txt @@ -0,0 +1,544 @@ +# Data visualization with Matplotlib + +```{questions} +- What happens if you can't automatically produce plots? +- When to use Matplotlib for data visualization? +- When to prefer other libraries? +``` + +```{objectives} +- Be able to create simple plots with Matplotlib and tweak them +- Know about object-oriented vs pyplot interfaces of Matplotlib +- Be able to adapt gallery examples +- Know how to look for help +- Know that other tools exist +``` + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **Try to minimize manual post-processing**. This could bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Vega-Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization, statistics built in + (we have an [entire lesson about data visualization using Vega-Altair](https://coderefinery.github.io/data-visualization-python/)) + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/gallery/index.html): + Jupyter Notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative. + + +## Why are we starting with Matplotlib? + +- Matplotlib is perhaps the most popular Python plotting library. +- Many libraries build on top of Matplotlib (example: [Seaborn](https://seaborn.pydata.org/examples/index.html)). +- MATLAB users will feel familiar. +- Even if you choose to use another library (see above list), chances are high + that you need to adapt a Matplotlib plot of somebody else. +- Libraries that are built on top of Matplotlib may need knowledge of Matplotlib + for custom adjustments. + +However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code. + +Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. + + +## Getting started with Matplotlib + +We can start in a Jupyter Notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK. + +Let us create our first plot using +{func}`~matplotlib.pyplot.subplots`, +{obj}`~matplotlib.axes.Axes.scatter`, and some other methods on the +{obj}`~matplotlib.axes.Axes` object: + +```python +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("my-first-plot.png") +``` + +```{figure} data-visualization/first-plot/getting-started.png +:alt: Result of our first plot +:width: 80% + +This is the result of our first plot. +``` + +When running a Matplotlib script on a remote server without a +"display" (e.g. compute cluster), you may need to add the +{obj}`matplotlib.use` call: + +```python +import matplotlib.pyplot as plt +matplotlib.use("Agg") + +# ... rest of the script +``` + +## Exercise: Matplotlib + +````{challenge} Exercise Matplotlib-1: extend the previous example (15 min) +- Extend the previous plot by also plotting this set of values but this time + using a different color (`#56B4E9`): + ```python + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + ``` + +- Then add another color (`#009E73`) which plots the second dataset, scaled + by 2.0. + ```python + # here we multiply all elements of data2_y by 2.0 + data2_y_scaled = [y * 2.0 for y in data2_y] + ``` + +- Try to add a legend to the plot with {meth}`matplotlib.axes.Axes.legend` and searching the web for clues on + how to add labels to each dataset. + You can also consult this great + [quick start guide](https://matplotlib.org/stable/users/explain/quick_start.html). + +- At the end it should look like this one: + ```{figure} data-visualization/first-plot/exercise.png + :alt: Result of the exercise + ``` + +- Experiment also by using named colors (e.g. "red") instead of the hex-codes. +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 9, 12, 17-18, 23 +--- +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +# this is dataset 2 +data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + +# here we multiply all elements of data2_y by 2.0 +data2_y_scaled = [y * 2.0 for y in data2_y] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00", label="set 1") +ax.scatter(x=data_x, y=data2_y, c="#56B4E9", label="set 2") +ax.scatter(x=data_x, y=data2_y_scaled, c="#009E73", label="set 2 (scaled)") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") +ax.legend() + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("exercise-plot.png") +``` +```` + +```{discussion} Why these colors? +This qualitative color palette is opimized for all color-vision +deficiencies, see and +[Okabe, M., and K. Ito. 2008. "Color Universal Design (CUD): +How to Make Figures and Presentations That Are Friendly to Colorblind People"](http://jfly.iam.u-tokyo.ac.jp/color/). +``` + +--- + +## Matplotlib has two different interfaces + +When plotting with Matplotlib, it is useful to know and understand that +there are **two approaches** even though the reasons of this dual approach is +outside the scope of this lesson. + +- The more modern option is an **object-oriented interface** or **explicit interface** (the + {class}`fig ` and {class}`ax ` objects + can be configured separately and passed around to functions): + ```{code-block} python + --- + emphasize-lines: 8-14 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + ``` + +- The more traditional option mimics MATLAB plotting and uses the + **pyplot interface** or **implicit interface** ({mod}`plt ` carries + the global settings): + ```{code-block} python + --- + emphasize-lines: 8-12 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + plt.scatter(x=data_x, y=data_y, c="#E69F00") + + plt.xlabel("we should label the x axis") + plt.ylabel("we should label the y axis") + plt.title("some title") + ``` + +When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, **we +recommend to learn and use the object oriented interface.** + +```{discussion} Why do we emphasize this? +One day you may want to write functions which wrap +around Matplotlib function calls and then you can send {class}`~matplotlib.figure.Figure` and {class}`~matplotlib.axes.Axes` +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions. + +When using the pyplot interface, settings are modified for the entire +{mod}`matplotlib.pyplot` package. The latter is acceptable for simple scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls. +``` + +--- + +## Styling and customizing plots + +- Before you customize plots "manually" using a graphical program, please + consider how this affects reproducibility. +- **Try to minimize manual post-processing**. This might bite you when you + need to regenerate 50 figures one day before submission deadline or + regenerate a set of figures after the person who created them left the group. +- Matplotlib and also all the other libraries allow to customize almost every aspect of a plot. +- It is useful to study [Matplotlib parts of a figure](https://matplotlib.org/stable/users/explain/quick_start.html#parts-of-a-figure) + so that we know what to search for to customize things. +- Matplotlib cheatsheets: +- You can also select among pre-defined themes/ + [style + sheets](https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html) + with {obj}`~matplotlib.style.use`, for instance: + ```python + plt.style.use('ggplot') + ``` + + +## Exercises: Styling and customization + +Here are 3 exercises where we try to adapt existing scripts to either **tweak +how the plot looks** (exercises 1 and 2) or to **modify the input data** (example 3). + +This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice: +- Select an example that is close to what you have in mind +- Being able to adapt it to your needs +- Being able to search for help +- Being able to understand help request answers (not easy) + +````{challenge} Exercise Customization-1: log scale in Matplotlib (15 min) +In this exercise we will learn how to use log scales. + +- To demonstrate this we first fetch some data to plot: + ```python + import pandas as pd + + url = ( + "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + ) + gapminder_data = pd.read_csv(url).query("year == 2007") + + gapminder_data + ``` +- Try the above snippet in a notebook and it will give you an overview over the data. + +- Then we can plot the data, first using a linear scale: + ```python + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + + ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) + + ax.set_xlabel("GDP per capita (PPP dollars)") + ax.set_ylabel("Life expectancy (years)") + ``` + + This is the result but we realize that a linear scale is not ideal here: + ```{figure} data-visualization/customizing/gapminder-linear.png + :alt: Gapminder data plotted using a linear scale + ``` + +- Your task is to switch to a log scale and arrive at this result: + ```{figure} data-visualization/customizing/gapminder-log.png + :alt: Gapminder data plotted using log scale + ``` + +- What does ``alpha=0.5`` do? +```` + +````{solution} +See {meth}`ax.set_xscale() `. + +```{code-block} python +--- +emphasize-lines: 5 +--- +fig, ax = plt.subplots() + +ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP per capita (PPP dollars)") +ax.set_ylabel("Life expectancy (years)") +``` +* {obj}`alpha ` sets transparency + of points. +```` + +````{challenge} Exercise Customization-2: preparing a plot for publication (15 min) +Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches. + +For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small. + +Your task is to make the tickmarks and the axis label font larger, using +[Matplotlib parts of a figure](https://matplotlib.org/stable/users/explain/quick_start.html#parts-of-a-figure) +and web search, and to arrive at this: + +```{figure} data-visualization/customizing/gapminder-larger-font.png +:alt: Gapminder data plotted with larger font and larger ticks +``` +```` + +````{solution} +See {meth}`ax.tick_params `. + +```{code-block} python +--- +emphasize-lines: 7-8, 10-12 +--- +fig, ax = plt.subplots() + +ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data) + +ax.set_xscale("log") + +ax.set_xlabel("GDP per capita (PPP dollars)", fontsize=15) +ax.set_ylabel("Life expectancy (years)", fontsize=15) + +ax.tick_params(which="major", length=10) +ax.tick_params(which="minor", length=5) +ax.tick_params(labelsize=15) +``` +```` + +````{challenge} Exercise Customization-3: adapting a gallery example +**This is a great exercise which is very close to real life.** + +- Your task is to select one visualization library (some need to be installed first - in + doubt choose Matplotlib or Seaborn since they are part of Anaconda installation): + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Vega-Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization, statistics built in + (we have an [entire lesson about data visualization using Vega-Altair](https://coderefinery.github.io/data-visualization-python/)) + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/gallery/index.html): + Jupyter Notebook extension for 3D visualization + +- Browse the various example galleries (links above). +- Select one example that is close to your recent visualization project or simply interests you. +- Note that you might need to install additional Python packages in order make use of the libraries. + This could be the visualization library itself, and in addition also any required dependency package. +- First try to reproduce this example in the Jupyter Notebook. +- Then try to print out the data that is used in this example just before the call of the plotting function + to learn about its structure. Is it a pandas dataframe? Is it a NumPy array? Is it a dictionary? A list? + a list of lists? +- Then try to modify the data a bit. +- If you have time, try to feed it different, simplified data. + This will be key for adapting the examples to your projects. + +Example "solution" for such an exploration below. +```` + +````{solution} An example exploration +- Let us imagine we were browsing +- And this example plot caught our eye: +- Try to run it in the notebook. +- The `d` seems to be the data. Right before the call to `sns.violinplot`, add a `print(d)`: + ```{code-block} python + --- + emphasize-lines: 12 + --- + import numpy as np + import seaborn as sns + + sns.set_theme() + + # Create a random dataset across several variables + rs = np.random.default_rng(0) + n, p = 40, 8 + d = rs.normal(0, 2, (n, p)) + d += np.log(np.arange(1, p + 1)) * -5 + 10 + + print(d) + + # Show each distribution with both violins and points + sns.violinplot(data=d, palette="light:g", inner="points", orient="h") + ``` +- The print reveals that `d` is a NumPy array and looks like a two-dimensional list: + ```text + [[10.25146044 6.27005437 5.78778386 3.27832843 0.88147169 1.76439276 2.87844934 1.49695422] + [ 8.59252953 4.00342116 3.26038963 3.15118015 -2.69725111 0.60361933 -2.22137264 -1.86174242] + ... many more lines ... + [12.45950762 4.32352988 6.56724895 3.42215312 0.34419915 0.46123886 -1.56953795 0.95292133]] + ``` +- Now let's try with a much simplified two-dimensional list: + ```{code-block} python + --- + emphasize-lines: 12, 13 + --- + # import numpy as np + import seaborn as sns + + sns.set_theme() + + # # Create a random dataset across several variables + # rs = np.random.default_rng(0) + # n, p = 40, 8 + # d = rs.normal(0, 2, (n, p)) + # d += np.log(np.arange(1, p + 1)) * -5 + 10 + + d = [[1.0, 2.0, 2.0, 3.0, 3.0, 3.0], + [1.0, 1.0, 1.0, 2.0, 2.0, 3.0]] + + # Show each distribution with both violins and points + sns.violinplot(data=d, palette="light:g", inner="points", orient="h") + ``` +- Seems to work! And finally we arrive at a working example with our own data with all + the "clutter" removed: + ```python + import seaborn as sns + + # l1 and l2 are note great names but they will do for a quick test + l1 = [1.0, 2.0, 2.0, 3.0, 3.0, 3.0] + l2 = [1.0, 1.0, 1.0, 2.0, 2.0, 3.0] + + sns.violinplot(data=[l1, l2], palette="light:g", inner="points", orient="h") + ``` +- And now we can focus the rest of our work to read our real data. +- Finally we can customize the plot, e.g. web search for "seaborn violin plot axis labels" + and add `ax.set_yticklabels(['dataset 1', 'dataset 2'])`. +```` + +--- + +```{discussion} +After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on. +``` + +--- + +## Matplotlib and pandas DataFrames + +In the above exercises we have sent individual columns of the `gapminder_data` DataFrame +into `ax.scatter()` like this: +```python +fig, ax = plt.subplots() + +ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5) +``` + +It is possible to do this instead and let Matplotlib "unpack" the columns: +```python +fig, ax = plt.subplots() + +ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data) +``` + +Other input types are possible. See [Types of inputs to plotting +functions](https://matplotlib.org/stable/users/explain/quick_start.html#types-of-inputs-to-plotting-functions). + +--- + +```{keypoints} +- Minimize manual post-processing, script everything. +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Figures for presentation slides and figures for manuscripts have + different requirements. +- Think about color-vision deficiencies when choosing colors. Use + existing solutions for this problem. +``` diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/dependencies.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/dependencies.rst.txt new file mode 100644 index 00000000..eca6fd50 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/dependencies.rst.txt @@ -0,0 +1,501 @@ +.. _dependency_management: + +Dependency management +===================== + +.. questions:: + + - Do you expect your code to work in one year? Five? What if it + uses ``numpy`` or ``tensorflow`` or ``random-github-package`` ? + - How can my collaborators get the same results as me? What about + future me? + - How can my collaborators easily install my codes with all the necessary dependencies? + - How can I make it easy for my colleagues to reproduce my results? + - How can I work on two (or more) projects with different and conflicting dependencies? + +.. objectives:: + + - Learn how to record dependencies + - Be able to communicate the dependencies as part of a report/thesis/publication + - Learn how to use isolated environments for different projects + - Simplify the use and reuse of scripts and projects + + +How do you track dependencies of your project? +---------------------------------------------- + +* **Dependency**: Reliance on a external component. In this case, a + separately installed software package such as ``numpy``. + + + +Exercises 1 +----------- + +.. challenge:: Dependencies-1: Discuss dependency management (5 min) + + Please discuss **in breakout rooms** and answer via **collaborative document** the + following questions: + + - How do you install Python packages (libraries) that you use in your work? + From PyPI using pip? From other places using pip? Using conda? + - How do you track/record the dependencies? Do you write them into a file or README? Into + ``requirements.txt`` or ``environment.yml``? + - If you track dependencies in a file, why do you do this? + - Have you ever experienced that a project needed a different version of a Python + library than the one on your computer? If yes, how did you solve it? + + +.. _pypi: + +PyPI (The Python Package Index) and (Ana)conda +---------------------------------------------- + +- PyPI (The Python Package Index) and Conda are popular packaging/dependency + management tools. + +- When you run ``pip install`` you typically install from `PyPI + `__ but you can also ``pip install`` from a GitHub + repository and similar. + +- When you run ``conda install`` you typically install from `Anaconda Cloud + `__ where there are conda channels maintained + by Anaconda Inc. and by various communities. + + +Why are there two ecosystems? + + +.. admonition:: PyPI + + - **Installation tool:** ``pip`` + - **Summary:** PyPI is traditionally used for Python-only packages or + for Python interfaces to external libraries. There are also packages + that have bundled external libraries (such as numpy). + - **Amount of packages:** Huge number. Old versions are supported for + a long time. + - **How libraries are handled:** If your code depends on external + libraries or tools, these things need to be either included in the + pip-package or provided via some other installation system (like + operating system installer or manual installation). + - **Pros:** + - Easy to use + - Package creation is easy + - **Cons:** + - Installing packages that need external libraries can be complicated + +.. admonition:: Conda + + - **Installation tool:** ``conda`` or ``mamba`` + - **Summary:** Conda aims to be a more general package distribution tool + and it tries to provide not only the Python packages, but also libraries + and tools needed by the Python packages. Most scientific software written + in Python uses external libraries to speed up calculations and installing + these libraries can often become complicated without conda. + - **Amount of packages:** Curated list of packages in defaults-channel, huge + number in community managed channels. Other packages can be installed via pip. + - **How libraries are handled:** Required libraries are installed as separate + conda packages. + - **Pros:** + - Quite easy to use + - Easier to manage packages that need external libraries + - **Cons:** + - Package creation is harder + +.. admonition:: Anaconda vs. miniconda vs. conda vs. mamba vs. Anaconda Cloud vs. conda-forge vs. miniforge + :class: dropdown + + Package sources: + + - `Anaconda Cloud `__ - a package cloud maintained by + Anaconda Inc. It is a free repository that houses conda package channels. + - `Conda-forge `__ - the largest open source + community channel. + + Package managers: + + - `conda `__ - a package and environment management system + used by Anaconda. It is an open source project maintained by Anaconda Inc.. + - `mamba `__ - a drop in + replacement for conda that does installations faster. + + Package manager deployments: + + - `Anaconda `__ - a distribution of conda packages + made by Anaconda Inc.. It is free for academic and non-commercial use. + - `Miniconda `__ - a minimal installer that + has conda and uses + `default channels `__ + by default. + - `Miniforge `__ - Miniconda replacement + that uses conda-forge as the default channel. Contains mamba as well. + + +In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages. + + +Creating isolated environments +------------------------------ + +An **isolated environment** allows installing packages without +affecting the rest of your operating system or any other projects. +Isolated environments solve a couple of problems: + +- You can install specific versions of packages into them. + +- You can create one environment for each project and you won't encounter any + problems if the two projects require different versions of packages. + +- If you make some mistake and install something you did not want or need, you + can remove the environment and create a new one. + +- You can export a list of packages in an environment and share it with your + code. This makes replicating your results easier. + + +Exercises 2 +----------- + +.. challenge:: Dependencies-2: Create a conda environment (15 min) + + .. highlight:: console + + Chloe just joined your team and will be working on her Master Thesis. She is + quite familiar with Python, still finishing some Python assignments (due in a + few weeks) and you give her a Python code for analyzing and plotting your + favorite data. The thing is that your Python code has been developed by + another Master Student (from last year) and requires a older version of + Numpy (1.24.3) and Matplotlib (3.7.2) (otherwise the code fails). The code + could probably work with a recent version of Python but has been validated with + Python 3.10 only. Having no idea what the code does, she decides that the best + approach is to **create an isolated environment** with the same dependencies + that were used previously. This will give her a baseline for future upgrade and + developments. + + For this first exercise, we will be using conda for creating an isolated environment. + + 1. Create a conda environment:: + + $ conda create --name python310-env python=3.10 numpy=1.24.3 matplotlib=3.7.2 + + Conda environments can also be managed (create, update, delete) from the + **anaconda-navigator**. Check out the corresponding documentation `here + `_. + + 2. Activate the environment:: + + $ conda activate python310-env + + .. callout:: conda activate versus source activate + + ``conda activate`` will only work if you have run ``conda init`` + in the past. Running ``conda init`` will make loading environments + easier as you will always have a conda environment loaded. + + However, this can also cause problems as programs in the + main environment will be constantly loaded and they might be used + even when they're not supposed to be used. A common example is + not having ``pip`` installed in a conda environment which results + ``pip`` from main environment to be used instead. + + You can always try:: + + $ source activate python310-env + + 3. Open a Python console and check that you have effectively the + right version for each package: + + .. code-block:: python + + import numpy + import matplotlib + + print('Numpy version: ', numpy.__version__) + print('Matplotlib version: ', matplotlib.__version__) + + Or use the one-liner if you have access to a terminal like bash: + + .. code-block:: python + + python -c 'import numpy; print(numpy.__version__)' + python -c 'import matplotlib;print(matplotlib.__version__)' + + 4. Deactivate the environment:: + + $ conda deactivate + + 5. Check Numpy and Matplotlib versions in the default environment to make + sure they are different from **python310-env**. + + There is no need to specify the conda environment when using deactivate. It + deactivates the current environment. + + +Exercises 3 +----------- + +.. challenge:: Dependencies-3: Create a virtualenv (15 min, optional) + + This is the same exercise as before but we use virtualenv rather than conda. + + + 1. Create a venv:: + + $ python3 -m venv scicomp + + Here ``scicomp`` is the name of the virtual environment. It creates a new + folder called ``scicomp``. + + 2. Activate it. To activate your newly created virtual environment locate the + script called ``activate`` and *source* it. + + - **Linux/Mac-OSX**: look at ``bin`` folder in the ``scicomp`` folder:: + + $ source scicomp/bin/activate + + - **Windows**: most likely you can find it in the ``Scripts`` folder. + + 3. Install Numpy 1.24.3 and Matplotlib 3.7.2 into the virtual environment:: + + $ pip install numpy==1.24.3 + $ pip install matplotlib==3.7.2 + + 4. Deactivate it:: + + $ deactivate + +Problems that might happen with manual installation +--------------------------------------------------- + +Running the install commands manually can result in unexpected behaviour +such as: + +- The installer might remove an already installed packages or update them. +- The installer might not find a package that works with already installed packages. + +The reason for this is that the installer does not know what commands +you ran in the past. It only knows the state of your environment and what +you're currently telling it to install. + +These kinds of problems can be mitigated by recording dependencies in an +``environment.yml`` or ``requirements.txt``. + +Recording dependencies +---------------------- + +There are two standard ways to record dependencies for Python projects: +``requirements.txt`` and ``environment.yml``. + +``requirements.txt`` (used by virtual environment) is a simple +text file which looks like this: + +.. code-block:: none + + numpy + matplotlib + pandas + scipy + +``environments.yml`` (for conda) is a yaml-file which looks like this: + +.. code-block:: yaml + + name: my-environment + channels: + - defaults + dependencies: + - numpy + - matplotlib + - pandas + - scipy + +If you need to recreate the exact same environment later on, it can be very +useful to **pin dependencies** to certain versions. For example, there +is usually a delay between doing research and that research being published. +During this time the dependencies might update and reviewers or interested +researchers might not be able to replicate your results or run your code. + +.. callout:: Conda channels + + - Sometimes the package version you would need does not seem to be + available. You may have to select another `conda channel + `__. + + Most popular channels are + `defaults `__, + which is managed by + Anaconda Inc. and `conda-forge `__, + which is managed by the open source community. These two channels are + mutually incompatible. + + Channel priority goes from top to bottom. + + +Here are the two files again, but this time with versions pinned: + +``requirements.txt`` with versions: + +.. code-block:: none + + numpy==1.24.3 + matplotlib==3.7.2 + pandas==2.0.3 + scipy==1.10.1 + +``environments.yml`` with versions: + +.. code-block:: yaml + + name: my-environment + channels: + - defaults + dependencies: + - python=3.10 + - numpy=1.24.3 + - matplotlib=3.7.2 + - pandas=2.0.3 + - scipy=1.10.1 + +- Conda can also read and write ``requirements.txt``. +- ``requirements.txt`` can also refer to packages on Github. +- ``environments.yml`` can also contain a ``pip`` section. +- See also: https://coderefinery.github.io/reproducible-research/dependencies/ . + +.. admonition:: Putting too strict requirements can be counter-productive + + Putting exact version numbers can be good for single-use applications, + like replicating a research paper, but it is usually bad for long-term + maintenance because the program won't update at the same time as it's + requirements do. + + If you're creating a library, adding strict dependencies can also create + a situation where the library cannot coexist with another library. + +Dependencies 4 +-------------- + +.. challenge:: Dependencies-4: Freeze an environment (15 min) + + - Create the file ``environment.yml`` or ``requirements.txt`` + + - Create an environment based on these dependencies: + - Conda: ``$ conda env create --file environment.yml`` + - Virtual environment: First create and activate, then ``$ pip install -r requirements.txt`` + + - Freeze the environment: + - Conda: ``$ conda env export > environment.yml`` + - Virtual environment: ``$ pip freeze > requirements.txt`` + + - Have a look at the generated ("frozen") file. + +.. admonition:: Hint: Updating packages from dependency files + + Instead of installing packages with ``$ pip install somepackage``, + you can add ``somepackage`` to ``requirements.txt`` and re-run + ``$ pip install -r requirements.txt``. + + With conda, you can add the package to ``environment.yml`` and + run ``$ conda env update --file environment.yml`` + + +How to communicate the dependencies as part of a report/thesis/publication +-------------------------------------------------------------------------- + +Each notebook or script or project which depends on libraries should come with +either a ``requirements.txt`` or a ``environment.yml``, unless you are creating +and distributing this project as Python package (see next section). + +- Attach a ``requirements.txt`` or a ``environment.yml`` to your thesis. +- Even better: put ``requirements.txt`` or a ``environment.yml`` in your Git repository along your code. +- Even better: also binderize your analysis pipeline (more about that in a later session). + + +.. _version_pinning: + +Version pinning for package creators +------------------------------------ + +We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in ``setup.py`` or ``pyproject.toml`` +(PyPI) or ``meta.yaml`` (conda). + +These dependencies will then be used by either other libraries (who in turn +write their own ``setup.py`` or ``pyproject.toml`` or ``meta.yaml``) or by +people directly (filling out ``requirements.txt`` or a ``environment.yml``). + +Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from ``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy==1.19.2', + 'matplotlib==3.3.2' + 'pandas==1.1.2' + 'scipy==1.5.2' + ] + # ... + +or you can define a range or keep them undefined like here (example taken from +``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy', + 'matplotlib' + 'pandas' + 'scipy' + ] + # ... + +Should we pin the versions here or not? + +- Pinning versions here would be good for reproducibility. + +- However pinning versions may make it difficult for this library to be used in a project alongside other + libraries with conflicting version dependencies. + +- Therefore **as library creator make the version requirements as wide as possible**. + + - Set minimum version when you know of a reason: ``>=2.1`` + + - Sometimes set maximum version to next major version (``<4``) (when + you currently use ``3.x.y``) when you expect issues with next + major version. + +- As the "end consumer" of libraries, define your dependencies as narrowly as possible. + + +See also +-------- + +Other tools for dependency management: + +- `Poetry `__: dependency management and packaging +- `Pipenv `__: dependency management, alternative to Poetry +- `pyenv `__: if you need different Python versions for different projects +- `micropipenv `__: lightweight tool to "rule them all" +- `mamba `__: a drop in replacement for + conda that does installations faster. +- `miniforge `__: Miniconda alternative with + conda-forge as the default channel and optionally mamba as the default installer. +- `micromamba `__: + tiny version of Mamba as a static C++ executable. Does not need base environment or + Python for installing an environment. + +Other resources: + +- https://scicomp.aalto.fi/scicomp/packaging-software/ + + +.. keypoints:: + + - Install dependencies by first recording them in ``requirements.txt`` or + ``environment.yml`` and install using these files, then you have a trace. + - Use isolated environments and avoid installing packages system-wide. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/exercises.md.txt b/branch/rkdarst--dependengi-exercise-time/_sources/exercises.md.txt new file mode 100644 index 00000000..61028b90 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/exercises.md.txt @@ -0,0 +1,12 @@ +# List of exercises + +## Full list + +This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests. + +```{exerciselist} +``` diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/guide.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/guide.rst.txt new file mode 100644 index 00000000..3dc6f602 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/guide.rst.txt @@ -0,0 +1,125 @@ +Instructor's guide +================== + +Learner personas +---------------- + +A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don't know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren't sure if they +are going in the right direction. + +A2 can use numpy and pandas, but have learned little bits here and +there and hasn't had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages) + +B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves. + + +Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren't familiar. + +Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter + + + +About each section +------------------ + +In general, "Python for Scientific Computing could be a multi-year +course. We can't even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path. + +* **Python intro:** We can't really replace a Python tutorial, but + here we try to outline some of the main points. We don't go over + this in the course. + +* **Jupyter:** Jupyter is somewhat useful, but the main reason we go + over it is that it provides a convenient user interface for the + other programming lessons (it's easier to spend a bit of time with + Jupyter than expect people to be able to use some + editor/IDE/shell/etc). So, we do start from the beginning, so that + people can do the other lessons, but also try to teach some advanced + tips and tricks. + +* **Numpy:** The basic of much of the rest of scipy, so we need to + cover it. We try to get the main principles out, but if someone + already knows it this can be a bit boring. We try to make sure + everyone comes out with an appreciation for vectorization and + broadcasting. + +* **Pandas:** A lot of similar goals to the Numpy section, especially + the concepts behind Dataframes that one needs to know in order to + read other documentation. + +* **Visualization:** Matplotlib is getting a bit old, but is still the + backbone of other plotting packages. We try to get forth the ideas + of the matplotlib API that can be seen in other packages and the + importance of scripted plots. + +* **Data formats:** Input/output/storage is a common task, and can + easily either be a bottleneck or a huge mess. This lessons tries to + show some best practices with data formats and, as usual, get the + idea to not "do it yourself". Pandas is used as a common framework, + but we should point out there are plenty of other options. + +* **Scripts:** The most important lesson here is to break out of + Jupyter/run buttons of editors. If you can't make actual programs + with an actual interface, you can't scale up. + + * This is the first lesson to introduce the command line. We + recommend being as simple as possible: at least demonstrate the + JupyterLab terminal and discuss the bigger picture behind what it + means and why. + + * This is also the first lesson to use non-Jupyter code editor. We + recommend again being simple: use the JupyterLab code editor to + start off, and carefully explain what is going on. + +* **Scipy:** We don't cover much here (this is super short), but the + point is scipy exists and the concept of wrapping existing C/fortran + libraries and so on. + +* **Library ecosystem:** This was an overview of the types of packages + available in the "scipy ecosystem", which is a large and ill-defined + thing. But there is another point: choosing what to use. Do you + trust a half-done thing published on someone's personal webpage? If + it's on Github? How do you make your code more reusable? When + coming from academic courses, you get a "build it yourself" idea, + which isn't sustainable in research. + +* **Parallel programming:** + +* **Dependencies:** The main point here is environments, another thing + you often don't learn in courses. + + * There is a lot of material here. Consider what you will demo, + what will be done as exercises, and what is advanced/optional. + However, it is the fourth-day lesson that is most interactive, so + it is OK if it take a while to go through everything. + + * If someone else installs Anaconda for a user (e.g. admin-managed + laptop), the conda environment creations (with ``--name``, + possibly with ``--prefix`` too?) may not work. Be prepared for + this and mention it. You don't need to solve the problem but + acknowledge that the lesson becomes a demo. The virtualenv part + should hopefully work for them. + +* **Binder:** Binder exists and can help make code + reproducible/reusable by others. + +* **Packaging:** How to make your code reusable by others. By the + time we get here, people are tired and the topics get involved. We + more explicitly say "you might want to watch and take this as a + demo". + diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/index.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/index.rst.txt new file mode 100644 index 00000000..7159e43e --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/index.rst.txt @@ -0,0 +1,227 @@ +=============================== +Python for Scientific Computing +=============================== + +.. admonition:: Attending the course 7-10.november.2023? + + `See the course page here + `__ + and watch at https://twitch.tv/coderefinery. + Whether you are or aren't, the course material is below. Videos + will appear in `this playlist `__. + + +Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, matplotlib for visualization, and so on. In +addition, it talks about *how* python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write. + +This course (like any course) can't teach you Python... it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to. + +.. _prerequisites: + +.. prereq:: + + - Knowing basic Python syntax. We assume that you can do some + Python programming, but not much more that that. We don't cover + standard Python programming. `Here a short course on basic Python + syntax, with further references `__. + - Watch or read the `command line crash course + `__, if you aren't + familiar. + - You should be able to use a text editor to edit files some. + - The :doc:`software installation ` described below + (basically, anaconda). + + These are not prerequisites: + + - Any external libraries, e.g. numpy + - Knowing how to make scripts or use Jupyter + + +.. admonition:: Videos and archived Q&A + + Videos and material from past instances: + + * 2021: `this YouTube playlist + `__. + * 2022: `here + `__, + Q&A: `days 1-2 + `__, `days 3-4 + `__ + + * 2023 (appearing here as the course happens): `Videos `__ + + +.. csv-table:: + :widths: auto + :delim: ; + + (prereq) ; :doc:`python` + 30 min ; :doc:`jupyter` + 60 min ; :doc:`numpy` or :doc:`numpy-advanced` + 60 min ; :doc:`pandas` + 60 min ; :doc:`data-visualization` + 30 min ; :doc:`data-formats` + 60 min ; :doc:`scripts` + 30 min ; :doc:`web-apis` + 15 min ; :doc:`scipy` + 30 min ; :doc:`libraries` + 45 min ; :doc:`parallel` + 30 min ; :doc:`dependencies` + 30 min ; :doc:`binder` + 60 min ; :doc:`packaging` + + +.. toctree:: + :maxdepth: 1 + :caption: The lesson + :hidden: + + python + jupyter + numpy + numpy-advanced + pandas + data-visualization + data-formats + productivity + scripts + scipy + libraries + dependencies + binder + parallel + packaging + web-apis + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + installation + quick-reference + exercises + guide + + +.. _learner-personas: + +Who is the course for? +====================== + +The course is targeted towards these learner personas: + +* A is a early career PhD researcher who has been using Python a bit, + but is not sure what they know or don't know. They want to be able + to do their research more efficiently and make sure that they are + using the right tools. A may know that numpy exists, etc. and could + theoretically read some about it themselves, but aren't sure if they + are going in the right direction. + +* A2 can use numpy and pandas, but have learned little bits here and + there and hasn't had a comprehensive introduction. They want to + ensure they are using best practices. (Baseline of high-level + packages) + +* B is a mid-to-late undergraduate student who has used Python in some + classes. They have possibly learned the syntax and enough to use it + in courses, but in a course-like manner where they are expected to + create everything themselves: they want to know how to reuse tools + that already exist. + + +Motivation +========== + +Why Python +---------- + +Python has become popular, largely due to good reasons. It's very easy +to get started, there's lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities. + + +Why not Python for Scientific Computing +--------------------------------------- + +While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools. + +- Implementing performance-critical kernels. Python is a **very** + slow language, which often doesn't matter if you can offload the + heavy lifting to fast compiled code, e.g. by using Numpy array + operations. But if what you're trying to do isn't *vectorizable* + then you're out of luck. An alternative to Python, albeit much less + mature and with a smaller ecosystem, but which provides very fast + generated code, is *Julia*. + +- Creating libraries that can be called from other languages. In this + case you'll often want to create a library with a C interface, which + can then be called from most languages. Suitable languages for this + sort of task, depending on what you are doing, could be Rust, C, + C++, or Fortran. + +- You really like static typing, or functional programming + approaches. *Haskell* might be what you're looking for. + + +Python 2 vs Python 3 +-------------------- + +Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard. + +At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2. + + + +Credits +======= + +This course was originally designed by Janne Blomqvist. + +In 2020 it was completely redesigned by a team of the following: + +* Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, ... +* Editor: +* Testers and advisors: Enrico Glerean + +We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html + + +See also +======== + +* `High Performance Data Analytics in Python + `__ is a logical follow-up to + this lesson that goes more in-depth to tools of high-performance + and large-scale Python. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/installation.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/installation.rst.txt new file mode 100644 index 00000000..ed28b94c --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/installation.rst.txt @@ -0,0 +1,232 @@ +Software installation +===================== + +This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or some other way access to it. For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line for some lessons). + +**If you need installation help, show this page to someone around you +and they can probably do all you need** + + +Generic list of tools required +------------------------------ + +Note: The actual installation instructions are below. This is a +generic description which will help those who already understand all +of the tools. + +* **Python 3** (Anaconda is recommended, it will include everything) + + * With some extra packages installed. They are all included in + Aanconda, and are listed in the ``environment.yml`` file you can + find under miniconda below. +* Text editor (several lessons, can also be done through Jupyterlab) +* Command-line shell (several lessons, can also be done through Jupyterlab) +* git (not needed, this lesson is usually done as a demo) + +.. admonition:: Generic instructions with miniconda and an environment file (advanced) + :class: dropdown + + This is the advanced, minimal method of installing the Python + packages. For most people, we recommend Anaconda (below). You + will actually learn about miniconda during the workshop. This + doesn't provide the graphical Anaconda navigator, so you'll need to + activate the miniconda environment using the command line. + + You can read how to install miniconda from the `CodeRefinery + installation instructions + `__. + + Then `this environment file + `__ + contains all packages needed, and can be installed with: + + .. code:: console + + $ conda env create -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + Each time you start a new shell, you need to activate miniconda (if + you don't do run ``conda init``), and then you need to activate the + proper environment with ``conda activate python-for-scicomp``. + + We might have missed some packages, though, which can be later + installed with ``conda install``. + + + +Python +------ + +We expect you to have a working Python installation with some common +libraries. We recommend that you install the `Anaconda python +distribution `__. The +`Anaconda Navigator `__ +provides a convenient way to access the software. + +.. admonition:: Other options + :class: toggle + + We recommend Anaconda, Anaconda Navigator, and JupyterLab in these + instructions because it is simple and can be used by everyone. As + you advance in your career, we + recommend that you explore other options as well, but + that can come later. + + Any other Python distribution which you can install libraries into + would work, but because there are so many different ways to do this, + we don't support them. You would need the extra libraries mentioned + in the Miniconda instructions above. + + +JupyterLab +~~~~~~~~~~ + +We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). If you install the full +Anaconda distribution, this will be available and can be started +either through Anaconda Navigator or command line. + + + +Verification of Python and JupyterLab +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. admonition:: Watch the video + + See this `verification in video form + `__ - if you can do this, you are + ready to go for day one. Your exact steps may be a bit different. + +**You should be able to start JupyterLab.** You can do this from the +`Anaconda Navigator `__ (recommended if you have it): + +.. figure:: img/installation/anaconda-navigator-jupyterlab.png + :class: with-border + + Starting JupyterLab from the Anaconda Navigator. + +... or you can start JupyterLab from the command line: + +.. code-block:: console + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + +**Verify that you can start a Jupyter notebook.** We will learn how to +do this in day 1, but you can try running ``print("Hello, world!")`` +if you want. + +.. figure:: img/installation/jupyterlab-notebook.png + :class: with-border + + Starting a Jupyter Notebook from JupyterLab. + + +Text editor +----------- + +For one portion of the course, you will need a text editor. **If you +don't know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.** + +.. admonition:: Other editors + :class: toggle + + Because we need to be simple in our teaching, we only teach the + most basic editors. We encourage you to try out more advanced ones + yourself. + + For other editors, see the `CodeRefinery instructions + `__. You don't + exactly need a terminal editor - the graphical ones, such as VSCode or + whatever you use now, will work as well. + + + +Command line +------------ + +**You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed.** If you want to +test in advance: + +* You can start it from JupyterLab (recommended): + + .. figure:: img/installation/jupyterlab-terminal.png + :class: with-border + :scale: 75% + + From the JupyterLab launcher, select "Terminal". + +.. admonition:: Other ways to access the command line + :class: toggle + + * From the Anaconda Navigator: + + .. figure:: img/installation/anaconda-prompt.png + :class: with-border + + From the Anaconda Navigator, you can select "environments" on the + left, then click on one, then the arrow, then "Open terminal". + + * From your operating system's terminal applications, if you activate + Anaconda. + + + +Verification of the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify command line usage, type the following commands (without the +``$``), and you should see the corresponding output that lists the +Python version: + +.. code-block:: console + + $ python -V + Python 3.8.3 + + ## Or python3... + $ python3 -V + Python 3.8.3 + +Any version of Python 3 through a recent Anaconda should work for the +course. + + + +Zoom +---- + +If this is an online workshop, it might use Zoom. You can see +`CodeRefinery instructions for it +`__. + + + +Need help? +---------- + +If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up! + + + +See also +-------- + +* `Research Software Hour on conda + `__ +* `Conda manual `__ (technical) +* `Anaconda individual edition home + `__ +* `Anaconda getting started + `__ diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/jupyter.ipynb.txt b/branch/rkdarst--dependengi-exercise-time/_sources/jupyter.ipynb.txt new file mode 100644 index 00000000..2280f557 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/jupyter.ipynb.txt @@ -0,0 +1,439 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter\n", + "\n", + "\n", + "```{questions}\n", + "\n", + " - What is the purpose of a \"Computational narrative\"?\n", + " - What role does Jupyter play in development?\n", + " - When is Jupyter not a good tool?\n", + "```\n", + "\n", + "```{objectives}\n", + "\n", + " This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.\n", + "\n", + " - Be able to use Jupyter to run examples for the rest of the course.\n", + " - Be able to run Jupyter in a directory do your own work.\n", + " - You won't be a Jupyter expert after this, but should be able to do the rest of the course.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is Jupyter?\n", + "\n", + "Jupyter is a web-based interactive computing system. It is most well known for having the *notebook file format* and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a *computational narrative*.\n", + "\n", + "Jupyter is good for data exploration and interactive work.\n", + "\n", + "**We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.**\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting started with Jupyter\n", + "\n", + "* Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run `jupyter-lab`. You can also start in from Anaconda Navigator.\n", + "\n", + "For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here, we see a tour of the JupyterLab interface:\n", + "\n", + "![Main UI tour](img/jupyter/main-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 1\n", + "```{challenge} Exercises: Jupyter-1\n", + "\n", + " 1. Start Jupyter in the directory you want to use for this course.\n", + " - If you are starting from the navigator, change to the directory you want to use.\n", + " - If you are starting from the command line, you should navigate to the directory you want to use first.\n", + "\n", + " 2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.\n", + "\n", + " 4. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.\n", + "\n", + " 5. (optional, advanced) Look at the notebook file in a text\n", + " editor. How does it work?\n", + "\n", + "If everything works for you, this will end very quickly. You can begin reading the next sections independently.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Running code in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A notebook is divided into **cells**. Each cell has some **input**, and when it is executed an **output** appears right below it.\n", + "\n", + "There are different types of cells: primarily **code** cells and **markdown** cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/). For example the previous sentence is:\n", + "\n", + "```none\n", + "Markdown is a lightweight way of giving *style* to `text` - you \n", + "can check out [this reference](https://commonmark.org/help/).\n", + "```\n", + "\n", + "![notebook UI](img/jupyter/notebook-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When using keyboard shortcuts, you can switch between edit mode and command mode with `Enter` and `Esc`. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:\n", + "* `Ctrl-Enter`: Run cell\n", + "* `Shift-Enter`: Run cell and select cell below\n", + "* `Alt-Enter`: Run cell and insert new cell below\n", + "* `a` / `b`: insert new cell above/below\n", + "* `m` / `y`: markdown cell / code cell\n", + "* `x`: cut cell\n", + "* `c`: copy cell\n", + "* `v`: paste cell\n", + "* `d, d`: delete cell" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, let's look at some code samples:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0\n", + "1\n", + "2\n" + ] + } + ], + "source": [ + "for i in range(3):\n", + " print(i)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "10\n" + ] + } + ], + "source": [ + "print(sum(range(5)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By convention, if the last thing in a cell is an object, that object gets printed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "45" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sum(range(5))\n", + "sum(range(10))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to raw cells, there are **magics**, which exist outside of Python. They are a property of the runtime itself (in Python's case, they come from **IPython**. For example, the following cell magic [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) will use the {py:mod}`timeit` module to time a cell by running it multiple times):" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "54.1 ms ± 993 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "for x in range(1000000):\n", + " x**2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Another example is [%%bash](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-bash) which will turn the cell into a shell script (This will only work on operating systems with the Bash shell installed - MacOS and Linux at least):" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1\n", + "2\n", + "3\n" + ] + } + ], + "source": [ + "%%bash\n", + "for x in $(seq 3) ; do\n", + " echo $x\n", + "done" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "* A **cell magic** starts with `%%`, goes on the first line of a cell, and applies to the whole cell\n", + "* A **line magic** starts with `%`, goes on any line, and applies to that line." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "```{challenge} Exercises: Jupyter-2\n", + "\n", + " 1. Run some trivial code, such as ``print(1)``.\n", + "\n", + " 2. Run some slightly less trivial code, like print out the first\n", + " ten [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number).\n", + "\n", + " 3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the [reference](https://commonmark.org/help/) to add a heading, bullet list, and some (bold, italic, or inline code)\n", + "\n", + " 4. Use the [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) magic function to time your Fibonacci\n", + " function.\n", + "\n", + " 5. Again using ``%%timeit``, figure out the fastest way to sum the\n", + " numbers 0 to 1000000.\n", + " \n", + " 6. Once you are done, close your notebooks and other tabs you don't need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.\n", + "```\n", + "\n", + "`````{solution} Solutions: Jupyter-2\n", + "\n", + "1. --\n", + "\n", + "2. Simple fibonacci code\n", + "\n", + " ```python\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " print(a)\n", + " a, b = b, a+b\n", + " ```\n", + "\n", + "3. Markdown description\n", + "\n", + " ```md\n", + " # Fibonacci\n", + " * Start with two variables `a` and `b`\n", + " * Repeat 10 times\n", + " * Print old `a`, then increment both\n", + " * Makes use of the Python *tuple assignment*: `a, b = new_a, new_b`\n", + " ```\n", + "\n", + "4. In this case, the print() statements get out of hand, so we comment that out. In general, writing output usually takes a lot of time reletive to the computation, so we don't want to time that (unless output is the main point of the code, then we do have to time it!\n", + "\n", + " ```ipython\n", + " %%timeit\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " #print(a)\n", + " a, b = b, a+b\n", + " ```\n", + " ```none\n", + " 395 ns ± 10.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n", + " ```\n", + "\n", + "5. --\n", + "\n", + "6. --\n", + "\n", + "`````" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why Jupyter?\n", + "\n", + "- Being able to **edit, check, re-edit** quickly is great for **prototyping and testing new ideas**\n", + " - Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.\n", + "- You can make a **complete story** - in one place. No more having code, figures, and description in different places.\n", + " - Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.\n", + "- Notebook as an interactive publication itself - for example the discovery of gravitational waves data is [released as a notebook](https://www.gw-openscience.org/tutorials/).\n", + "- Jupyter Notebooks display on Github - low-barrier way to share your analysis.\n", + "- Teaching - great for getting difficult software distribution out of the way." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why not Jupyter?\n", + "\n", + "Jupyter is great for many things, but there are some problems if not used well:\n", + "\n", + "- They **don't promote modularity**, and once you get started in a\n", + " notebook it can be hard to migrate to modules.\n", + "- They are **difficult to test**. There are things to run notebooks as\n", + " unit tests like [nbval](https://nbval.readthedocs.io/), but it's not\n", + " perfect.\n", + "- Notebooks can be **version controlled**\n", + " ([nbdime](https://nbdime.readthedocs.io/) helps with that), but\n", + " there are **still limitations**.\n", + "- You can **change code after you run it** and run code out of order.\n", + " This can make debugging hard and results irreproducible if you\n", + " aren't careful.\n", + "- Notebooks **aren't named by default** and tend to **acquire a bunch of\n", + " unrelated stuff**. Be careful with organization!\n", + "- Once lots of code is in notebooks, it can be **hard to change to\n", + " proper programs that can be scripted**.\n", + "\n", + "You can read more about these downsides .\n", + "\n", + "**But these downsides aren't specific to Jupyter!** They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "```{challenge} Exercises: Jupyter-3\n", + "\n", + " (optional) Discuss the following in groups:\n", + "\n", + " 1. Have any of you used Jupyter in a way that became impossible to\n", + " maintain: too many files, code all spread out, not able to find\n", + " your code and run it in the right order. How did you solve that?\n", + "\n", + " 2. On the other hand, what are your successes with Jupyter?\n", + " \n", + " 3. How can you prevent these problems by better development strategies?\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## See also\n", + "\n", + "- The [CodeRefinery Jupyter lesson](https://coderefinery.github.io/jupyter/) has much more, and the source of some of the content above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{keypoints}\n", + "\n", + " - Jupyter is powerful and can be used for interactive work\n", + " - ... but not the end solution when you need to scale up.\n", + "```" + ] + } + ], + "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.10.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/libraries.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/libraries.rst.txt new file mode 100644 index 00000000..047a480a --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/libraries.rst.txt @@ -0,0 +1,353 @@ +Library ecosystem +================= + +.. questions:: + + - What happens when you need some method Beyond what we discuss in this course, what is available? + - How do you decide what to build on for your work? + +.. objectives:: + + - Know of some other available packages, but don't necessarily know + how to use them. + - Be able to evaluate what you should reuse and what you should + develop yourself. + +You can't do everything yourself. In fact, once we heard a quote such +as this: + + When you are a student, you are expected to do everything + yourself, and that is how you are evaluated. When you become a + researcher, you *have* to be able to reuse what others have done. + We don't have much practice in doing this. + -- A student + +In this lesson, we'll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types: + +- Well-maintained libraries that are used by many others. +- A wide variety of public code that might work but isn't necessarily + well-maintained (for example, code from articles). + +We'll start with the first then go to the second. + + + +Glossary +-------- + +Library + A collection of code used by a program. + +Package + A library that has been made easily installable and reusable. + Often published on public repositories such as the `Python Package + Index `__ + +Dependency + A requirement of another program, not included in that program. + + + +The Python/SciPy ecosystem +-------------------------- + +This section is nothing more than a tour of what exists in Python. +You aren't expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work. + +The "core" packages `could be considered +`__. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy): + +* Python +* Numpy - arrays, everything builds on this +* Scipy - scientific functions (not necessarily a lot builds on this) +* matplotlib - plotting, many other plotting tools build on this +* pandas - data structures +* IPython / Jupyter: interactive work + + + +Core numerics libraries +~~~~~~~~~~~~~~~~~~~~~~~ + +* `numpy `__ - arrays and array math. +* `scipy `__ - software + for math, science, and engineering. + + + +Plotting +~~~~~~~~ + +* `matplotlib `__ - base plotting package, + somewhat low level but almost everything builds on it. +* `seaborn `__ - higher level plotting + interface; statistical graphics. +* `mayavi `__ - 3D plotting +* `PIL `__ - image manipulation. The + original PIL is no longer maintained, the new "Pillow" is a drop-in + replacement. + + + +Data analysis and other important core packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `pandas `__ - columnar + data analysis +* `statsmodels `__ - just what it says +* `SymPy `__ - symbolic math +* `networkx `__ - graph and network analysis +* `h5py `__ and `PyTables `__ - interfaces to + the `HDF5 `__ on-disk file format +* `dateutil `__ and `pytz + `__ - date arithmetic and handling, + timezone database and conversion + + + +Interactive computing and human interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Interactive computing + + * `IPython `__ - nicer interactive interpreter + * `Jupyter `__ (notebook, lab, hub, ...) - + web-based interface to IPython and other languages + +* Testing + + * `pytest `__ - automated testing interface + +* Documentation + + * `Sphinx `__ - documentation generator + (also used for this lesson...) + +* Development environments + + * `Spyder `__ - interactive Python + development environment. + +* `Binder `__ - load any git repository in + Jupyter automatically, good for reproducible research + + + +Speeding up code and parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `PyMPI `__ - Message + Passing Interface (MPI) in Python for parallelizing jobs. +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `numba `__ - just in time compiling of + functions for speed-up +* `PyPy `__ - Python written in Python so that + it can internally optimize more. +* `Dask `__ - distributed array data structure for + distributed computation +* `Joblib `__ - easy embarrassingly + parallel computing +* `IPyParallel `__ - easy + parallel task engine +* `numexpr `__ - Fast evaluation of + array expressions by automatically compiling the arithmetic. + + + +Machine learning +~~~~~~~~~~~~~~~~ + +If you need some machine learning, you probably already know what you +need and this list is short and irrelevant. + +- `tensorflow `__ +- `pytorch `__ +- `nltk `__ - natural language processing +- `scikit-learn `__ - simple tools for + predictive data analysis + + + +Connecting Python to other languages +------------------------------------ + +As we discussed with Scipy, very many of the above packages aren't +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things: + +* **Extending Python** by writing your own modules in C. + + * It's actually common to first have (or write) an analysis package + in C or C++, then make the Python interface. Then it can be + supported by other languages, too. + + * Or one starts an analysis package in Python, and slowly moves bits + of it to C over time as there is need. + +* **Embedding Python**, where you have another primary application + that uses Python under the hood as an internal scripting language. + +These features aren't exactly unique to Python, but Python does +support them very well. Read more: `Extending and embedding Python +`__. + + + +Tools for interfacing with other languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These days, one rarely directly extends the Python interpreter, but uses + +* `cffi `__ and `ctypes + `__ - interface to C + and compatible libraries +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `f2py `__ - interface to Fortran + code +* `swig `__ - connect to a variety of programming languages. +* ``Boost.python`` - Another Python/C++ interface +* TODO: Julia modules for Python? + + + +Evaluating Python packages for reuse +------------------------------------ + +Above, we talked about well-maintained mainstream packages. **Do you +trust random code you find online (for example included in a paper)?** + +Especially consider scientific results, which *have* to be correct. +Still, you also *can't* build everything yourself, so you have to +carefully evaluate the situation. + +Below are some things to consider: + +* Are there releases? Have they been going on for a while? + +* Are releases installable without copy-paste? + +* Are dependencies handled well? + +* Does the code randomly change, so that it no longer works with your + code. Is this relevant? + +* Is there good documentation, that not just tells how to use it but + how it works? + +* Is there automated testing? What's your evaluation of the risk of + undetectable scientific errors? + +* Is there a community, or is it one person? Is it backed by some + organization? Does it have a permanent home? + +* Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) + where a community *could* form? + +* Do others post issues and make contributions? Are these issues + dealt with in a timely manner? Can you search past bug reports? + +* Is the software citeable? + + + +Is your work reuseable? +----------------------- + +Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a `CodeRefinery workshop `__ will make +sure you have the tools to produce high-quality, reusable code. + + + +What's next? +------------ + +* The `CodeRefinery workshop `__ mentioned + above will prepare you for others to reuse your code and for you to + contribute to other code. +* The upcoming :doc:`dependencies` lesson will teach you how to + record and manage dependencies so that anyone can seamlessly reuse + your code. + + + +Exercises +--------- + +.. exercise:: Libraries 1.1: Libraries in your work + + What libraries do you use in your work? What have you made, which + you could have reused from some other source. What have you used + from some other source that you wished you had re-created? + + Discuss in your groups or HackMD. + +.. solution:: Libraries 1.1 + + ... is there anything to say here? + + +.. exercise:: Libraries 1.2: Evaluating packages + + Below are some links to some packages, both public and made by the + authors of this lesson. Evaluate them, considering "would I use + this in my project?" + + a) https://github.com/networkx/networkx/ + b) some code on webpage in a paper's footnote + c) https://github.com/rkdarst/pcd + d) https://github.com/dftlibs/numgrid + e) https://github.com/rkdarst/dynbench + f) https://vpython.org/ + +.. solution:: Libraries 1.2 + + a) networkx: This seems to be a relatively large, active project + using best practices. Probably usable. + b) I would probably use it if I had to, but would prefer not to. + c) This (written by one of the authors of this lesson) has no + documenting, no community, no best practices, and is very old. + Probably not a good idea to try to use it + d) This project uses best practices, but doesn't seem to have a big + community. It's probably fine to use, but who knows if it will + be maintained 10 years from now. It does have automated tests + via Github Actions (``.github/workflows`` and the green checks), + so the authors have put some work into making it correct. + e) This (also written by one of the authors) looks like it was made + for a paper of some sort. It has some minimal documentation, + but still is missing many best practices and is clearly not + maintained anymore (look at the ancient pull request). Probably + not a good idea to use unless you have to. + f) This project has a pretty website, and some information. But + seems to not be using best practices of an open repository, and + custom locations which could disappear at any time. + + You notice that several of the older projects here were written by + one of the authors of this lesson. It goes to show that everyone + starts somewhere and improves over time - don't feel bad if your + work isn't perfect, as long as you keep trying to get better! + + + +See also +-------- + +* `Topical Software in the SciPy ecosystem + `__ - relatively + detailed (but not comprehensive) list of projects + + +.. keypoints:: + + - Almost everything you need can already be found, except your + incremental work. + - When do you build on that other work, and when do you create + things yourself? diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/numpy-advanced.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/numpy-advanced.rst.txt new file mode 100644 index 00000000..aba1ec3b --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/numpy-advanced.rst.txt @@ -0,0 +1,407 @@ +Advanced NumPy +============== + +.. questions:: + + - How can NumPy be so fast? + - Why are some things fast and some things slow? + - How can I control whether NumPy makes a copy or operates in-place? + +.. objectives:: + + - Understand why NumPy has so many specialized functions for specific operations + - Understand the underlying machinery of the Numpy :class:`~numpy.ndarray` object + - Understand when and why NumPy makes a copy of the data rather than a view + + This is intended as a follow-up to the :doc:`basic NumPy lesson `. The intended + audience for this advanced lesson is those who have used NumPy before and + now want to learn how to get the most out of this amazing package. + + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +`Guide to NumPy `_ by +Travis E. Oliphant, its initial creator. + + + +NumPy can be really fast +------------------------ + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast. + +.. highlight:: c + +How fast can NumPy be? Let's race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:: + + #include + #include + #define N_ELEMENTS 100000000 + int main(int argc, char** argv) { + double* a = (double*) malloc(sizeof(double) * N_ELEMENTS); + int i; + for(i=0; i` before continuing with this + advanced lesson. If you are taking a live course - don't + worry, watch and learn and explore some during the exercises! + +.. solution:: Solutions: Numpy-Advanced-1 + + The script can be implemented like this:: + + import numpy as np + print(np.random.rand(100_000_000).sum()) + + +.. highlight:: python + +The libraries behind the curtain: MKL and BLAS +---------------------------------------------- + +NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel's `Math Kernel Library (MKL) `_, +which are in turn derived from a Fortran library called +`Basic Linear Algebra Subprograms (BLAS) `_. +BLAS for Fortran was `published in 1979 `_ +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +`specialized CPU instructions for manipulating arrays `_. +In other words, they are *fast*. + +One of the functions inside the BLAS library is a +`function `_ +to compute the "norm" of a vector, which is the same as computing its length, using the +`Pythagorean theorem `_: +:math:`\sqrt(a[0]^2 + a[1]^2 + \ldots)`. + +Let's race the BLAS function versus a naive "manual" version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:: + + import numpy as np + rng = np.random.default_rng(seed=0) + a = rng.random(100_000_000) + +We now implement the Pythagorean theorem using basic NumPy functionality and +use ``%%timeit`` to record how long it takes to execute:: + + %%timeit + l = np.sqrt(np.sum(a ** 2)) + print(l) + +And here is the version using the specialized BLAS function :func:`~numpy.linalg.norm`:: + + %%timeit + l = np.linalg.norm(a) + print(l) + + +NumPy tries to avoid copying data +---------------------------------- + +Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy's +:class:`numpy.ndarray` datastructure works behind the scenes. + + +An example: matrix transpose +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let's see how long NumPy's +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +:func:`~numpy.random.rand` matrix:: + + import numpy as np + a = np.random.rand(10_000, 20_000) + print(f'Matrix `a` takes up {a.nbytes / 10**6} MB') + +Let's time the :meth:`~numpy.ndarray.transpose` method:: + + %%timeit + b = a.transpose() + +It takes mere nanoseconds to transpose 1600 MB of data! How? + + +The ndarray exposed +~~~~~~~~~~~~~~~~~~~ +The first thing you need to know about :class:`numpy.ndarray` is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector. + +.. image:: img/numpy-advanced/01_memory_layout.svg + +NumPy is faking the second dimension behind the scenes! When we request the +element at say, ``[2, 3]``, NumPy converts this to the correct index in the +long 1D array ``[11]``. + + * Converting ``[2, 3]`` → ``[11]`` is called "raveling" + * The reverse, converting ``[11]`` → ``[2, 3]`` is called "unraveling" + +The implications of this are many, so take let's take some time to understand +it properly by writing our own ``ravel()`` function. + +Exercise 2 +---------- + +.. challenge:: Exercises: Numpy-Advanced-2 + + Write a function called ``ravel()`` that takes the row and column of an + element in a 2D matrix and produces the appropriate index in an 1D array, + where all the rows are concatenated. See the image above to remind yourself + how each row of the 2D matrix ends up in the 1D array. + + The function takes these inputs: + + - ``row`` The row of the requested element in the matrix as integer index. + - ``col`` The column of the requested element in the matrix as integer index. + - ``n_rows`` The total number of rows of the matrix. + - ``n_cols`` The total number of columns of the matrix. + + Here are some examples of input and desired output: + + - ``ravel(2, 3, n_rows=4, n_cols=4)`` → ``11`` + - ``ravel(2, 3, n_rows=4, n_cols=8)`` → ``19`` + - ``ravel(0, 0, n_rows=1, n_cols=1)`` → ``0`` + - ``ravel(3, 3, n_rows=4, n_cols=4)`` → ``15`` + - ``ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000)`` → ``69_318_923`` + +.. solution:: Solutions: Numpy-Advanced-2 + + The function can be implemented like this:: + + def ravel(row, col, n_rows, n_cols): + return row * n_cols + col + +Strides +------- + +As seen in the exercise, to get to the next row, we have to skip over +``n_cols`` indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of "strides":: + + np.zeros((4, 8)).strides # (64, 8) + np.zeros((4, 5, 6, 7, 8)).strides # (13440, 2688, 448, 64, 8) + +The :attr:`~numpy.ndarray.strides` attribute contains for each dimension, the number of *bytes* (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes. + +So now we know the mystery behind the speed of :meth:`~numpy.ndarray.transpose`. NumPy can avoid +copying any data by just modifying the :attr:`~numpy.ndarray.strides` of the array:: + + import numpy as np + + a = np.random.rand(10_000, 20_000) + b = a.transpose() + + print(a.strides) # (160000, 8) + print(b.strides) # (8, 160000) + +Another example: reshaping +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modifying the shape of an array through :func:`numpy.reshape` is also +accomplished without any copying of data by modifying the :attr:`~numpy.ndarray.strides`:: + + a = np.random.rand(20_000, 10_000) + print(f'{a.strides=}') # (80000, 8) + b = a.reshape(40_000, 5_000) + print(f'{b.strides=}') # (40000, 8) + c = a.reshape(20_000, 5_000, 2) + print(f'{c.strides=}') # (80000, 16, 8) + + +Exercises 3 +----------- + +.. challenge:: Exercises: Numpy-Advanced-3 + + A little known feature of NumPy is the ``numpy.stride_tricks`` module + that allows you to modify the :attr:`~numpy.ndarray.strides` attribute directly. Playing + around with this is very educational. + + 1. Create your own ``transpose()`` function that will transpose a 2D matrix + by reversing its :attr:`~numpy.ndarray.shape` and :attr:`~numpy.ndarray.strides` attributes using + :func:`numpy.lib.stride_tricks.as_strided`. + + 2. Create a (5 ✕ 100 000 000 000) array containing on the first row all + 1's, the second row all 2's, and so on. Start with an 1D array + ``a = np.array([1., 2., 3., 4., 5.])`` + and modify its ``shape`` and ``strides`` attributes using + :func:`numpy.lib.stride_tricks.as_strided` to obtain the desired 2D + matrix:: + + array([[1., 1., 1., ..., 1., 1., 1.], + [2., 2., 2., ..., 2., 2., 2.], + [3., 3., 3., ..., 3., 3., 3.], + [4., 4., 4., ..., 4., 4., 4.], + [5., 5., 5., ..., 5., 5., 5.]]) + + +.. solution:: Solutions: Numpy-Advanced-3 + + 1. The ``transpose()`` function can be implemented like this:: + + from numpy.lib.stride_tricks import as_strided + def transpose(a): + return as_strided(a, shape=a.shape[::-1], strides=a.strides[::-1]) + + # Testing the function on a small matrix + a = np.array([[1, 2, 3], + [4, 5, 6]]) + print('Before transpose:') + print(a) + print('After transpose:') + print(transpose(a)) + + 2. By setting one of the ``.strides`` to `0`, we can repeat a value + infinitely many times without using any additional memory:: + + from numpy.lib.stride_tricks import as_strided + a = np.array([1., 2., 3., 4., 5.]) + as_strided(a, shape=(5, 100_000_000_000), strides=(8, 0)) + + +A fast thing + a fast thing = a fast thing? +------------------------------------------- + +If :func:`numpy.transpose` is fast, and :func:`numpy.reshape` is fast, then +doing them both must be fast too, right?:: + + # Create a large array + a = np.random.rand(10_000, 20_000) + +Measuring the time it takes to first transpose and then reshape:: + + %%timeit -n 1 -r 1 + a.T.reshape(40_000, 5_000) + +In this case, the data actually had to be copied and it's super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the :attr:`~numpy.ndarray.strides`:: + + a = np.array([[1, 2, 3], [4, 5, 6]]) + + print('Original array:') + print(a) + + print('\nTransposed:') + print(a.T) + + print('\nTransposed and then reshaped:') + print(a.T.reshape(2, 3)) + + +Copy versus view +---------------- + +Whenever NumPy constructs a new array by modifying the :attr:`~numpy.ndarray.strides` instead of +copying data, we way it created a "view". This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +:class:`numpy.ndarray` object will have a reference to the original array in +its :attr:`~numpy.ndarray.base` attribute:: + + a = np.zeros((5, 5)) + print(a.base) # None + b = a[:2, :2] + print(b.base.shape) # (5, 5) + +.. warning:: + When you create a large array and select only a portion of it, the large + array will stay in memory if a view was created! + +The new array ``b`` object has a pointer to the same memory buffer as the array +it has been derived from:: + + print(a.__array_interface__['data']) + print(b.__array_interface__['data']) + +Views are created by virtue of modifying the value of the :attr:`~numpy.ndarray.shape` attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:: + + b = a[1:3, 1:3] # This view does not start at the beginning + offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0] + print('Offset:', offset, 'bytes') # Offset: 48 bytes + +.. image:: img/numpy-advanced/02_views.svg + +Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:: + + b[0, 0] = 1. + print(a) # Original matrix was modified + +Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:: + + c = a[[0, 2]] # Select rows 0 and 2 + print(c.base) # None. So not a view. + + +See also +-------- + +* `Guide to Numpy `__ +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + * `Advanced NumPy: Master stride tricks with 25 illustrated exercises `__ + + + +.. keypoints:: + + - The best way to make your code more efficient is to learn more about the + NumPy API and use specialized functions whenever possible. + - NumPy will avoid copying data whenever it can. Whether it can depends on + what kind of layout the data is currently in. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/numpy.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/numpy.rst.txt new file mode 100644 index 00000000..06f76be3 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/numpy.rst.txt @@ -0,0 +1,518 @@ +.. _numpy: + +NumPy +===== + +.. questions:: + + - Why use NumPy instead of pure python? + - How to use basic NumPy? + - What is vectorization? + +.. objectives:: + + - Understand the Numpy array object + - Be able to use basic NumPy functionality + - Understand enough of NumPy to seach for answers to the rest of your questions ;) + + We expect most people to be able to do all the basic exercises + here. It is probably quite easy for many people; we have advanced + exercises at the end in that case. + + + +So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible. + +.. highlight:: python + +What is an array? +----------------- + +For example, consider ``[1, 2.5, 'asdf', False, [1.5, True]]`` - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately. + +NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it. + +An array is a 'grid' of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has: + +* :ref:`dtype ` - data type. Arrays always contain one type +* :term:`shape` - shape of the data, for example ``3×2`` or ``3×2×500`` or even + ``500`` (one dimensional) or ``[]`` (zero dimensional). +* :attr:`data ` - raw data storage in memory. This can be passed to C or + Fortran code for efficient calculations. + + +To test the performance of pure Python vs NumPy we can write in our jupyter notebook: + +Create one list and one 'empty' list, to store the result in :: + + a = list(range(10000)) + b = [ 0 ] * 10000 + +In a new cell starting with ``%%timeit``, loop through the list ``a`` and fill the second list ``b`` with ``a`` squared :: + + %%timeit + for i in range(len(a)): + b[i] = a[i]**2 + +That looks and feels quite fast. But let's take a look at how NumPy performs for the same task. + +So for the NumPy example, create one array and one 'empty' array to store the result in :: + + import numpy as np + a = np.arange(10000) + b = np.zeros(10000) + +In a new cell starting with ``%%timeit``, fill ``b`` with ``a`` squared :: + + %%timeit + b = a ** 2 + +We see that compared to working with numpy arrays, working with traditional python lists is actually slow. + + +Creating arrays +--------------- + +There are different ways of creating arrays (:func:`numpy.array`, :attr:`numpy.ndarray.shape`, :attr:`numpy.ndarray.size`):: + + a = np.array([1,2,3]) # 1-dimensional array (rank 1) + b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2) + + b.shape # the shape (rows,columns) + b.size # number of elements + +In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (:func:`numpy.zeros`, :func:`numpy.ones`, :func:`numpy.full`, :func:`numpy.eye`, :func:`numpy.arange`, :func:`numpy.linspace`):: + + np.zeros((2, 3)) # 2x3 array with all elements 0 + np.ones((1,2)) # 1x2 array with all elements 1 + np.full((2,2),7) # 2x2 array with all elements 7 + np.eye(2) # 2x2 identity matrix + + np.arange(10) # Evenly spaced values in an interval + np.linspace(0,9,10) # same as above, see exercise + + c = np.ones((3,3)) + d = np.ones((3, 2), 'bool') # 3x2 boolean array + +Arrays can also be stored and read from a (.npy) file (:func:`numpy.save`, :func:`numpy.load`):: + + np.save('x.npy', a) # save the array a to a .npy file + x = np.load('x.npy') # load an array from a .npy file and store it in variable x + +In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (:attr:`numpy.ndarray.dtype`, :meth:`numpy.ndarray.astype`):: + + d.dtype # datatype of the array + d.astype('int') # change datatype from boolean to integer + +In the last example, ``.astype('int')``, it will make a **copy** of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed. + + + +Exercises 1 +----------- + +.. challenge:: Exercises: Numpy-1 + + 1. **Datatypes** Try out :func:`np.arange(10) ` and :func:`np.linspace(0,9,10) `, what is the difference? Can you adjust one to do the same as the other? + + 2. **Datatypes** Create a 3x2 array of random float numbers (check :func:`numpy.random.random`) between 0 and 1. Now change the arrays datatype to int (:meth:`array.astype `). How does the array look like? + + 3. **Reshape** Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check :meth:`array.reshape `) in any way possible. What is not possible? + + 4. **NumPyI/O** Save above array to .npy file (:func:`numpy.save`) and read it in again. + +.. solution:: Solutions: Numpy-1 + + 1. **Datatypes** + + - ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**, + - while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**. + + Both ``np.linspace`` and ``np.arange`` take dtype as an argument and can be adjusted to match each other in that way. + + 2. **Datatypes** eg ``a = np.random.random((3,2))``. ``a.astype('int')`` results in an all zero array, not as maybe expected the rounded int (all numbers [0, 1) are cast to 0). + + 3. **Reshape** eg ``b = np.random.randint(0,10,(3,2))``. + + ``b.reshape((6,1))`` and ``b.reshape((2,3))`` possible. + + It is not possible to reshape to shapes using more or less elements than ``b.size = 6``, so for example ``b.reshape((12,1))`` gives an error. + + 4. **NumPyI/O** ``np.save('x.npy', b)`` and ``x = np.load('x.npy')`` + + + +Array maths and vectorization +----------------------------- + +Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do. + +By default, basic arithmetic (``+``, ``-``, ``*``, ``/``) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is "vectorized" +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop. + +Note that unlike Matlab, where ``*`` means matrix multiplication, NumPy uses +``*`` to perform element-by-element multiplication and uses the ``@`` symbol to +perform matrix multiplication:: + + a = np.array([[1,2],[3,4]]) + b = np.array([[5,6],[7,8]]) + + # Addition + c = a + b + d = np.add(a,b) + + # Matrix multiplication + e = a @ b + f = np.dot(a, b) + +Other common mathematical operations include: ``-`` (:data:`numpy.subtract`), ``*`` (:data:`numpy.multiply`), ``/`` (:data:`numpy.divide`), ``.T`` (:func:`numpy.transpose`), :data:`numpy.sqrt`, :func:`numpy.sum`, :func:`numpy.mean`, ... + + + +Exercises 2 +----------- + +.. challenge:: Exercises: Numpy-2 + + - **Matrix multiplication** What is the difference between :data:`numpy.multiply` and :func:`numpy.dot` ? Try it. + - **Axis** What is the difference between :func:`np.sum(axis=1) ` vs + :func:`np.sum(axis=0) ` on a two-dimensional array? What if you leave out the axis parameter? + + +.. solution:: Solutions: Numpy-2 + + - **Matrix multiplication** ``np.multiply`` does elementwise multiplication on two arrays, while ``np.dot`` enables matrix multiplication. + - **Axis** ``axis=1`` does the operation (here: ``np.sum``) over each row, while axis=0 does it over each column. If axis is left out, the sum of the full array is given. + + + +Indexing and Slicing +-------------------- + +.. seealso:: + + :ref:`Numpy basic indexing docs ` + +NumPy has many ways to extract values out of arrays: + +- You can select a single element +- You can select rows or columns +- You can select ranges where a condition is true. + +Clever and efficient use of these operations is a key to NumPy's +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C. + +:: + + a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15 + a[0] # first row + a[:,0] # first column + a[1:3,1:3] # middle 2x2 array + + a[(0, 1), (1, 1)] # second element of first and second row as array + +Boolean indexing on above created array:: + + idx = (a > 0) # creates boolean matrix of same size as a + a[idx] # array with matching values of above criterion + + a[a > 0] # same as above in one line + + + +Exercises 3 +----------- + +.. challenge:: Exercise: Numpy-3 + + :: + + a = np.eye(4) + b = a[:,0] + b[0] = 5 + + - **View vs copy** Try out above code. How does ``a`` look like before ``b`` has changed and after? How could it be avoided? + +.. solution:: Solution: Numpy-3 + + - **View vs copy** The change in ``b`` has also changed the array ``a``! + This is because ``b`` is merely a view of a part of array ``a``. Both + variables point to the same memory. Hence, if one is changed, the other + one also changes. If you need to keep the original array as is, use + ``np.copy(a)``. + + +Types of operations +------------------- + +There are different types of standard operations in NumPy: + +**ufuncs**, ":ref:`universal functions `": These are element-by-element +functions with standardized arguments: + +- One, two, or three input arguments +- For example, ``a + b`` is similar to :data:`np.add(a, b) ` but the ufunc + has more control. +- ``out=`` output argument, store output in this array (rather than + make a new array) - saves copying data! +- See the `full reference + `__ + +- They also do **broadcasting** (:ref:`ref `). Can you add a 1-dimensional array of shape `(3)` + to an 2-dimensional array of shape `(3, 2)`? With broadcasting you + can! + + :: + + a = np.array([[1, 2, 3], + [4, 5, 6]]) + b = np.array([10, 10, 10]) + a + b # array([[11, 12, 13], + # [14, 15, 16]]) + + Broadcasting is smart and consistent about what it does, which I'm + not clever enough to explain quickly here: `the manual page on + broadcasting + `__. + The basic idea is that it expands dimensions of the smaller array so + that they are compatible in shape. + +**Array methods** do something to one array: + +- Some of these are the same as ufuncs:: + + x = np.arange(12) + x.shape = (3, 4) + x # array([[ 0, 1, 2, 3], + # [ 4, 5, 6, 7], + # [ 8, 9, 10, 11]]) + x.max() # 11 + x.max(axis=0) # array([ 8, 9, 10, 11]) + x.max(axis=1) # array([ 3, 7, 11]) + +**Other functions**: there are countless other functions covering +linear algebra, scientific functions, etc. + + + +Exercises 4 +----------- + +.. challenge:: Exercises: Numpy-4 + + - **In-place addition**: Create an array, add it to itself using a + ufunc. + + - **In-place addition** (advanced): Create an array of + ``dtype='float'``, and an array of ``dtype='int'``. Try to use the + int array is the output argument of the first two arrays. + + - **Output arguments and timing** Repeat the initial ``b = a ** + 2`` example using the output arguments and time it. Can you make + it even faster using the output argument? + +.. solution:: Solution: Numpy-4 + + - **in-place addition**:: + + x = np.array([1, 2, 3]) + id(x) # get the memory-ID of x + np.add(x, x, x) # Third argument is output array + np.add(x, x, x) + print(x) + id(x) # get the memory-ID of x + # - notice it is the same + + You note that ``np.add()`` has a third argument that is the + output array (same as ``out=``), *and* the function returns that + same array. + + + - **Output arguments and timing** In this case, on my computer, it was + actually slower (this is due to it being such a small array!):: + + a = np.arange(10000) + b = np.zeros(10000) + + :: + + %%timeit + numpy.square(a, out=b) + + This is a good example of why you always need to time things + before deciding what is best. + + +Linear algebra and other advanced math +-------------------------------------- + +In general, you use :class:`arrays ` (n-dimensions), not :class:`matrixes ` +(specialized 2-dimensional) in NumPy. + +Internally, NumPy doesn't invent its own math routines: it relies on +`BLAS +`__ +and `LAPACK `__ to do this kind +of math - the same as many other languages. + +- `Linear algebra in numpy + `__ + +- `Many, many other array functions + `__ + +- `Scipy `__ has even + more functions + +- Many other libraries use NumPy arrays as the standard data + structure: they take data in this format, and return it similarly. + Thus, all the other packages you may want to use are compatible + +- If you need to write your own fast code in C, NumPy arrays can be + used to pass data. This is known as `extending Python + `__. + + + + +Additional exercises +-------------------- + +.. challenge:: Numpy-5 + + If you have extra time, try these out. These are advanced and + optional, and will not be done in most courses. + + 1. Reverse a vector. Given a vector, reverse it such that the last + element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]`` + + 2. Create a 2D array with zeros on the borders and 1 inside. + + 3. Create a random array with elements [0, 1), then add 10 to all + elements in the range [0.2, 0.7). + + 4. What is :func:`np.round(0.5) `? What is ``np.round(1.5)``? Why? + + 5. In addition to ``np.round``, explore :data:`numpy.ceil`, :data:`numpy.floor`, + :data:`numpy.trunc`. In particular, take note of how they behave with + negative numbers. + + 6. Recall the identity :math:`\sin^2(x) + \cos^2(x) = 1`. Create a + random 4x4 array with values in the range [0, 10). Now test the + equality with :data:`numpy.equal`. What result do you get with + :func:`numpy.allclose` instead of ``np.equal``? + + 7. Create a 1D array with 10 random elements. Sort it. + + 8. What's the difference between :meth:`np_array.sort() ` and + :func:`np.sort(np_array) `? + + 9. For the random array in question 8, instead of sorting it, perform + an indirect sort. That is, return the list of indices which would + index the array in sorted order. + + 10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next + combine them into a single 8x4 array with the content of the zeros + array on top and the ones on the bottom. Finally, do the same, + but create a 4x8 array with the zeros on the left and the ones on + the right. + + 11. NumPy functionality Create two 2D arrays and do matrix multiplication + first manually (for loop), then using the np.dot function. Use %%timeit + to compare execution times. What is happening? + + +.. solution:: Solution Numpy-5 + + 1. One solution is:: + + a = np.array([1, 2, 3]) + a[::-1] + + 2. One solution is:: + + b = np.ones((10,10)) + b[:,[0, -1]]=0 + b[[0, -1],:]=0 + + 3. A possible solution is:: + + x = np.random.rand(100) + y = x + 10*(x >= 0.2)*(x < 0.7) + + 4. For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. + + 5. Let's test those functions with few negative and positive values:: + + a = np.array([-3.3, -2.5, -1.5, -0.75, -0.5, 0.5, 0.75, 1.5, 2.5, 3]) + np.round(a) + np.ceil(a) + np.floor(a) + np.trun(a) + + 6. One solution is:: + + x = 10*np.random.rand(4,4) + oo = np.ones((4,4)) + s2c2 = np.square(np.sin(x))+np.square(np.cos(x)) + np.equal(oo,s2c2) + np.allclose(oo,s2c2) + + 7. Sorting the array itself, without copying it:: + + x = np.random.rand(10) + x.sort() + + 8. NumPy.sort() returns a sorted copy of an array. + + 9. ``np.argsort(x)`` + + 10. One solution is:: + + z = np.zeros((4,4)) + o = np.ones((4,4)) + np.concatenate((z,o)) + np.concatenate((z,o),axis=1) + + 11. Using numpy without numpy functionality (np.dot) in this case, is still slow. + + + +See also +-------- + +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + +* `2020 Nature paper on NumPy's role and basic concepts `__ + + + +.. keypoints:: + + - NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally. + - Be aware of some NumPy specific peculiarities diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/packaging.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/packaging.rst.txt new file mode 100644 index 00000000..7b795f1f --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/packaging.rst.txt @@ -0,0 +1,324 @@ +Packaging +========= + +.. questions:: + + - How to organize Python projects larger than one script? + - What is a good file and folder structure for Python projects? + - How can you make your Python functions most usable by your collaborators? + - How to prepare your code to make a Python package? + - How to publish your Python package? + +.. objectives:: + + - Learn to identify the components of a Python package + - Learn to create a Python package + - Learn to publish a Python package + + +Organizing Python projects +-------------------------- + +Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file. + +In the :ref:`scripts` episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further. + +**Recommendations**: + +- Collect related functions into modules (files). +- Collect related modules into packages (we will show how). +- Add a ``LICENSE`` file to your code + (see `Software Licensing and Open source explained with cakes `__). +- Write a ``README.md`` file describing what the code does and how to use it. +- It is also recommended to `document your package `__. +- When the project grows, you might need `automated testing `__. + +To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: ``scipy``. + +These are the 3 files: + +.. literalinclude:: packaging-example-project/calculator/adding.py + :caption: adding.py + +.. literalinclude:: packaging-example-project/calculator/subtracting.py + :caption: subtracting.py + +.. literalinclude:: packaging-example-project/calculator/integrating.py + :caption: integrating.py + +We will add a fourth file: + +.. literalinclude:: packaging-example-project/calculator/__init__.py + :caption: __init__.py + +This ``__init__.py`` file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using *relative imports* +(with the dot). + +This is how we will arrange the files in the project folder/repository: + +.. code-block:: none + :emphasize-lines: 3-6 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + └── README.md + +Now we are ready to test the package. For this we need to be in the "root" +folder, what we have called the *project-folder*. We also need to have +``scipy`` available in our environment: + +.. literalinclude:: packaging-example-project/test.py + +The package is not yet pip-installable, though. We will make this possible in +the next section. + + +Testing a local pip install +--------------------------- + +To make our example package pip-installable we need to add one more file: + +.. code-block:: none + :emphasize-lines: 9 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + ├── README.md + └── pyproject.toml + +This is how ``pyproject.toml`` looks: + +.. literalinclude:: packaging-example-project/pyproject.toml + :caption: pyproject.toml + :emphasize-lines: 13-15 + +Note how our package requires ``scipy`` and we decided to not pin the version +here (see :ref:`version_pinning`). + +Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see :ref:`pypi`) + + + +Exercises 1 +----------- + +.. challenge:: Packaging-1 + + To test a local pip install: + + - Create a new folder outside of our example project + - Create a new virtual environment (:ref:`dependency_management`) + - Install the example package from the project folder + into the new environment: ``$ pip install /path/to/project-folder/`` + - Test the local installation: + + .. literalinclude:: packaging-example-project/test.py + + +Sharing packages via PyPI +------------------------- + +Once we are able to pip-install the example package locally, we are ready for +upload. + +We exercise by uploading to `test-PyPI `__, not the +real `PyPI `__, so that if we mess things up, nothing bad +happens. + +We need two more things: + +- We will do this using `Twine `__ so you need + to pip install that, too. +- You need an account on `test-PyPI `__. + +.. highlight:: console + +Let's try it out. First we create the distribution package:: + + $ python3 -m build + +We need twine:: + + $ pip install twine + +And use twine to upload the distribution files to test-PyPI:: + + $ twine upload -r testpypi dist/* + + Uploading distributions to https://test.pypi.org/legacy/ + Enter your username: + Enter your password: + +Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt "myname"):: + + $ pip install -i https://test.pypi.org/simple/ calculator-myname + + +Tools that simplify sharing via PyPI +------------------------------------ + +The solution that we have used to create the example package (using +``setuptools`` and ``twine``) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using ``pyproject.toml`` as more general +alternative to the previous ``setup.py``. + +There are at least two tools which try to make the packaging and PyPI interaction easier: + +- `Poetry `__ +- `Flit `__ + + +Building a conda package and share it +------------------------------------- + +.. demo:: + + Most people will watch and observe this, due to speed which we will + move. + +.. callout:: Prerequisites + + To create a conda package, `conda-build` package is required. You may install it with **Anaconda Navigator** or from the command line:: + + $ conda install conda-build + + +The simplest way for creating a conda package for your python script is to +first publish it in `PyPI `__ following the steps explained +above. + + +Building a python package with conda skeleton pypi +*************************************************** + +Once build, the conda package can be installed locally. For this example, we +will use `runtest `__. `runtest +`__ is a numerically tolerant end-to-end test +library for research software. + +1. Create pypi skeleton:: + + $ conda skeleton pypi runtest + + The command above will create a new folder called `runtest` containing a file `meta.yaml`, the conda recipe for `runtest`. + +2. Edit `meta.yaml` and update requirements: + + .. code-block:: yaml + + requirements: + host: + - pip + - python + - flit + run: + - python + - flit + + In the requirements above, we specified what is required for the `host `__ and for `running `__ the package. + + .. callout:: Remark + + For pure python recipes, this is all you need for building a python package with conda. + If your package needs to be built (for instance compilation), you would need additional files e.g. `build.sh` (to build on Linux/Mac-OSX) and `bld.bat` (to build on Windows systems). You can also add test scripts for testing your package. See `documentation `__ + + +3. Build your package with conda + + Your package is now ready to be build with conda:: + + $ conda-build runtest + + + .. callout:: Conda package location + + Look at the messages produced while building. The location of the local conda package is given (search for `anaconda upload`): + + .. code-block:: none + + ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2 + + The prefix `~/anaconda3/` may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder `win-64` differs too (for instance `linux-64` on Linux machines). + + The conda package we have created is specific to your platform (here `win-64`). It can be converted to other platforms using `conda convert `__. + +4. Check within new environment + + It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments. + + :: + + $ conda create -n local-runtest --use-local runtest + + We can then check `runtest` has been successfully installed in `local-runtest` conda environment. Open a new Terminal with `local-runtest` environment (either from the command line:: + + $ conda activate local-runtest + + or via **Anaconda Navigator** (Open Terminal), import runtest and + check its version: + + .. code-block:: python + + import runtest + print(runtest.__version__) + + +.. callout:: Building a conda package from scratch + + It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the `conda-build documentation `__ for more information. + +To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a `conda channel `__ (see below). + + + +Publishing a python package +*************************** + +- Upload your package to *Anaconda.org*: see instructions `here + `__. + Please note that you will have to create an account on Anaconda. + +- Upload your package to `conda-forge `__: + conda-forge is a conda channel: it contains community-led collection of + recipes, build infrastructure and distributions for the conda package + manager. Anyone can public conda packages to conda-forge if certain + `guidelines `__ are respected. + +- Upload your package to `bioconda `_: bioconda is + a very popular channel for the conda package manager specializing in + bioinformatics software. As for conda-forge, you need to follow their + `guidelines `__ when + building conda recipes. + +You can also `create your own conda channel +`__ +for publishing your packages. + + +.. keypoints:: + + - It is worth it to organize your code for publishing, even if only + you are using it. + - PyPI is a place for Python packages + - conda is similar but is not limited to Python diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/pandas.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/pandas.rst.txt new file mode 100644 index 00000000..1be7f36d --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/pandas.rst.txt @@ -0,0 +1,604 @@ +Pandas +====== + +.. questions:: + + - How do I learn a new Python package? + - How can I use pandas dataframes in my research? + +.. objectives:: + + - Learn simple and some more advanced usage of pandas dataframes + - Get a feeling for when pandas is useful and know where to find more information + - Understand enough of pandas to be able to read its documentation. + +.. default-domain:: py + + +Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including: + +- a `Getting started guide `__ + (including tutorials and a 10 minute flash intro) +- a `"10 minutes to pandas" `__ + tutorial +- thorough `Documentation `__ containing a user guide, + API reference and contribution guide +- a `cheatsheet `__ +- a `cookbook `__. + +A quick Pandas preview +---------------------- + +Let's get a flavor of what we can do with pandas (you won't be able to follow everything yet). We will be working with an example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:: + + import pandas as pd + +We can download the data from `this GitHub repository `__ +by visiting the page and saving it to disk, or by directly reading into +a :class:`~pandas.DataFrame`:: + + url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv" + titanic = pd.read_csv(url, index_col='Name') + +We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:: + + # print the first 5 lines of the dataframe + titanic.head() + +:: + + # print summary statistics for each column + titanic.describe() + +Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38\% of passengers survived, etc. + +Let's say we're interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn't survive, and plot corresponding histograms of +the age distribution (:meth:`pandas.DataFrame.groupby`, :meth:`pandas.DataFrame.hist`):: + + print(titanic.groupby("Survived")["Age"].mean()) + +:: + + titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10), + layout=(2,1), zorder=2, sharex=True, rwidth=0.9); + + +Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let's get back to basics. + +.. callout:: Getting help + + Series and DataFrames have a lot functionality, but + how can we find out what methods are available and how they work? One way is to visit + the `API reference `__ + and reading through the list. + Another way is to use the autocompletion feature in Jupyter and type e.g. + ``titanic["Age"].`` in a notebook and then hit ``TAB`` twice - this should open + up a list menu of available methods and attributes. + + Jupyter also offers quick access to help pages (docstrings) which can be + more efficient than searching the internet. Two ways exist: + + - Write a function name followed by question mark and execute the cell, e.g. + write ``titanic.hist?`` and hit ``SHIFT + ENTER``. + - Write the function name and hit ``SHIFT + TAB``. + - Right click and select "Show contextual help". This tab will + update with help for anything you click. + + +What's in a dataframe? +---------------------- + +As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +:class:`pandas.DataFrame` +is composed of rows and columns: + +.. image:: img/pandas/01_table_dataframe.svg + +Each column of a dataframe is a :class:`pandas.Series` object +- a dataframe is thus a collection of series:: + + # print some information about the columns + titanic.info() + +Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type ``int64`` or of type ``object``. + +Let's inspect one column of the Titanic passanger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):: + + titanic["Age"] + titanic.Age # same as above + +:: + + type(titanic["Age"]) # a pandas Series object + +The columns have names. Here's how to get them (:attr:`~pandas.DataFrame.columns`):: + + titanic.columns + +However, the rows also have names! This is what Pandas calls the :obj:`~pandas.DataFrame.index`:: + + titanic.index + +We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and +values. We can refer to columns and rows either by their name +(:attr:`~pandas.DataFrame.loc`, :attr:`~pandas.DataFrame.at`) or by +their index (:attr:`~pandas.DataFrame.iloc`, +:attr:`~pandas.DataFrame.iat`):: + + titanic.loc['Lam, Mr. Ali',"Age"] # select single value by row and column + titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"] # slice the dataframe by row and column *names* + titanic.iloc[0:2,3:6] # same slice as above by row and column *numbers* + + titanic.at['Lam, Mr. Ali',"Age"] = 42 # set single value by row and column *name* (fast) + titanic.at['Lam, Mr. Ali',"Age"] # select single value by row and column *name* (fast) + titanic.iat[0,5] # select same value by row and column *number* (fast) + + titanic["is_passenger"] = True # set a whole column + +Dataframes also support boolean indexing, just like we saw for ``numpy`` +arrays:: + + titanic[titanic["Age"] > 70] + # ".str" creates a string object from a column + titanic[titanic.index.str.contains("Margaret")] + +What if your dataset has missing data? Pandas uses the value :py:data:`numpy.nan` +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:: + + titanic.isna() # returns boolean mask of NaN values + titanic.dropna() # drop missing values + titanic.dropna(how="any") # or how="all" + titanic.dropna(subset=["Cabin"]) # only drop NaNs from one column + titanic.fillna(0) # replace NaNs with zero + titanic.fillna(method='ffill') # forward-fill NaNs + + + +Exercises 1 +----------- + +.. challenge:: Exploring dataframes + + - Have a look at the available methods and attributes using the + `API reference `__ + or the autocomplete feature in Jupyter. + - Try out a few methods using the Titanic dataset and have a look at + the docstrings (help pages) of methods that pique your interest + - Compute the mean age of the first 10 passengers by slicing and the :py:meth:`pandas.DataFrame.mean` method + - (Advanced) Using boolean indexing, compute the survival rate + (mean of "Survived" values) among passengers over and under the average age. + + .. solution:: + + - Mean age of the first 10 passengers:: + + titanic.iloc[:10,:]["Age"].mean() + + or:: + + titanic.loc[:"Nasser, Mrs. Nicholas (Adele Achem)","Age"].mean() + + or:: + + titanic.iloc[:10,4].mean() + + - Survival rate among passengers over and under average age:: + + titanic[titanic["Age"] > titanic["Age"].mean()]["Survived"].mean() + + and:: + + titanic[titanic["Age"] < titanic["Age"].mean()]["Survived"].mean() + + +Tidy data +--------- + +The above analysis was rather straightforward thanks to the fact +that the dataset is *tidy*. + +.. image:: img/pandas/tidy_data.png + +In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data. + +What would untidy data look like? Here's an example from +some run time statistics from a 1500 m running event:: + + runners = pd.DataFrame([ + {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240}, + {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300}, + {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360}, + ]) + +What makes this data untidy is that the column names `400, 800, 1200, 1500` +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row. + +To make untidy data tidy, a common operation is to "melt" it, +which is to convert it from wide form to a long form:: + + runners = pd.melt(runners, id_vars="Runner", + value_vars=[400, 800, 1200, 1500], + var_name="distance", + value_name="time" + ) + +In this form it's easier to **filter**, **group**, **join** +and **aggregate** the data, and it's also easier to model relationships +between variables. + +The opposite of melting is to *pivot* data, which can be useful to +view data in different ways as we'll see below. + +For a detailed exposition of data tidying, have a look at +`this article `__. + + + +Working with dataframes +----------------------- + +We saw above how we can read in data into a dataframe using the :func:`~pandas.read_csv` function. +Pandas also understands multiple other formats, for example using :obj:`~pandas.read_excel`, +:obj:`~pandas.read_hdf`, :obj:`~pandas.read_json`, etc. (and corresponding methods to write to file: +:obj:`~pandas.DataFrame.to_csv`, :obj:`~pandas.DataFrame.to_excel`, :obj:`~pandas.DataFrame.to_hdf`, :obj:`~pandas.DataFrame.to_json`, etc.) + +But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +:class:`~pandas.DataFrame` docs):: + + import numpy as np + dates = pd.date_range('20130101', periods=6) + df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD')) + df + +or a dictionary (see same docs):: + + df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'], + 'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'], + 'C': np.array([3] * 8, dtype='int32'), + 'D': np.random.randn(8), + 'E': np.random.randn(8)}) + df + +There are many ways to operate on dataframes. Let's look at a +few examples in order to get a feeling of what's possible +and what the use cases can be. + +We can easily split and :func:`concatenate ` dataframes:: + + sub1, sub2, sub3 = df[:2], df[2:4], df[4:] + pd.concat([sub1, sub2, sub3]) + +When pulling data from multiple dataframes, a powerful :obj:`pandas.DataFrame.merge` method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:: + + age = pd.DataFrame([ + {"Runner": "Runner 4", "Age": 18}, + {"Runner": "Runner 2", "Age": 21}, + {"Runner": "Runner 1", "Age": 23}, + {"Runner": "Runner 3", "Age": 19}, + ]) + +We now want to use this table to annotate the original ``runners`` table from +before with their age. Note that the ``runners`` and ``age`` dataframes have a +different ordering to it, and ``age`` has an entry for ``Dave`` which is not +present in the ``runners`` table. We can let Pandas deal with all of it using +the :obj:`~pandas.DataFrame.merge` method:: + + # Add the age for each runner + runners.merge(age, on="Runner") + +In fact, much of what can be done in SQL +`is also possible with pandas `__. + +:obj:`~pandas.DataFrame.groupby` is a powerful method which splits a dataframe and aggregates data +in groups. To see what's possible, let's return to the Titanic dataset. Let's +test the old saying "Women and children first". We start by creating a new +column ``Child`` to indicate whether a passenger was a child or not, based on +the existing ``Age`` column. For this example, let's assume that you are a +child when you are younger than 12 years:: + + titanic["Child"] = titanic["Age"] < 12 + +Now we can test the saying by grouping the data on ``Sex`` and then creating further sub-groups based on ``Child``:: + + titanic.groupby(["Sex", "Child"])["Survived"].mean() + +Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +:obj:`~pandas.DataFrame.std`, :obj:`~pandas.DataFrame.min`, +:obj:`~pandas.DataFrame.max`, :obj:`~pandas.DataFrame.cumsum`, +:obj:`~pandas.DataFrame.median`, :obj:`~pandas.DataFrame.skew`, +:obj:`~pandas.DataFrame.var` etc. + + + +Exercises 2 +----------- + +.. challenge:: Analyze the Titanic passenger list dataset + + In the Titanic passenger list dataset, + investigate the family size of the passengers (i.e. the "SibSp" column). + + - What different family sizes exist in the passenger list? Hint: try the :meth:`~pandas.Series.unique` method + - What are the names of the people in the largest family group? + - (Advanced) Create histograms showing the distribution of family sizes for + passengers split by the fare, i.e. one group of high-fare passengers (where + the fare is above average) and one for low-fare passengers + (Hint: instead of an existing column name, you can give a lambda function + as a parameter to :meth:`~pandas.DataFrame.hist` to compute a value on the fly. For example + ``lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich"``). + + .. solution:: + + - Existing family sizes:: + + titanic["SibSp"].unique() + + - We get 8 from above. There is no ``Name`` column, since we + made ``Name`` the index when we loaded the dataframe with + ``read_csv``, so we use :attr:`pandas.DataFrame.index` to get + the names. So, names of members of largest family(ies):: + + titanic[titanic["SibSp"] == 8].index + + - Histogram of family size based on fare class:: + + titanic.hist("SibSp", + lambda x: "Poor" if titanic["Fare"].loc[x] < titanic["Fare"].mean() else "Rich", + rwidth=0.9) + + + + +Time series superpowers +----------------------- + +An introduction of pandas wouldn't be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv . + +Unfortunately this API does not allow "non-browser requests", so +:obj:`pandas.read_csv` will not work directly on it. Instead, we put a +local copy on Github which we can access (the original data is CC-0, +so we are allowed to do this). (Aside: if you do JupyterLab → +File → Open from URL → paste the URL above, it will open it in +JupyterLab *and* download a copy for your use.) + +We can then load and explore the data:: + + nobel = pd.read_csv("https://github.com/AaltoSciComp/python-for-scicomp/raw/master/resources/data/laureate.csv") + nobel.head() + +This dataset has three columns for time, "born"/"died" and "year". +These are represented as strings and integers, respectively, and +need to be converted to datetime format. :func:`pandas.to_datetime` +makes this easy:: + + # the errors='coerce' argument is needed because the dataset is a bit messy + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + +Pandas knows a lot about dates (using :ref:`/user_guide/basics.rst#dt-accessor`):: + + print(nobel["born"].dt.day) + print(nobel["born"].dt.year) + print(nobel["born"].dt.weekday) + +We can add a column containing the (approximate) lifespan in years rounded +to one decimal:: + + nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1) + +and then plot a :meth:`histogram ` of lifespans:: + + nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9) + +Finally, let's see one more example of an informative plot (:meth:`~pandas.DataFrame.boxplot`) +produced by a single line of code:: + + nobel.boxplot(column="lifespan", by="category") + + + +Exercises 3 +----------- + +.. challenge:: Analyze the Nobel prize dataset + + - What country has received the largest number of Nobel prizes, and how many? + How many countries are represented in the dataset? Hint: use the :obj:`~pandas.Series.describe` method + on the ``bornCountryCode`` column. + - Create a histogram of the age when the laureates received their Nobel prizes. + Hint: follow the above steps we performed for the lifespan. + - List all the Nobel laureates from your country. + + Now more advanced steps: + + - Now define an array of 4 countries of your choice and extract + only laureates from these countries (you need to look at the + data and find how countries are written, and replace ``COUNTRY`` + with those strings):: + + countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4]) + subset = nobel.loc[nobel['bornCountry'].isin(countries)] + + - Use :meth:`~pandas.DataFrame.groupby` to compute how many nobel prizes each country received in + each category. The :meth:`~pandas.core.groupby.GroupBy.size` method tells us how many rows, hence nobel + prizes, are in each group:: + + nobel.groupby(['bornCountry', 'category']).size() + + - (Optional) Create a pivot table to view a spreadsheet like structure, and view it + + - First add a column “number” to the nobel dataframe containing 1’s + (to enable the counting below). We need to make a copy of + ``subset``, because right now it is only a view:: + + subset = subset.copy() + subset.loc[:, 'number'] = 1 + + - Then create the :meth:`~pandas.DataFrame.pivot_table`:: + + table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum) + + - (Optional) Install the **seaborn** visualization library if you don't + already have it, and create a heatmap of your table:: + + import seaborn as sns + sns.heatmap(table,linewidths=.5); + + - Play around with other nice looking plots:: + + sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset); + + :: + + sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5); + + :: + + subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))] + sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm"); + + :: + + sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count"); + + + .. solution:: + + Below is solutions for the basic steps, advanced steps are + inline above. + + We use the :meth:`describe` method: + + :: + + nobel.bornCountryCode.describe() + # count 956 + # unique 81 + # top US + # freq 287 + + We see that the US has received the largest number of Nobel prizes, + and 81 countries are represented. + + To calculate the age at which laureates receive their prize, we need + to ensure that the "year" and "born" columns are in datetime format:: + + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + + Then we add a column with the age at which Nobel prize was received + and plot a histogram:: + + nobel["age_nobel"] = round((nobel["year"] - nobel["born"]).dt.days / 365, 1) + nobel.hist(column="age_nobel", bins=25, figsize=(8,10), rwidth=0.9) + + We can print names of all laureates from a given country, e.g.:: + + nobel[nobel["country"] == "Sweden"].loc[:, "firstname":"surname"] + +Beyond the basics +----------------- + +Larger DataFrame operations might be faster using :func:`~pandas.eval` with string expressions, `see +`__:: + + import pandas as pd + # Make some really big dataframes + nrows, ncols = 100000, 100 + rng = np.random.RandomState(42) + df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols)) + for i in range(4)) + +Adding dataframes the pythonic way yields:: + + %timeit df1 + df2 + df3 + df4 + # 80ms + +And by using :func:`~pandas.eval`:: + + %timeit pd.eval('df1 + df2 + df3 + df4') + # 40ms + + +We can assign function return lists as dataframe columns:: + + def fibo(n): + """Compute Fibonacci numbers. Here we skip the overhead from the + recursive function calls by using a list. """ + if n < 0: + raise NotImplementedError('Not defined for negative values') + elif n < 2: + return n + memo = [0]*(n+1) + memo[0] = 0 + memo[1] = 1 + for i in range(2, n+1): + memo[i] = memo[i-1] + memo[i-2] + return memo + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = fibo(99) # Assigns list to column + + +There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its `API +`__. You should try to get good at +searching the web for an example showing what you can do. And when +there is not, you can always +apply your own functions to the data using :obj:`~pandas.DataFrame.apply`:: + + + from functools import lru_cache + + @lru_cache + def fib(x): + """Compute Fibonacci numbers. The @lru_cache remembers values we + computed before, which speeds up this function a lot.""" + if x < 0: + raise NotImplementedError('Not defined for negative values') + elif x < 2: + return x + else: + return fib(x - 2) + fib(x - 1) + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = df['Generation'].apply(fib) + + +Note that the numpy precisision for integers caps at int64 while python ints are unbounded -- +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df['Number of Rabbits'][99] given by both functions above +is in fact . + + +.. keypoints:: + + - pandas dataframes are a good data structure for tabular data + - Dataframes allow both simple and advanced analysis in very compact form diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/parallel-pi-multiprocessing.ipynb.txt b/branch/rkdarst--dependengi-exercise-time/_sources/parallel-pi-multiprocessing.ipynb.txt new file mode 100644 index 00000000..970dbada --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/parallel-pi-multiprocessing.ipynb.txt @@ -0,0 +1,303 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Python multithreading solution\n", + "Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import random" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "def sample(n):\n", + " \"\"\"Make n trials of points in the square. Return (n, number_in_circle)\n", + " \n", + " This is our basic function. By design, it returns everything it\\\n", + " needs to compute the final answer: both n (even though it is an input\n", + " argument) and n_inside_circle. To compute our final answer, all we\n", + " have to do is sum up the n:s and the n_inside_circle:s and do our\n", + " computation\"\"\"\n", + " n_inside_circle = 0\n", + " for i in range(n):\n", + " x = random.random()\n", + " y = random.random()\n", + " if x**2 + y**2 < 1.0:\n", + " n_inside_circle += 1\n", + " return n, n_inside_circle" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it just for timing\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Do the actual calculation (the previous result doesn't get saved)\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is the \"calculate answer\" phase." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.144548" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "pi = 4.0 * (n_inside_circle / n)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in parallel with multiprocessing\n", + "This divides the calculation into 10 tasks and runs `sample` on each of them. Then it re-combines the results." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import multiprocessing.pool\n", + "pool = multiprocessing.pool.Pool()\n", + "# The default pool makes one process per CPU" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it once to time it\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "pool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.140768" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in \"parallel\" with threads\n", + "To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool = multiprocessing.pool.ThreadPool()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%timeit -o\n", + "# Do it once to time it\n", + "threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.142388" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Future ideas\n", + "\n", + "You could make a separate `calculate` function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.\n", + "\n", + "Notice the similarity to [split-apply-combine](https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html) or [map-reduce](https://en.wikipedia.org/wiki/MapReduce) which is a specialization of split-apply-combine." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/parallel.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/parallel.rst.txt new file mode 100644 index 00000000..7c895ac9 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/parallel.rst.txt @@ -0,0 +1,517 @@ +Parallel programming +==================== + +.. questions:: + + - When you need more than one processor, what do you do? + - How can we use more than one processor/core in Python? + +.. objectives:: + + - Understand the major strategies of parallelizing code + - Understand mechanics of the ``multiprocessing`` package + - Know when to use more advanced packages or approaches + + + +Modes of parallelism +-------------------- + +You realize you do have more computation to do than you can on one processor? +What do you do? + +1. Profile your code, identify the *actual* slow spots. + +2. Can you improve your code in those areas? Use an existing library? + +3. Are there are any low-effort optimizations that you can make? + +4. Consider using `numba `__ or + `cython `__ to accelerate key functions. + +5. Think about parallelizing. + + +Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers). + +**Parallel computing** is when many different tasks are carried out +simultaneously. There are three main models: + +* **Embarrassingly parallel:** the code does not need to + synchronize/communicate with other instances, and you can run + multiple instances of the code separately, and combine the results + later. If you can do this, great! (array jobs, task queues, + workflow management tools) + +* **Multithreading:** Parallel threads need to communicate and do so via + the same memory (variables, state, etc). (OpenMP, ``threading``) + +* **Multiprocessing, message passing:** Different processes manage + their own memory segments. They share data by communicating (passing + messages) as needed. (``multiprocessing``, MPI). + +.. warning:: + + Parallel programming is not magic, but many things can go wrong and + you can get unexpected results or difficult to debug problems. + Parallel programming is a fascinating world to get involved in, but + make sure you invest enough time to do it well. + + See the video by Raymond Hettinger ("See Also" at bottom + of page) for an entertaining take on this. + + + +Multithreading and the GIL +-------------------------- + +The designers of the Python language made the choice +that **only one thread in a process can run actual Python code** +by using the so-called **global interpreter lock (GIL)**. +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. *But it's not all bad!:* + +* External libraries (NumPy, SciPy, Pandas, etc), written in C or other + languages, can release the lock and run multi-threaded. + +* Most input/output releases the GIL, and input/output is slow. The + ``threading`` library can be used to multithread I/O. + +* Python libraries like ``multiprocessing`` and ``mpi4py`` run *multiple + Python processes* and this circumvents the GIL. + + +Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix: + +.. code-block:: python + + import numpy as np + import time + + A = np.random.random((4000,4000)) + A = A * A.T + time_start = time.time() + np.linalg.inv(A) + time_end = time.time() + print("time spent for inverting A is", round(time_end - time_start,2), 's') + +If we run this in a Jupyter notebook or through a Python script, **it +will automatically use multithreading** through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either ``export OMP_NUM_THREADS=1`` or ``export MKL_NUM_THREADS=1``, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime. + + +.. seealso:: + + * `More on the global interpreter lock + `__ + * `Threading python module + `__. This is + very low level and you shouldn't use it unless you really know what + you are doing. + * We recommend you find a UNIX threading tutorial first before embarking + on using the :py:mod:`threading` module. + + + +multiprocessing +--------------- + +As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +:py:mod:`multiprocessing` module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock. + +To show an example, +the `split-apply-combine `__ +or `map-reduce `__ paradigm is +quite useful for many scientific workflows. Consider you have this:: + + def square(x): + return x*x + +You can apply the function to every element in a list using the +:py:func:`map` function: + +.. code-block:: pycon + + >>> list(map(square, [1, 2, 3, 4, 5, 6])) + [1, 4, 9, 16, 25, 36] + +The :py:class:`multiprocessing.pool.Pool` class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list: + +.. code-block:: pycon + + >>> from multiprocessing import Pool + >>> with Pool() as pool: + ... pool.map(square, [1, 2, 3, 4, 5, 6]) + [1, 4, 9, 16, 25, 36] + +.. warning:: + + Running the above example **interactively** in a Jupyter notebook + or through an Python/IPython terminal may or may not work on your + computer! This is a feature and not a bug, as covered in the + `documentation `__. + + Fortunately, there is a fork of multiprocesssing called + `multiprocess `__ which does + work in interactive environments. All we have to do is install it + by ``pip install multiprocess`` and change the import statement: + ``from multiprocess import Pool``. + + +Exercises, multiprocessing +-------------------------- + +.. challenge:: Parallel-1, multiprocessing + + Here, you find some code which calculates pi by a stochastic + algorithm. You don't really need to worry how the algorithm works, + but it computes random points in a 1x1 square, and computes the + number that fall into a circle. Copy it into a Jupyter notebook + and use the ``%%timeit`` cell magic on the computation part (the + one highlighted line after timeit below): + + .. code-block:: python + :emphasize-lines: 20 + + import random + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x**2 + y**2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + %%timeit + n, n_inside_circle = sample(10**6) + + pi = 4.0 * (n_inside_circle / n) + pi + + Using the :py:class:`multiprocessing.pool.Pool` code from the lesson, run + the ``sample`` function 10 times, each with ``10**5`` samples + only. Combine the results and time the calculation. What is the + difference in time taken? + + NOTE: If you're working in an interactive environment and this + doesn't work with the ``multiprocessing`` module, install and use + the ``multiprocess`` module instead! + + (optional, advanced) Do the same but with + :py:class:`multiprocessing.pool.ThreadPool` instead. This works identically + to ``Pool``, but uses threads instead of different processes. + Compare the time taken. + + .. solution:: + + See the finished notebook here: + + .. toctree:: + + parallel-pi-multiprocessing + + You notice the version with ``ThreadPool`` is no faster, and + probably takes even longer. This is because this is a + pure-Python function which can not run simultaneously in + multiple threads. + +.. challenge:: (advanced) Parallel-2 Running on a cluster + + How does the pool know how many CPUs to take? What happens if you + run on a computer cluster and request only part of the CPUs on a + node? + + .. solution:: + + Pool by default uses one process for each CPU on the node - it + doesn't know about your cluster's scheduling system. It's + possible that you have permission to use 2 CPUs but it is trying + to use 12. This is generally a bad situation, and will just + slow you down (and make other users on the same node upset)! + + You either need to be able to specify the number of CPUs to use + (and pass it the right number), or make it aware of the cluster + system. For example, on a Slurm cluster you would check the + environment variable ``SLURM_CPUS_PER_TASK``. + + Whatever you do, document what your code is doing under the + hood, so that other users know what is going on (we've learned + this from experience...). + + +MPI +--- + +The message passing interface (MPI) approach to parallelization +is that: + +- Tasks (cores) have a rank and are numbered 0, 1, 2, 3, ... +- Each task (core) manages its own memory +- Tasks communicate and share data by sending messages +- Many higher-level functions exist to distribute information to other tasks + and gather information from other tasks +- All tasks typically run the entire code and we have to be careful to avoid + that all tasks do the same thing + +Introductory MPI lessons where Python is included: + +- https://rantahar.github.io/introduction-to-mpi/ +- https://pdc-support.github.io/introduction-to-mpi/ + +These blog posts are good for gentle MPI/mpi4py introduction: + +- https://www.kth.se/blogs/pdc/2019/08/parallel-programming-in-python-mpi4py-part-1/ +- https://www.kth.se/blogs/pdc/2019/11/parallel-programming-in-python-mpi4py-part-2/ + +Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together. + +Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work: + +.. code-block:: python + :emphasize-lines: 3,23-25,29,39,42 + + import random + import time + from mpi4py import MPI + + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x ** 2 + y ** 2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + + comm = MPI.COMM_WORLD + size = comm.Get_size() + rank = comm.Get_rank() + + n = 10 ** 7 + + if size > 1: + n_task = int(n / size) + else: + n_task = n + + t0 = time.perf_counter() + _, n_inside_circle = sample(n_task) + t = time.perf_counter() - t0 + + print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}") + n_inside_circle = comm.gather(n_inside_circle, root=0) + print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}") + + if rank == 0: + pi_estimate = 4.0 * sum(n_inside_circle) / n + print( + f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds" + ) + + + +Exercises, MPI +-------------- + +.. challenge:: Parallel-3, MPI + + We can do this as **exercise or as demo**. Note that this example requires ``mpi4py`` and a + MPI installation such as for instance `OpenMPI `__. + + - Try to run this example on one core: ``$ python example.py``. + - Then compare the output with a run on multiple cores (in this case 2): ``$ mpiexec -n 2 python example.py``. + - Can you guess what the ``comm.gather`` function does by looking at the print-outs right before and after. + - Why do we have the if-statement ``if rank == 0`` at the end? + - Why did we use ``_, n_inside_circle = sample(n_task)`` and not ``n, n_inside_circle = sample(n_task)``? + + + .. solution:: + + We first run the example normally, and get: + + .. code-block:: console + + $ python example.py + before gather: rank 0, n_inside_circle: 7854305 + after gather: rank 0, n_inside_circle: [7854305] + + number of darts: 10000000, estimate: 3.141722, time spent: 2.5 seconds + + Next we take advantage of the MPI parallelisation and run on 2 cores: + + .. code-block:: console + + $ mpirun -n 2 python mpi_test.py + before gather: rank 0, n_inside_circle: 3926634 + before gather: rank 1, n_inside_circle: 3925910 + after gather: rank 1, n_inside_circle: None + after gather: rank 0, n_inside_circle: [3926634, 3925910] + + number of darts: 10000000, estimate: 3.1410176, time spent: 1.3 seconds + + Note that two MPI processes are now printing output. Also, the parallel + version runs twice as fast! + + The ``comm.gather`` function collects (gathers) values of a + given variable from all MPI ranks onto one `root` rank, which is + conventionally rank 0. + + A conditional ``if rank == 0`` is typically used to print output + (or write data to file, etc) from only one rank. + + An underscore ``_`` is often used as a variable name in cases + where the data is unimportant and will not be reused. + +Coupling to other languages +--------------------------- + +As mentioned further up in "Multithreading and the GIL", Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP "directly". + +However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don't +need parallelism, but need to make an optimized algorithm for a small part of the code. + +Two strategies are common: + +- Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization: + + - C: use the `cffi `__ package (C foreign function interface). :py:mod:`ctypes` is a similar but slightly more primitive module that is in the standard library. + - C++: use `pybind11 `__ + - Fortran: create a C interface using ``iso_c_binding`` and then couple the C layer to Python + using `cffi `__ + - Rust: use `PyO3 `__ + +- Let compiled languages do the shared-memory parallelization part (as in above + point) and let Python do the MPI work and distribute tasks across nodes using + an ``mpi4py`` layer. + +Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course. + +Before you take this route, **profile the application** first to be sure where +the bottleneck is. + +Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason. + + + +Dask and task queues +-------------------- + +There are other strategies that go completely beyond the manual +parallelization methods above. We won't go into much detail. + +Dask +~~~~ + +`Dask `__ is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs. + +Dask is very popular for data analysis and is used by a number of high-level Python libraries: + +- Dask arrays scale NumPy (see also `xarray `__ +- Dask dataframes scale Pandas workflows +- Dask-ML scales Scikit-Learn + +Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block. + +.. discussion:: Example from dask.org + + .. code-block:: + + # Arrays implement the Numpy API + import dask.array as da + x = da.random.random(size=(10000, 10000), + chunks=(1000, 1000)) + x + x.T - x.mean(axis=0) + # It runs using multiple threads on your machine. + # It could also be distributed to multiple machines + + + +Exercises, Dask +--------------- + +.. challenge:: Dask-Examples (optional) + + `Dask examples `__ illustrate the usage of dask and can be run interactively through `mybinder `__. Start an `interactive session on mybinder `__ and test/run a few dask examples. + +.. warning: dask on HPC + + On HPC, it is important to use `dask-mpi `__ that deploys dask using MPI4Py. The setup can be a bit tricky and we recommend the usage of `dask-jobqueue and dask-drmaa `__: these packages need to be installed on the target platform (not through conda) to fully benefit from the native underlying MPI libraries. + +Task queues +~~~~~~~~~~~ + +A **task queue** has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for *embarrassingly parallel* jobs. + +There are different descriptions of `task queues in Python +`__. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant. + + + +See also +-------- + +* `Thinking about Concurrency, Raymond Hettinger + `__. Good introduction to simple and + safe concurrent code. +* `Introduction to Numba and Cython `__. +* `More detailed exposition of parallel computing in Python `__. +* `Introduction to Dask for scalable analytics `__. + +.. keypoints:: + + - Pure Python is not very good for highly parallel code. + - Luckily it interfaces to many things which *are* good, and give + you the full control you need. + - Combining vectorized functions (NumPy, Scipy, pandas, etc.) with + the parallel strategies listed here will get you very far. + - Another popular framework similar to `multiprocessing` is + `joblib `__. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/productivity.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/productivity.rst.txt new file mode 100644 index 00000000..77947234 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/productivity.rst.txt @@ -0,0 +1,548 @@ +Productivity tools +================== + +.. questions:: + + - Do you have preferences on the visual aspects of the code + and how it should look? + - Do you use any tools that help you create better looking + code faster? + +.. objectives:: + + - Learn tools that can help you be more productive. + - Learn how to follow standards that other people have created + and how to pick your own favorite. + +Spotting code problems with linters +----------------------------------- + +Python as a programming language has a syntax that specifies the +rules that the code must follow. If the code is not written with +valid syntax, you will get an error. + +.. code-block:: python + + # Valid syntax, returns 1 + a = 1 + print(a) + + # Invalid syntax, returns SyntaxError + True = 1 + +Spotting syntax errors can be time consuming and to help this +programmers have created **linters**. Linters are tools that +check whether code's syntax is correct. + +Some popular linters include: + +- `Ruff `__ +- `Pylint `__ +- `flake8 `__ + +In the following example lets use ``pylint`` to check the following +script (:download:`lint_example.py +<../resources/code/productivity/lint_example.py>`: to easily download +to JupyterLab, use File → Open from URL → Paste URL → It will download +and open in a window.): + +.. code-block:: python + + import numpy + import matplotlib.pyplot as plt + + x = np.linspace(0, np.pi, 100)) + y = np.sin(x) + + plt.plot(x, y) + + plt.show() + +To run ``pylint`` from the terminal in JupyterLab, File → New → +Terminal. Make sure you are in the right directory, then you can run +``pylint``: + +.. code-block:: console + + $ pylint lint_example.py + ************* Module lint_example + lint_example.py:4:31: E0001: Parsing failed: 'unmatched ')' (, line 4)' (syntax-error) + + +From here we can see that ``pylint`` says that there is a unmatched bracket +on line 4. We also get an message code E0001 (syntax-error). We can find +description for the message from +`Pylint's messages list `__ +and look at the +`specific error page `__ to see an example that describes the error. + +After fixing the problem with the bracket and running ``pylint`` again we +get more errors: + +.. code-block:: console + + $ pylint lint_example.py + ************* Module lint_example + lint_example.py:1:0: C0114: Missing module docstring (missing-module-docstring) + lint_example.py:4:4: E0602: Undefined variable 'np' (undefined-variable) + lint_example.py:4:19: E0602: Undefined variable 'np' (undefined-variable) + lint_example.py:5:4: E0602: Undefined variable 'np' (undefined-variable) + lint_example.py:1:0: W0611: Unused import numpy (unused-import) + + ------------------------------------------------------------------ + Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00) + +Here we see the following suggestions: + +- On line 1 we're missing a module docstring. This is a warning that we're + going against a coding convetion and thus we get a ``CXXXX`` message code. + This is not critical, so let's not focus on this for now. +- On lines 4 and 5 we have undefined variable ``np``. This will create + error if we would execute the code and thus we get a ``EXXXX`` message code. +- On line 1 we have unused import for ``numpy`` module. This won't create an + error, but Pylint flags this as unnecessary and will give a warning + with ``WXXX`` message code. + +At the end Pylint will give a rating for the code. In this case the +errors will give an overall rating of ``0.00/10`` as the code won't execute +correctly. + +From these messages we can deduce that the main problem is that the import +statement does not use ``import numpy as np`` and thus ``np`` is undefined. + +After changing the import stamement, the code works correctly and running +``pylint lint_example.py`` will only warn about the missing docstring. +You can also notice that the changes have increased the rating and +Pylint will show the improvement since last run. + +.. code-block:: console + + $ pylint lint_example.py + ************* Module lint_example + lint_example.py:1:0: C0114: Missing module docstring (missing-module-docstring) + + ------------------------------------------------------------------ + Your code has been rated at 8.33/10 (previous run: 0.00/10, +8.33) + + +Exercise 1 +---------- + +.. challenge:: Using Pylint + + The following code uses scikit-learn to fit a simple linear + model to randomly generated data with some error. You can download it + :download:`here <../resources/code/productivity/exercise1.py>` (see + above for how to easily download and run in JupyterLab). + + It has four mistakes in it. One of these cannot be found by + Pylint. + + Fix the following code with Pylint and try to determine why + Pylint did not find the last mistake. + + .. code-block:: python + + """ + pylint exercise 1 + """ + import numpy as np + import pandas as pd + import matplotlib.pyplot as plt + from sklearn import linear_model + + + def f(x): + """ + Example function: + + f(x) = x/2 + 2 + """" + return 0.5*x + 2 + + + # Create example data + x_data = np.linspace(0, 10, 100) + err = 2 * np.random.random(x_data.shape[0]) + y_data = f(x_data) + err + + # Put data into dataframe + df = pd.DataFrame({'x': x_data, 'y': y_data}) + + # Create linear model and fit data + reg = linear_model.LinearRegression(fit_intercept=True) + + reg.fit(df[['x'], df[['y']]) + + slope = reg.coef_[0][0] + intercept = reg.intercept_[0] + + df['pred'] = reg.predict(df[['x']]) + + fig, ax = plt.subplots() + + ax.scater(df[['x']], df[['y']], alpha=0.5) + ax.plot(df[['x']], df[['pred']] + color='black', linestyle='--', + label=f'Prediction with slope {slope:.2f} and intercept {intercept:.2f}') + ax.set_ylabel('y') + ax.set_xlabel('x') + ax.legend() + + plt.show() + +.. solution:: + + Solution is available + :download:`here <../resources/code/productivity/exercise1_solution.py>`. + + Errors were as follows: + + 1. Line 15 has an extra ``"``-character, which results in syntax-error. + 2. Line 30 has a missing ``]``-bracker, which results in syntax-error. + 3. Line 40 is missing a comma at the end, which results in syntax-error. + 4. On line 39 the function ``scatter`` is misspelled. Pylint does not + notice this as it does not run the code and thus it does not + create the ax-object. + + .. code-block:: python + + """ + pylint exercise 1 + """ + import numpy as np + import pandas as pd + import matplotlib.pyplot as plt + from sklearn import linear_model + + + def f(x): + """ + Example function: + + f(x) = x/2 + 2 + """ + return 0.5*x + 2 + + + # Create example data + x_data = np.linspace(0, 10, 100) + err = 2 * np.random.random(x_data.shape[0]) + y_data = f(x_data) + err + + # Put data into dataframe + df = pd.DataFrame({'x': x_data, 'y': y_data}) + + # Create linear model and fit data + reg = linear_model.LinearRegression(fit_intercept=True) + + reg.fit(df[['x']], df[['y']]) + + slope = reg.coef_[0][0] + intercept = reg.intercept_[0] + + df['pred'] = reg.predict(df[['x']]) + + fig, ax = plt.subplots() + + ax.scatter(df[['x']], df[['y']], alpha=0.5) + ax.plot(df[['x']], df[['pred']], + color='black', linestyle='--', + label=f'Prediction with slope {slope:.2f} and intercept {intercept:.2f}') + ax.set_ylabel('y') + ax.set_xlabel('x') + ax.legend() + + plt.show() + +Enforcing consistent code style +------------------------------- + +Python is a very flexible language which makes it possible to use +all kinds of coding styles. + +For example, one could use the following naming styles for variables: + +.. code-block:: python + + # Different variable styles + myvariable = 1 # Lowercase + myVariable = 1 # Camel case + MyVariable = 1 # Pascal case + my_variable = 1 # Snake case + +Everyone has their own preference to what style to use and everybody +has freedom to use their preferred style, but to improve legibility +of code there are official style guides for +`code (PEP 8) `__ and for +`docstrings (PEP 257) `__. + +There are many code checkers that give you suggestions on how +to modify your code or do the modifications automatically: + +- `flake8 `__ +- `black `__ +- `Ruff `__ +- `yapf `__ + +Let's use black and flake8 (with ``pep8-naming``-extension) to modify +:download:`code_style_example.py <../resources/code/productivity/code_style_example.py>`: + +.. code-block:: python + + import numpy as np + + def PI_estimate(n): + """This function calculates an estimate of pi with dart thrower algorithm. + """ + + pi_Numbers = np.random.random(size = 2*n) + x = pi_Numbers[ :n ] + y = pi_Numbers[ n: ] + + return 4*np.sum((x * x + y*y ) < 1)/n + + + for number in range(1,8): + + n = 10** number + + print(f'Estimate for PI with {n:8d} dart throws: {PI_estimate( n )}') + + +Running flake8 to check for style problems we get the following output: + +.. code-block:: console + + $ flake8 code_style_example.py + code_style_example.py:1:7: E271 multiple spaces after keyword + code_style_example.py:1:14: E272 multiple spaces before keyword + code_style_example.py:3:1: E302 expected 2 blank lines, found 1 + code_style_example.py:3:4: E271 multiple spaces after keyword + code_style_example.py:3:6: N802 function name 'PI_estimate' should be lowercase + code_style_example.py:7:6: N806 variable 'pi_Numbers' in function should be lowercase + code_style_example.py:7:17: E222 multiple spaces after operator + code_style_example.py:7:40: E251 unexpected spaces around keyword / parameter equals + code_style_example.py:7:42: E251 unexpected spaces around keyword / parameter equals + code_style_example.py:8:20: E201 whitespace after '[' + code_style_example.py:8:23: E202 whitespace before ']' + code_style_example.py:9:20: E201 whitespace after '[' + code_style_example.py:9:23: E202 whitespace before ']' + code_style_example.py:11:33: E202 whitespace before ')' + code_style_example.py:14:11: E272 multiple spaces before keyword + code_style_example.py:14:23: E231 missing whitespace after ',' + code_style_example.py:16:11: E225 missing whitespace around operator + code_style_example.py:18:67: E201 whitespace after '(' + code_style_example.py:18:69: E202 whitespace before ')' + +There are plenty of errors and warnings. We could fix these manually, but +instead let's use ``black`` to format the code. Black is an "uncompromising +Python code formatter" from Python Software Foundation and it automatically +modifies your code to match their recommended coding style. + +It should fix most of the errors automatically without changing the +functionality. + +After running ``black code_style_example.py`` the code looks like this: + +.. code-block:: python + + import numpy as np + + + def PI_estimate(n): + """This function calculates an estimate of pi with dart thrower algorithm.""" + + pi_Numbers = np.random.random(size=2 * n) + x = pi_Numbers[:n] + y = pi_Numbers[n:] + + return 4 * np.sum((x * x + y * y) < 1) / n + + + for number in range(1, 8): + n = 10**number + + print(f"Estimate for PI with {n:8d} dart throws: {PI_estimate( n )}") + +Much cleaner. If we want to check for variable naming syntax we can still run +``flake8 code_style_example.py``: + +.. code-block:: console + + $ flake8 code_style_example.py + code_style_example.py:4:6: N802 function name 'PI_estimate' should be lowercase + code_style_example.py:5:80: E501 line too long (81 > 79 characters) + code_style_example.py:7:6: N806 variable 'pi_Numbers' in function should be lowercase + code_style_example.py:17:67: E201 whitespace after '(' + code_style_example.py:17:69: E202 whitespace before ')' + +Fixing these problems we get the final piece of code: + +.. code-block:: python + + import numpy as np + + + def pi_estimate(n): + """ + This function calculates an estimate of pi with dart thrower algorithm. + """ + + pi_numbers = np.random.random(size=2 * n) + x = pi_numbers[:n] + y = pi_numbers[n:] + + return 4 * np.sum((x * x + y * y) < 1) / n + + + for number in range(1, 8): + n = 10**number + + print(f"Estimate for PI with {n:8d} dart throws: {pi_estimate(n)}") + +Comparing the fixed one to the original one the code is much more legible. + +.. admonition:: Problems with styles and writing your own kind of code + :class: dropdown + + There style black uses is + `a bit different to PEP 8 `__ + and one can definitely argue that it + `does not handle mathematical expressions in the optimal way `__. + + However, one can turn formatting off for math heavy sections with ``# fmt: on``- + and ``# fmt: off``-comments. Alternatively, you can use formatter such as + `yapf `__, which supports formatting based on + arithmetic precedence: + + .. code-block:: console + + $ yapf --style='{based_on_style: pep8, arithmetic_precedence_indication=true}' --diff code_style_example.py + --- code_style_example.py (original) + +++ code_style_example.py (reformatted) + @@ -10,7 +10,7 @@ + x = pi_numbers[:n] + y = pi_numbers[n:] + + - return 4 * np.sum((x * x + y * y) < 1) / n + + return 4 * np.sum((x*x + y*y) < 1) / n + + + for number in range(1, 8): + + From this diff we see that ``yapf`` would change the multiplications to + match the arithmetic precedence. + + All formatters allow for massive amounts of style changes and you can + configure them by creating a configuration file in your repository. + + If the formatter makes a change that you do not like you can usually + disable the change by changing the configuration of the formatter. + + +Exercise 2 +---------- + +.. challenge:: Using black to format code + + Format + :download:`this code <../resources/code/productivity/exercise2.py>` + with black: + + .. code-block:: python + + import numpy as np + import matplotlib.pyplot as plt + + def dice_toss(n,m): + + """Throw n dice m times and the total value together.""" + dice_rolls = np.random.randint(1,6,size=(m, n)) + + roll_averages = np.sum(dice_rolls,axis = -1) + + return roll_averages + fig,ax = plt.subplots( ) + + n = int( input('Number of dices to toss:\n')) + + bins = np.arange(1, 6 * n+1) + + m = 1000 + + ax.hist(dice_toss(n,m), bins = bins) + + ax.set_title(f'Histogram of {n} dice tosses') + + ax.set_xlabel('Total value' ) + + ax.set_ylabel('Number of instances') + + plt.show() + +.. solution:: + + Running ``black exercise2.py`` will produce + :download:`this piece of code <../resources/code/productivity/exercise2_solution.py>`. + + .. code-block:: python + + import numpy as np + import matplotlib.pyplot as plt + + + def dice_toss(n, m): + """Throw n dice m times and the total value together.""" + dice_rolls = np.random.randint(1, 6, size=(m, n)) + + roll_averages = np.sum(dice_rolls, axis=-1) + + return roll_averages + + + fig, ax = plt.subplots() + + n = int(input("Number of dices to toss:\n")) + + bins = np.arange(1, 6 * n + 1) + + m = 1000 + + ax.hist(dice_toss(n, m), bins=bins) + + ax.set_title(f"Histogram of {n} dice tosses") + + ax.set_xlabel("Total value") + + ax.set_ylabel("Number of instances") + + plt.show() + + +Integrating productivity tools with git +--------------------------------------- + +If you're using version control you can easily add tools such as +pylint, flake8, black and ruff as automatic using tools like +`pre-commit `__. + +Pre-commit is a tool that makes it easy to automatically run various +code checkers when you're doing a new commit to the repository. + +For more information see their website. + + +Other nice tools +---------------- + +- `isort `__ - Sorts import statements for you +- `jupyterlab_code_formatter `__ - Adds formatting functionality to jupyterlab. + +.. keypoints:: + + - Using linters and formatters can help you write cleaner code. + - You should adapt your own code and documentation style based + on standards that other people use. + - Using pre-commit with your git repository can make many of the + checks automatic. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/python.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/python.rst.txt new file mode 100644 index 00000000..b9f21315 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/python.rst.txt @@ -0,0 +1,186 @@ +Introduction to Python +====================== + +.. questions:: + + - What are the basic blocks of Python language? + - How are functions and classes defined in Python? + +.. objectives:: + + - Get a *very* short introduction to Python types and syntax + - Be able to follow the rest of the examples in the course, even if you don't understand everything perfectly. + + We expect everyone to be able to know the following basic material + to follow the course (though it is not *everything* you need to + know about Python). + +If you are not familiar with Python, here is a *very* short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise. + +.. seealso:: + + This page contains an overview of the basics of Python. You can + also refer to `This Python overview from a different lesson + `__ + which is slightly more engaging. + + + +Scalars +------- + +Scalar types, that is, single elements of various types: + +:: + + i = 42 # integer + i = 2**77 # Integers have arbitrary precision + g = 3.14 # floating point number + c = 2 - 3j # Complex number + b = True # boolean + s = "Hello!" # String (Unicode) + q = b'Hello' # bytes (8-bit values) + +Read more: :class:`int`, :class:`float`, :class:`complex`, +:class:`bool`, :class:`str`, :class:`bytes`. + + +Collections +----------- + +Collections are data structures capable of storing multiple values. + +:: + + l = [1, 2, 3] # list + l[1] # lists are indexed by int + l[1] = True # list elements can be any type + d = {"Janne": 123, "Richard": 456} # dictionary + d["Janne"] + s = set(("apple", "cherry", "banana", "apple")) # Set of unique values + s + +Read more: :class:`list`, :class:`tuple`, :class:`dict`, :class:`set`. + + +Control structures +------------------ + +Python has the usual control structures, that is conditional +statements and loops. For example, the :ref:`if` statement: + +:: + + x = 2 + if x == 3: + print('x is 3') + elif x == 2: + print('x is 2') + else: + print('x is something else') + +:ref:`While ` loops loop until some condition is met: + +:: + + x = 0 + while x < 42: + print('x is ', x) + x += 0.2 + +:ref:`For ` loops loop over some collection of values: + +:: + + xs = [1, 2, 3, 4] + for x in xs: + print(x) + + +Often you want to loop over a sequence of integers, in that case the +:class:`range` function is useful: + +:: + + for x in range(9): + print(x) + +Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the :func:`enumerate` +function: + +:: + + xs = [1, 'hello', 'world'] + for ii, x in enumerate(xs): + print(ii, x) + + +Functions and classes +--------------------- + +Python functions are defined by the :ref:`def` keyword. They take a +number of arguments, and return a number of return values. + +:: + + def hello(name): + """Say hello to the person given by the argument""" + print('Hello', name) + return 'Hello ' + name + + hello("Anne") + +Classes are defined by the :ref:`class` keyword: + +:: + + class Hello: + def __init__(self, name): + self._name = name + def say(self): + print('Hello', self._name) + + h = Hello("Richard") + h.say() + + +Python type system +------------------ + +Python is strongly and dynamically typed. + +Strong here means, roughly, that it's not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior). + +:: + + x = 42 + type(x) + x + "hello" + +Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type: + +:: + + x = 42 + x = "hello" + + +*Jargon*: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation. + + +??? (lesson here) + + + +.. keypoints:: + + - Python offers a nice set of basic types as many other programming languages + - Python is strongly typed and dynamically typed diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/quick-reference.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/quick-reference.rst.txt new file mode 100644 index 00000000..6d3141e5 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/quick-reference.rst.txt @@ -0,0 +1,26 @@ +Quick reference +=============== + +* `Pandas cheatsheet + `__ (pandas.pydata.org) + +* `Pandas cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy cheatsheet + `__ + (via `Datacamp + `__) + +* `JupyterLab cheatsheet + `__ + +* `Matplotlib cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy, Pandas, Matplotlib, Scikit-learn all together + `__ diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/scipy.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/scipy.rst.txt new file mode 100644 index 00000000..0d921a43 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/scipy.rst.txt @@ -0,0 +1,183 @@ +SciPy +===== + +.. questions:: + + - When you need more advanced mathematical functions, where do you + look? + +.. objectives:: + + - Understand that SciPy exists and what kinds of things it has. + - Understand the importance of using external libraries and how to + use them. + - Understand the purpose of wrapping existing C/Fortran code. + - Non-objective: know details of everything (or anything) in SciPy. + +.. seealso:: + + * Main article: `SciPy documentation `__ + + + +SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms. + + + +What's in SciPy? +---------------- + +Briefly, it contains functionality for + +- Special functions (Bessel, Gamma, etc.) +- Numerical integration +- Optimization +- Interpolation +- Fast Fourier Transform (FFT) +- Signal processing +- Linear algebra (more complete than in NumPy) +- Sparse matrices +- Statistics +- More I/O routine, e.g. Matrix Market format for sparse matrices, + MATLAB files (.mat), etc. + +Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages. + +Most functions are documented ridiculously well from a scientific +standpoint: you aren't just using some unknown function, but have a +full scientific description and citation to the method and +implementation. + + + +Exercises: use SciPy +-------------------- + +These exercises do not exist because *you* might need *these* +functions someday. They are because *you* will need to *read +documentation and understand documentation of an an external library* +eventually. + +1: Numerical integration +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Define a function of one variable and using + `scipy.integrate.quad `__ + calculate the integral of your function in the + interval ``[0.0, 4.0]``. Then vary the interval and also modify the function and check + whether scipy can integrate it. + + +.. solution:: + + .. code-block:: python + + from scipy import integrate + + def myfunction(x): + # you need to define result + return result + + integral = integrate.quad(myfunction, 0.0, 4.0) + print(integral) + + `quad + `__ + uses the Fortran library QUADPACK, which one can assume is pretty + good. You can also see a whole lot of scientific information about + the function on the docs page - including the scientific names of + the methods used. + + + +2: Sparse matrices +~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Use the SciPy sparse matrix functionality to create a random sparse + matrix with a probability of non-zero elements of 0.05 and size 10000 + x 10000. The use the SciPy sparse linear algebra support to calculate + the matrix-vector product of the sparse matrix you just created and a + random vector. Use the %timeit macro to measure how long it + takes. Does the optional ``format`` argument when you create the + sparse matrix make a difference? + + Then, compare to how long it takes if you'd instead first convert the + sparse matrix to a normal NumPy dense array, and use the NumPy ``dot`` + method to calculate the matrix-vector product. + + Can you figure out a quick rule of thumb when it's worth using a + sparse matrix representation vs. a dense representation? + +.. solution:: + + The basic code to do the test is: + + .. code-block:: + + import numpy + import scipy.sparse + + vector = numpy.random.random(10000) + matrix = scipy.sparse.rand(10000, 10000, density=.05, format='csc') + + # We time this line + matrix.dot(vector) + + From the top of the `spare matrix module documentation + `__, we can + see there are a variety of different available sparse matrix types: + ``bsr``, ``coo``, ``csr``, ``csc``, etc. These each represent a + different way of storing the matrices. + + It seems that ``csr`` and ``csc`` are fairly fast. ``lil`` and + ``dok`` are slow but it says that these are good for creating + matrices with random insertions. + + For example, ``csr`` takes 7ms, ``lil`` 42ms, ``dok`` 1600ms, and + converting to a non-sparse array ``matrix.toarray()`` and + multiplying takes 64ms on one particular computer. + + This code allows us to time the performance at different + densities. It seems that with the ``csr`` format, sparse is better + below densities of around .4 to .5: + + ..code-block:: + + for density in [.01, .05, .1, .2, .3, .4, .5]: + matrix = scipy.sparse.rand(10000, 10000, density=density, format='csr') + time_sparse = timeit.timeit('matrix.dot(vector)', number=10, globals=globals()) + matrix2 = matrix.toarray() + time_full = timeit.timeit('matrix2.dot(vector)', number=10, globals=globals()) + print(f"{density} {time_sparse:.3f} {time_full:.3f}") + + + +See also +-------- + +* `SciPy general introduction `__ +* `SciPy documentation + `__ + + + +.. keypoints:: + + - When you need advance math or scientific functions, let's just + admit it: you do a web search first. + - But when you see something in SciPy come up, you know your + solutions are in good hands. diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/scripts.rst.txt b/branch/rkdarst--dependengi-exercise-time/_sources/scripts.rst.txt new file mode 100644 index 00000000..ca04ecd4 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/scripts.rst.txt @@ -0,0 +1,329 @@ +.. _scripts: + +Scripts +======= + +.. questions:: + + - Why are command line programs useful, compared to Jupyter + notebooks and similar? + - How to create a Python script? + - How to generalize a Python script? + +.. objectives:: + + - Learn how to streamline your Python notebooks by creating repeatable Python scripts + - Learn how to import other Python files + - Learn to parse command line arguments in Python + +Why scripts? +------------- + +So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work. + +But after several weeks of hard work with Python, you may end up: + +- either with 10 different notebooks (so that you can run them concurrently) +- or with a very long notebook which is becoming hardly readable! + +Let's imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks? + +In this episode, we will learn how to automate your work using Python scripts so that + +* you do not need to manually configure your notebooks to be able to run with different parameters +* can easily run you work via other tools, such as on computing clusters. + + +From Jupyter notebooks to Python scripts +----------------------------------------- + +Save as Python script +--------------------- + +Jupyter notebooks can be parameterized for instance using `papermill `_. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See `CodeRefinery's lesson on Modular code development `__. + +Within JupyterLab, you can export any Jupyter notebook to a Python script: + +.. figure:: https://jupyterlab.readthedocs.io/en/stable/_images/exporting-menu.png + + Select File (top menu bar) → Export Notebook as → **Export notebook to Executable Script**. + + +.. highlight:: console + +Actually, you could also export your notebook in many other formats. +Check the `JupyterLab documentation `_ for more information. +If you are working by the command line (File → New → Terminal), you can also convert files in the terminal by running:: + + $ jupyter nbconvert --to script your_notebook_name.ipynb + + +Exercises 1 +----------- + +.. challenge:: Scripts-1 + + .. highlight:: console + + + 1. Download the :download:`weather_observations.ipynb <../resources/code/scripts/weather_observations.ipynb>` and the weather_data file and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from `rp5.kz `_ and was slightly adjusted for this lecture. + + **Hint:** Copy the URL above (right-click) and in JupyterLab, use + File → Open from URL → Paste the URL. It will both download it to + the directory JupyterLab is in and open it for you. + + 2. Open a terminal in Jupyter: File → New Launcher, then click + "Terminal" there. (if you do it this way, it will be in the right + directory. File → New → Terminal might not be.) + + 3. Convert the Jupyter script to a Python script by calling:: + + $ jupyter nbconvert --to script weather_observations.ipynb + + 4. Run the script (note: you may have ``python3`` rather than ``python``):: + + $ python weather_observations.py + + + +Command line arguments with :data:`sys.argv` +-------------------------------------------- + +We now have a Python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +**What we need is to allow the code to do something different based on something outside the code itself**: in this case, to +plot information for different time ranges. This can be achieved by +using Pythons :py:mod:`sys` package, which provides access to arguments given to the Python interpreter at +startup in the :py:data:`sys.argv` list. The first (i.e. ``sys.argv[0]`` entry of this array is the script that is running, +and any further argument (separated by space) is appended to this list, like such: + +.. code-block:: console + + $ python my_script.py A B + $ # sys.argv[1] is 'A' + $ # sys.argv[2] is 'B' + +Lets see how it works: We modify the **weather_observations.py** script such that we allow start +and end times as well as the output file to be passed in as arguments +to the function. Open it (find the ``.py`` file from the JupyterLab +file browser) and make these edits: + +.. code-block:: python + :emphasize-lines: 1,5-6,8,14-15 + + import sys + import pandas as pd + + # define the start and end time for the plot + start_date = pd.to_datetime(sys.argv[1], dayfirst=True) + end_date = pd.to_datetime(sys.argv[2], dayfirst=True) + ... + + # select the data + weather = weather[weather['Local time'].between(start_date,end_date)] + ... + + # save the figure + output_file_name = sys.argv[3] + fig.savefig(output_file_name) + +We can try it out (see the file ``spring_in_tapiola.png`` made in the +file browser): + +.. code-block:: console + + $ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png + + +.. discussion:: + + - Does it work? + + - Why is this better than modifying the script every time I want it to + plot data for a different period? + + - What problems do you expect when using this approach (using :data:`sys.argv`)? + +This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time: + +- `argparse `__: + built-in to Python, this is the one that we will show below. +- `doctopt `__: you write the help text and this generates a parser for you. +- `click `__: another nice + library for command line interfaces - very easy to use. + + +Parsing command line arguments with :mod:`argparse` +--------------------------------------------------- + +:py:mod:`Argparse ` not only gives you descriptive command line arguments, it also automatically +generates a ``--help`` option for you. To use ``argparse`` you first set up a parser +by calling :class:`parser = argparse.ArgumentParser() ` and then you add arguments using +:py:meth:`parser.add_argument(args) `. There are two different types of arguments: + +- Positional arguments +- Optional arguments + +**Positional arguments** are detected by their order, while **optional arguments** need to be +given with their respective flags ( like ``--name`` or ``-n``). +The following example would parse a positional argument ``Name`` of type ``string`` +and an optional argument ``date`` of type ``string`` which defaults to ``01/01/2000``. + +.. code-block:: python + :emphasize-lines: 3, 5-8, 10 + + import argparse + + parser = argparse.ArgumentParser() + # One positional and one optional argument + parser.add_argument('name', type=str, metavar="N", + help="The name of the subject") + parser.add_argument('-d', '--date', type=string, default="01/01/2000", + help="Birth date of the subject") + + args = parser.parse_args() + + print(args.name + " was born on " + args.date) + +If this code was in ``birthday.py`` and we would call ``python birthday.py --help`` it +would show the following message: + +.. code-block:: console + + $ python birthday.py --help + usage: birthday.py [-h] [-d DATE] N + + positional arguments: + N The name of the subject + + optional arguments: + -h, --help show this help message and exit + -d DATE, --date DATE Birth date of the subject + + +Exercises 2 +----------- + +.. challenge:: Scripts-2 + + 1. Take the Python script (``weather_observations.py``) we have written in the preceding exercise and use + :py:mod:`argparse` to specify the input (URL) and output files and allow the start and end dates to be set. + + * Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on. + * Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output. + * Hint: The start and end dates should be optional parameters with the defaults as they are in the current script. + + 2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). + Also try using this data for Cairo: ``https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv`` + + +.. solution:: + + .. literalinclude:: ../resources/code/scripts/weather_observations_argparse.py + :language: python + :emphasize-lines: 2,4-8,10,13,16-17,37 + + + + +.. discussion:: + + **What was the point of doing this?** + + Now you can do this: + + .. code-block:: console + + $ python weather_observations.py --help + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png + $ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png + $ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output temperature_cairo.png + + - We can now process different input files without changing the script. + - We can select multiple time ranges without modifying the script. + - We can easily save these commands to know what we did. + - This way we can also loop over file patterns (using shell loops or similar) or use + the script in a workflow management system and process many files in parallel. + - By changing from :data:`sys.argv` to :mod:`argparse` we made the script more robust against + user input errors and also got a help text (accessible via ``--help``). + + +Load larger option lists using config files +------------------------------------------- + +In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line: + +.. code-block:: console + + + $ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021 + + +This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple ``Parameter = Value`` +format, and parse it yourself, or you can use e.g. the ``JSON`` or ``YAML`` formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won't go into the details of the formats, and will only give +a short example using YAML here. + +The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (`yaml `__) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the :mod:`json` package). + +The Python module :download:`optionsparser.py <../resources/code/scripts/optionsparser.py>` provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values. + +In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation ...), set the labels and titles explicitly etc. + +In the YAML format, names and values are separated by ``:``. Our above example would therefore translate to the following YAML file: + +.. literalinclude:: ../resources/code/scripts/weather_options.yml + :language: yaml + +Exercises 3 (optional) +---------------------- + +.. challenge:: Scripts-3 + + 1. Download the :download:`optionsparser.py ` + function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). + Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line + (using e.g. :mod:`argparse` or :data:`sys.argv`) still needs to be read from the command line. + + + 2. Run your script with different config files. + + +.. solution:: + + The modified **weather_observations.py** script: + + .. literalinclude:: ../resources/code/scripts/weather_observations_config.py + :language: python + :emphasize-lines: 5,9-12,15-27,30,33,36-37,58 + +What did this config file parser get us? Now, we have separated the +code from the configuration. We could save all the configuration in +version control - separately and have one script that runs them. If +done right, our work could be much more reproducible and +understandable. + + +.. admonition:: Further reading + + - Linking Jupyterlab notebooks to python scripts (making linking ``.py``- and ``.ipynb``-files easier) using `jupytext `_ + - The `wikipedia page about YAML `_ contains a lot of additional information on the YAML syntax. + - `The Coderefinery Lesson about reproducible research `_ can give additional information about good coding practices and workflow automation. + + - `CodeRefinery's lesson on Modular code development `__ diff --git a/branch/rkdarst--dependengi-exercise-time/_sources/web-apis.ipynb.txt b/branch/rkdarst--dependengi-exercise-time/_sources/web-apis.ipynb.txt new file mode 100644 index 00000000..f1d35371 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_sources/web-apis.ipynb.txt @@ -0,0 +1,678 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c87bb04a-3f53-45ac-bbc9-fe182c844219", + "metadata": { + "tags": [] + }, + "source": [ + "# Web APIs with Python\n", + "\n", + ":::{questions}\n", + "- Have you ever needed to get some data from somewhere else on the web?\n", + ":::\n", + "\n", + ":::{objectives}\n", + "- Understand a web server and API and why might you need to talk to one.\n", + "- Basics of the [requests](https://requests.readthedocs.io/en/latest/) Python library\n", + "- Some lightweight recommendations on saving data when you get to more serious data download.\n", + ":::\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "2398bb45-e061-4e7a-8931-82906a3892ff", + "metadata": { + "tags": [] + }, + "source": [ + "## Requests\n", + "\n", + "Requests is a Python library that makes **requests** to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.\n", + "\n", + "First, let's take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c69a16ac-a5b3-4ff0-a949-720b5bbd37cd", + "metadata": {}, + "outputs": [], + "source": [ + "# Embed the requests homepage\n", + "from IPython.display import IFrame\n", + "requests_documentation_url = \"https://requests.readthedocs.io/en/latest/\"\n", + "IFrame(requests_documentation_url, '100%', '30%')" + ] + }, + { + "cell_type": "markdown", + "id": "6d6b334b-309e-429b-aad5-0ab76f071c15", + "metadata": {}, + "source": [ + "## Retrieve data from API\n", + "\n", + "An **API (Application Programming Interface)** is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the **request-response** cycle.\n", + "\n", + "We can find a list of some free APIs (available without authentication) at . These APIs can be used for developing and testing our code." + ] + }, + { + "cell_type": "markdown", + "id": "0a21faac-a7d8-448d-a8db-6fb23b9bd64c", + "metadata": { + "tags": [] + }, + "source": [ + "Let's make a request to the Cat Fact API. If we go to , it gives us the definitions:\n", + "* GET `/fact` is the **API endpoint**.\n", + "* **GET** is the type of request we make and\n", + "* `/fact` is the **path**.\n", + "\n", + "You can even test this in your web browser: \n", + "\n", + "Using the Requests library, we do this with {func}`~requests.get`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fa134bb7-1250-46bd-bd80-e3e0d0820523", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "64a7f3be-420b-4e1c-a76d-67d9e6b29f4f", + "metadata": { + "tags": [] + }, + "source": [ + "The {class}`requests.Response` object tells us what the server said. We can access the response content using {attr}`~requests.Response.content`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b3e1ddb3-76a1-4e53-a32b-4005d92626c6", + "metadata": {}, + "outputs": [], + "source": [ + "response_content = response.content\n", + "\n", + "# Display\n", + "display(response_content)" + ] + }, + { + "cell_type": "markdown", + "id": "3886ff1c-0619-4fc5-828a-269257db6e63", + "metadata": { + "tags": [] + }, + "source": [ + "The response content is in the [JSON format](https://en.wikipedia.org/wiki/JSON) and Requests gives us the {meth}`~requests.Response.json` method that decodes it and returns the corresponding data as Python objects. This is equivalent to {func}`json.load`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7651cd8c-9581-4d04-b3bf-c57997a5684a", + "metadata": {}, + "outputs": [], + "source": [ + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json)" + ] + }, + { + "cell_type": "markdown", + "id": "10ca2577-94a4-4689-a01a-2681fe4c5d20", + "metadata": { + "tags": [] + }, + "source": [ + "(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)" + ] + }, + { + "cell_type": "markdown", + "id": "80e02c0b-9b59-44ea-ab26-092b6cdb510b", + "metadata": { + "tags": [] + }, + "source": [ + "## API which requires parameters\n", + "\n", + "Let's then examine another API which accepts [parameters](https://requests.readthedocs.io/en/latest/user/quickstart/#passing-parameters-in-urls) to specify the information request. In particular, we will request a list of Finnish universities from using the `/search` end point and a parameter _country_ with value _Finland_, like this:\n", + "`http://universities.hipolabs.com/search?country=Finland` ." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b98cba34-0f3a-43fb-befe-0e1c48fdb1c3", + "metadata": {}, + "outputs": [], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search?country=Finland'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])" + ] + }, + { + "cell_type": "markdown", + "id": "18ee30d2-e072-41b2-b4d4-8203cb5e86ce", + "metadata": { + "tags": [] + }, + "source": [ + "URLs containing parameters can always be constructed manually using the _&_ character and then listing the parameter (_key_, _value_) pairs as above.\n", + "\n", + "However, _Requests_ allows us to provide the parameters as a dictionary of strings, using the _params_ keyword argument to {func}`~requests.get`. This is easier to read and less error-prone." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1c1ddced-d423-42cd-89ac-3a0c6d751d9d", + "metadata": {}, + "outputs": [], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search'\n", + "\n", + "# Make the parameter dictionary\n", + "parameters = {'country' : 'Finland'}\n", + "\n", + "# Get response\n", + "response = requests.get(url, params=parameters)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])\n" + ] + }, + { + "cell_type": "markdown", + "id": "35c751c9-009c-46f7-af8a-40c4132dcfbd", + "metadata": {}, + "source": [ + "## Exercises 1" + ] + }, + { + "cell_type": "markdown", + "id": "033d8d63-43db-4a3e-a9cd-e142134a0b9b", + "metadata": {}, + "source": [ + "::::{exercise} Exercise WebAPIs-1: Request different activity suggestions from the Bored API\n", + "\n", + "Go to the [documentation page of the Bored API](https://www.boredapi.com/documentation). The Bored API is an open API which can be used to randomly generate activity suggestions.\n", + "\n", + "Let's examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response\n", + "\n", + "```json\n", + "{\n", + " \"activity\": \"Learn Express.js\",\n", + " \"accessibility\": 0.25,\n", + " \"type\": \"education\",\n", + " \"participants\": 1,\n", + " \"price\": 0.1,\n", + " \"link\": \"https://expressjs.com/\",\n", + " \"key\": \"3943506\"\n", + "} \n", + "```\n", + "\n", + "Let's replicate the query and see if we can get another random suggestion.\n", + "::::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1744a2a7-5c9a-48d4-96b4-9d523b2e43bc", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Send the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "77fdd8cd-2c85-474e-bceb-2a737c92521b", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "69ae7da6-6c9c-4f2a-94ea-fc75f437eb80", + "metadata": {}, + "source": [ + "Next, let's try to narrow down the suggestions by adding some parameters\n", + "- type\n", + "- participants\n", + "\n", + "All possible parameter values are presented at the bottom of the bored documentation page. [Relevant parts in the _Requests_ documentation](https://requests.readthedocs.io/en/latest/user/quickstart/#parameters)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "933feded-0d73-4038-b909-6f713cb3782a", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'education',\n", + " 'participants' : 1,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f9dbeea0-31d3-43b0-8d18-94b608e82a77", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(\"Response\")\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "301eb0af-2db2-474b-87e4-8d8815a3a04b", + "metadata": {}, + "source": [ + "Let's narrow the request further with more parameters\n", + "- price range\n", + "- accessibility range\n", + "\n", + "(All possible parameter values are again presented at the bottom of the document page.)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d04823d4-154e-48ec-9576-f537bd20c271", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'social',\n", + " 'participants' : 2,\n", + " 'minprice' : 0,\n", + " 'maxprice' : 1000,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "87978afc-6d0d-46c0-ad0f-e5b851d302e1", + "metadata": {}, + "outputs": [], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())\n", + "display(\"\")" + ] + }, + { + "cell_type": "markdown", + "id": "0a019d02-cd86-4fdc-874e-b99557955cd1", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "\n", + ":::{exercise} Exercise WebAPIs-2: Examine request and response headers\n", + "\n", + "Request [headers](https://requests.readthedocs.io/en/latest/user/quickstart/#response-headers) are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).\n", + "\n", + "Let's first make a request.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eb583c27-2ce3-420e-a116-b717f8fa0e3e", + "metadata": {}, + "outputs": [], + "source": [ + "# Import modules\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Make the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "271d5abd-6648-4976-899e-25e93d5d8f73", + "metadata": {}, + "source": [ + "We can access the headers of the original request" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "91f78d05-60e7-48ad-8f13-bc4d445e75bc", + "metadata": {}, + "outputs": [], + "source": [ + "display(\"Request headers\")\n", + "display(dict(response.request.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "d6149ec8-c57f-4fab-aaa5-6a61fc7d0291", + "metadata": {}, + "source": [ + "We can also access the headers of the response " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d4ff753a-d3dd-41c9-b533-386d0b30d4c3", + "metadata": {}, + "outputs": [], + "source": [ + "display(\"Response headers\")\n", + "display(dict(response.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "7132bc48-90a0-49ea-a215-a87006aecf1d", + "metadata": {}, + "source": [ + "In many cases, the default headers\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive'}\n", + "```\n", + "\n", + "added automatically by _Requests_ are sufficient. However, similarly to parameters, we can pass [custom headers](https://requests.readthedocs.io/en/latest/user/quickstart/#custom-headers) to the _get_ function as an argument. \n", + "\n", + "This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive',\n", + " 'example-user-id' : 'example-password'}\n", + "```\n", + "\n", + "For examples of APIs using this type of authentication, see\n", + "\n", + "- [Imgur API](https://api.imgur.com/oauth2)\n", + "\n", + "For more on authentication, see also [_Requests_ documentation](https://requests.readthedocs.io/en/latest/user/authentication/). \n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "3d50de82-4f2c-4bc4-8f23-3cb4bdb62127", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "\n", + ":::{exercise} Exercise WebAPIs-3: Scrape links from a webpage (Advanced)\n", + "\n", + "Let's use _Requests_ to get the HTML source code of www.example.com, examine it, and use the [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) library to extract links from it. **Note:** This requires the extra `bs4` Python package to be installed, which was not in our initial requirements. Consider this a demo.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cc3373a9-e54f-4049-b715-481ec9893189", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# Define webpage to scrape\n", + "url = \"http://www.example.com/\"\n", + "\n", + "# Make a request for the URL\n", + "response = requests.get(url)\n", + "\n", + "# Examine the response\n", + "display(response.content)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d59e52c4-95cf-427d-b3d4-8d0a6dc02aa5", + "metadata": {}, + "outputs": [], + "source": [ + "# Looks like HTML :) Let's access it using the text attribute\n", + "html = response.text\n", + "\n", + "print(html)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "327695ae-b376-4d5b-9293-6e89ff272790", + "metadata": {}, + "outputs": [], + "source": [ + "# Import beautiful soup module\n", + "from bs4 import BeautifulSoup\n", + "\n", + "# Create soup\n", + "soup = BeautifulSoup(html, 'html.parser')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0e21c6de-a845-4823-b777-bf2cd44fbfd2", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract page title from the HTML\n", + "print(f\"Found title: {soup.title.text}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a7fa0e7b-b171-4e65-b987-84a101da58df", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract links (hrefs) from the HTML\n", + "for link in soup.find_all('a'):\n", + " print(f\"Found link: {link.get('href')}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6581edcb-c170-4cc7-a442-d8d8c724ca50", + "metadata": {}, + "outputs": [], + "source": [ + "# Extract all text from the HTML\n", + "print(f\"Found text: {soup.get_text()}\") " + ] + }, + { + "cell_type": "markdown", + "id": "7cdff2d8-0c98-45b3-a825-ed1492d10302", + "metadata": {}, + "source": [ + "## After exercises: Saving retrieved data to disk\n", + "\n", + "Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudal study.\n", + "\n", + "To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don't, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).\n", + "\n", + "For example, let's retrieve three cat facts and save them to a JSONLINES file using the [jsonlines library](https://jsonlines.readthedocs.io/en/latest/)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "80a8dcd1-ba04-45de-840e-aa014c19a75c", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "import jsonlines\n", + "import time\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make three requests in loop and make a list of response JSON objects\n", + "for i in range(3):\n", + "\n", + " # Logging\n", + " print(f\"Make request {i}\")\n", + "\n", + " # Make a request\n", + " response = requests.get(url)\n", + " \n", + " # Decode to JSON\n", + " response_json = response.json()\n", + " \n", + " # Open a jsonlines writer in 'append' mode \n", + " with jsonlines.open('catfacts.jsonl', mode='a') as writer:\n", + "\n", + " # Write\n", + " writer.write(response_json)\n", + " \n", + " # Sleep for one second between requests\n", + " time.sleep(1)\n" + ] + }, + { + "cell_type": "markdown", + "id": "efb4a0ff-6a70-471a-af61-39c0350d4166", + "metadata": {}, + "source": [ + "We can then read the objects from the disk using the same library." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2d424c23-bdf3-47f7-a643-4312a07c955a", + "metadata": {}, + "outputs": [], + "source": [ + "# Open a jsonlines reader\n", + "with jsonlines.open('catfacts.jsonl', mode='r') as reader:\n", + " \n", + " # Read and display\n", + " for obj in reader:\n", + " display(obj)" + ] + }, + { + "cell_type": "markdown", + "id": "2f6b8117-b1ef-43cb-9458-0fe4ac49b67a", + "metadata": {}, + "source": [ + "## Wrap-up\n", + "\n", + "\n", + ":::{keypoints}\n", + "- Requests is a common tool\n", + "- Web APIs may often require some trial and error, but actually getting data is usually not that difficult\n", + "- Storing all the data and processing it well can be a much larger issue.\n", + ":::\n", + "\n" + ] + } + ], + "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.8.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/branch/rkdarst--dependengi-exercise-time/_static/_sphinx_javascript_frameworks_compat.js b/branch/rkdarst--dependengi-exercise-time/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..8549469d --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,134 @@ +/* + * _sphinx_javascript_frameworks_compat.js + * ~~~~~~~~~~ + * + * Compatability shim for jQuery and underscores.js. + * + * WILL BE REMOVED IN Sphinx 6.0 + * xref RemovedInSphinx60Warning + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/branch/rkdarst--dependengi-exercise-time/_static/basic.css b/branch/rkdarst--dependengi-exercise-time/_static/basic.css new file mode 100644 index 00000000..4e9a9f1f --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/basic.css @@ -0,0 +1,900 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/_static/check-solid.svg b/branch/rkdarst--dependengi-exercise-time/_static/check-solid.svg new file mode 100644 index 00000000..92fad4b5 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/branch/rkdarst--dependengi-exercise-time/_static/clipboard.min.js b/branch/rkdarst--dependengi-exercise-time/_static/clipboard.min.js new file mode 100644 index 00000000..54b3c463 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/branch/rkdarst--dependengi-exercise-time/_static/copybutton.css b/branch/rkdarst--dependengi-exercise-time/_static/copybutton.css new file mode 100644 index 00000000..f1916ec7 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/branch/rkdarst--dependengi-exercise-time/_static/copybutton.js b/branch/rkdarst--dependengi-exercise-time/_static/copybutton.js new file mode 100644 index 00000000..b3987037 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/copybutton.js @@ -0,0 +1,248 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copier dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = ``; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = 'div.highlight pre'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} + + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '.linenos, .gp'; + + let text = filterText(target, exclude); + return formatCopyText(text, '', false, true, true, true, '', '') +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/_static/copybutton_funcs.js b/branch/rkdarst--dependengi-exercise-time/_static/copybutton_funcs.js new file mode 100644 index 00000000..dbe1aaad --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/badge_only.css b/branch/rkdarst--dependengi-exercise-time/_static/css/badge_only.css new file mode 100644 index 00000000..c718cee4 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}} \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Bold.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Bold.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Regular.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Regular.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.eot b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.svg b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.ttf b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold-italic.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold-italic.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold-italic.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-bold.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal-italic.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal-italic.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal-italic.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal.woff b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal.woff differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal.woff2 b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/css/fonts/lato-normal.woff2 differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/css/theme.css b/branch/rkdarst--dependengi-exercise-time/_static/css/theme.css new file mode 100644 index 00000000..19a446a0 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search>a:hover{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.version{margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel,.rst-content .menuselection{font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .guilabel,.rst-content .menuselection{border:1px solid #7fbbe3;background:#e7f2fa}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/_static/doctools.js b/branch/rkdarst--dependengi-exercise-time/_static/doctools.js new file mode 100644 index 00000000..527b876c --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/branch/rkdarst--dependengi-exercise-time/_static/documentation_options.js b/branch/rkdarst--dependengi-exercise-time/_static/documentation_options.js new file mode 100644 index 00000000..c066c69a --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/documentation_options.js @@ -0,0 +1,14 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'dirhtml', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/_static/file.png b/branch/rkdarst--dependengi-exercise-time/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/_static/file.png differ diff --git a/branch/rkdarst--dependengi-exercise-time/_static/jquery-3.6.0.js b/branch/rkdarst--dependengi-exercise-time/_static/jquery-3.6.0.js new file mode 100644 index 00000000..fc6c299b --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/_static/jquery-3.6.0.js @@ -0,0 +1,10881 @@ +/*! + * jQuery JavaScript Library v3.6.0 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright OpenJS Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + * + * Date: 2021-03-02T17:08Z + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var flat = arr.flat ? function( array ) { + return arr.flat.call( array ); +} : function( array ) { + return arr.concat.apply( [], array ); +}; + + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + +var isFunction = function isFunction( obj ) { + + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML elements + // (i.e., `typeof document.createElement( "object" ) === "function"`). + // We don't want to classify *any* DOM node as a function. + // Support: QtWeb <=3.8.5, WebKit <=534.34, wkhtmltopdf tool <=0.12.5 + // Plus for old WebKit, typeof returns "function" for HTML collections + // (e.g., `typeof document.getElementsByTagName("div") === "function"`). (gh-4756) + return typeof obj === "function" && typeof obj.nodeType !== "number" && + typeof obj.item !== "function"; + }; + + +var isWindow = function isWindow( obj ) { + return obj != null && obj === obj.window; + }; + + +var document = window.document; + + + + var preservedScriptAttributes = { + type: true, + src: true, + nonce: true, + noModule: true + }; + + function DOMEval( code, node, doc ) { + doc = doc || document; + + var i, val, + script = doc.createElement( "script" ); + + script.text = code; + if ( node ) { + for ( i in preservedScriptAttributes ) { + + // Support: Firefox 64+, Edge 18+ + // Some browsers don't support the "nonce" property on scripts. + // On the other hand, just using `getAttribute` is not enough as + // the `nonce` attribute is reset to an empty string whenever it + // becomes browsing-context connected. + // See https://github.com/whatwg/html/issues/2369 + // See https://html.spec.whatwg.org/#nonce-attributes + // The `node.getAttribute` check was added for the sake of + // `jQuery.globalEval` so that it can fake a nonce-containing node + // via an object. + val = node[ i ] || node.getAttribute && node.getAttribute( i ); + if ( val ) { + script.setAttribute( i, val ); + } + } + } + doc.head.appendChild( script ).parentNode.removeChild( script ); + } + + +function toType( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; +} +/* global Symbol */ +// Defining this global in .eslintrc.json would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.6.0", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + + // Return all the elements in a clean array + if ( num == null ) { + return slice.call( this ); + } + + // Return just the one element from the set + return num < 0 ? this[ num + this.length ] : this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + even: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return ( i + 1 ) % 2; + } ) ); + }, + + odd: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return i % 2; + } ) ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + copy = options[ name ]; + + // Prevent Object.prototype pollution + // Prevent never-ending loop + if ( name === "__proto__" || target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = Array.isArray( copy ) ) ) ) { + src = target[ name ]; + + // Ensure proper type for the source value + if ( copyIsArray && !Array.isArray( src ) ) { + clone = []; + } else if ( !copyIsArray && !jQuery.isPlainObject( src ) ) { + clone = {}; + } else { + clone = src; + } + copyIsArray = false; + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + // Evaluates a script in a provided context; falls back to the global one + // if not specified. + globalEval: function( code, options, doc ) { + DOMEval( code, { nonce: options && options.nonce }, doc ); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return flat( ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), + function( _i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); + } ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = toType( obj ); + + if ( isFunction( obj ) || isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.6 + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://js.foundation/ + * + * Date: 2021-02-16 + */ +( function( window ) { +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + nonnativeSelectorCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ( {} ).hasOwnProperty, + arr = [], + pop = arr.pop, + pushNative = arr.push, + push = arr.push, + slice = arr.slice, + + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[ i ] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|" + + "ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // https://www.w3.org/TR/css-syntax-3/#ident-token-diagram + identifier = "(?:\\\\[\\da-fA-F]{1,6}" + whitespace + + "?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + + // "Attribute values must be CSS identifiers [capture 5] + // or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + + whitespace + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + + "*" ), + rdescend = new RegExp( whitespace + "|>" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + + whitespace + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + + whitespace + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + whitespace + + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rhtml = /HTML$/i, + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\[\\da-fA-F]{1,6}" + whitespace + "?|\\\\([^\\r\\n\\f])", "g" ), + funescape = function( escape, nonHex ) { + var high = "0x" + escape.slice( 1 ) - 0x10000; + + return nonHex ? + + // Strip the backslash prefix from a non-hex escape sequence + nonHex : + + // Replace a hexadecimal escape sequence with the encoded Unicode code point + // Support: IE <=11+ + // For values outside the Basic Multilingual Plane (BMP), manually construct a + // surrogate pair + high < 0 ? + String.fromCharCode( high + 0x10000 ) : + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + inDisabledFieldset = addCombinator( + function( elem ) { + return elem.disabled === true && elem.nodeName.toLowerCase() === "fieldset"; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + ( arr = slice.call( preferredDoc.childNodes ) ), + preferredDoc.childNodes + ); + + // Support: Android<4.0 + // Detect silently failing push.apply + // eslint-disable-next-line no-unused-expressions + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + pushNative.apply( target, slice.call( els ) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + + // Can't trust NodeList.length + while ( ( target[ j++ ] = els[ i++ ] ) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + setDocument( context ); + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && ( match = rquickExpr.exec( selector ) ) ) { + + // ID selector + if ( ( m = match[ 1 ] ) ) { + + // Document context + if ( nodeType === 9 ) { + if ( ( elem = context.getElementById( m ) ) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && ( elem = newContext.getElementById( m ) ) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[ 2 ] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( ( m = match[ 3 ] ) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !nonnativeSelectorCache[ selector + " " ] && + ( !rbuggyQSA || !rbuggyQSA.test( selector ) ) && + + // Support: IE 8 only + // Exclude object elements + ( nodeType !== 1 || context.nodeName.toLowerCase() !== "object" ) ) { + + newSelector = selector; + newContext = context; + + // qSA considers elements outside a scoping root when evaluating child or + // descendant combinators, which is not what we want. + // In such cases, we work around the behavior by prefixing every selector in the + // list with an ID selector referencing the scope context. + // The technique has to be used as well when a leading combinator is used + // as such selectors are not recognized by querySelectorAll. + // Thanks to Andrew Dupont for this technique. + if ( nodeType === 1 && + ( rdescend.test( selector ) || rcombinators.test( selector ) ) ) { + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + + // We can use :scope instead of the ID hack if the browser + // supports it & if we're not changing the context. + if ( newContext !== context || !support.scope ) { + + // Capture the context ID, setting it first if necessary + if ( ( nid = context.getAttribute( "id" ) ) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", ( nid = expando ) ); + } + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[ i ] = ( nid ? "#" + nid : ":scope" ) + " " + + toSelector( groups[ i ] ); + } + newSelector = groups.join( "," ); + } + + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + nonnativeSelectorCache( selector, true ); + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return ( cache[ key + " " ] = value ); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement( "fieldset" ); + + try { + return !!fn( el ); + } catch ( e ) { + return false; + } finally { + + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split( "|" ), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[ i ] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( ( cur = cur.nextSibling ) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return ( name === "input" || name === "button" ) && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + + // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Only certain elements can match :enabled or :disabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled + if ( "form" in elem ) { + + // Check for inherited disabledness on relevant non-disabled elements: + // * listed form-associated elements in a disabled fieldset + // https://html.spec.whatwg.org/multipage/forms.html#category-listed + // https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled + // * option elements in a disabled optgroup + // https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled + // All such elements have a "form" property. + if ( elem.parentNode && elem.disabled === false ) { + + // Option elements defer to a parent optgroup if present + if ( "label" in elem ) { + if ( "label" in elem.parentNode ) { + return elem.parentNode.disabled === disabled; + } else { + return elem.disabled === disabled; + } + } + + // Support: IE 6 - 11 + // Use the isDisabled shortcut property to check for disabled fieldset ancestors + return elem.isDisabled === disabled || + + // Where there is no isDisabled, check manually + /* jshint -W018 */ + elem.isDisabled !== !disabled && + inDisabledFieldset( elem ) === disabled; + } + + return elem.disabled === disabled; + + // Try to winnow out elements that can't be disabled before trusting the disabled property. + // Some victims get caught in our net (label, legend, menu, track), but it shouldn't + // even exist on them, let alone have a boolean value. + } else if ( "label" in elem ) { + return elem.disabled === disabled; + } + + // Remaining elements are neither :enabled nor :disabled + return false; + }; +} + +/** + * Returns a function to use in pseudos for positionals + * @param {Function} fn + */ +function createPositionalPseudo( fn ) { + return markFunction( function( argument ) { + argument = +argument; + return markFunction( function( seed, matches ) { + var j, + matchIndexes = fn( [], seed.length, argument ), + i = matchIndexes.length; + + // Match elements found at the specified indexes + while ( i-- ) { + if ( seed[ ( j = matchIndexes[ i ] ) ] ) { + seed[ j ] = !( matches[ j ] = seed[ j ] ); + } + } + } ); + } ); +} + +/** + * Checks a node for validity as a Sizzle context + * @param {Element|Object=} context + * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + */ +function testContext( context ) { + return context && typeof context.getElementsByTagName !== "undefined" && context; +} + +// Expose support vars for convenience +support = Sizzle.support = {}; + +/** + * Detects XML nodes + * @param {Element|Object} elem An element or a document + * @returns {Boolean} True iff elem is a non-HTML XML node + */ +isXML = Sizzle.isXML = function( elem ) { + var namespace = elem && elem.namespaceURI, + docElem = elem && ( elem.ownerDocument || elem ).documentElement; + + // Support: IE <=8 + // Assume HTML when documentElement doesn't yet exist, such as inside loading iframes + // https://bugs.jquery.com/ticket/4833 + return !rhtml.test( namespace || docElem && docElem.nodeName || "HTML" ); +}; + +/** + * Sets document-related variables once based on the current document + * @param {Element|Object} [doc] An element or document object to use to set the document + * @returns {Object} Returns the current document + */ +setDocument = Sizzle.setDocument = function( node ) { + var hasCompare, subWindow, + doc = node ? node.ownerDocument || node : preferredDoc; + + // Return early if doc is invalid or already selected + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( doc == document || doc.nodeType !== 9 || !doc.documentElement ) { + return document; + } + + // Update global variables + document = doc; + docElem = document.documentElement; + documentIsHTML = !isXML( document ); + + // Support: IE 9 - 11+, Edge 12 - 18+ + // Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936) + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( preferredDoc != document && + ( subWindow = document.defaultView ) && subWindow.top !== subWindow ) { + + // Support: IE 11, Edge + if ( subWindow.addEventListener ) { + subWindow.addEventListener( "unload", unloadHandler, false ); + + // Support: IE 9 - 10 only + } else if ( subWindow.attachEvent ) { + subWindow.attachEvent( "onunload", unloadHandler ); + } + } + + // Support: IE 8 - 11+, Edge 12 - 18+, Chrome <=16 - 25 only, Firefox <=3.6 - 31 only, + // Safari 4 - 5 only, Opera <=11.6 - 12.x only + // IE/Edge & older browsers don't support the :scope pseudo-class. + // Support: Safari 6.0 only + // Safari 6.0 supports :scope but it's an alias of :root there. + support.scope = assert( function( el ) { + docElem.appendChild( el ).appendChild( document.createElement( "div" ) ); + return typeof el.querySelectorAll !== "undefined" && + !el.querySelectorAll( ":scope fieldset div" ).length; + } ); + + /* Attributes + ---------------------------------------------------------------------- */ + + // Support: IE<8 + // Verify that getAttribute really returns attributes and not properties + // (excepting IE8 booleans) + support.attributes = assert( function( el ) { + el.className = "i"; + return !el.getAttribute( "className" ); + } ); + + /* getElement(s)By* + ---------------------------------------------------------------------- */ + + // Check if getElementsByTagName("*") returns only elements + support.getElementsByTagName = assert( function( el ) { + el.appendChild( document.createComment( "" ) ); + return !el.getElementsByTagName( "*" ).length; + } ); + + // Support: IE<9 + support.getElementsByClassName = rnative.test( document.getElementsByClassName ); + + // Support: IE<10 + // Check if getElementById returns elements by name + // The broken getElementById methods don't pick up programmatically-set names, + // so use a roundabout getElementsByName test + support.getById = assert( function( el ) { + docElem.appendChild( el ).id = expando; + return !document.getElementsByName || !document.getElementsByName( expando ).length; + } ); + + // ID filter and find + if ( support.getById ) { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + return elem.getAttribute( "id" ) === attrId; + }; + }; + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var elem = context.getElementById( id ); + return elem ? [ elem ] : []; + } + }; + } else { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + var node = typeof elem.getAttributeNode !== "undefined" && + elem.getAttributeNode( "id" ); + return node && node.value === attrId; + }; + }; + + // Support: IE 6 - 7 only + // getElementById is not reliable as a find shortcut + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var node, i, elems, + elem = context.getElementById( id ); + + if ( elem ) { + + // Verify the id attribute + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + + // Fall back on getElementsByName + elems = context.getElementsByName( id ); + i = 0; + while ( ( elem = elems[ i++ ] ) ) { + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + } + } + + return []; + } + }; + } + + // Tag + Expr.find[ "TAG" ] = support.getElementsByTagName ? + function( tag, context ) { + if ( typeof context.getElementsByTagName !== "undefined" ) { + return context.getElementsByTagName( tag ); + + // DocumentFragment nodes don't have gEBTN + } else if ( support.qsa ) { + return context.querySelectorAll( tag ); + } + } : + + function( tag, context ) { + var elem, + tmp = [], + i = 0, + + // By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too + results = context.getElementsByTagName( tag ); + + // Filter out possible comments + if ( tag === "*" ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem.nodeType === 1 ) { + tmp.push( elem ); + } + } + + return tmp; + } + return results; + }; + + // Class + Expr.find[ "CLASS" ] = support.getElementsByClassName && function( className, context ) { + if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) { + return context.getElementsByClassName( className ); + } + }; + + /* QSA/matchesSelector + ---------------------------------------------------------------------- */ + + // QSA and matchesSelector support + + // matchesSelector(:active) reports false when true (IE9/Opera 11.5) + rbuggyMatches = []; + + // qSa(:focus) reports false when true (Chrome 21) + // We allow this because of a bug in IE8/9 that throws an error + // whenever `document.activeElement` is accessed on an iframe + // So, we allow :focus to pass through QSA all the time to avoid the IE error + // See https://bugs.jquery.com/ticket/13378 + rbuggyQSA = []; + + if ( ( support.qsa = rnative.test( document.querySelectorAll ) ) ) { + + // Build QSA regex + // Regex strategy adopted from Diego Perini + assert( function( el ) { + + var input; + + // Select is set to empty string on purpose + // This is to test IE's treatment of not explicitly + // setting a boolean content attribute, + // since its presence should be enough + // https://bugs.jquery.com/ticket/12359 + docElem.appendChild( el ).innerHTML = "" + + ""; + + // Support: IE8, Opera 11-12.16 + // Nothing should be selected when empty strings follow ^= or $= or *= + // The test attribute must be unknown in Opera but "safe" for WinRT + // https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section + if ( el.querySelectorAll( "[msallowcapture^='']" ).length ) { + rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); + } + + // Support: IE8 + // Boolean attributes and "value" are not treated correctly + if ( !el.querySelectorAll( "[selected]" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); + } + + // Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+ + if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) { + rbuggyQSA.push( "~=" ); + } + + // Support: IE 11+, Edge 15 - 18+ + // IE 11/Edge don't find elements on a `[name='']` query in some cases. + // Adding a temporary attribute to the document before the selection works + // around the issue. + // Interestingly, IE 10 & older don't seem to have the issue. + input = document.createElement( "input" ); + input.setAttribute( "name", "" ); + el.appendChild( input ); + if ( !el.querySelectorAll( "[name='']" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*name" + whitespace + "*=" + + whitespace + "*(?:''|\"\")" ); + } + + // Webkit/Opera - :checked should return selected option elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + // IE8 throws error here and will not see later tests + if ( !el.querySelectorAll( ":checked" ).length ) { + rbuggyQSA.push( ":checked" ); + } + + // Support: Safari 8+, iOS 8+ + // https://bugs.webkit.org/show_bug.cgi?id=136851 + // In-page `selector#id sibling-combinator selector` fails + if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) { + rbuggyQSA.push( ".#.+[+~]" ); + } + + // Support: Firefox <=3.6 - 5 only + // Old Firefox doesn't throw on a badly-escaped identifier. + el.querySelectorAll( "\\\f" ); + rbuggyQSA.push( "[\\r\\n\\f]" ); + } ); + + assert( function( el ) { + el.innerHTML = "" + + ""; + + // Support: Windows 8 Native Apps + // The type and name attributes are restricted during .innerHTML assignment + var input = document.createElement( "input" ); + input.setAttribute( "type", "hidden" ); + el.appendChild( input ).setAttribute( "name", "D" ); + + // Support: IE8 + // Enforce case-sensitivity of name attribute + if ( el.querySelectorAll( "[name=d]" ).length ) { + rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); + } + + // FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled) + // IE8 throws error here and will not see later tests + if ( el.querySelectorAll( ":enabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: IE9-11+ + // IE's :disabled selector does not pick up the children of disabled fieldsets + docElem.appendChild( el ).disabled = true; + if ( el.querySelectorAll( ":disabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: Opera 10 - 11 only + // Opera 10-11 does not throw on post-comma invalid pseudos + el.querySelectorAll( "*,:x" ); + rbuggyQSA.push( ",.*:" ); + } ); + } + + if ( ( support.matchesSelector = rnative.test( ( matches = docElem.matches || + docElem.webkitMatchesSelector || + docElem.mozMatchesSelector || + docElem.oMatchesSelector || + docElem.msMatchesSelector ) ) ) ) { + + assert( function( el ) { + + // Check to see if it's possible to do matchesSelector + // on a disconnected node (IE 9) + support.disconnectedMatch = matches.call( el, "*" ); + + // This should fail with an exception + // Gecko does not error, returns false instead + matches.call( el, "[s!='']:x" ); + rbuggyMatches.push( "!=", pseudos ); + } ); + } + + rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join( "|" ) ); + rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join( "|" ) ); + + /* Contains + ---------------------------------------------------------------------- */ + hasCompare = rnative.test( docElem.compareDocumentPosition ); + + // Element contains another + // Purposefully self-exclusive + // As in, an element does not contain itself + contains = hasCompare || rnative.test( docElem.contains ) ? + function( a, b ) { + var adown = a.nodeType === 9 ? a.documentElement : a, + bup = b && b.parentNode; + return a === bup || !!( bup && bup.nodeType === 1 && ( + adown.contains ? + adown.contains( bup ) : + a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 + ) ); + } : + function( a, b ) { + if ( b ) { + while ( ( b = b.parentNode ) ) { + if ( b === a ) { + return true; + } + } + } + return false; + }; + + /* Sorting + ---------------------------------------------------------------------- */ + + // Document order sorting + sortOrder = hasCompare ? + function( a, b ) { + + // Flag for duplicate removal + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + // Sort on method existence if only one input has compareDocumentPosition + var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; + if ( compare ) { + return compare; + } + + // Calculate position if both inputs belong to the same document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + compare = ( a.ownerDocument || a ) == ( b.ownerDocument || b ) ? + a.compareDocumentPosition( b ) : + + // Otherwise we know they are disconnected + 1; + + // Disconnected nodes + if ( compare & 1 || + ( !support.sortDetached && b.compareDocumentPosition( a ) === compare ) ) { + + // Choose the first element that is related to our preferred document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( a == document || a.ownerDocument == preferredDoc && + contains( preferredDoc, a ) ) { + return -1; + } + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( b == document || b.ownerDocument == preferredDoc && + contains( preferredDoc, b ) ) { + return 1; + } + + // Maintain original order + return sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + } + + return compare & 4 ? -1 : 1; + } : + function( a, b ) { + + // Exit early if the nodes are identical + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + var cur, + i = 0, + aup = a.parentNode, + bup = b.parentNode, + ap = [ a ], + bp = [ b ]; + + // Parentless nodes are either documents or disconnected + if ( !aup || !bup ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + return a == document ? -1 : + b == document ? 1 : + /* eslint-enable eqeqeq */ + aup ? -1 : + bup ? 1 : + sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + + // If the nodes are siblings, we can do a quick check + } else if ( aup === bup ) { + return siblingCheck( a, b ); + } + + // Otherwise we need full lists of their ancestors for comparison + cur = a; + while ( ( cur = cur.parentNode ) ) { + ap.unshift( cur ); + } + cur = b; + while ( ( cur = cur.parentNode ) ) { + bp.unshift( cur ); + } + + // Walk down the tree looking for a discrepancy + while ( ap[ i ] === bp[ i ] ) { + i++; + } + + return i ? + + // Do a sibling check if the nodes have a common ancestor + siblingCheck( ap[ i ], bp[ i ] ) : + + // Otherwise nodes in our document sort first + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + ap[ i ] == preferredDoc ? -1 : + bp[ i ] == preferredDoc ? 1 : + /* eslint-enable eqeqeq */ + 0; + }; + + return document; +}; + +Sizzle.matches = function( expr, elements ) { + return Sizzle( expr, null, null, elements ); +}; + +Sizzle.matchesSelector = function( elem, expr ) { + setDocument( elem ); + + if ( support.matchesSelector && documentIsHTML && + !nonnativeSelectorCache[ expr + " " ] && + ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && + ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { + + try { + var ret = matches.call( elem, expr ); + + // IE 9's matchesSelector returns false on disconnected nodes + if ( ret || support.disconnectedMatch || + + // As well, disconnected nodes are said to be in a document + // fragment in IE 9 + elem.document && elem.document.nodeType !== 11 ) { + return ret; + } + } catch ( e ) { + nonnativeSelectorCache( expr, true ); + } + } + + return Sizzle( expr, document, null, [ elem ] ).length > 0; +}; + +Sizzle.contains = function( context, elem ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( context.ownerDocument || context ) != document ) { + setDocument( context ); + } + return contains( context, elem ); +}; + +Sizzle.attr = function( elem, name ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( elem.ownerDocument || elem ) != document ) { + setDocument( elem ); + } + + var fn = Expr.attrHandle[ name.toLowerCase() ], + + // Don't get fooled by Object.prototype properties (jQuery #13807) + val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? + fn( elem, name, !documentIsHTML ) : + undefined; + + return val !== undefined ? + val : + support.attributes || !documentIsHTML ? + elem.getAttribute( name ) : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; +}; + +Sizzle.escape = function( sel ) { + return ( sel + "" ).replace( rcssescape, fcssescape ); +}; + +Sizzle.error = function( msg ) { + throw new Error( "Syntax error, unrecognized expression: " + msg ); +}; + +/** + * Document sorting and removing duplicates + * @param {ArrayLike} results + */ +Sizzle.uniqueSort = function( results ) { + var elem, + duplicates = [], + j = 0, + i = 0; + + // Unless we *know* we can detect duplicates, assume their presence + hasDuplicate = !support.detectDuplicates; + sortInput = !support.sortStable && results.slice( 0 ); + results.sort( sortOrder ); + + if ( hasDuplicate ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem === results[ i ] ) { + j = duplicates.push( i ); + } + } + while ( j-- ) { + results.splice( duplicates[ j ], 1 ); + } + } + + // Clear input after sorting to release objects + // See https://github.com/jquery/sizzle/pull/225 + sortInput = null; + + return results; +}; + +/** + * Utility function for retrieving the text value of an array of DOM nodes + * @param {Array|Element} elem + */ +getText = Sizzle.getText = function( elem ) { + var node, + ret = "", + i = 0, + nodeType = elem.nodeType; + + if ( !nodeType ) { + + // If no nodeType, this is expected to be an array + while ( ( node = elem[ i++ ] ) ) { + + // Do not traverse comment nodes + ret += getText( node ); + } + } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { + + // Use textContent for elements + // innerText usage removed for consistency of new lines (jQuery #11153) + if ( typeof elem.textContent === "string" ) { + return elem.textContent; + } else { + + // Traverse its children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + ret += getText( elem ); + } + } + } else if ( nodeType === 3 || nodeType === 4 ) { + return elem.nodeValue; + } + + // Do not include comment or processing instruction nodes + + return ret; +}; + +Expr = Sizzle.selectors = { + + // Can be adjusted by the user + cacheLength: 50, + + createPseudo: markFunction, + + match: matchExpr, + + attrHandle: {}, + + find: {}, + + relative: { + ">": { dir: "parentNode", first: true }, + " ": { dir: "parentNode" }, + "+": { dir: "previousSibling", first: true }, + "~": { dir: "previousSibling" } + }, + + preFilter: { + "ATTR": function( match ) { + match[ 1 ] = match[ 1 ].replace( runescape, funescape ); + + // Move the given value to match[3] whether quoted or unquoted + match[ 3 ] = ( match[ 3 ] || match[ 4 ] || + match[ 5 ] || "" ).replace( runescape, funescape ); + + if ( match[ 2 ] === "~=" ) { + match[ 3 ] = " " + match[ 3 ] + " "; + } + + return match.slice( 0, 4 ); + }, + + "CHILD": function( match ) { + + /* matches from matchExpr["CHILD"] + 1 type (only|nth|...) + 2 what (child|of-type) + 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) + 4 xn-component of xn+y argument ([+-]?\d*n|) + 5 sign of xn-component + 6 x of xn-component + 7 sign of y-component + 8 y of y-component + */ + match[ 1 ] = match[ 1 ].toLowerCase(); + + if ( match[ 1 ].slice( 0, 3 ) === "nth" ) { + + // nth-* requires argument + if ( !match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + // numeric x and y parameters for Expr.filter.CHILD + // remember that false/true cast respectively to 0/1 + match[ 4 ] = +( match[ 4 ] ? + match[ 5 ] + ( match[ 6 ] || 1 ) : + 2 * ( match[ 3 ] === "even" || match[ 3 ] === "odd" ) ); + match[ 5 ] = +( ( match[ 7 ] + match[ 8 ] ) || match[ 3 ] === "odd" ); + + // other types prohibit arguments + } else if ( match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + return match; + }, + + "PSEUDO": function( match ) { + var excess, + unquoted = !match[ 6 ] && match[ 2 ]; + + if ( matchExpr[ "CHILD" ].test( match[ 0 ] ) ) { + return null; + } + + // Accept quoted arguments as-is + if ( match[ 3 ] ) { + match[ 2 ] = match[ 4 ] || match[ 5 ] || ""; + + // Strip excess characters from unquoted arguments + } else if ( unquoted && rpseudo.test( unquoted ) && + + // Get excess from tokenize (recursively) + ( excess = tokenize( unquoted, true ) ) && + + // advance to the next closing parenthesis + ( excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length ) ) { + + // excess is a negative index + match[ 0 ] = match[ 0 ].slice( 0, excess ); + match[ 2 ] = unquoted.slice( 0, excess ); + } + + // Return only captures needed by the pseudo filter method (type and argument) + return match.slice( 0, 3 ); + } + }, + + filter: { + + "TAG": function( nodeNameSelector ) { + var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); + return nodeNameSelector === "*" ? + function() { + return true; + } : + function( elem ) { + return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; + }; + }, + + "CLASS": function( className ) { + var pattern = classCache[ className + " " ]; + + return pattern || + ( pattern = new RegExp( "(^|" + whitespace + + ")" + className + "(" + whitespace + "|$)" ) ) && classCache( + className, function( elem ) { + return pattern.test( + typeof elem.className === "string" && elem.className || + typeof elem.getAttribute !== "undefined" && + elem.getAttribute( "class" ) || + "" + ); + } ); + }, + + "ATTR": function( name, operator, check ) { + return function( elem ) { + var result = Sizzle.attr( elem, name ); + + if ( result == null ) { + return operator === "!="; + } + if ( !operator ) { + return true; + } + + result += ""; + + /* eslint-disable max-len */ + + return operator === "=" ? result === check : + operator === "!=" ? result !== check : + operator === "^=" ? check && result.indexOf( check ) === 0 : + operator === "*=" ? check && result.indexOf( check ) > -1 : + operator === "$=" ? check && result.slice( -check.length ) === check : + operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 : + operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : + false; + /* eslint-enable max-len */ + + }; + }, + + "CHILD": function( type, what, _argument, first, last ) { + var simple = type.slice( 0, 3 ) !== "nth", + forward = type.slice( -4 ) !== "last", + ofType = what === "of-type"; + + return first === 1 && last === 0 ? + + // Shortcut for :nth-*(n) + function( elem ) { + return !!elem.parentNode; + } : + + function( elem, _context, xml ) { + var cache, uniqueCache, outerCache, node, nodeIndex, start, + dir = simple !== forward ? "nextSibling" : "previousSibling", + parent = elem.parentNode, + name = ofType && elem.nodeName.toLowerCase(), + useCache = !xml && !ofType, + diff = false; + + if ( parent ) { + + // :(first|last|only)-(child|of-type) + if ( simple ) { + while ( dir ) { + node = elem; + while ( ( node = node[ dir ] ) ) { + if ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) { + + return false; + } + } + + // Reverse direction for :only-* (if we haven't yet done so) + start = dir = type === "only" && !start && "nextSibling"; + } + return true; + } + + start = [ forward ? parent.firstChild : parent.lastChild ]; + + // non-xml :nth-child(...) stores cache data on `parent` + if ( forward && useCache ) { + + // Seek `elem` from a previously-cached index + + // ...in a gzip-friendly way + node = parent; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex && cache[ 2 ]; + node = nodeIndex && parent.childNodes[ nodeIndex ]; + + while ( ( node = ++nodeIndex && node && node[ dir ] || + + // Fallback to seeking `elem` from the start + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + // When found, cache indexes on `parent` and break + if ( node.nodeType === 1 && ++diff && node === elem ) { + uniqueCache[ type ] = [ dirruns, nodeIndex, diff ]; + break; + } + } + + } else { + + // Use previously-cached element index if available + if ( useCache ) { + + // ...in a gzip-friendly way + node = elem; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex; + } + + // xml :nth-child(...) + // or :nth-last-child(...) or :nth(-last)?-of-type(...) + if ( diff === false ) { + + // Use the same loop as above to seek `elem` from the start + while ( ( node = ++nodeIndex && node && node[ dir ] || + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + if ( ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) && + ++diff ) { + + // Cache the index of each encountered element + if ( useCache ) { + outerCache = node[ expando ] || + ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + uniqueCache[ type ] = [ dirruns, diff ]; + } + + if ( node === elem ) { + break; + } + } + } + } + } + + // Incorporate the offset, then check against cycle size + diff -= last; + return diff === first || ( diff % first === 0 && diff / first >= 0 ); + } + }; + }, + + "PSEUDO": function( pseudo, argument ) { + + // pseudo-class names are case-insensitive + // http://www.w3.org/TR/selectors/#pseudo-classes + // Prioritize by case sensitivity in case custom pseudos are added with uppercase letters + // Remember that setFilters inherits from pseudos + var args, + fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || + Sizzle.error( "unsupported pseudo: " + pseudo ); + + // The user may use createPseudo to indicate that + // arguments are needed to create the filter function + // just as Sizzle does + if ( fn[ expando ] ) { + return fn( argument ); + } + + // But maintain support for old signatures + if ( fn.length > 1 ) { + args = [ pseudo, pseudo, "", argument ]; + return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? + markFunction( function( seed, matches ) { + var idx, + matched = fn( seed, argument ), + i = matched.length; + while ( i-- ) { + idx = indexOf( seed, matched[ i ] ); + seed[ idx ] = !( matches[ idx ] = matched[ i ] ); + } + } ) : + function( elem ) { + return fn( elem, 0, args ); + }; + } + + return fn; + } + }, + + pseudos: { + + // Potentially complex pseudos + "not": markFunction( function( selector ) { + + // Trim the selector passed to compile + // to avoid treating leading and trailing + // spaces as combinators + var input = [], + results = [], + matcher = compile( selector.replace( rtrim, "$1" ) ); + + return matcher[ expando ] ? + markFunction( function( seed, matches, _context, xml ) { + var elem, + unmatched = matcher( seed, null, xml, [] ), + i = seed.length; + + // Match elements unmatched by `matcher` + while ( i-- ) { + if ( ( elem = unmatched[ i ] ) ) { + seed[ i ] = !( matches[ i ] = elem ); + } + } + } ) : + function( elem, _context, xml ) { + input[ 0 ] = elem; + matcher( input, null, xml, results ); + + // Don't keep the element (issue #299) + input[ 0 ] = null; + return !results.pop(); + }; + } ), + + "has": markFunction( function( selector ) { + return function( elem ) { + return Sizzle( selector, elem ).length > 0; + }; + } ), + + "contains": markFunction( function( text ) { + text = text.replace( runescape, funescape ); + return function( elem ) { + return ( elem.textContent || getText( elem ) ).indexOf( text ) > -1; + }; + } ), + + // "Whether an element is represented by a :lang() selector + // is based solely on the element's language value + // being equal to the identifier C, + // or beginning with the identifier C immediately followed by "-". + // The matching of C against the element's language value is performed case-insensitively. + // The identifier C does not have to be a valid language name." + // http://www.w3.org/TR/selectors/#lang-pseudo + "lang": markFunction( function( lang ) { + + // lang value must be a valid identifier + if ( !ridentifier.test( lang || "" ) ) { + Sizzle.error( "unsupported lang: " + lang ); + } + lang = lang.replace( runescape, funescape ).toLowerCase(); + return function( elem ) { + var elemLang; + do { + if ( ( elemLang = documentIsHTML ? + elem.lang : + elem.getAttribute( "xml:lang" ) || elem.getAttribute( "lang" ) ) ) { + + elemLang = elemLang.toLowerCase(); + return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; + } + } while ( ( elem = elem.parentNode ) && elem.nodeType === 1 ); + return false; + }; + } ), + + // Miscellaneous + "target": function( elem ) { + var hash = window.location && window.location.hash; + return hash && hash.slice( 1 ) === elem.id; + }, + + "root": function( elem ) { + return elem === docElem; + }, + + "focus": function( elem ) { + return elem === document.activeElement && + ( !document.hasFocus || document.hasFocus() ) && + !!( elem.type || elem.href || ~elem.tabIndex ); + }, + + // Boolean properties + "enabled": createDisabledPseudo( false ), + "disabled": createDisabledPseudo( true ), + + "checked": function( elem ) { + + // In CSS3, :checked should return both checked and selected elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + var nodeName = elem.nodeName.toLowerCase(); + return ( nodeName === "input" && !!elem.checked ) || + ( nodeName === "option" && !!elem.selected ); + }, + + "selected": function( elem ) { + + // Accessing this property makes selected-by-default + // options in Safari work properly + if ( elem.parentNode ) { + // eslint-disable-next-line no-unused-expressions + elem.parentNode.selectedIndex; + } + + return elem.selected === true; + }, + + // Contents + "empty": function( elem ) { + + // http://www.w3.org/TR/selectors/#empty-pseudo + // :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5), + // but not by others (comment: 8; processing instruction: 7; etc.) + // nodeType < 6 works because attributes (2) do not appear as children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + if ( elem.nodeType < 6 ) { + return false; + } + } + return true; + }, + + "parent": function( elem ) { + return !Expr.pseudos[ "empty" ]( elem ); + }, + + // Element/input types + "header": function( elem ) { + return rheader.test( elem.nodeName ); + }, + + "input": function( elem ) { + return rinputs.test( elem.nodeName ); + }, + + "button": function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === "button" || name === "button"; + }, + + "text": function( elem ) { + var attr; + return elem.nodeName.toLowerCase() === "input" && + elem.type === "text" && + + // Support: IE<8 + // New HTML5 attribute values (e.g., "search") appear with elem.type === "text" + ( ( attr = elem.getAttribute( "type" ) ) == null || + attr.toLowerCase() === "text" ); + }, + + // Position-in-collection + "first": createPositionalPseudo( function() { + return [ 0 ]; + } ), + + "last": createPositionalPseudo( function( _matchIndexes, length ) { + return [ length - 1 ]; + } ), + + "eq": createPositionalPseudo( function( _matchIndexes, length, argument ) { + return [ argument < 0 ? argument + length : argument ]; + } ), + + "even": createPositionalPseudo( function( matchIndexes, length ) { + var i = 0; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "odd": createPositionalPseudo( function( matchIndexes, length ) { + var i = 1; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "lt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? + argument + length : + argument > length ? + length : + argument; + for ( ; --i >= 0; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "gt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? argument + length : argument; + for ( ; ++i < length; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ) + } +}; + +Expr.pseudos[ "nth" ] = Expr.pseudos[ "eq" ]; + +// Add button/input type pseudos +for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { + Expr.pseudos[ i ] = createInputPseudo( i ); +} +for ( i in { submit: true, reset: true } ) { + Expr.pseudos[ i ] = createButtonPseudo( i ); +} + +// Easy API for creating new setFilters +function setFilters() {} +setFilters.prototype = Expr.filters = Expr.pseudos; +Expr.setFilters = new setFilters(); + +tokenize = Sizzle.tokenize = function( selector, parseOnly ) { + var matched, match, tokens, type, + soFar, groups, preFilters, + cached = tokenCache[ selector + " " ]; + + if ( cached ) { + return parseOnly ? 0 : cached.slice( 0 ); + } + + soFar = selector; + groups = []; + preFilters = Expr.preFilter; + + while ( soFar ) { + + // Comma and first run + if ( !matched || ( match = rcomma.exec( soFar ) ) ) { + if ( match ) { + + // Don't consume trailing commas as valid + soFar = soFar.slice( match[ 0 ].length ) || soFar; + } + groups.push( ( tokens = [] ) ); + } + + matched = false; + + // Combinators + if ( ( match = rcombinators.exec( soFar ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + + // Cast descendant combinators to space + type: match[ 0 ].replace( rtrim, " " ) + } ); + soFar = soFar.slice( matched.length ); + } + + // Filters + for ( type in Expr.filter ) { + if ( ( match = matchExpr[ type ].exec( soFar ) ) && ( !preFilters[ type ] || + ( match = preFilters[ type ]( match ) ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + type: type, + matches: match + } ); + soFar = soFar.slice( matched.length ); + } + } + + if ( !matched ) { + break; + } + } + + // Return the length of the invalid excess + // if we're just parsing + // Otherwise, throw an error or return tokens + return parseOnly ? + soFar.length : + soFar ? + Sizzle.error( selector ) : + + // Cache the tokens + tokenCache( selector, groups ).slice( 0 ); +}; + +function toSelector( tokens ) { + var i = 0, + len = tokens.length, + selector = ""; + for ( ; i < len; i++ ) { + selector += tokens[ i ].value; + } + return selector; +} + +function addCombinator( matcher, combinator, base ) { + var dir = combinator.dir, + skip = combinator.next, + key = skip || dir, + checkNonElements = base && key === "parentNode", + doneName = done++; + + return combinator.first ? + + // Check against closest ancestor/preceding element + function( elem, context, xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + return matcher( elem, context, xml ); + } + } + return false; + } : + + // Check against all ancestor/preceding elements + function( elem, context, xml ) { + var oldCache, uniqueCache, outerCache, + newCache = [ dirruns, doneName ]; + + // We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching + if ( xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + if ( matcher( elem, context, xml ) ) { + return true; + } + } + } + } else { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + outerCache = elem[ expando ] || ( elem[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ elem.uniqueID ] || + ( outerCache[ elem.uniqueID ] = {} ); + + if ( skip && skip === elem.nodeName.toLowerCase() ) { + elem = elem[ dir ] || elem; + } else if ( ( oldCache = uniqueCache[ key ] ) && + oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { + + // Assign to newCache so results back-propagate to previous elements + return ( newCache[ 2 ] = oldCache[ 2 ] ); + } else { + + // Reuse newcache so results back-propagate to previous elements + uniqueCache[ key ] = newCache; + + // A match means we're done; a fail means we have to keep checking + if ( ( newCache[ 2 ] = matcher( elem, context, xml ) ) ) { + return true; + } + } + } + } + } + return false; + }; +} + +function elementMatcher( matchers ) { + return matchers.length > 1 ? + function( elem, context, xml ) { + var i = matchers.length; + while ( i-- ) { + if ( !matchers[ i ]( elem, context, xml ) ) { + return false; + } + } + return true; + } : + matchers[ 0 ]; +} + +function multipleContexts( selector, contexts, results ) { + var i = 0, + len = contexts.length; + for ( ; i < len; i++ ) { + Sizzle( selector, contexts[ i ], results ); + } + return results; +} + +function condense( unmatched, map, filter, context, xml ) { + var elem, + newUnmatched = [], + i = 0, + len = unmatched.length, + mapped = map != null; + + for ( ; i < len; i++ ) { + if ( ( elem = unmatched[ i ] ) ) { + if ( !filter || filter( elem, context, xml ) ) { + newUnmatched.push( elem ); + if ( mapped ) { + map.push( i ); + } + } + } + } + + return newUnmatched; +} + +function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { + if ( postFilter && !postFilter[ expando ] ) { + postFilter = setMatcher( postFilter ); + } + if ( postFinder && !postFinder[ expando ] ) { + postFinder = setMatcher( postFinder, postSelector ); + } + return markFunction( function( seed, results, context, xml ) { + var temp, i, elem, + preMap = [], + postMap = [], + preexisting = results.length, + + // Get initial elements from seed or context + elems = seed || multipleContexts( + selector || "*", + context.nodeType ? [ context ] : context, + [] + ), + + // Prefilter to get matcher input, preserving a map for seed-results synchronization + matcherIn = preFilter && ( seed || !selector ) ? + condense( elems, preMap, preFilter, context, xml ) : + elems, + + matcherOut = matcher ? + + // If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results, + postFinder || ( seed ? preFilter : preexisting || postFilter ) ? + + // ...intermediate processing is necessary + [] : + + // ...otherwise use results directly + results : + matcherIn; + + // Find primary matches + if ( matcher ) { + matcher( matcherIn, matcherOut, context, xml ); + } + + // Apply postFilter + if ( postFilter ) { + temp = condense( matcherOut, postMap ); + postFilter( temp, [], context, xml ); + + // Un-match failing elements by moving them back to matcherIn + i = temp.length; + while ( i-- ) { + if ( ( elem = temp[ i ] ) ) { + matcherOut[ postMap[ i ] ] = !( matcherIn[ postMap[ i ] ] = elem ); + } + } + } + + if ( seed ) { + if ( postFinder || preFilter ) { + if ( postFinder ) { + + // Get the final matcherOut by condensing this intermediate into postFinder contexts + temp = []; + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) ) { + + // Restore matcherIn since elem is not yet a final match + temp.push( ( matcherIn[ i ] = elem ) ); + } + } + postFinder( null, ( matcherOut = [] ), temp, xml ); + } + + // Move matched elements from seed to results to keep them synchronized + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) && + ( temp = postFinder ? indexOf( seed, elem ) : preMap[ i ] ) > -1 ) { + + seed[ temp ] = !( results[ temp ] = elem ); + } + } + } + + // Add elements to results, through postFinder if defined + } else { + matcherOut = condense( + matcherOut === results ? + matcherOut.splice( preexisting, matcherOut.length ) : + matcherOut + ); + if ( postFinder ) { + postFinder( null, results, matcherOut, xml ); + } else { + push.apply( results, matcherOut ); + } + } + } ); +} + +function matcherFromTokens( tokens ) { + var checkContext, matcher, j, + len = tokens.length, + leadingRelative = Expr.relative[ tokens[ 0 ].type ], + implicitRelative = leadingRelative || Expr.relative[ " " ], + i = leadingRelative ? 1 : 0, + + // The foundational matcher ensures that elements are reachable from top-level context(s) + matchContext = addCombinator( function( elem ) { + return elem === checkContext; + }, implicitRelative, true ), + matchAnyContext = addCombinator( function( elem ) { + return indexOf( checkContext, elem ) > -1; + }, implicitRelative, true ), + matchers = [ function( elem, context, xml ) { + var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( + ( checkContext = context ).nodeType ? + matchContext( elem, context, xml ) : + matchAnyContext( elem, context, xml ) ); + + // Avoid hanging onto element (issue #299) + checkContext = null; + return ret; + } ]; + + for ( ; i < len; i++ ) { + if ( ( matcher = Expr.relative[ tokens[ i ].type ] ) ) { + matchers = [ addCombinator( elementMatcher( matchers ), matcher ) ]; + } else { + matcher = Expr.filter[ tokens[ i ].type ].apply( null, tokens[ i ].matches ); + + // Return special upon seeing a positional matcher + if ( matcher[ expando ] ) { + + // Find the next relative operator (if any) for proper handling + j = ++i; + for ( ; j < len; j++ ) { + if ( Expr.relative[ tokens[ j ].type ] ) { + break; + } + } + return setMatcher( + i > 1 && elementMatcher( matchers ), + i > 1 && toSelector( + + // If the preceding token was a descendant combinator, insert an implicit any-element `*` + tokens + .slice( 0, i - 1 ) + .concat( { value: tokens[ i - 2 ].type === " " ? "*" : "" } ) + ).replace( rtrim, "$1" ), + matcher, + i < j && matcherFromTokens( tokens.slice( i, j ) ), + j < len && matcherFromTokens( ( tokens = tokens.slice( j ) ) ), + j < len && toSelector( tokens ) + ); + } + matchers.push( matcher ); + } + } + + return elementMatcher( matchers ); +} + +function matcherFromGroupMatchers( elementMatchers, setMatchers ) { + var bySet = setMatchers.length > 0, + byElement = elementMatchers.length > 0, + superMatcher = function( seed, context, xml, results, outermost ) { + var elem, j, matcher, + matchedCount = 0, + i = "0", + unmatched = seed && [], + setMatched = [], + contextBackup = outermostContext, + + // We must always have either seed elements or outermost context + elems = seed || byElement && Expr.find[ "TAG" ]( "*", outermost ), + + // Use integer dirruns iff this is the outermost matcher + dirrunsUnique = ( dirruns += contextBackup == null ? 1 : Math.random() || 0.1 ), + len = elems.length; + + if ( outermost ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + outermostContext = context == document || context || outermost; + } + + // Add elements passing elementMatchers directly to results + // Support: IE<9, Safari + // Tolerate NodeList properties (IE: "length"; Safari: ) matching elements by id + for ( ; i !== len && ( elem = elems[ i ] ) != null; i++ ) { + if ( byElement && elem ) { + j = 0; + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( !context && elem.ownerDocument != document ) { + setDocument( elem ); + xml = !documentIsHTML; + } + while ( ( matcher = elementMatchers[ j++ ] ) ) { + if ( matcher( elem, context || document, xml ) ) { + results.push( elem ); + break; + } + } + if ( outermost ) { + dirruns = dirrunsUnique; + } + } + + // Track unmatched elements for set filters + if ( bySet ) { + + // They will have gone through all possible matchers + if ( ( elem = !matcher && elem ) ) { + matchedCount--; + } + + // Lengthen the array for every element, matched or not + if ( seed ) { + unmatched.push( elem ); + } + } + } + + // `i` is now the count of elements visited above, and adding it to `matchedCount` + // makes the latter nonnegative. + matchedCount += i; + + // Apply set filters to unmatched elements + // NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount` + // equals `i`), unless we didn't visit _any_ elements in the above loop because we have + // no element matchers and no seed. + // Incrementing an initially-string "0" `i` allows `i` to remain a string only in that + // case, which will result in a "00" `matchedCount` that differs from `i` but is also + // numerically zero. + if ( bySet && i !== matchedCount ) { + j = 0; + while ( ( matcher = setMatchers[ j++ ] ) ) { + matcher( unmatched, setMatched, context, xml ); + } + + if ( seed ) { + + // Reintegrate element matches to eliminate the need for sorting + if ( matchedCount > 0 ) { + while ( i-- ) { + if ( !( unmatched[ i ] || setMatched[ i ] ) ) { + setMatched[ i ] = pop.call( results ); + } + } + } + + // Discard index placeholder values to get only actual matches + setMatched = condense( setMatched ); + } + + // Add matches to results + push.apply( results, setMatched ); + + // Seedless set matches succeeding multiple successful matchers stipulate sorting + if ( outermost && !seed && setMatched.length > 0 && + ( matchedCount + setMatchers.length ) > 1 ) { + + Sizzle.uniqueSort( results ); + } + } + + // Override manipulation of globals by nested matchers + if ( outermost ) { + dirruns = dirrunsUnique; + outermostContext = contextBackup; + } + + return unmatched; + }; + + return bySet ? + markFunction( superMatcher ) : + superMatcher; +} + +compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { + var i, + setMatchers = [], + elementMatchers = [], + cached = compilerCache[ selector + " " ]; + + if ( !cached ) { + + // Generate a function of recursive functions that can be used to check each element + if ( !match ) { + match = tokenize( selector ); + } + i = match.length; + while ( i-- ) { + cached = matcherFromTokens( match[ i ] ); + if ( cached[ expando ] ) { + setMatchers.push( cached ); + } else { + elementMatchers.push( cached ); + } + } + + // Cache the compiled function + cached = compilerCache( + selector, + matcherFromGroupMatchers( elementMatchers, setMatchers ) + ); + + // Save selector and tokenization + cached.selector = selector; + } + return cached; +}; + +/** + * A low-level selection function that works with Sizzle's compiled + * selector functions + * @param {String|Function} selector A selector or a pre-compiled + * selector function built with Sizzle.compile + * @param {Element} context + * @param {Array} [results] + * @param {Array} [seed] A set of elements to match against + */ +select = Sizzle.select = function( selector, context, results, seed ) { + var i, tokens, token, type, find, + compiled = typeof selector === "function" && selector, + match = !seed && tokenize( ( selector = compiled.selector || selector ) ); + + results = results || []; + + // Try to minimize operations if there is only one selector in the list and no seed + // (the latter of which guarantees us context) + if ( match.length === 1 ) { + + // Reduce context if the leading compound selector is an ID + tokens = match[ 0 ] = match[ 0 ].slice( 0 ); + if ( tokens.length > 2 && ( token = tokens[ 0 ] ).type === "ID" && + context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[ 1 ].type ] ) { + + context = ( Expr.find[ "ID" ]( token.matches[ 0 ] + .replace( runescape, funescape ), context ) || [] )[ 0 ]; + if ( !context ) { + return results; + + // Precompiled matchers will still verify ancestry, so step up a level + } else if ( compiled ) { + context = context.parentNode; + } + + selector = selector.slice( tokens.shift().value.length ); + } + + // Fetch a seed set for right-to-left matching + i = matchExpr[ "needsContext" ].test( selector ) ? 0 : tokens.length; + while ( i-- ) { + token = tokens[ i ]; + + // Abort if we hit a combinator + if ( Expr.relative[ ( type = token.type ) ] ) { + break; + } + if ( ( find = Expr.find[ type ] ) ) { + + // Search, expanding context for leading sibling combinators + if ( ( seed = find( + token.matches[ 0 ].replace( runescape, funescape ), + rsibling.test( tokens[ 0 ].type ) && testContext( context.parentNode ) || + context + ) ) ) { + + // If seed is empty or no tokens remain, we can return early + tokens.splice( i, 1 ); + selector = seed.length && toSelector( tokens ); + if ( !selector ) { + push.apply( results, seed ); + return results; + } + + break; + } + } + } + } + + // Compile and execute a filtering function if one is not provided + // Provide `match` to avoid retokenization if we modified the selector above + ( compiled || compile( selector, match ) )( + seed, + context, + !documentIsHTML, + results, + !context || rsibling.test( selector ) && testContext( context.parentNode ) || context + ); + return results; +}; + +// One-time assignments + +// Sort stability +support.sortStable = expando.split( "" ).sort( sortOrder ).join( "" ) === expando; + +// Support: Chrome 14-35+ +// Always assume duplicates if they aren't passed to the comparison function +support.detectDuplicates = !!hasDuplicate; + +// Initialize against the default document +setDocument(); + +// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27) +// Detached nodes confoundingly follow *each other* +support.sortDetached = assert( function( el ) { + + // Should return 1, but returns 4 (following) + return el.compareDocumentPosition( document.createElement( "fieldset" ) ) & 1; +} ); + +// Support: IE<8 +// Prevent attribute/property "interpolation" +// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx +if ( !assert( function( el ) { + el.innerHTML = ""; + return el.firstChild.getAttribute( "href" ) === "#"; +} ) ) { + addHandle( "type|href|height|width", function( elem, name, isXML ) { + if ( !isXML ) { + return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); + } + } ); +} + +// Support: IE<9 +// Use defaultValue in place of getAttribute("value") +if ( !support.attributes || !assert( function( el ) { + el.innerHTML = ""; + el.firstChild.setAttribute( "value", "" ); + return el.firstChild.getAttribute( "value" ) === ""; +} ) ) { + addHandle( "value", function( elem, _name, isXML ) { + if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { + return elem.defaultValue; + } + } ); +} + +// Support: IE<9 +// Use getAttributeNode to fetch booleans when getAttribute lies +if ( !assert( function( el ) { + return el.getAttribute( "disabled" ) == null; +} ) ) { + addHandle( booleans, function( elem, name, isXML ) { + var val; + if ( !isXML ) { + return elem[ name ] === true ? name.toLowerCase() : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; + } + } ); +} + +return Sizzle; + +} )( window ); + + + +jQuery.find = Sizzle; +jQuery.expr = Sizzle.selectors; + +// Deprecated +jQuery.expr[ ":" ] = jQuery.expr.pseudos; +jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort; +jQuery.text = Sizzle.getText; +jQuery.isXMLDoc = Sizzle.isXML; +jQuery.contains = Sizzle.contains; +jQuery.escapeSelector = Sizzle.escape; + + + + +var dir = function( elem, dir, until ) { + var matched = [], + truncate = until !== undefined; + + while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) { + if ( elem.nodeType === 1 ) { + if ( truncate && jQuery( elem ).is( until ) ) { + break; + } + matched.push( elem ); + } + } + return matched; +}; + + +var siblings = function( n, elem ) { + var matched = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType === 1 && n !== elem ) { + matched.push( n ); + } + } + + return matched; +}; + + +var rneedsContext = jQuery.expr.match.needsContext; + + + +function nodeName( elem, name ) { + + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + +} +var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i ); + + + +// Implement the identical functionality for filter and not +function winnow( elements, qualifier, not ) { + if ( isFunction( qualifier ) ) { + return jQuery.grep( elements, function( elem, i ) { + return !!qualifier.call( elem, i, elem ) !== not; + } ); + } + + // Single element + if ( qualifier.nodeType ) { + return jQuery.grep( elements, function( elem ) { + return ( elem === qualifier ) !== not; + } ); + } + + // Arraylike of elements (jQuery, arguments, Array) + if ( typeof qualifier !== "string" ) { + return jQuery.grep( elements, function( elem ) { + return ( indexOf.call( qualifier, elem ) > -1 ) !== not; + } ); + } + + // Filtered directly for both simple and complex selectors + return jQuery.filter( qualifier, elements, not ); +} + +jQuery.filter = function( expr, elems, not ) { + var elem = elems[ 0 ]; + + if ( not ) { + expr = ":not(" + expr + ")"; + } + + if ( elems.length === 1 && elem.nodeType === 1 ) { + return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : []; + } + + return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) { + return elem.nodeType === 1; + } ) ); +}; + +jQuery.fn.extend( { + find: function( selector ) { + var i, ret, + len = this.length, + self = this; + + if ( typeof selector !== "string" ) { + return this.pushStack( jQuery( selector ).filter( function() { + for ( i = 0; i < len; i++ ) { + if ( jQuery.contains( self[ i ], this ) ) { + return true; + } + } + } ) ); + } + + ret = this.pushStack( [] ); + + for ( i = 0; i < len; i++ ) { + jQuery.find( selector, self[ i ], ret ); + } + + return len > 1 ? jQuery.uniqueSort( ret ) : ret; + }, + filter: function( selector ) { + return this.pushStack( winnow( this, selector || [], false ) ); + }, + not: function( selector ) { + return this.pushStack( winnow( this, selector || [], true ) ); + }, + is: function( selector ) { + return !!winnow( + this, + + // If this is a positional/relative selector, check membership in the returned set + // so $("p:first").is("p:last") won't return true for a doc with two "p". + typeof selector === "string" && rneedsContext.test( selector ) ? + jQuery( selector ) : + selector || [], + false + ).length; + } +} ); + + +// Initialize a jQuery object + + +// A central reference to the root jQuery(document) +var rootjQuery, + + // A simple way to check for HTML strings + // Prioritize #id over to avoid XSS via location.hash (#9521) + // Strict HTML recognition (#11290: must start with <) + // Shortcut simple #id case for speed + rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/, + + init = jQuery.fn.init = function( selector, context, root ) { + var match, elem; + + // HANDLE: $(""), $(null), $(undefined), $(false) + if ( !selector ) { + return this; + } + + // Method init() accepts an alternate rootjQuery + // so migrate can support jQuery.sub (gh-2101) + root = root || rootjQuery; + + // Handle HTML strings + if ( typeof selector === "string" ) { + if ( selector[ 0 ] === "<" && + selector[ selector.length - 1 ] === ">" && + selector.length >= 3 ) { + + // Assume that strings that start and end with <> are HTML and skip the regex check + match = [ null, selector, null ]; + + } else { + match = rquickExpr.exec( selector ); + } + + // Match html or make sure no context is specified for #id + if ( match && ( match[ 1 ] || !context ) ) { + + // HANDLE: $(html) -> $(array) + if ( match[ 1 ] ) { + context = context instanceof jQuery ? context[ 0 ] : context; + + // Option to run scripts is true for back-compat + // Intentionally let the error be thrown if parseHTML is not present + jQuery.merge( this, jQuery.parseHTML( + match[ 1 ], + context && context.nodeType ? context.ownerDocument || context : document, + true + ) ); + + // HANDLE: $(html, props) + if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) { + for ( match in context ) { + + // Properties of context are called as methods if possible + if ( isFunction( this[ match ] ) ) { + this[ match ]( context[ match ] ); + + // ...and otherwise set as attributes + } else { + this.attr( match, context[ match ] ); + } + } + } + + return this; + + // HANDLE: $(#id) + } else { + elem = document.getElementById( match[ 2 ] ); + + if ( elem ) { + + // Inject the element directly into the jQuery object + this[ 0 ] = elem; + this.length = 1; + } + return this; + } + + // HANDLE: $(expr, $(...)) + } else if ( !context || context.jquery ) { + return ( context || root ).find( selector ); + + // HANDLE: $(expr, context) + // (which is just equivalent to: $(context).find(expr) + } else { + return this.constructor( context ).find( selector ); + } + + // HANDLE: $(DOMElement) + } else if ( selector.nodeType ) { + this[ 0 ] = selector; + this.length = 1; + return this; + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( isFunction( selector ) ) { + return root.ready !== undefined ? + root.ready( selector ) : + + // Execute immediately if ready is not present + selector( jQuery ); + } + + return jQuery.makeArray( selector, this ); + }; + +// Give the init function the jQuery prototype for later instantiation +init.prototype = jQuery.fn; + +// Initialize central reference +rootjQuery = jQuery( document ); + + +var rparentsprev = /^(?:parents|prev(?:Until|All))/, + + // Methods guaranteed to produce a unique set when starting from a unique set + guaranteedUnique = { + children: true, + contents: true, + next: true, + prev: true + }; + +jQuery.fn.extend( { + has: function( target ) { + var targets = jQuery( target, this ), + l = targets.length; + + return this.filter( function() { + var i = 0; + for ( ; i < l; i++ ) { + if ( jQuery.contains( this, targets[ i ] ) ) { + return true; + } + } + } ); + }, + + closest: function( selectors, context ) { + var cur, + i = 0, + l = this.length, + matched = [], + targets = typeof selectors !== "string" && jQuery( selectors ); + + // Positional selectors never match, since there's no _selection_ context + if ( !rneedsContext.test( selectors ) ) { + for ( ; i < l; i++ ) { + for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) { + + // Always skip document fragments + if ( cur.nodeType < 11 && ( targets ? + targets.index( cur ) > -1 : + + // Don't pass non-elements to Sizzle + cur.nodeType === 1 && + jQuery.find.matchesSelector( cur, selectors ) ) ) { + + matched.push( cur ); + break; + } + } + } + } + + return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched ); + }, + + // Determine the position of an element within the set + index: function( elem ) { + + // No argument, return index in parent + if ( !elem ) { + return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; + } + + // Index in selector + if ( typeof elem === "string" ) { + return indexOf.call( jQuery( elem ), this[ 0 ] ); + } + + // Locate the position of the desired element + return indexOf.call( this, + + // If it receives a jQuery object, the first element is used + elem.jquery ? elem[ 0 ] : elem + ); + }, + + add: function( selector, context ) { + return this.pushStack( + jQuery.uniqueSort( + jQuery.merge( this.get(), jQuery( selector, context ) ) + ) + ); + }, + + addBack: function( selector ) { + return this.add( selector == null ? + this.prevObject : this.prevObject.filter( selector ) + ); + } +} ); + +function sibling( cur, dir ) { + while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {} + return cur; +} + +jQuery.each( { + parent: function( elem ) { + var parent = elem.parentNode; + return parent && parent.nodeType !== 11 ? parent : null; + }, + parents: function( elem ) { + return dir( elem, "parentNode" ); + }, + parentsUntil: function( elem, _i, until ) { + return dir( elem, "parentNode", until ); + }, + next: function( elem ) { + return sibling( elem, "nextSibling" ); + }, + prev: function( elem ) { + return sibling( elem, "previousSibling" ); + }, + nextAll: function( elem ) { + return dir( elem, "nextSibling" ); + }, + prevAll: function( elem ) { + return dir( elem, "previousSibling" ); + }, + nextUntil: function( elem, _i, until ) { + return dir( elem, "nextSibling", until ); + }, + prevUntil: function( elem, _i, until ) { + return dir( elem, "previousSibling", until ); + }, + siblings: function( elem ) { + return siblings( ( elem.parentNode || {} ).firstChild, elem ); + }, + children: function( elem ) { + return siblings( elem.firstChild ); + }, + contents: function( elem ) { + if ( elem.contentDocument != null && + + // Support: IE 11+ + // elements with no `data` attribute has an object + // `contentDocument` with a `null` prototype. + getProto( elem.contentDocument ) ) { + + return elem.contentDocument; + } + + // Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only + // Treat the template element as a regular one in browsers that + // don't support it. + if ( nodeName( elem, "template" ) ) { + elem = elem.content || elem; + } + + return jQuery.merge( [], elem.childNodes ); + } +}, function( name, fn ) { + jQuery.fn[ name ] = function( until, selector ) { + var matched = jQuery.map( this, fn, until ); + + if ( name.slice( -5 ) !== "Until" ) { + selector = until; + } + + if ( selector && typeof selector === "string" ) { + matched = jQuery.filter( selector, matched ); + } + + if ( this.length > 1 ) { + + // Remove duplicates + if ( !guaranteedUnique[ name ] ) { + jQuery.uniqueSort( matched ); + } + + // Reverse order for parents* and prev-derivatives + if ( rparentsprev.test( name ) ) { + matched.reverse(); + } + } + + return this.pushStack( matched ); + }; +} ); +var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g ); + + + +// Convert String-formatted options into Object-formatted ones +function createOptions( options ) { + var object = {}; + jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) { + object[ flag ] = true; + } ); + return object; +} + +/* + * Create a callback list using the following parameters: + * + * options: an optional list of space-separated options that will change how + * the callback list behaves or a more traditional option object + * + * By default a callback list will act like an event callback list and can be + * "fired" multiple times. + * + * Possible options: + * + * once: will ensure the callback list can only be fired once (like a Deferred) + * + * memory: will keep track of previous values and will call any callback added + * after the list has been fired right away with the latest "memorized" + * values (like a Deferred) + * + * unique: will ensure a callback can only be added once (no duplicate in the list) + * + * stopOnFalse: interrupt callings when a callback returns false + * + */ +jQuery.Callbacks = function( options ) { + + // Convert options from String-formatted to Object-formatted if needed + // (we check in cache first) + options = typeof options === "string" ? + createOptions( options ) : + jQuery.extend( {}, options ); + + var // Flag to know if list is currently firing + firing, + + // Last fire value for non-forgettable lists + memory, + + // Flag to know if list was already fired + fired, + + // Flag to prevent firing + locked, + + // Actual callback list + list = [], + + // Queue of execution data for repeatable lists + queue = [], + + // Index of currently firing callback (modified by add/remove as needed) + firingIndex = -1, + + // Fire callbacks + fire = function() { + + // Enforce single-firing + locked = locked || options.once; + + // Execute callbacks for all pending executions, + // respecting firingIndex overrides and runtime changes + fired = firing = true; + for ( ; queue.length; firingIndex = -1 ) { + memory = queue.shift(); + while ( ++firingIndex < list.length ) { + + // Run callback and check for early termination + if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false && + options.stopOnFalse ) { + + // Jump to end and forget the data so .add doesn't re-fire + firingIndex = list.length; + memory = false; + } + } + } + + // Forget the data if we're done with it + if ( !options.memory ) { + memory = false; + } + + firing = false; + + // Clean up if we're done firing for good + if ( locked ) { + + // Keep an empty list if we have data for future add calls + if ( memory ) { + list = []; + + // Otherwise, this object is spent + } else { + list = ""; + } + } + }, + + // Actual Callbacks object + self = { + + // Add a callback or a collection of callbacks to the list + add: function() { + if ( list ) { + + // If we have memory from a past run, we should fire after adding + if ( memory && !firing ) { + firingIndex = list.length - 1; + queue.push( memory ); + } + + ( function add( args ) { + jQuery.each( args, function( _, arg ) { + if ( isFunction( arg ) ) { + if ( !options.unique || !self.has( arg ) ) { + list.push( arg ); + } + } else if ( arg && arg.length && toType( arg ) !== "string" ) { + + // Inspect recursively + add( arg ); + } + } ); + } )( arguments ); + + if ( memory && !firing ) { + fire(); + } + } + return this; + }, + + // Remove a callback from the list + remove: function() { + jQuery.each( arguments, function( _, arg ) { + var index; + while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) { + list.splice( index, 1 ); + + // Handle firing indexes + if ( index <= firingIndex ) { + firingIndex--; + } + } + } ); + return this; + }, + + // Check if a given callback is in the list. + // If no argument is given, return whether or not list has callbacks attached. + has: function( fn ) { + return fn ? + jQuery.inArray( fn, list ) > -1 : + list.length > 0; + }, + + // Remove all callbacks from the list + empty: function() { + if ( list ) { + list = []; + } + return this; + }, + + // Disable .fire and .add + // Abort any current/pending executions + // Clear all callbacks and values + disable: function() { + locked = queue = []; + list = memory = ""; + return this; + }, + disabled: function() { + return !list; + }, + + // Disable .fire + // Also disable .add unless we have memory (since it would have no effect) + // Abort any pending executions + lock: function() { + locked = queue = []; + if ( !memory && !firing ) { + list = memory = ""; + } + return this; + }, + locked: function() { + return !!locked; + }, + + // Call all callbacks with the given context and arguments + fireWith: function( context, args ) { + if ( !locked ) { + args = args || []; + args = [ context, args.slice ? args.slice() : args ]; + queue.push( args ); + if ( !firing ) { + fire(); + } + } + return this; + }, + + // Call all the callbacks with the given arguments + fire: function() { + self.fireWith( this, arguments ); + return this; + }, + + // To know if the callbacks have already been called at least once + fired: function() { + return !!fired; + } + }; + + return self; +}; + + +function Identity( v ) { + return v; +} +function Thrower( ex ) { + throw ex; +} + +function adoptValue( value, resolve, reject, noValue ) { + var method; + + try { + + // Check for promise aspect first to privilege synchronous behavior + if ( value && isFunction( ( method = value.promise ) ) ) { + method.call( value ).done( resolve ).fail( reject ); + + // Other thenables + } else if ( value && isFunction( ( method = value.then ) ) ) { + method.call( value, resolve, reject ); + + // Other non-thenables + } else { + + // Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer: + // * false: [ value ].slice( 0 ) => resolve( value ) + // * true: [ value ].slice( 1 ) => resolve() + resolve.apply( undefined, [ value ].slice( noValue ) ); + } + + // For Promises/A+, convert exceptions into rejections + // Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in + // Deferred#then to conditionally suppress rejection. + } catch ( value ) { + + // Support: Android 4.0 only + // Strict mode functions invoked without .call/.apply get global-object context + reject.apply( undefined, [ value ] ); + } +} + +jQuery.extend( { + + Deferred: function( func ) { + var tuples = [ + + // action, add listener, callbacks, + // ... .then handlers, argument index, [final state] + [ "notify", "progress", jQuery.Callbacks( "memory" ), + jQuery.Callbacks( "memory" ), 2 ], + [ "resolve", "done", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 0, "resolved" ], + [ "reject", "fail", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 1, "rejected" ] + ], + state = "pending", + promise = { + state: function() { + return state; + }, + always: function() { + deferred.done( arguments ).fail( arguments ); + return this; + }, + "catch": function( fn ) { + return promise.then( null, fn ); + }, + + // Keep pipe for back-compat + pipe: function( /* fnDone, fnFail, fnProgress */ ) { + var fns = arguments; + + return jQuery.Deferred( function( newDefer ) { + jQuery.each( tuples, function( _i, tuple ) { + + // Map tuples (progress, done, fail) to arguments (done, fail, progress) + var fn = isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ]; + + // deferred.progress(function() { bind to newDefer or newDefer.notify }) + // deferred.done(function() { bind to newDefer or newDefer.resolve }) + // deferred.fail(function() { bind to newDefer or newDefer.reject }) + deferred[ tuple[ 1 ] ]( function() { + var returned = fn && fn.apply( this, arguments ); + if ( returned && isFunction( returned.promise ) ) { + returned.promise() + .progress( newDefer.notify ) + .done( newDefer.resolve ) + .fail( newDefer.reject ); + } else { + newDefer[ tuple[ 0 ] + "With" ]( + this, + fn ? [ returned ] : arguments + ); + } + } ); + } ); + fns = null; + } ).promise(); + }, + then: function( onFulfilled, onRejected, onProgress ) { + var maxDepth = 0; + function resolve( depth, deferred, handler, special ) { + return function() { + var that = this, + args = arguments, + mightThrow = function() { + var returned, then; + + // Support: Promises/A+ section 2.3.3.3.3 + // https://promisesaplus.com/#point-59 + // Ignore double-resolution attempts + if ( depth < maxDepth ) { + return; + } + + returned = handler.apply( that, args ); + + // Support: Promises/A+ section 2.3.1 + // https://promisesaplus.com/#point-48 + if ( returned === deferred.promise() ) { + throw new TypeError( "Thenable self-resolution" ); + } + + // Support: Promises/A+ sections 2.3.3.1, 3.5 + // https://promisesaplus.com/#point-54 + // https://promisesaplus.com/#point-75 + // Retrieve `then` only once + then = returned && + + // Support: Promises/A+ section 2.3.4 + // https://promisesaplus.com/#point-64 + // Only check objects and functions for thenability + ( typeof returned === "object" || + typeof returned === "function" ) && + returned.then; + + // Handle a returned thenable + if ( isFunction( then ) ) { + + // Special processors (notify) just wait for resolution + if ( special ) { + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ) + ); + + // Normal processors (resolve) also hook into progress + } else { + + // ...and disregard older resolution values + maxDepth++; + + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ), + resolve( maxDepth, deferred, Identity, + deferred.notifyWith ) + ); + } + + // Handle all other returned values + } else { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Identity ) { + that = undefined; + args = [ returned ]; + } + + // Process the value(s) + // Default process is resolve + ( special || deferred.resolveWith )( that, args ); + } + }, + + // Only normal processors (resolve) catch and reject exceptions + process = special ? + mightThrow : + function() { + try { + mightThrow(); + } catch ( e ) { + + if ( jQuery.Deferred.exceptionHook ) { + jQuery.Deferred.exceptionHook( e, + process.stackTrace ); + } + + // Support: Promises/A+ section 2.3.3.3.4.1 + // https://promisesaplus.com/#point-61 + // Ignore post-resolution exceptions + if ( depth + 1 >= maxDepth ) { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Thrower ) { + that = undefined; + args = [ e ]; + } + + deferred.rejectWith( that, args ); + } + } + }; + + // Support: Promises/A+ section 2.3.3.3.1 + // https://promisesaplus.com/#point-57 + // Re-resolve promises immediately to dodge false rejection from + // subsequent errors + if ( depth ) { + process(); + } else { + + // Call an optional hook to record the stack, in case of exception + // since it's otherwise lost when execution goes async + if ( jQuery.Deferred.getStackHook ) { + process.stackTrace = jQuery.Deferred.getStackHook(); + } + window.setTimeout( process ); + } + }; + } + + return jQuery.Deferred( function( newDefer ) { + + // progress_handlers.add( ... ) + tuples[ 0 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onProgress ) ? + onProgress : + Identity, + newDefer.notifyWith + ) + ); + + // fulfilled_handlers.add( ... ) + tuples[ 1 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onFulfilled ) ? + onFulfilled : + Identity + ) + ); + + // rejected_handlers.add( ... ) + tuples[ 2 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onRejected ) ? + onRejected : + Thrower + ) + ); + } ).promise(); + }, + + // Get a promise for this deferred + // If obj is provided, the promise aspect is added to the object + promise: function( obj ) { + return obj != null ? jQuery.extend( obj, promise ) : promise; + } + }, + deferred = {}; + + // Add list-specific methods + jQuery.each( tuples, function( i, tuple ) { + var list = tuple[ 2 ], + stateString = tuple[ 5 ]; + + // promise.progress = list.add + // promise.done = list.add + // promise.fail = list.add + promise[ tuple[ 1 ] ] = list.add; + + // Handle state + if ( stateString ) { + list.add( + function() { + + // state = "resolved" (i.e., fulfilled) + // state = "rejected" + state = stateString; + }, + + // rejected_callbacks.disable + // fulfilled_callbacks.disable + tuples[ 3 - i ][ 2 ].disable, + + // rejected_handlers.disable + // fulfilled_handlers.disable + tuples[ 3 - i ][ 3 ].disable, + + // progress_callbacks.lock + tuples[ 0 ][ 2 ].lock, + + // progress_handlers.lock + tuples[ 0 ][ 3 ].lock + ); + } + + // progress_handlers.fire + // fulfilled_handlers.fire + // rejected_handlers.fire + list.add( tuple[ 3 ].fire ); + + // deferred.notify = function() { deferred.notifyWith(...) } + // deferred.resolve = function() { deferred.resolveWith(...) } + // deferred.reject = function() { deferred.rejectWith(...) } + deferred[ tuple[ 0 ] ] = function() { + deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments ); + return this; + }; + + // deferred.notifyWith = list.fireWith + // deferred.resolveWith = list.fireWith + // deferred.rejectWith = list.fireWith + deferred[ tuple[ 0 ] + "With" ] = list.fireWith; + } ); + + // Make the deferred a promise + promise.promise( deferred ); + + // Call given func if any + if ( func ) { + func.call( deferred, deferred ); + } + + // All done! + return deferred; + }, + + // Deferred helper + when: function( singleValue ) { + var + + // count of uncompleted subordinates + remaining = arguments.length, + + // count of unprocessed arguments + i = remaining, + + // subordinate fulfillment data + resolveContexts = Array( i ), + resolveValues = slice.call( arguments ), + + // the primary Deferred + primary = jQuery.Deferred(), + + // subordinate callback factory + updateFunc = function( i ) { + return function( value ) { + resolveContexts[ i ] = this; + resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value; + if ( !( --remaining ) ) { + primary.resolveWith( resolveContexts, resolveValues ); + } + }; + }; + + // Single- and empty arguments are adopted like Promise.resolve + if ( remaining <= 1 ) { + adoptValue( singleValue, primary.done( updateFunc( i ) ).resolve, primary.reject, + !remaining ); + + // Use .then() to unwrap secondary thenables (cf. gh-3000) + if ( primary.state() === "pending" || + isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) { + + return primary.then(); + } + } + + // Multiple arguments are aggregated like Promise.all array elements + while ( i-- ) { + adoptValue( resolveValues[ i ], updateFunc( i ), primary.reject ); + } + + return primary.promise(); + } +} ); + + +// These usually indicate a programmer mistake during development, +// warn about them ASAP rather than swallowing them by default. +var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/; + +jQuery.Deferred.exceptionHook = function( error, stack ) { + + // Support: IE 8 - 9 only + // Console exists when dev tools are open, which can happen at any time + if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) { + window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack ); + } +}; + + + + +jQuery.readyException = function( error ) { + window.setTimeout( function() { + throw error; + } ); +}; + + + + +// The deferred used on DOM ready +var readyList = jQuery.Deferred(); + +jQuery.fn.ready = function( fn ) { + + readyList + .then( fn ) + + // Wrap jQuery.readyException in a function so that the lookup + // happens at the time of error handling instead of callback + // registration. + .catch( function( error ) { + jQuery.readyException( error ); + } ); + + return this; +}; + +jQuery.extend( { + + // Is the DOM ready to be used? Set to true once it occurs. + isReady: false, + + // A counter to track how many items to wait for before + // the ready event fires. See #6781 + readyWait: 1, + + // Handle when the DOM is ready + ready: function( wait ) { + + // Abort if there are pending holds or we're already ready + if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) { + return; + } + + // Remember that the DOM is ready + jQuery.isReady = true; + + // If a normal DOM Ready event fired, decrement, and wait if need be + if ( wait !== true && --jQuery.readyWait > 0 ) { + return; + } + + // If there are functions bound, to execute + readyList.resolveWith( document, [ jQuery ] ); + } +} ); + +jQuery.ready.then = readyList.then; + +// The ready event handler and self cleanup method +function completed() { + document.removeEventListener( "DOMContentLoaded", completed ); + window.removeEventListener( "load", completed ); + jQuery.ready(); +} + +// Catch cases where $(document).ready() is called +// after the browser event has already occurred. +// Support: IE <=9 - 10 only +// Older IE sometimes signals "interactive" too soon +if ( document.readyState === "complete" || + ( document.readyState !== "loading" && !document.documentElement.doScroll ) ) { + + // Handle it asynchronously to allow scripts the opportunity to delay ready + window.setTimeout( jQuery.ready ); + +} else { + + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", completed ); + + // A fallback to window.onload, that will always work + window.addEventListener( "load", completed ); +} + + + + +// Multifunctional method to get and set values of a collection +// The value/s can optionally be executed if it's a function +var access = function( elems, fn, key, value, chainable, emptyGet, raw ) { + var i = 0, + len = elems.length, + bulk = key == null; + + // Sets many values + if ( toType( key ) === "object" ) { + chainable = true; + for ( i in key ) { + access( elems, fn, i, key[ i ], true, emptyGet, raw ); + } + + // Sets one value + } else if ( value !== undefined ) { + chainable = true; + + if ( !isFunction( value ) ) { + raw = true; + } + + if ( bulk ) { + + // Bulk operations run against the entire set + if ( raw ) { + fn.call( elems, value ); + fn = null; + + // ...except when executing function values + } else { + bulk = fn; + fn = function( elem, _key, value ) { + return bulk.call( jQuery( elem ), value ); + }; + } + } + + if ( fn ) { + for ( ; i < len; i++ ) { + fn( + elems[ i ], key, raw ? + value : + value.call( elems[ i ], i, fn( elems[ i ], key ) ) + ); + } + } + } + + if ( chainable ) { + return elems; + } + + // Gets + if ( bulk ) { + return fn.call( elems ); + } + + return len ? fn( elems[ 0 ], key ) : emptyGet; +}; + + +// Matches dashed string for camelizing +var rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g; + +// Used by camelCase as callback to replace() +function fcamelCase( _all, letter ) { + return letter.toUpperCase(); +} + +// Convert dashed to camelCase; used by the css and data modules +// Support: IE <=9 - 11, Edge 12 - 15 +// Microsoft forgot to hump their vendor prefix (#9572) +function camelCase( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); +} +var acceptData = function( owner ) { + + // Accepts only: + // - Node + // - Node.ELEMENT_NODE + // - Node.DOCUMENT_NODE + // - Object + // - Any + return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType ); +}; + + + + +function Data() { + this.expando = jQuery.expando + Data.uid++; +} + +Data.uid = 1; + +Data.prototype = { + + cache: function( owner ) { + + // Check if the owner object already has a cache + var value = owner[ this.expando ]; + + // If not, create one + if ( !value ) { + value = {}; + + // We can accept data for non-element nodes in modern browsers, + // but we should not, see #8335. + // Always return an empty object. + if ( acceptData( owner ) ) { + + // If it is a node unlikely to be stringify-ed or looped over + // use plain assignment + if ( owner.nodeType ) { + owner[ this.expando ] = value; + + // Otherwise secure it in a non-enumerable property + // configurable must be true to allow the property to be + // deleted when data is removed + } else { + Object.defineProperty( owner, this.expando, { + value: value, + configurable: true + } ); + } + } + } + + return value; + }, + set: function( owner, data, value ) { + var prop, + cache = this.cache( owner ); + + // Handle: [ owner, key, value ] args + // Always use camelCase key (gh-2257) + if ( typeof data === "string" ) { + cache[ camelCase( data ) ] = value; + + // Handle: [ owner, { properties } ] args + } else { + + // Copy the properties one-by-one to the cache object + for ( prop in data ) { + cache[ camelCase( prop ) ] = data[ prop ]; + } + } + return cache; + }, + get: function( owner, key ) { + return key === undefined ? + this.cache( owner ) : + + // Always use camelCase key (gh-2257) + owner[ this.expando ] && owner[ this.expando ][ camelCase( key ) ]; + }, + access: function( owner, key, value ) { + + // In cases where either: + // + // 1. No key was specified + // 2. A string key was specified, but no value provided + // + // Take the "read" path and allow the get method to determine + // which value to return, respectively either: + // + // 1. The entire cache object + // 2. The data stored at the key + // + if ( key === undefined || + ( ( key && typeof key === "string" ) && value === undefined ) ) { + + return this.get( owner, key ); + } + + // When the key is not a string, or both a key and value + // are specified, set or extend (existing objects) with either: + // + // 1. An object of properties + // 2. A key and value + // + this.set( owner, key, value ); + + // Since the "set" path can have two possible entry points + // return the expected data based on which path was taken[*] + return value !== undefined ? value : key; + }, + remove: function( owner, key ) { + var i, + cache = owner[ this.expando ]; + + if ( cache === undefined ) { + return; + } + + if ( key !== undefined ) { + + // Support array or space separated string of keys + if ( Array.isArray( key ) ) { + + // If key is an array of keys... + // We always set camelCase keys, so remove that. + key = key.map( camelCase ); + } else { + key = camelCase( key ); + + // If a key with the spaces exists, use it. + // Otherwise, create an array by matching non-whitespace + key = key in cache ? + [ key ] : + ( key.match( rnothtmlwhite ) || [] ); + } + + i = key.length; + + while ( i-- ) { + delete cache[ key[ i ] ]; + } + } + + // Remove the expando if there's no more data + if ( key === undefined || jQuery.isEmptyObject( cache ) ) { + + // Support: Chrome <=35 - 45 + // Webkit & Blink performance suffers when deleting properties + // from DOM nodes, so set to undefined instead + // https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted) + if ( owner.nodeType ) { + owner[ this.expando ] = undefined; + } else { + delete owner[ this.expando ]; + } + } + }, + hasData: function( owner ) { + var cache = owner[ this.expando ]; + return cache !== undefined && !jQuery.isEmptyObject( cache ); + } +}; +var dataPriv = new Data(); + +var dataUser = new Data(); + + + +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + +var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, + rmultiDash = /[A-Z]/g; + +function getData( data ) { + if ( data === "true" ) { + return true; + } + + if ( data === "false" ) { + return false; + } + + if ( data === "null" ) { + return null; + } + + // Only convert to a number if it doesn't change the string + if ( data === +data + "" ) { + return +data; + } + + if ( rbrace.test( data ) ) { + return JSON.parse( data ); + } + + return data; +} + +function dataAttr( elem, key, data ) { + var name; + + // If nothing was found internally, try to fetch any + // data from the HTML5 data-* attribute + if ( data === undefined && elem.nodeType === 1 ) { + name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase(); + data = elem.getAttribute( name ); + + if ( typeof data === "string" ) { + try { + data = getData( data ); + } catch ( e ) {} + + // Make sure we set the data so it isn't changed later + dataUser.set( elem, key, data ); + } else { + data = undefined; + } + } + return data; +} + +jQuery.extend( { + hasData: function( elem ) { + return dataUser.hasData( elem ) || dataPriv.hasData( elem ); + }, + + data: function( elem, name, data ) { + return dataUser.access( elem, name, data ); + }, + + removeData: function( elem, name ) { + dataUser.remove( elem, name ); + }, + + // TODO: Now that all calls to _data and _removeData have been replaced + // with direct calls to dataPriv methods, these can be deprecated. + _data: function( elem, name, data ) { + return dataPriv.access( elem, name, data ); + }, + + _removeData: function( elem, name ) { + dataPriv.remove( elem, name ); + } +} ); + +jQuery.fn.extend( { + data: function( key, value ) { + var i, name, data, + elem = this[ 0 ], + attrs = elem && elem.attributes; + + // Gets all values + if ( key === undefined ) { + if ( this.length ) { + data = dataUser.get( elem ); + + if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) { + i = attrs.length; + while ( i-- ) { + + // Support: IE 11 only + // The attrs elements can be null (#14894) + if ( attrs[ i ] ) { + name = attrs[ i ].name; + if ( name.indexOf( "data-" ) === 0 ) { + name = camelCase( name.slice( 5 ) ); + dataAttr( elem, name, data[ name ] ); + } + } + } + dataPriv.set( elem, "hasDataAttrs", true ); + } + } + + return data; + } + + // Sets multiple values + if ( typeof key === "object" ) { + return this.each( function() { + dataUser.set( this, key ); + } ); + } + + return access( this, function( value ) { + var data; + + // The calling jQuery object (element matches) is not empty + // (and therefore has an element appears at this[ 0 ]) and the + // `value` parameter was not undefined. An empty jQuery object + // will result in `undefined` for elem = this[ 0 ] which will + // throw an exception if an attempt to read a data cache is made. + if ( elem && value === undefined ) { + + // Attempt to get data from the cache + // The key will always be camelCased in Data + data = dataUser.get( elem, key ); + if ( data !== undefined ) { + return data; + } + + // Attempt to "discover" the data in + // HTML5 custom data-* attrs + data = dataAttr( elem, key ); + if ( data !== undefined ) { + return data; + } + + // We tried really hard, but the data doesn't exist. + return; + } + + // Set the data... + this.each( function() { + + // We always store the camelCased key + dataUser.set( this, key, value ); + } ); + }, null, value, arguments.length > 1, null, true ); + }, + + removeData: function( key ) { + return this.each( function() { + dataUser.remove( this, key ); + } ); + } +} ); + + +jQuery.extend( { + queue: function( elem, type, data ) { + var queue; + + if ( elem ) { + type = ( type || "fx" ) + "queue"; + queue = dataPriv.get( elem, type ); + + // Speed up dequeue by getting out quickly if this is just a lookup + if ( data ) { + if ( !queue || Array.isArray( data ) ) { + queue = dataPriv.access( elem, type, jQuery.makeArray( data ) ); + } else { + queue.push( data ); + } + } + return queue || []; + } + }, + + dequeue: function( elem, type ) { + type = type || "fx"; + + var queue = jQuery.queue( elem, type ), + startLength = queue.length, + fn = queue.shift(), + hooks = jQuery._queueHooks( elem, type ), + next = function() { + jQuery.dequeue( elem, type ); + }; + + // If the fx queue is dequeued, always remove the progress sentinel + if ( fn === "inprogress" ) { + fn = queue.shift(); + startLength--; + } + + if ( fn ) { + + // Add a progress sentinel to prevent the fx queue from being + // automatically dequeued + if ( type === "fx" ) { + queue.unshift( "inprogress" ); + } + + // Clear up the last queue stop function + delete hooks.stop; + fn.call( elem, next, hooks ); + } + + if ( !startLength && hooks ) { + hooks.empty.fire(); + } + }, + + // Not public - generate a queueHooks object, or return the current one + _queueHooks: function( elem, type ) { + var key = type + "queueHooks"; + return dataPriv.get( elem, key ) || dataPriv.access( elem, key, { + empty: jQuery.Callbacks( "once memory" ).add( function() { + dataPriv.remove( elem, [ type + "queue", key ] ); + } ) + } ); + } +} ); + +jQuery.fn.extend( { + queue: function( type, data ) { + var setter = 2; + + if ( typeof type !== "string" ) { + data = type; + type = "fx"; + setter--; + } + + if ( arguments.length < setter ) { + return jQuery.queue( this[ 0 ], type ); + } + + return data === undefined ? + this : + this.each( function() { + var queue = jQuery.queue( this, type, data ); + + // Ensure a hooks for this queue + jQuery._queueHooks( this, type ); + + if ( type === "fx" && queue[ 0 ] !== "inprogress" ) { + jQuery.dequeue( this, type ); + } + } ); + }, + dequeue: function( type ) { + return this.each( function() { + jQuery.dequeue( this, type ); + } ); + }, + clearQueue: function( type ) { + return this.queue( type || "fx", [] ); + }, + + // Get a promise resolved when queues of a certain type + // are emptied (fx is the type by default) + promise: function( type, obj ) { + var tmp, + count = 1, + defer = jQuery.Deferred(), + elements = this, + i = this.length, + resolve = function() { + if ( !( --count ) ) { + defer.resolveWith( elements, [ elements ] ); + } + }; + + if ( typeof type !== "string" ) { + obj = type; + type = undefined; + } + type = type || "fx"; + + while ( i-- ) { + tmp = dataPriv.get( elements[ i ], type + "queueHooks" ); + if ( tmp && tmp.empty ) { + count++; + tmp.empty.add( resolve ); + } + } + resolve(); + return defer.promise( obj ); + } +} ); +var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source; + +var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" ); + + +var cssExpand = [ "Top", "Right", "Bottom", "Left" ]; + +var documentElement = document.documentElement; + + + + var isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ); + }, + composed = { composed: true }; + + // Support: IE 9 - 11+, Edge 12 - 18+, iOS 10.0 - 10.2 only + // Check attachment across shadow DOM boundaries when possible (gh-3504) + // Support: iOS 10.0-10.2 only + // Early iOS 10 versions support `attachShadow` but not `getRootNode`, + // leading to errors. We need to check for `getRootNode`. + if ( documentElement.getRootNode ) { + isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ) || + elem.getRootNode( composed ) === elem.ownerDocument; + }; + } +var isHiddenWithinTree = function( elem, el ) { + + // isHiddenWithinTree might be called from jQuery#filter function; + // in that case, element will be second argument + elem = el || elem; + + // Inline style trumps all + return elem.style.display === "none" || + elem.style.display === "" && + + // Otherwise, check computed style + // Support: Firefox <=43 - 45 + // Disconnected elements can have computed display: none, so first confirm that elem is + // in the document. + isAttached( elem ) && + + jQuery.css( elem, "display" ) === "none"; + }; + + + +function adjustCSS( elem, prop, valueParts, tween ) { + var adjusted, scale, + maxIterations = 20, + currentValue = tween ? + function() { + return tween.cur(); + } : + function() { + return jQuery.css( elem, prop, "" ); + }, + initial = currentValue(), + unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ), + + // Starting value computation is required for potential unit mismatches + initialInUnit = elem.nodeType && + ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) && + rcssNum.exec( jQuery.css( elem, prop ) ); + + if ( initialInUnit && initialInUnit[ 3 ] !== unit ) { + + // Support: Firefox <=54 + // Halve the iteration target value to prevent interference from CSS upper bounds (gh-2144) + initial = initial / 2; + + // Trust units reported by jQuery.css + unit = unit || initialInUnit[ 3 ]; + + // Iteratively approximate from a nonzero starting point + initialInUnit = +initial || 1; + + while ( maxIterations-- ) { + + // Evaluate and update our best guess (doubling guesses that zero out). + // Finish if the scale equals or crosses 1 (making the old*new product non-positive). + jQuery.style( elem, prop, initialInUnit + unit ); + if ( ( 1 - scale ) * ( 1 - ( scale = currentValue() / initial || 0.5 ) ) <= 0 ) { + maxIterations = 0; + } + initialInUnit = initialInUnit / scale; + + } + + initialInUnit = initialInUnit * 2; + jQuery.style( elem, prop, initialInUnit + unit ); + + // Make sure we update the tween properties later on + valueParts = valueParts || []; + } + + if ( valueParts ) { + initialInUnit = +initialInUnit || +initial || 0; + + // Apply relative offset (+=/-=) if specified + adjusted = valueParts[ 1 ] ? + initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] : + +valueParts[ 2 ]; + if ( tween ) { + tween.unit = unit; + tween.start = initialInUnit; + tween.end = adjusted; + } + } + return adjusted; +} + + +var defaultDisplayMap = {}; + +function getDefaultDisplay( elem ) { + var temp, + doc = elem.ownerDocument, + nodeName = elem.nodeName, + display = defaultDisplayMap[ nodeName ]; + + if ( display ) { + return display; + } + + temp = doc.body.appendChild( doc.createElement( nodeName ) ); + display = jQuery.css( temp, "display" ); + + temp.parentNode.removeChild( temp ); + + if ( display === "none" ) { + display = "block"; + } + defaultDisplayMap[ nodeName ] = display; + + return display; +} + +function showHide( elements, show ) { + var display, elem, + values = [], + index = 0, + length = elements.length; + + // Determine new display value for elements that need to change + for ( ; index < length; index++ ) { + elem = elements[ index ]; + if ( !elem.style ) { + continue; + } + + display = elem.style.display; + if ( show ) { + + // Since we force visibility upon cascade-hidden elements, an immediate (and slow) + // check is required in this first loop unless we have a nonempty display value (either + // inline or about-to-be-restored) + if ( display === "none" ) { + values[ index ] = dataPriv.get( elem, "display" ) || null; + if ( !values[ index ] ) { + elem.style.display = ""; + } + } + if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) { + values[ index ] = getDefaultDisplay( elem ); + } + } else { + if ( display !== "none" ) { + values[ index ] = "none"; + + // Remember what we're overwriting + dataPriv.set( elem, "display", display ); + } + } + } + + // Set the display of the elements in a second loop to avoid constant reflow + for ( index = 0; index < length; index++ ) { + if ( values[ index ] != null ) { + elements[ index ].style.display = values[ index ]; + } + } + + return elements; +} + +jQuery.fn.extend( { + show: function() { + return showHide( this, true ); + }, + hide: function() { + return showHide( this ); + }, + toggle: function( state ) { + if ( typeof state === "boolean" ) { + return state ? this.show() : this.hide(); + } + + return this.each( function() { + if ( isHiddenWithinTree( this ) ) { + jQuery( this ).show(); + } else { + jQuery( this ).hide(); + } + } ); + } +} ); +var rcheckableType = ( /^(?:checkbox|radio)$/i ); + +var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]*)/i ); + +var rscriptType = ( /^$|^module$|\/(?:java|ecma)script/i ); + + + +( function() { + var fragment = document.createDocumentFragment(), + div = fragment.appendChild( document.createElement( "div" ) ), + input = document.createElement( "input" ); + + // Support: Android 4.0 - 4.3 only + // Check state lost if the name is set (#11217) + // Support: Windows Web Apps (WWA) + // `name` and `type` must use .setAttribute for WWA (#14901) + input.setAttribute( "type", "radio" ); + input.setAttribute( "checked", "checked" ); + input.setAttribute( "name", "t" ); + + div.appendChild( input ); + + // Support: Android <=4.1 only + // Older WebKit doesn't clone checked state correctly in fragments + support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + + // Support: IE <=11 only + // Make sure textarea (and checkbox) defaultValue is properly cloned + div.innerHTML = ""; + support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; + + // Support: IE <=9 only + // IE <=9 replaces "; + support.option = !!div.lastChild; +} )(); + + +// We have to close these tags to support XHTML (#13200) +var wrapMap = { + + // XHTML parsers do not magically insert elements in the + // same way that tag soup parsers do. So we cannot shorten + // this by omitting or other required elements. + thead: [ 1, "", "
" ], + col: [ 2, "", "
" ], + tr: [ 2, "", "
" ], + td: [ 3, "", "
" ], + + _default: [ 0, "", "" ] +}; + +wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; +wrapMap.th = wrapMap.td; + +// Support: IE <=9 only +if ( !support.option ) { + wrapMap.optgroup = wrapMap.option = [ 1, "" ]; +} + + +function getAll( context, tag ) { + + // Support: IE <=9 - 11 only + // Use typeof to avoid zero-argument method invocation on host objects (#15151) + var ret; + + if ( typeof context.getElementsByTagName !== "undefined" ) { + ret = context.getElementsByTagName( tag || "*" ); + + } else if ( typeof context.querySelectorAll !== "undefined" ) { + ret = context.querySelectorAll( tag || "*" ); + + } else { + ret = []; + } + + if ( tag === undefined || tag && nodeName( context, tag ) ) { + return jQuery.merge( [ context ], ret ); + } + + return ret; +} + + +// Mark scripts as having already been evaluated +function setGlobalEval( elems, refElements ) { + var i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + dataPriv.set( + elems[ i ], + "globalEval", + !refElements || dataPriv.get( refElements[ i ], "globalEval" ) + ); + } +} + + +var rhtml = /<|&#?\w+;/; + +function buildFragment( elems, context, scripts, selection, ignored ) { + var elem, tmp, tag, wrap, attached, j, + fragment = context.createDocumentFragment(), + nodes = [], + i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + elem = elems[ i ]; + + if ( elem || elem === 0 ) { + + // Add nodes directly + if ( toType( elem ) === "object" ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); + + // Convert non-html into a text node + } else if ( !rhtml.test( elem ) ) { + nodes.push( context.createTextNode( elem ) ); + + // Convert html into DOM nodes + } else { + tmp = tmp || fragment.appendChild( context.createElement( "div" ) ); + + // Deserialize a standard representation + tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase(); + wrap = wrapMap[ tag ] || wrapMap._default; + tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ]; + + // Descend through wrappers to the right content + j = wrap[ 0 ]; + while ( j-- ) { + tmp = tmp.lastChild; + } + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, tmp.childNodes ); + + // Remember the top-level container + tmp = fragment.firstChild; + + // Ensure the created nodes are orphaned (#12392) + tmp.textContent = ""; + } + } + } + + // Remove wrapper from fragment + fragment.textContent = ""; + + i = 0; + while ( ( elem = nodes[ i++ ] ) ) { + + // Skip elements already in the context collection (trac-4087) + if ( selection && jQuery.inArray( elem, selection ) > -1 ) { + if ( ignored ) { + ignored.push( elem ); + } + continue; + } + + attached = isAttached( elem ); + + // Append to fragment + tmp = getAll( fragment.appendChild( elem ), "script" ); + + // Preserve script evaluation history + if ( attached ) { + setGlobalEval( tmp ); + } + + // Capture executables + if ( scripts ) { + j = 0; + while ( ( elem = tmp[ j++ ] ) ) { + if ( rscriptType.test( elem.type || "" ) ) { + scripts.push( elem ); + } + } + } + } + + return fragment; +} + + +var rtypenamespace = /^([^.]*)(?:\.(.+)|)/; + +function returnTrue() { + return true; +} + +function returnFalse() { + return false; +} + +// Support: IE <=9 - 11+ +// focus() and blur() are asynchronous, except when they are no-op. +// So expect focus to be synchronous when the element is already active, +// and blur to be synchronous when the element is not already active. +// (focus and blur are always synchronous in other supported browsers, +// this just defines when we can count on it). +function expectSync( elem, type ) { + return ( elem === safeActiveElement() ) === ( type === "focus" ); +} + +// Support: IE <=9 only +// Accessing document.activeElement can throw unexpectedly +// https://bugs.jquery.com/ticket/13393 +function safeActiveElement() { + try { + return document.activeElement; + } catch ( err ) { } +} + +function on( elem, types, selector, data, fn, one ) { + var origFn, type; + + // Types can be a map of types/handlers + if ( typeof types === "object" ) { + + // ( types-Object, selector, data ) + if ( typeof selector !== "string" ) { + + // ( types-Object, data ) + data = data || selector; + selector = undefined; + } + for ( type in types ) { + on( elem, type, selector, data, types[ type ], one ); + } + return elem; + } + + if ( data == null && fn == null ) { + + // ( types, fn ) + fn = selector; + data = selector = undefined; + } else if ( fn == null ) { + if ( typeof selector === "string" ) { + + // ( types, selector, fn ) + fn = data; + data = undefined; + } else { + + // ( types, data, fn ) + fn = data; + data = selector; + selector = undefined; + } + } + if ( fn === false ) { + fn = returnFalse; + } else if ( !fn ) { + return elem; + } + + if ( one === 1 ) { + origFn = fn; + fn = function( event ) { + + // Can use an empty set, since event contains the info + jQuery().off( event ); + return origFn.apply( this, arguments ); + }; + + // Use same guid so caller can remove using origFn + fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ ); + } + return elem.each( function() { + jQuery.event.add( this, types, fn, data, selector ); + } ); +} + +/* + * Helper functions for managing events -- not part of the public interface. + * Props to Dean Edwards' addEvent library for many of the ideas. + */ +jQuery.event = { + + global: {}, + + add: function( elem, types, handler, data, selector ) { + + var handleObjIn, eventHandle, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.get( elem ); + + // Only attach events to objects that accept data + if ( !acceptData( elem ) ) { + return; + } + + // Caller can pass in an object of custom data in lieu of the handler + if ( handler.handler ) { + handleObjIn = handler; + handler = handleObjIn.handler; + selector = handleObjIn.selector; + } + + // Ensure that invalid selectors throw exceptions at attach time + // Evaluate against documentElement in case elem is a non-element node (e.g., document) + if ( selector ) { + jQuery.find.matchesSelector( documentElement, selector ); + } + + // Make sure that the handler has a unique ID, used to find/remove it later + if ( !handler.guid ) { + handler.guid = jQuery.guid++; + } + + // Init the element's event structure and main handler, if this is the first + if ( !( events = elemData.events ) ) { + events = elemData.events = Object.create( null ); + } + if ( !( eventHandle = elemData.handle ) ) { + eventHandle = elemData.handle = function( e ) { + + // Discard the second event of a jQuery.event.trigger() and + // when an event is called after a page has unloaded + return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ? + jQuery.event.dispatch.apply( elem, arguments ) : undefined; + }; + } + + // Handle multiple events separated by a space + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // There *must* be a type, no attaching namespace-only handlers + if ( !type ) { + continue; + } + + // If event changes its type, use the special event handlers for the changed type + special = jQuery.event.special[ type ] || {}; + + // If selector defined, determine special event api type, otherwise given type + type = ( selector ? special.delegateType : special.bindType ) || type; + + // Update special based on newly reset type + special = jQuery.event.special[ type ] || {}; + + // handleObj is passed to all event handlers + handleObj = jQuery.extend( { + type: type, + origType: origType, + data: data, + handler: handler, + guid: handler.guid, + selector: selector, + needsContext: selector && jQuery.expr.match.needsContext.test( selector ), + namespace: namespaces.join( "." ) + }, handleObjIn ); + + // Init the event handler queue if we're the first + if ( !( handlers = events[ type ] ) ) { + handlers = events[ type ] = []; + handlers.delegateCount = 0; + + // Only use addEventListener if the special events handler returns false + if ( !special.setup || + special.setup.call( elem, data, namespaces, eventHandle ) === false ) { + + if ( elem.addEventListener ) { + elem.addEventListener( type, eventHandle ); + } + } + } + + if ( special.add ) { + special.add.call( elem, handleObj ); + + if ( !handleObj.handler.guid ) { + handleObj.handler.guid = handler.guid; + } + } + + // Add to the element's handler list, delegates in front + if ( selector ) { + handlers.splice( handlers.delegateCount++, 0, handleObj ); + } else { + handlers.push( handleObj ); + } + + // Keep track of which events have ever been used, for event optimization + jQuery.event.global[ type ] = true; + } + + }, + + // Detach an event or set of events from an element + remove: function( elem, types, handler, selector, mappedTypes ) { + + var j, origCount, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.hasData( elem ) && dataPriv.get( elem ); + + if ( !elemData || !( events = elemData.events ) ) { + return; + } + + // Once for each type.namespace in types; type may be omitted + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // Unbind all events (on this namespace, if provided) for the element + if ( !type ) { + for ( type in events ) { + jQuery.event.remove( elem, type + types[ t ], handler, selector, true ); + } + continue; + } + + special = jQuery.event.special[ type ] || {}; + type = ( selector ? special.delegateType : special.bindType ) || type; + handlers = events[ type ] || []; + tmp = tmp[ 2 ] && + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ); + + // Remove matching events + origCount = j = handlers.length; + while ( j-- ) { + handleObj = handlers[ j ]; + + if ( ( mappedTypes || origType === handleObj.origType ) && + ( !handler || handler.guid === handleObj.guid ) && + ( !tmp || tmp.test( handleObj.namespace ) ) && + ( !selector || selector === handleObj.selector || + selector === "**" && handleObj.selector ) ) { + handlers.splice( j, 1 ); + + if ( handleObj.selector ) { + handlers.delegateCount--; + } + if ( special.remove ) { + special.remove.call( elem, handleObj ); + } + } + } + + // Remove generic event handler if we removed something and no more handlers exist + // (avoids potential for endless recursion during removal of special event handlers) + if ( origCount && !handlers.length ) { + if ( !special.teardown || + special.teardown.call( elem, namespaces, elemData.handle ) === false ) { + + jQuery.removeEvent( elem, type, elemData.handle ); + } + + delete events[ type ]; + } + } + + // Remove data and the expando if it's no longer used + if ( jQuery.isEmptyObject( events ) ) { + dataPriv.remove( elem, "handle events" ); + } + }, + + dispatch: function( nativeEvent ) { + + var i, j, ret, matched, handleObj, handlerQueue, + args = new Array( arguments.length ), + + // Make a writable jQuery.Event from the native event object + event = jQuery.event.fix( nativeEvent ), + + handlers = ( + dataPriv.get( this, "events" ) || Object.create( null ) + )[ event.type ] || [], + special = jQuery.event.special[ event.type ] || {}; + + // Use the fix-ed jQuery.Event rather than the (read-only) native event + args[ 0 ] = event; + + for ( i = 1; i < arguments.length; i++ ) { + args[ i ] = arguments[ i ]; + } + + event.delegateTarget = this; + + // Call the preDispatch hook for the mapped type, and let it bail if desired + if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) { + return; + } + + // Determine handlers + handlerQueue = jQuery.event.handlers.call( this, event, handlers ); + + // Run delegates first; they may want to stop propagation beneath us + i = 0; + while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) { + event.currentTarget = matched.elem; + + j = 0; + while ( ( handleObj = matched.handlers[ j++ ] ) && + !event.isImmediatePropagationStopped() ) { + + // If the event is namespaced, then each handler is only invoked if it is + // specially universal or its namespaces are a superset of the event's. + if ( !event.rnamespace || handleObj.namespace === false || + event.rnamespace.test( handleObj.namespace ) ) { + + event.handleObj = handleObj; + event.data = handleObj.data; + + ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle || + handleObj.handler ).apply( matched.elem, args ); + + if ( ret !== undefined ) { + if ( ( event.result = ret ) === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + } + } + } + + // Call the postDispatch hook for the mapped type + if ( special.postDispatch ) { + special.postDispatch.call( this, event ); + } + + return event.result; + }, + + handlers: function( event, handlers ) { + var i, handleObj, sel, matchedHandlers, matchedSelectors, + handlerQueue = [], + delegateCount = handlers.delegateCount, + cur = event.target; + + // Find delegate handlers + if ( delegateCount && + + // Support: IE <=9 + // Black-hole SVG instance trees (trac-13180) + cur.nodeType && + + // Support: Firefox <=42 + // Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861) + // https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click + // Support: IE 11 only + // ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343) + !( event.type === "click" && event.button >= 1 ) ) { + + for ( ; cur !== this; cur = cur.parentNode || this ) { + + // Don't check non-elements (#13208) + // Don't process clicks on disabled elements (#6911, #8165, #11382, #11764) + if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) { + matchedHandlers = []; + matchedSelectors = {}; + for ( i = 0; i < delegateCount; i++ ) { + handleObj = handlers[ i ]; + + // Don't conflict with Object.prototype properties (#13203) + sel = handleObj.selector + " "; + + if ( matchedSelectors[ sel ] === undefined ) { + matchedSelectors[ sel ] = handleObj.needsContext ? + jQuery( sel, this ).index( cur ) > -1 : + jQuery.find( sel, this, null, [ cur ] ).length; + } + if ( matchedSelectors[ sel ] ) { + matchedHandlers.push( handleObj ); + } + } + if ( matchedHandlers.length ) { + handlerQueue.push( { elem: cur, handlers: matchedHandlers } ); + } + } + } + } + + // Add the remaining (directly-bound) handlers + cur = this; + if ( delegateCount < handlers.length ) { + handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } ); + } + + return handlerQueue; + }, + + addProp: function( name, hook ) { + Object.defineProperty( jQuery.Event.prototype, name, { + enumerable: true, + configurable: true, + + get: isFunction( hook ) ? + function() { + if ( this.originalEvent ) { + return hook( this.originalEvent ); + } + } : + function() { + if ( this.originalEvent ) { + return this.originalEvent[ name ]; + } + }, + + set: function( value ) { + Object.defineProperty( this, name, { + enumerable: true, + configurable: true, + writable: true, + value: value + } ); + } + } ); + }, + + fix: function( originalEvent ) { + return originalEvent[ jQuery.expando ] ? + originalEvent : + new jQuery.Event( originalEvent ); + }, + + special: { + load: { + + // Prevent triggered image.load events from bubbling to window.load + noBubble: true + }, + click: { + + // Utilize native event to ensure correct state for checkable inputs + setup: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Claim the first handler + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + // dataPriv.set( el, "click", ... ) + leverageNative( el, "click", returnTrue ); + } + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Force setup before triggering a click + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + leverageNative( el, "click" ); + } + + // Return non-false to allow normal event-path propagation + return true; + }, + + // For cross-browser consistency, suppress native .click() on links + // Also prevent it if we're currently inside a leveraged native-event stack + _default: function( event ) { + var target = event.target; + return rcheckableType.test( target.type ) && + target.click && nodeName( target, "input" ) && + dataPriv.get( target, "click" ) || + nodeName( target, "a" ); + } + }, + + beforeunload: { + postDispatch: function( event ) { + + // Support: Firefox 20+ + // Firefox doesn't alert if the returnValue field is not set. + if ( event.result !== undefined && event.originalEvent ) { + event.originalEvent.returnValue = event.result; + } + } + } + } +}; + +// Ensure the presence of an event listener that handles manually-triggered +// synthetic events by interrupting progress until reinvoked in response to +// *native* events that it fires directly, ensuring that state changes have +// already occurred before other listeners are invoked. +function leverageNative( el, type, expectSync ) { + + // Missing expectSync indicates a trigger call, which must force setup through jQuery.event.add + if ( !expectSync ) { + if ( dataPriv.get( el, type ) === undefined ) { + jQuery.event.add( el, type, returnTrue ); + } + return; + } + + // Register the controller as a special universal handler for all event namespaces + dataPriv.set( el, type, false ); + jQuery.event.add( el, type, { + namespace: false, + handler: function( event ) { + var notAsync, result, + saved = dataPriv.get( this, type ); + + if ( ( event.isTrigger & 1 ) && this[ type ] ) { + + // Interrupt processing of the outer synthetic .trigger()ed event + // Saved data should be false in such cases, but might be a leftover capture object + // from an async native handler (gh-4350) + if ( !saved.length ) { + + // Store arguments for use when handling the inner native event + // There will always be at least one argument (an event object), so this array + // will not be confused with a leftover capture object. + saved = slice.call( arguments ); + dataPriv.set( this, type, saved ); + + // Trigger the native event and capture its result + // Support: IE <=9 - 11+ + // focus() and blur() are asynchronous + notAsync = expectSync( this, type ); + this[ type ](); + result = dataPriv.get( this, type ); + if ( saved !== result || notAsync ) { + dataPriv.set( this, type, false ); + } else { + result = {}; + } + if ( saved !== result ) { + + // Cancel the outer synthetic event + event.stopImmediatePropagation(); + event.preventDefault(); + + // Support: Chrome 86+ + // In Chrome, if an element having a focusout handler is blurred by + // clicking outside of it, it invokes the handler synchronously. If + // that handler calls `.remove()` on the element, the data is cleared, + // leaving `result` undefined. We need to guard against this. + return result && result.value; + } + + // If this is an inner synthetic event for an event with a bubbling surrogate + // (focus or blur), assume that the surrogate already propagated from triggering the + // native event and prevent that from happening again here. + // This technically gets the ordering wrong w.r.t. to `.trigger()` (in which the + // bubbling surrogate propagates *after* the non-bubbling base), but that seems + // less bad than duplication. + } else if ( ( jQuery.event.special[ type ] || {} ).delegateType ) { + event.stopPropagation(); + } + + // If this is a native event triggered above, everything is now in order + // Fire an inner synthetic event with the original arguments + } else if ( saved.length ) { + + // ...and capture the result + dataPriv.set( this, type, { + value: jQuery.event.trigger( + + // Support: IE <=9 - 11+ + // Extend with the prototype to reset the above stopImmediatePropagation() + jQuery.extend( saved[ 0 ], jQuery.Event.prototype ), + saved.slice( 1 ), + this + ) + } ); + + // Abort handling of the native event + event.stopImmediatePropagation(); + } + } + } ); +} + +jQuery.removeEvent = function( elem, type, handle ) { + + // This "if" is needed for plain objects + if ( elem.removeEventListener ) { + elem.removeEventListener( type, handle ); + } +}; + +jQuery.Event = function( src, props ) { + + // Allow instantiation without the 'new' keyword + if ( !( this instanceof jQuery.Event ) ) { + return new jQuery.Event( src, props ); + } + + // Event object + if ( src && src.type ) { + this.originalEvent = src; + this.type = src.type; + + // Events bubbling up the document may have been marked as prevented + // by a handler lower down the tree; reflect the correct value. + this.isDefaultPrevented = src.defaultPrevented || + src.defaultPrevented === undefined && + + // Support: Android <=2.3 only + src.returnValue === false ? + returnTrue : + returnFalse; + + // Create target properties + // Support: Safari <=6 - 7 only + // Target should not be a text node (#504, #13143) + this.target = ( src.target && src.target.nodeType === 3 ) ? + src.target.parentNode : + src.target; + + this.currentTarget = src.currentTarget; + this.relatedTarget = src.relatedTarget; + + // Event type + } else { + this.type = src; + } + + // Put explicitly provided properties onto the event object + if ( props ) { + jQuery.extend( this, props ); + } + + // Create a timestamp if incoming event doesn't have one + this.timeStamp = src && src.timeStamp || Date.now(); + + // Mark it as fixed + this[ jQuery.expando ] = true; +}; + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + constructor: jQuery.Event, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse, + isSimulated: false, + + preventDefault: function() { + var e = this.originalEvent; + + this.isDefaultPrevented = returnTrue; + + if ( e && !this.isSimulated ) { + e.preventDefault(); + } + }, + stopPropagation: function() { + var e = this.originalEvent; + + this.isPropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopPropagation(); + } + }, + stopImmediatePropagation: function() { + var e = this.originalEvent; + + this.isImmediatePropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopImmediatePropagation(); + } + + this.stopPropagation(); + } +}; + +// Includes all common event props including KeyEvent and MouseEvent specific props +jQuery.each( { + altKey: true, + bubbles: true, + cancelable: true, + changedTouches: true, + ctrlKey: true, + detail: true, + eventPhase: true, + metaKey: true, + pageX: true, + pageY: true, + shiftKey: true, + view: true, + "char": true, + code: true, + charCode: true, + key: true, + keyCode: true, + button: true, + buttons: true, + clientX: true, + clientY: true, + offsetX: true, + offsetY: true, + pointerId: true, + pointerType: true, + screenX: true, + screenY: true, + targetTouches: true, + toElement: true, + touches: true, + which: true +}, jQuery.event.addProp ); + +jQuery.each( { focus: "focusin", blur: "focusout" }, function( type, delegateType ) { + jQuery.event.special[ type ] = { + + // Utilize native event if possible so blur/focus sequence is correct + setup: function() { + + // Claim the first handler + // dataPriv.set( this, "focus", ... ) + // dataPriv.set( this, "blur", ... ) + leverageNative( this, type, expectSync ); + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function() { + + // Force setup before trigger + leverageNative( this, type ); + + // Return non-false to allow normal event-path propagation + return true; + }, + + // Suppress native focus or blur as it's already being fired + // in leverageNative. + _default: function() { + return true; + }, + + delegateType: delegateType + }; +} ); + +// Create mouseenter/leave events using mouseover/out and event-time checks +// so that event delegation works in jQuery. +// Do the same for pointerenter/pointerleave and pointerover/pointerout +// +// Support: Safari 7 only +// Safari sends mouseenter too often; see: +// https://bugs.chromium.org/p/chromium/issues/detail?id=470258 +// for the description of the bug (it existed in older Chrome versions as well). +jQuery.each( { + mouseenter: "mouseover", + mouseleave: "mouseout", + pointerenter: "pointerover", + pointerleave: "pointerout" +}, function( orig, fix ) { + jQuery.event.special[ orig ] = { + delegateType: fix, + bindType: fix, + + handle: function( event ) { + var ret, + target = this, + related = event.relatedTarget, + handleObj = event.handleObj; + + // For mouseenter/leave call the handler if related is outside the target. + // NB: No relatedTarget if the mouse left/entered the browser window + if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) { + event.type = handleObj.origType; + ret = handleObj.handler.apply( this, arguments ); + event.type = fix; + } + return ret; + } + }; +} ); + +jQuery.fn.extend( { + + on: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn ); + }, + one: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn, 1 ); + }, + off: function( types, selector, fn ) { + var handleObj, type; + if ( types && types.preventDefault && types.handleObj ) { + + // ( event ) dispatched jQuery.Event + handleObj = types.handleObj; + jQuery( types.delegateTarget ).off( + handleObj.namespace ? + handleObj.origType + "." + handleObj.namespace : + handleObj.origType, + handleObj.selector, + handleObj.handler + ); + return this; + } + if ( typeof types === "object" ) { + + // ( types-object [, selector] ) + for ( type in types ) { + this.off( type, selector, types[ type ] ); + } + return this; + } + if ( selector === false || typeof selector === "function" ) { + + // ( types [, fn] ) + fn = selector; + selector = undefined; + } + if ( fn === false ) { + fn = returnFalse; + } + return this.each( function() { + jQuery.event.remove( this, types, fn, selector ); + } ); + } +} ); + + +var + + // Support: IE <=10 - 11, Edge 12 - 13 only + // In IE/Edge using regex groups here causes severe slowdowns. + // See https://connect.microsoft.com/IE/feedback/details/1736512/ + rnoInnerhtml = /\s*$/g; + +// Prefer a tbody over its parent table for containing new rows +function manipulationTarget( elem, content ) { + if ( nodeName( elem, "table" ) && + nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) { + + return jQuery( elem ).children( "tbody" )[ 0 ] || elem; + } + + return elem; +} + +// Replace/restore the type attribute of script elements for safe DOM manipulation +function disableScript( elem ) { + elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type; + return elem; +} +function restoreScript( elem ) { + if ( ( elem.type || "" ).slice( 0, 5 ) === "true/" ) { + elem.type = elem.type.slice( 5 ); + } else { + elem.removeAttribute( "type" ); + } + + return elem; +} + +function cloneCopyEvent( src, dest ) { + var i, l, type, pdataOld, udataOld, udataCur, events; + + if ( dest.nodeType !== 1 ) { + return; + } + + // 1. Copy private data: events, handlers, etc. + if ( dataPriv.hasData( src ) ) { + pdataOld = dataPriv.get( src ); + events = pdataOld.events; + + if ( events ) { + dataPriv.remove( dest, "handle events" ); + + for ( type in events ) { + for ( i = 0, l = events[ type ].length; i < l; i++ ) { + jQuery.event.add( dest, type, events[ type ][ i ] ); + } + } + } + } + + // 2. Copy user data + if ( dataUser.hasData( src ) ) { + udataOld = dataUser.access( src ); + udataCur = jQuery.extend( {}, udataOld ); + + dataUser.set( dest, udataCur ); + } +} + +// Fix IE bugs, see support tests +function fixInput( src, dest ) { + var nodeName = dest.nodeName.toLowerCase(); + + // Fails to persist the checked state of a cloned checkbox or radio button. + if ( nodeName === "input" && rcheckableType.test( src.type ) ) { + dest.checked = src.checked; + + // Fails to return the selected option to the default selected state when cloning options + } else if ( nodeName === "input" || nodeName === "textarea" ) { + dest.defaultValue = src.defaultValue; + } +} + +function domManip( collection, args, callback, ignored ) { + + // Flatten any nested arrays + args = flat( args ); + + var fragment, first, scripts, hasScripts, node, doc, + i = 0, + l = collection.length, + iNoClone = l - 1, + value = args[ 0 ], + valueIsFunction = isFunction( value ); + + // We can't cloneNode fragments that contain checked, in WebKit + if ( valueIsFunction || + ( l > 1 && typeof value === "string" && + !support.checkClone && rchecked.test( value ) ) ) { + return collection.each( function( index ) { + var self = collection.eq( index ); + if ( valueIsFunction ) { + args[ 0 ] = value.call( this, index, self.html() ); + } + domManip( self, args, callback, ignored ); + } ); + } + + if ( l ) { + fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored ); + first = fragment.firstChild; + + if ( fragment.childNodes.length === 1 ) { + fragment = first; + } + + // Require either new content or an interest in ignored elements to invoke the callback + if ( first || ignored ) { + scripts = jQuery.map( getAll( fragment, "script" ), disableScript ); + hasScripts = scripts.length; + + // Use the original fragment for the last item + // instead of the first because it can end up + // being emptied incorrectly in certain situations (#8070). + for ( ; i < l; i++ ) { + node = fragment; + + if ( i !== iNoClone ) { + node = jQuery.clone( node, true, true ); + + // Keep references to cloned scripts for later restoration + if ( hasScripts ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( scripts, getAll( node, "script" ) ); + } + } + + callback.call( collection[ i ], node, i ); + } + + if ( hasScripts ) { + doc = scripts[ scripts.length - 1 ].ownerDocument; + + // Reenable scripts + jQuery.map( scripts, restoreScript ); + + // Evaluate executable scripts on first document insertion + for ( i = 0; i < hasScripts; i++ ) { + node = scripts[ i ]; + if ( rscriptType.test( node.type || "" ) && + !dataPriv.access( node, "globalEval" ) && + jQuery.contains( doc, node ) ) { + + if ( node.src && ( node.type || "" ).toLowerCase() !== "module" ) { + + // Optional AJAX dependency, but won't run scripts if not present + if ( jQuery._evalUrl && !node.noModule ) { + jQuery._evalUrl( node.src, { + nonce: node.nonce || node.getAttribute( "nonce" ) + }, doc ); + } + } else { + DOMEval( node.textContent.replace( rcleanScript, "" ), node, doc ); + } + } + } + } + } + } + + return collection; +} + +function remove( elem, selector, keepData ) { + var node, + nodes = selector ? jQuery.filter( selector, elem ) : elem, + i = 0; + + for ( ; ( node = nodes[ i ] ) != null; i++ ) { + if ( !keepData && node.nodeType === 1 ) { + jQuery.cleanData( getAll( node ) ); + } + + if ( node.parentNode ) { + if ( keepData && isAttached( node ) ) { + setGlobalEval( getAll( node, "script" ) ); + } + node.parentNode.removeChild( node ); + } + } + + return elem; +} + +jQuery.extend( { + htmlPrefilter: function( html ) { + return html; + }, + + clone: function( elem, dataAndEvents, deepDataAndEvents ) { + var i, l, srcElements, destElements, + clone = elem.cloneNode( true ), + inPage = isAttached( elem ); + + // Fix IE cloning issues + if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && + !jQuery.isXMLDoc( elem ) ) { + + // We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2 + destElements = getAll( clone ); + srcElements = getAll( elem ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + fixInput( srcElements[ i ], destElements[ i ] ); + } + } + + // Copy the events from the original to the clone + if ( dataAndEvents ) { + if ( deepDataAndEvents ) { + srcElements = srcElements || getAll( elem ); + destElements = destElements || getAll( clone ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + cloneCopyEvent( srcElements[ i ], destElements[ i ] ); + } + } else { + cloneCopyEvent( elem, clone ); + } + } + + // Preserve script evaluation history + destElements = getAll( clone, "script" ); + if ( destElements.length > 0 ) { + setGlobalEval( destElements, !inPage && getAll( elem, "script" ) ); + } + + // Return the cloned set + return clone; + }, + + cleanData: function( elems ) { + var data, elem, type, + special = jQuery.event.special, + i = 0; + + for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) { + if ( acceptData( elem ) ) { + if ( ( data = elem[ dataPriv.expando ] ) ) { + if ( data.events ) { + for ( type in data.events ) { + if ( special[ type ] ) { + jQuery.event.remove( elem, type ); + + // This is a shortcut to avoid jQuery.event.remove's overhead + } else { + jQuery.removeEvent( elem, type, data.handle ); + } + } + } + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataPriv.expando ] = undefined; + } + if ( elem[ dataUser.expando ] ) { + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataUser.expando ] = undefined; + } + } + } + } +} ); + +jQuery.fn.extend( { + detach: function( selector ) { + return remove( this, selector, true ); + }, + + remove: function( selector ) { + return remove( this, selector ); + }, + + text: function( value ) { + return access( this, function( value ) { + return value === undefined ? + jQuery.text( this ) : + this.empty().each( function() { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + this.textContent = value; + } + } ); + }, null, value, arguments.length ); + }, + + append: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.appendChild( elem ); + } + } ); + }, + + prepend: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.insertBefore( elem, target.firstChild ); + } + } ); + }, + + before: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this ); + } + } ); + }, + + after: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this.nextSibling ); + } + } ); + }, + + empty: function() { + var elem, + i = 0; + + for ( ; ( elem = this[ i ] ) != null; i++ ) { + if ( elem.nodeType === 1 ) { + + // Prevent memory leaks + jQuery.cleanData( getAll( elem, false ) ); + + // Remove any remaining nodes + elem.textContent = ""; + } + } + + return this; + }, + + clone: function( dataAndEvents, deepDataAndEvents ) { + dataAndEvents = dataAndEvents == null ? false : dataAndEvents; + deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents; + + return this.map( function() { + return jQuery.clone( this, dataAndEvents, deepDataAndEvents ); + } ); + }, + + html: function( value ) { + return access( this, function( value ) { + var elem = this[ 0 ] || {}, + i = 0, + l = this.length; + + if ( value === undefined && elem.nodeType === 1 ) { + return elem.innerHTML; + } + + // See if we can take a shortcut and just use innerHTML + if ( typeof value === "string" && !rnoInnerhtml.test( value ) && + !wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) { + + value = jQuery.htmlPrefilter( value ); + + try { + for ( ; i < l; i++ ) { + elem = this[ i ] || {}; + + // Remove element nodes and prevent memory leaks + if ( elem.nodeType === 1 ) { + jQuery.cleanData( getAll( elem, false ) ); + elem.innerHTML = value; + } + } + + elem = 0; + + // If using innerHTML throws an exception, use the fallback method + } catch ( e ) {} + } + + if ( elem ) { + this.empty().append( value ); + } + }, null, value, arguments.length ); + }, + + replaceWith: function() { + var ignored = []; + + // Make the changes, replacing each non-ignored context element with the new content + return domManip( this, arguments, function( elem ) { + var parent = this.parentNode; + + if ( jQuery.inArray( this, ignored ) < 0 ) { + jQuery.cleanData( getAll( this ) ); + if ( parent ) { + parent.replaceChild( elem, this ); + } + } + + // Force callback invocation + }, ignored ); + } +} ); + +jQuery.each( { + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function( name, original ) { + jQuery.fn[ name ] = function( selector ) { + var elems, + ret = [], + insert = jQuery( selector ), + last = insert.length - 1, + i = 0; + + for ( ; i <= last; i++ ) { + elems = i === last ? this : this.clone( true ); + jQuery( insert[ i ] )[ original ]( elems ); + + // Support: Android <=4.0 only, PhantomJS 1 only + // .get() because push.apply(_, arraylike) throws on ancient WebKit + push.apply( ret, elems.get() ); + } + + return this.pushStack( ret ); + }; +} ); +var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" ); + +var getStyles = function( elem ) { + + // Support: IE <=11 only, Firefox <=30 (#15098, #14150) + // IE throws on elements created in popups + // FF meanwhile throws on frame elements through "defaultView.getComputedStyle" + var view = elem.ownerDocument.defaultView; + + if ( !view || !view.opener ) { + view = window; + } + + return view.getComputedStyle( elem ); + }; + +var swap = function( elem, options, callback ) { + var ret, name, + old = {}; + + // Remember the old values, and insert the new ones + for ( name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + ret = callback.call( elem ); + + // Revert the old values + for ( name in options ) { + elem.style[ name ] = old[ name ]; + } + + return ret; +}; + + +var rboxStyle = new RegExp( cssExpand.join( "|" ), "i" ); + + + +( function() { + + // Executing both pixelPosition & boxSizingReliable tests require only one layout + // so they're executed at the same time to save the second computation. + function computeStyleTests() { + + // This is a singleton, we need to execute it only once + if ( !div ) { + return; + } + + container.style.cssText = "position:absolute;left:-11111px;width:60px;" + + "margin-top:1px;padding:0;border:0"; + div.style.cssText = + "position:relative;display:block;box-sizing:border-box;overflow:scroll;" + + "margin:auto;border:1px;padding:1px;" + + "width:60%;top:1%"; + documentElement.appendChild( container ).appendChild( div ); + + var divStyle = window.getComputedStyle( div ); + pixelPositionVal = divStyle.top !== "1%"; + + // Support: Android 4.0 - 4.3 only, Firefox <=3 - 44 + reliableMarginLeftVal = roundPixelMeasures( divStyle.marginLeft ) === 12; + + // Support: Android 4.0 - 4.3 only, Safari <=9.1 - 10.1, iOS <=7.0 - 9.3 + // Some styles come back with percentage values, even though they shouldn't + div.style.right = "60%"; + pixelBoxStylesVal = roundPixelMeasures( divStyle.right ) === 36; + + // Support: IE 9 - 11 only + // Detect misreporting of content dimensions for box-sizing:border-box elements + boxSizingReliableVal = roundPixelMeasures( divStyle.width ) === 36; + + // Support: IE 9 only + // Detect overflow:scroll screwiness (gh-3699) + // Support: Chrome <=64 + // Don't get tricked when zoom affects offsetWidth (gh-4029) + div.style.position = "absolute"; + scrollboxSizeVal = roundPixelMeasures( div.offsetWidth / 3 ) === 12; + + documentElement.removeChild( container ); + + // Nullify the div so it wouldn't be stored in the memory and + // it will also be a sign that checks already performed + div = null; + } + + function roundPixelMeasures( measure ) { + return Math.round( parseFloat( measure ) ); + } + + var pixelPositionVal, boxSizingReliableVal, scrollboxSizeVal, pixelBoxStylesVal, + reliableTrDimensionsVal, reliableMarginLeftVal, + container = document.createElement( "div" ), + div = document.createElement( "div" ); + + // Finish early in limited (non-browser) environments + if ( !div.style ) { + return; + } + + // Support: IE <=9 - 11 only + // Style of cloned element affects source element cloned (#8908) + div.style.backgroundClip = "content-box"; + div.cloneNode( true ).style.backgroundClip = ""; + support.clearCloneStyle = div.style.backgroundClip === "content-box"; + + jQuery.extend( support, { + boxSizingReliable: function() { + computeStyleTests(); + return boxSizingReliableVal; + }, + pixelBoxStyles: function() { + computeStyleTests(); + return pixelBoxStylesVal; + }, + pixelPosition: function() { + computeStyleTests(); + return pixelPositionVal; + }, + reliableMarginLeft: function() { + computeStyleTests(); + return reliableMarginLeftVal; + }, + scrollboxSize: function() { + computeStyleTests(); + return scrollboxSizeVal; + }, + + // Support: IE 9 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Behavior in IE 9 is more subtle than in newer versions & it passes + // some versions of this test; make sure not to make it pass there! + // + // Support: Firefox 70+ + // Only Firefox includes border widths + // in computed dimensions. (gh-4529) + reliableTrDimensions: function() { + var table, tr, trChild, trStyle; + if ( reliableTrDimensionsVal == null ) { + table = document.createElement( "table" ); + tr = document.createElement( "tr" ); + trChild = document.createElement( "div" ); + + table.style.cssText = "position:absolute;left:-11111px;border-collapse:separate"; + tr.style.cssText = "border:1px solid"; + + // Support: Chrome 86+ + // Height set through cssText does not get applied. + // Computed height then comes back as 0. + tr.style.height = "1px"; + trChild.style.height = "9px"; + + // Support: Android 8 Chrome 86+ + // In our bodyBackground.html iframe, + // display for all div elements is set to "inline", + // which causes a problem only in Android 8 Chrome 86. + // Ensuring the div is display: block + // gets around this issue. + trChild.style.display = "block"; + + documentElement + .appendChild( table ) + .appendChild( tr ) + .appendChild( trChild ); + + trStyle = window.getComputedStyle( tr ); + reliableTrDimensionsVal = ( parseInt( trStyle.height, 10 ) + + parseInt( trStyle.borderTopWidth, 10 ) + + parseInt( trStyle.borderBottomWidth, 10 ) ) === tr.offsetHeight; + + documentElement.removeChild( table ); + } + return reliableTrDimensionsVal; + } + } ); +} )(); + + +function curCSS( elem, name, computed ) { + var width, minWidth, maxWidth, ret, + + // Support: Firefox 51+ + // Retrieving style before computed somehow + // fixes an issue with getting wrong values + // on detached elements + style = elem.style; + + computed = computed || getStyles( elem ); + + // getPropertyValue is needed for: + // .css('filter') (IE 9 only, #12537) + // .css('--customProperty) (#3144) + if ( computed ) { + ret = computed.getPropertyValue( name ) || computed[ name ]; + + if ( ret === "" && !isAttached( elem ) ) { + ret = jQuery.style( elem, name ); + } + + // A tribute to the "awesome hack by Dean Edwards" + // Android Browser returns percentage for some values, + // but width seems to be reliably pixels. + // This is against the CSSOM draft spec: + // https://drafts.csswg.org/cssom/#resolved-values + if ( !support.pixelBoxStyles() && rnumnonpx.test( ret ) && rboxStyle.test( name ) ) { + + // Remember the original values + width = style.width; + minWidth = style.minWidth; + maxWidth = style.maxWidth; + + // Put in the new values to get a computed value out + style.minWidth = style.maxWidth = style.width = ret; + ret = computed.width; + + // Revert the changed values + style.width = width; + style.minWidth = minWidth; + style.maxWidth = maxWidth; + } + } + + return ret !== undefined ? + + // Support: IE <=9 - 11 only + // IE returns zIndex value as an integer. + ret + "" : + ret; +} + + +function addGetHookIf( conditionFn, hookFn ) { + + // Define the hook, we'll check on the first run if it's really needed. + return { + get: function() { + if ( conditionFn() ) { + + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. + delete this.get; + return; + } + + // Hook needed; redefine it so that the support test is not executed again. + return ( this.get = hookFn ).apply( this, arguments ); + } + }; +} + + +var cssPrefixes = [ "Webkit", "Moz", "ms" ], + emptyStyle = document.createElement( "div" ).style, + vendorProps = {}; + +// Return a vendor-prefixed property or undefined +function vendorPropName( name ) { + + // Check for vendor prefixed names + var capName = name[ 0 ].toUpperCase() + name.slice( 1 ), + i = cssPrefixes.length; + + while ( i-- ) { + name = cssPrefixes[ i ] + capName; + if ( name in emptyStyle ) { + return name; + } + } +} + +// Return a potentially-mapped jQuery.cssProps or vendor prefixed property +function finalPropName( name ) { + var final = jQuery.cssProps[ name ] || vendorProps[ name ]; + + if ( final ) { + return final; + } + if ( name in emptyStyle ) { + return name; + } + return vendorProps[ name ] = vendorPropName( name ) || name; +} + + +var + + // Swappable if display is none or starts with table + // except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + rdisplayswap = /^(none|table(?!-c[ea]).+)/, + rcustomProp = /^--/, + cssShow = { position: "absolute", visibility: "hidden", display: "block" }, + cssNormalTransform = { + letterSpacing: "0", + fontWeight: "400" + }; + +function setPositiveNumber( _elem, value, subtract ) { + + // Any relative (+/-) values have already been + // normalized at this point + var matches = rcssNum.exec( value ); + return matches ? + + // Guard against undefined "subtract", e.g., when used as in cssHooks + Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) : + value; +} + +function boxModelAdjustment( elem, dimension, box, isBorderBox, styles, computedVal ) { + var i = dimension === "width" ? 1 : 0, + extra = 0, + delta = 0; + + // Adjustment may not be necessary + if ( box === ( isBorderBox ? "border" : "content" ) ) { + return 0; + } + + for ( ; i < 4; i += 2 ) { + + // Both box models exclude margin + if ( box === "margin" ) { + delta += jQuery.css( elem, box + cssExpand[ i ], true, styles ); + } + + // If we get here with a content-box, we're seeking "padding" or "border" or "margin" + if ( !isBorderBox ) { + + // Add padding + delta += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + + // For "border" or "margin", add border + if ( box !== "padding" ) { + delta += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + + // But still keep track of it otherwise + } else { + extra += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + + // If we get here with a border-box (content + padding + border), we're seeking "content" or + // "padding" or "margin" + } else { + + // For "content", subtract padding + if ( box === "content" ) { + delta -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + } + + // For "content" or "padding", subtract border + if ( box !== "margin" ) { + delta -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + } + } + + // Account for positive content-box scroll gutter when requested by providing computedVal + if ( !isBorderBox && computedVal >= 0 ) { + + // offsetWidth/offsetHeight is a rounded sum of content, padding, scroll gutter, and border + // Assuming integer scroll gutter, subtract the rest and round down + delta += Math.max( 0, Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + computedVal - + delta - + extra - + 0.5 + + // If offsetWidth/offsetHeight is unknown, then we can't determine content-box scroll gutter + // Use an explicit zero to avoid NaN (gh-3964) + ) ) || 0; + } + + return delta; +} + +function getWidthOrHeight( elem, dimension, extra ) { + + // Start with computed style + var styles = getStyles( elem ), + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-4322). + // Fake content-box until we know it's needed to know the true value. + boxSizingNeeded = !support.boxSizingReliable() || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + valueIsBorderBox = isBorderBox, + + val = curCSS( elem, dimension, styles ), + offsetProp = "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ); + + // Support: Firefox <=54 + // Return a confounding non-pixel value or feign ignorance, as appropriate. + if ( rnumnonpx.test( val ) ) { + if ( !extra ) { + return val; + } + val = "auto"; + } + + + // Support: IE 9 - 11 only + // Use offsetWidth/offsetHeight for when box sizing is unreliable. + // In those cases, the computed value can be trusted to be border-box. + if ( ( !support.boxSizingReliable() && isBorderBox || + + // Support: IE 10 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Interestingly, in some cases IE 9 doesn't suffer from this issue. + !support.reliableTrDimensions() && nodeName( elem, "tr" ) || + + // Fall back to offsetWidth/offsetHeight when value is "auto" + // This happens for inline elements with no explicit setting (gh-3571) + val === "auto" || + + // Support: Android <=4.1 - 4.3 only + // Also use offsetWidth/offsetHeight for misreported inline dimensions (gh-3602) + !parseFloat( val ) && jQuery.css( elem, "display", false, styles ) === "inline" ) && + + // Make sure the element is visible & connected + elem.getClientRects().length ) { + + isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; + + // Where available, offsetWidth/offsetHeight approximate border box dimensions. + // Where not available (e.g., SVG), assume unreliable box-sizing and interpret the + // retrieved value as a content box dimension. + valueIsBorderBox = offsetProp in elem; + if ( valueIsBorderBox ) { + val = elem[ offsetProp ]; + } + } + + // Normalize "" and auto + val = parseFloat( val ) || 0; + + // Adjust for the element's box model + return ( val + + boxModelAdjustment( + elem, + dimension, + extra || ( isBorderBox ? "border" : "content" ), + valueIsBorderBox, + styles, + + // Provide the current computed size to request scroll gutter calculation (gh-3589) + val + ) + ) + "px"; +} + +jQuery.extend( { + + // Add in style property hooks for overriding the default + // behavior of getting and setting a style property + cssHooks: { + opacity: { + get: function( elem, computed ) { + if ( computed ) { + + // We should always get a number back from opacity + var ret = curCSS( elem, "opacity" ); + return ret === "" ? "1" : ret; + } + } + } + }, + + // Don't automatically add "px" to these possibly-unitless properties + cssNumber: { + "animationIterationCount": true, + "columnCount": true, + "fillOpacity": true, + "flexGrow": true, + "flexShrink": true, + "fontWeight": true, + "gridArea": true, + "gridColumn": true, + "gridColumnEnd": true, + "gridColumnStart": true, + "gridRow": true, + "gridRowEnd": true, + "gridRowStart": true, + "lineHeight": true, + "opacity": true, + "order": true, + "orphans": true, + "widows": true, + "zIndex": true, + "zoom": true + }, + + // Add in properties whose names you wish to fix before + // setting or getting the value + cssProps: {}, + + // Get and set the style property on a DOM Node + style: function( elem, name, value, extra ) { + + // Don't set styles on text and comment nodes + if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { + return; + } + + // Make sure that we're working with the right name + var ret, type, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ), + style = elem.style; + + // Make sure that we're working with the right name. We don't + // want to query the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Gets hook for the prefixed version, then unprefixed version + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // Check if we're setting a value + if ( value !== undefined ) { + type = typeof value; + + // Convert "+=" or "-=" to relative numbers (#7345) + if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) { + value = adjustCSS( elem, name, ret ); + + // Fixes bug #9237 + type = "number"; + } + + // Make sure that null and NaN values aren't set (#7116) + if ( value == null || value !== value ) { + return; + } + + // If a number was passed in, add the unit (except for certain CSS properties) + // The isCustomProp check can be removed in jQuery 4.0 when we only auto-append + // "px" to a few hardcoded values. + if ( type === "number" && !isCustomProp ) { + value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" ); + } + + // background-* props affect original clone's values + if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { + style[ name ] = "inherit"; + } + + // If a hook was provided, use that value, otherwise just set the specified value + if ( !hooks || !( "set" in hooks ) || + ( value = hooks.set( elem, value, extra ) ) !== undefined ) { + + if ( isCustomProp ) { + style.setProperty( name, value ); + } else { + style[ name ] = value; + } + } + + } else { + + // If a hook was provided get the non-computed value from there + if ( hooks && "get" in hooks && + ( ret = hooks.get( elem, false, extra ) ) !== undefined ) { + + return ret; + } + + // Otherwise just get the value from the style object + return style[ name ]; + } + }, + + css: function( elem, name, extra, styles ) { + var val, num, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ); + + // Make sure that we're working with the right name. We don't + // want to modify the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Try prefixed name followed by the unprefixed name + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // If a hook was provided get the computed value from there + if ( hooks && "get" in hooks ) { + val = hooks.get( elem, true, extra ); + } + + // Otherwise, if a way to get the computed value exists, use that + if ( val === undefined ) { + val = curCSS( elem, name, styles ); + } + + // Convert "normal" to computed value + if ( val === "normal" && name in cssNormalTransform ) { + val = cssNormalTransform[ name ]; + } + + // Make numeric if forced or a qualifier was provided and val looks numeric + if ( extra === "" || extra ) { + num = parseFloat( val ); + return extra === true || isFinite( num ) ? num || 0 : val; + } + + return val; + } +} ); + +jQuery.each( [ "height", "width" ], function( _i, dimension ) { + jQuery.cssHooks[ dimension ] = { + get: function( elem, computed, extra ) { + if ( computed ) { + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit + return rdisplayswap.test( jQuery.css( elem, "display" ) ) && + + // Support: Safari 8+ + // Table columns in Safari have non-zero offsetWidth & zero + // getBoundingClientRect().width unless display is changed. + // Support: IE <=11 only + // Running getBoundingClientRect on a disconnected node + // in IE throws an error. + ( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ? + swap( elem, cssShow, function() { + return getWidthOrHeight( elem, dimension, extra ); + } ) : + getWidthOrHeight( elem, dimension, extra ); + } + }, + + set: function( elem, value, extra ) { + var matches, + styles = getStyles( elem ), + + // Only read styles.position if the test has a chance to fail + // to avoid forcing a reflow. + scrollboxSizeBuggy = !support.scrollboxSize() && + styles.position === "absolute", + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-3991) + boxSizingNeeded = scrollboxSizeBuggy || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + subtract = extra ? + boxModelAdjustment( + elem, + dimension, + extra, + isBorderBox, + styles + ) : + 0; + + // Account for unreliable border-box dimensions by comparing offset* to computed and + // faking a content-box to get border and padding (gh-3699) + if ( isBorderBox && scrollboxSizeBuggy ) { + subtract -= Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + parseFloat( styles[ dimension ] ) - + boxModelAdjustment( elem, dimension, "border", false, styles ) - + 0.5 + ); + } + + // Convert to pixels if value adjustment is needed + if ( subtract && ( matches = rcssNum.exec( value ) ) && + ( matches[ 3 ] || "px" ) !== "px" ) { + + elem.style[ dimension ] = value; + value = jQuery.css( elem, dimension ); + } + + return setPositiveNumber( elem, value, subtract ); + } + }; +} ); + +jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft, + function( elem, computed ) { + if ( computed ) { + return ( parseFloat( curCSS( elem, "marginLeft" ) ) || + elem.getBoundingClientRect().left - + swap( elem, { marginLeft: 0 }, function() { + return elem.getBoundingClientRect().left; + } ) + ) + "px"; + } + } +); + +// These hooks are used by animate to expand properties +jQuery.each( { + margin: "", + padding: "", + border: "Width" +}, function( prefix, suffix ) { + jQuery.cssHooks[ prefix + suffix ] = { + expand: function( value ) { + var i = 0, + expanded = {}, + + // Assumes a single number if not a string + parts = typeof value === "string" ? value.split( " " ) : [ value ]; + + for ( ; i < 4; i++ ) { + expanded[ prefix + cssExpand[ i ] + suffix ] = + parts[ i ] || parts[ i - 2 ] || parts[ 0 ]; + } + + return expanded; + } + }; + + if ( prefix !== "margin" ) { + jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber; + } +} ); + +jQuery.fn.extend( { + css: function( name, value ) { + return access( this, function( elem, name, value ) { + var styles, len, + map = {}, + i = 0; + + if ( Array.isArray( name ) ) { + styles = getStyles( elem ); + len = name.length; + + for ( ; i < len; i++ ) { + map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles ); + } + + return map; + } + + return value !== undefined ? + jQuery.style( elem, name, value ) : + jQuery.css( elem, name ); + }, name, value, arguments.length > 1 ); + } +} ); + + +function Tween( elem, options, prop, end, easing ) { + return new Tween.prototype.init( elem, options, prop, end, easing ); +} +jQuery.Tween = Tween; + +Tween.prototype = { + constructor: Tween, + init: function( elem, options, prop, end, easing, unit ) { + this.elem = elem; + this.prop = prop; + this.easing = easing || jQuery.easing._default; + this.options = options; + this.start = this.now = this.cur(); + this.end = end; + this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" ); + }, + cur: function() { + var hooks = Tween.propHooks[ this.prop ]; + + return hooks && hooks.get ? + hooks.get( this ) : + Tween.propHooks._default.get( this ); + }, + run: function( percent ) { + var eased, + hooks = Tween.propHooks[ this.prop ]; + + if ( this.options.duration ) { + this.pos = eased = jQuery.easing[ this.easing ]( + percent, this.options.duration * percent, 0, 1, this.options.duration + ); + } else { + this.pos = eased = percent; + } + this.now = ( this.end - this.start ) * eased + this.start; + + if ( this.options.step ) { + this.options.step.call( this.elem, this.now, this ); + } + + if ( hooks && hooks.set ) { + hooks.set( this ); + } else { + Tween.propHooks._default.set( this ); + } + return this; + } +}; + +Tween.prototype.init.prototype = Tween.prototype; + +Tween.propHooks = { + _default: { + get: function( tween ) { + var result; + + // Use a property on the element directly when it is not a DOM element, + // or when there is no matching style property that exists. + if ( tween.elem.nodeType !== 1 || + tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) { + return tween.elem[ tween.prop ]; + } + + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. + result = jQuery.css( tween.elem, tween.prop, "" ); + + // Empty strings, null, undefined and "auto" are converted to 0. + return !result || result === "auto" ? 0 : result; + }, + set: function( tween ) { + + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. + if ( jQuery.fx.step[ tween.prop ] ) { + jQuery.fx.step[ tween.prop ]( tween ); + } else if ( tween.elem.nodeType === 1 && ( + jQuery.cssHooks[ tween.prop ] || + tween.elem.style[ finalPropName( tween.prop ) ] != null ) ) { + jQuery.style( tween.elem, tween.prop, tween.now + tween.unit ); + } else { + tween.elem[ tween.prop ] = tween.now; + } + } + } +}; + +// Support: IE <=9 only +// Panic based approach to setting things on disconnected nodes +Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { + set: function( tween ) { + if ( tween.elem.nodeType && tween.elem.parentNode ) { + tween.elem[ tween.prop ] = tween.now; + } + } +}; + +jQuery.easing = { + linear: function( p ) { + return p; + }, + swing: function( p ) { + return 0.5 - Math.cos( p * Math.PI ) / 2; + }, + _default: "swing" +}; + +jQuery.fx = Tween.prototype.init; + +// Back compat <1.8 extension point +jQuery.fx.step = {}; + + + + +var + fxNow, inProgress, + rfxtypes = /^(?:toggle|show|hide)$/, + rrun = /queueHooks$/; + +function schedule() { + if ( inProgress ) { + if ( document.hidden === false && window.requestAnimationFrame ) { + window.requestAnimationFrame( schedule ); + } else { + window.setTimeout( schedule, jQuery.fx.interval ); + } + + jQuery.fx.tick(); + } +} + +// Animations created synchronously will run synchronously +function createFxNow() { + window.setTimeout( function() { + fxNow = undefined; + } ); + return ( fxNow = Date.now() ); +} + +// Generate parameters to create a standard animation +function genFx( type, includeWidth ) { + var which, + i = 0, + attrs = { height: type }; + + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right + includeWidth = includeWidth ? 1 : 0; + for ( ; i < 4; i += 2 - includeWidth ) { + which = cssExpand[ i ]; + attrs[ "margin" + which ] = attrs[ "padding" + which ] = type; + } + + if ( includeWidth ) { + attrs.opacity = attrs.width = type; + } + + return attrs; +} + +function createTween( value, prop, animation ) { + var tween, + collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ), + index = 0, + length = collection.length; + for ( ; index < length; index++ ) { + if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) { + + // We're done with this property + return tween; + } + } +} + +function defaultPrefilter( elem, props, opts ) { + var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display, + isBox = "width" in props || "height" in props, + anim = this, + orig = {}, + style = elem.style, + hidden = elem.nodeType && isHiddenWithinTree( elem ), + dataShow = dataPriv.get( elem, "fxshow" ); + + // Queue-skipping animations hijack the fx hooks + if ( !opts.queue ) { + hooks = jQuery._queueHooks( elem, "fx" ); + if ( hooks.unqueued == null ) { + hooks.unqueued = 0; + oldfire = hooks.empty.fire; + hooks.empty.fire = function() { + if ( !hooks.unqueued ) { + oldfire(); + } + }; + } + hooks.unqueued++; + + anim.always( function() { + + // Ensure the complete handler is called before this completes + anim.always( function() { + hooks.unqueued--; + if ( !jQuery.queue( elem, "fx" ).length ) { + hooks.empty.fire(); + } + } ); + } ); + } + + // Detect show/hide animations + for ( prop in props ) { + value = props[ prop ]; + if ( rfxtypes.test( value ) ) { + delete props[ prop ]; + toggle = toggle || value === "toggle"; + if ( value === ( hidden ? "hide" : "show" ) ) { + + // Pretend to be hidden if this is a "show" and + // there is still data from a stopped show/hide + if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) { + hidden = true; + + // Ignore all other no-op show/hide data + } else { + continue; + } + } + orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop ); + } + } + + // Bail out if this is a no-op like .hide().hide() + propTween = !jQuery.isEmptyObject( props ); + if ( !propTween && jQuery.isEmptyObject( orig ) ) { + return; + } + + // Restrict "overflow" and "display" styles during box animations + if ( isBox && elem.nodeType === 1 ) { + + // Support: IE <=9 - 11, Edge 12 - 15 + // Record all 3 overflow attributes because IE does not infer the shorthand + // from identically-valued overflowX and overflowY and Edge just mirrors + // the overflowX value there. + opts.overflow = [ style.overflow, style.overflowX, style.overflowY ]; + + // Identify a display type, preferring old show/hide data over the CSS cascade + restoreDisplay = dataShow && dataShow.display; + if ( restoreDisplay == null ) { + restoreDisplay = dataPriv.get( elem, "display" ); + } + display = jQuery.css( elem, "display" ); + if ( display === "none" ) { + if ( restoreDisplay ) { + display = restoreDisplay; + } else { + + // Get nonempty value(s) by temporarily forcing visibility + showHide( [ elem ], true ); + restoreDisplay = elem.style.display || restoreDisplay; + display = jQuery.css( elem, "display" ); + showHide( [ elem ] ); + } + } + + // Animate inline elements as inline-block + if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) { + if ( jQuery.css( elem, "float" ) === "none" ) { + + // Restore the original display value at the end of pure show/hide animations + if ( !propTween ) { + anim.done( function() { + style.display = restoreDisplay; + } ); + if ( restoreDisplay == null ) { + display = style.display; + restoreDisplay = display === "none" ? "" : display; + } + } + style.display = "inline-block"; + } + } + } + + if ( opts.overflow ) { + style.overflow = "hidden"; + anim.always( function() { + style.overflow = opts.overflow[ 0 ]; + style.overflowX = opts.overflow[ 1 ]; + style.overflowY = opts.overflow[ 2 ]; + } ); + } + + // Implement show/hide animations + propTween = false; + for ( prop in orig ) { + + // General show/hide setup for this element animation + if ( !propTween ) { + if ( dataShow ) { + if ( "hidden" in dataShow ) { + hidden = dataShow.hidden; + } + } else { + dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } ); + } + + // Store hidden/visible for toggle so `.stop().toggle()` "reverses" + if ( toggle ) { + dataShow.hidden = !hidden; + } + + // Show elements before animating them + if ( hidden ) { + showHide( [ elem ], true ); + } + + /* eslint-disable no-loop-func */ + + anim.done( function() { + + /* eslint-enable no-loop-func */ + + // The final step of a "hide" animation is actually hiding the element + if ( !hidden ) { + showHide( [ elem ] ); + } + dataPriv.remove( elem, "fxshow" ); + for ( prop in orig ) { + jQuery.style( elem, prop, orig[ prop ] ); + } + } ); + } + + // Per-property setup + propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim ); + if ( !( prop in dataShow ) ) { + dataShow[ prop ] = propTween.start; + if ( hidden ) { + propTween.end = propTween.start; + propTween.start = 0; + } + } + } +} + +function propFilter( props, specialEasing ) { + var index, name, easing, value, hooks; + + // camelCase, specialEasing and expand cssHook pass + for ( index in props ) { + name = camelCase( index ); + easing = specialEasing[ name ]; + value = props[ index ]; + if ( Array.isArray( value ) ) { + easing = value[ 1 ]; + value = props[ index ] = value[ 0 ]; + } + + if ( index !== name ) { + props[ name ] = value; + delete props[ index ]; + } + + hooks = jQuery.cssHooks[ name ]; + if ( hooks && "expand" in hooks ) { + value = hooks.expand( value ); + delete props[ name ]; + + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" + for ( index in value ) { + if ( !( index in props ) ) { + props[ index ] = value[ index ]; + specialEasing[ index ] = easing; + } + } + } else { + specialEasing[ name ] = easing; + } + } +} + +function Animation( elem, properties, options ) { + var result, + stopped, + index = 0, + length = Animation.prefilters.length, + deferred = jQuery.Deferred().always( function() { + + // Don't match elem in the :animated selector + delete tick.elem; + } ), + tick = function() { + if ( stopped ) { + return false; + } + var currentTime = fxNow || createFxNow(), + remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), + + // Support: Android 2.3 only + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) + temp = remaining / animation.duration || 0, + percent = 1 - temp, + index = 0, + length = animation.tweens.length; + + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( percent ); + } + + deferred.notifyWith( elem, [ animation, percent, remaining ] ); + + // If there's more to do, yield + if ( percent < 1 && length ) { + return remaining; + } + + // If this was an empty animation, synthesize a final progress notification + if ( !length ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + } + + // Resolve the animation and report its conclusion + deferred.resolveWith( elem, [ animation ] ); + return false; + }, + animation = deferred.promise( { + elem: elem, + props: jQuery.extend( {}, properties ), + opts: jQuery.extend( true, { + specialEasing: {}, + easing: jQuery.easing._default + }, options ), + originalProperties: properties, + originalOptions: options, + startTime: fxNow || createFxNow(), + duration: options.duration, + tweens: [], + createTween: function( prop, end ) { + var tween = jQuery.Tween( elem, animation.opts, prop, end, + animation.opts.specialEasing[ prop ] || animation.opts.easing ); + animation.tweens.push( tween ); + return tween; + }, + stop: function( gotoEnd ) { + var index = 0, + + // If we are going to the end, we want to run all the tweens + // otherwise we skip this part + length = gotoEnd ? animation.tweens.length : 0; + if ( stopped ) { + return this; + } + stopped = true; + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( 1 ); + } + + // Resolve when we played the last frame; otherwise, reject + if ( gotoEnd ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + deferred.resolveWith( elem, [ animation, gotoEnd ] ); + } else { + deferred.rejectWith( elem, [ animation, gotoEnd ] ); + } + return this; + } + } ), + props = animation.props; + + propFilter( props, animation.opts.specialEasing ); + + for ( ; index < length; index++ ) { + result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts ); + if ( result ) { + if ( isFunction( result.stop ) ) { + jQuery._queueHooks( animation.elem, animation.opts.queue ).stop = + result.stop.bind( result ); + } + return result; + } + } + + jQuery.map( props, createTween, animation ); + + if ( isFunction( animation.opts.start ) ) { + animation.opts.start.call( elem, animation ); + } + + // Attach callbacks from options + animation + .progress( animation.opts.progress ) + .done( animation.opts.done, animation.opts.complete ) + .fail( animation.opts.fail ) + .always( animation.opts.always ); + + jQuery.fx.timer( + jQuery.extend( tick, { + elem: elem, + anim: animation, + queue: animation.opts.queue + } ) + ); + + return animation; +} + +jQuery.Animation = jQuery.extend( Animation, { + + tweeners: { + "*": [ function( prop, value ) { + var tween = this.createTween( prop, value ); + adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween ); + return tween; + } ] + }, + + tweener: function( props, callback ) { + if ( isFunction( props ) ) { + callback = props; + props = [ "*" ]; + } else { + props = props.match( rnothtmlwhite ); + } + + var prop, + index = 0, + length = props.length; + + for ( ; index < length; index++ ) { + prop = props[ index ]; + Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || []; + Animation.tweeners[ prop ].unshift( callback ); + } + }, + + prefilters: [ defaultPrefilter ], + + prefilter: function( callback, prepend ) { + if ( prepend ) { + Animation.prefilters.unshift( callback ); + } else { + Animation.prefilters.push( callback ); + } + } +} ); + +jQuery.speed = function( speed, easing, fn ) { + var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : { + complete: fn || !fn && easing || + isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !isFunction( easing ) && easing + }; + + // Go to the end state if fx are off + if ( jQuery.fx.off ) { + opt.duration = 0; + + } else { + if ( typeof opt.duration !== "number" ) { + if ( opt.duration in jQuery.fx.speeds ) { + opt.duration = jQuery.fx.speeds[ opt.duration ]; + + } else { + opt.duration = jQuery.fx.speeds._default; + } + } + } + + // Normalize opt.queue - true/undefined/null -> "fx" + if ( opt.queue == null || opt.queue === true ) { + opt.queue = "fx"; + } + + // Queueing + opt.old = opt.complete; + + opt.complete = function() { + if ( isFunction( opt.old ) ) { + opt.old.call( this ); + } + + if ( opt.queue ) { + jQuery.dequeue( this, opt.queue ); + } + }; + + return opt; +}; + +jQuery.fn.extend( { + fadeTo: function( speed, to, easing, callback ) { + + // Show any hidden elements after setting opacity to 0 + return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show() + + // Animate to the value specified + .end().animate( { opacity: to }, speed, easing, callback ); + }, + animate: function( prop, speed, easing, callback ) { + var empty = jQuery.isEmptyObject( prop ), + optall = jQuery.speed( speed, easing, callback ), + doAnimation = function() { + + // Operate on a copy of prop so per-property easing won't be lost + var anim = Animation( this, jQuery.extend( {}, prop ), optall ); + + // Empty animations, or finishing resolves immediately + if ( empty || dataPriv.get( this, "finish" ) ) { + anim.stop( true ); + } + }; + + doAnimation.finish = doAnimation; + + return empty || optall.queue === false ? + this.each( doAnimation ) : + this.queue( optall.queue, doAnimation ); + }, + stop: function( type, clearQueue, gotoEnd ) { + var stopQueue = function( hooks ) { + var stop = hooks.stop; + delete hooks.stop; + stop( gotoEnd ); + }; + + if ( typeof type !== "string" ) { + gotoEnd = clearQueue; + clearQueue = type; + type = undefined; + } + if ( clearQueue ) { + this.queue( type || "fx", [] ); + } + + return this.each( function() { + var dequeue = true, + index = type != null && type + "queueHooks", + timers = jQuery.timers, + data = dataPriv.get( this ); + + if ( index ) { + if ( data[ index ] && data[ index ].stop ) { + stopQueue( data[ index ] ); + } + } else { + for ( index in data ) { + if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) { + stopQueue( data[ index ] ); + } + } + } + + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && + ( type == null || timers[ index ].queue === type ) ) { + + timers[ index ].anim.stop( gotoEnd ); + dequeue = false; + timers.splice( index, 1 ); + } + } + + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. + if ( dequeue || !gotoEnd ) { + jQuery.dequeue( this, type ); + } + } ); + }, + finish: function( type ) { + if ( type !== false ) { + type = type || "fx"; + } + return this.each( function() { + var index, + data = dataPriv.get( this ), + queue = data[ type + "queue" ], + hooks = data[ type + "queueHooks" ], + timers = jQuery.timers, + length = queue ? queue.length : 0; + + // Enable finishing flag on private data + data.finish = true; + + // Empty the queue first + jQuery.queue( this, type, [] ); + + if ( hooks && hooks.stop ) { + hooks.stop.call( this, true ); + } + + // Look for any active animations, and finish them + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && timers[ index ].queue === type ) { + timers[ index ].anim.stop( true ); + timers.splice( index, 1 ); + } + } + + // Look for any animations in the old queue and finish them + for ( index = 0; index < length; index++ ) { + if ( queue[ index ] && queue[ index ].finish ) { + queue[ index ].finish.call( this ); + } + } + + // Turn off finishing flag + delete data.finish; + } ); + } +} ); + +jQuery.each( [ "toggle", "show", "hide" ], function( _i, name ) { + var cssFn = jQuery.fn[ name ]; + jQuery.fn[ name ] = function( speed, easing, callback ) { + return speed == null || typeof speed === "boolean" ? + cssFn.apply( this, arguments ) : + this.animate( genFx( name, true ), speed, easing, callback ); + }; +} ); + +// Generate shortcuts for custom animations +jQuery.each( { + slideDown: genFx( "show" ), + slideUp: genFx( "hide" ), + slideToggle: genFx( "toggle" ), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" }, + fadeToggle: { opacity: "toggle" } +}, function( name, props ) { + jQuery.fn[ name ] = function( speed, easing, callback ) { + return this.animate( props, speed, easing, callback ); + }; +} ); + +jQuery.timers = []; +jQuery.fx.tick = function() { + var timer, + i = 0, + timers = jQuery.timers; + + fxNow = Date.now(); + + for ( ; i < timers.length; i++ ) { + timer = timers[ i ]; + + // Run the timer and safely remove it when done (allowing for external removal) + if ( !timer() && timers[ i ] === timer ) { + timers.splice( i--, 1 ); + } + } + + if ( !timers.length ) { + jQuery.fx.stop(); + } + fxNow = undefined; +}; + +jQuery.fx.timer = function( timer ) { + jQuery.timers.push( timer ); + jQuery.fx.start(); +}; + +jQuery.fx.interval = 13; +jQuery.fx.start = function() { + if ( inProgress ) { + return; + } + + inProgress = true; + schedule(); +}; + +jQuery.fx.stop = function() { + inProgress = null; +}; + +jQuery.fx.speeds = { + slow: 600, + fast: 200, + + // Default speed + _default: 400 +}; + + +// Based off of the plugin by Clint Helfers, with permission. +// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/ +jQuery.fn.delay = function( time, type ) { + time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time; + type = type || "fx"; + + return this.queue( type, function( next, hooks ) { + var timeout = window.setTimeout( next, time ); + hooks.stop = function() { + window.clearTimeout( timeout ); + }; + } ); +}; + + +( function() { + var input = document.createElement( "input" ), + select = document.createElement( "select" ), + opt = select.appendChild( document.createElement( "option" ) ); + + input.type = "checkbox"; + + // Support: Android <=4.3 only + // Default value for a checkbox should be "on" + support.checkOn = input.value !== ""; + + // Support: IE <=11 only + // Must access selectedIndex to make default options select + support.optSelected = opt.selected; + + // Support: IE <=11 only + // An input loses its value after becoming a radio + input = document.createElement( "input" ); + input.value = "t"; + input.type = "radio"; + support.radioValue = input.value === "t"; +} )(); + + +var boolHook, + attrHandle = jQuery.expr.attrHandle; + +jQuery.fn.extend( { + attr: function( name, value ) { + return access( this, jQuery.attr, name, value, arguments.length > 1 ); + }, + + removeAttr: function( name ) { + return this.each( function() { + jQuery.removeAttr( this, name ); + } ); + } +} ); + +jQuery.extend( { + attr: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set attributes on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + // Fallback to prop when attributes are not supported + if ( typeof elem.getAttribute === "undefined" ) { + return jQuery.prop( elem, name, value ); + } + + // Attribute hooks are determined by the lowercase version + // Grab necessary hook if one is defined + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + hooks = jQuery.attrHooks[ name.toLowerCase() ] || + ( jQuery.expr.match.bool.test( name ) ? boolHook : undefined ); + } + + if ( value !== undefined ) { + if ( value === null ) { + jQuery.removeAttr( elem, name ); + return; + } + + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + elem.setAttribute( name, value + "" ); + return value; + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + ret = jQuery.find.attr( elem, name ); + + // Non-existent attributes return null, we normalize to undefined + return ret == null ? undefined : ret; + }, + + attrHooks: { + type: { + set: function( elem, value ) { + if ( !support.radioValue && value === "radio" && + nodeName( elem, "input" ) ) { + var val = elem.value; + elem.setAttribute( "type", value ); + if ( val ) { + elem.value = val; + } + return value; + } + } + } + }, + + removeAttr: function( elem, value ) { + var name, + i = 0, + + // Attribute names can contain non-HTML whitespace characters + // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 + attrNames = value && value.match( rnothtmlwhite ); + + if ( attrNames && elem.nodeType === 1 ) { + while ( ( name = attrNames[ i++ ] ) ) { + elem.removeAttribute( name ); + } + } + } +} ); + +// Hooks for boolean attributes +boolHook = { + set: function( elem, value, name ) { + if ( value === false ) { + + // Remove boolean attributes when set to false + jQuery.removeAttr( elem, name ); + } else { + elem.setAttribute( name, name ); + } + return name; + } +}; + +jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( _i, name ) { + var getter = attrHandle[ name ] || jQuery.find.attr; + + attrHandle[ name ] = function( elem, name, isXML ) { + var ret, handle, + lowercaseName = name.toLowerCase(); + + if ( !isXML ) { + + // Avoid an infinite loop by temporarily removing this function from the getter + handle = attrHandle[ lowercaseName ]; + attrHandle[ lowercaseName ] = ret; + ret = getter( elem, name, isXML ) != null ? + lowercaseName : + null; + attrHandle[ lowercaseName ] = handle; + } + return ret; + }; +} ); + + + + +var rfocusable = /^(?:input|select|textarea|button)$/i, + rclickable = /^(?:a|area)$/i; + +jQuery.fn.extend( { + prop: function( name, value ) { + return access( this, jQuery.prop, name, value, arguments.length > 1 ); + }, + + removeProp: function( name ) { + return this.each( function() { + delete this[ jQuery.propFix[ name ] || name ]; + } ); + } +} ); + +jQuery.extend( { + prop: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set properties on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + + // Fix name and attach hooks + name = jQuery.propFix[ name ] || name; + hooks = jQuery.propHooks[ name ]; + } + + if ( value !== undefined ) { + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + return ( elem[ name ] = value ); + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + return elem[ name ]; + }, + + propHooks: { + tabIndex: { + get: function( elem ) { + + // Support: IE <=9 - 11 only + // elem.tabIndex doesn't always return the + // correct value when it hasn't been explicitly set + // https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + // Use proper attribute retrieval(#12072) + var tabindex = jQuery.find.attr( elem, "tabindex" ); + + if ( tabindex ) { + return parseInt( tabindex, 10 ); + } + + if ( + rfocusable.test( elem.nodeName ) || + rclickable.test( elem.nodeName ) && + elem.href + ) { + return 0; + } + + return -1; + } + } + }, + + propFix: { + "for": "htmlFor", + "class": "className" + } +} ); + +// Support: IE <=11 only +// Accessing the selectedIndex property +// forces the browser to respect setting selected +// on the option +// The getter ensures a default option is selected +// when in an optgroup +// eslint rule "no-unused-expressions" is disabled for this code +// since it considers such accessions noop +if ( !support.optSelected ) { + jQuery.propHooks.selected = { + get: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent && parent.parentNode ) { + parent.parentNode.selectedIndex; + } + return null; + }, + set: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent ) { + parent.selectedIndex; + + if ( parent.parentNode ) { + parent.parentNode.selectedIndex; + } + } + } + }; +} + +jQuery.each( [ + "tabIndex", + "readOnly", + "maxLength", + "cellSpacing", + "cellPadding", + "rowSpan", + "colSpan", + "useMap", + "frameBorder", + "contentEditable" +], function() { + jQuery.propFix[ this.toLowerCase() ] = this; +} ); + + + + + // Strip and collapse whitespace according to HTML spec + // https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace + function stripAndCollapse( value ) { + var tokens = value.match( rnothtmlwhite ) || []; + return tokens.join( " " ); + } + + +function getClass( elem ) { + return elem.getAttribute && elem.getAttribute( "class" ) || ""; +} + +function classesToArray( value ) { + if ( Array.isArray( value ) ) { + return value; + } + if ( typeof value === "string" ) { + return value.match( rnothtmlwhite ) || []; + } + return []; +} + +jQuery.fn.extend( { + addClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).addClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + if ( cur.indexOf( " " + clazz + " " ) < 0 ) { + cur += clazz + " "; + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + removeClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + if ( !arguments.length ) { + return this.attr( "class", "" ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + + // This expression is here for better compressibility (see addClass) + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + + // Remove *all* instances + while ( cur.indexOf( " " + clazz + " " ) > -1 ) { + cur = cur.replace( " " + clazz + " ", " " ); + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + toggleClass: function( value, stateVal ) { + var type = typeof value, + isValidValue = type === "string" || Array.isArray( value ); + + if ( typeof stateVal === "boolean" && isValidValue ) { + return stateVal ? this.addClass( value ) : this.removeClass( value ); + } + + if ( isFunction( value ) ) { + return this.each( function( i ) { + jQuery( this ).toggleClass( + value.call( this, i, getClass( this ), stateVal ), + stateVal + ); + } ); + } + + return this.each( function() { + var className, i, self, classNames; + + if ( isValidValue ) { + + // Toggle individual class names + i = 0; + self = jQuery( this ); + classNames = classesToArray( value ); + + while ( ( className = classNames[ i++ ] ) ) { + + // Check each className given, space separated list + if ( self.hasClass( className ) ) { + self.removeClass( className ); + } else { + self.addClass( className ); + } + } + + // Toggle whole class name + } else if ( value === undefined || type === "boolean" ) { + className = getClass( this ); + if ( className ) { + + // Store className if set + dataPriv.set( this, "__className__", className ); + } + + // If the element has a class name or if we're passed `false`, + // then remove the whole classname (if there was one, the above saved it). + // Otherwise bring back whatever was previously saved (if anything), + // falling back to the empty string if nothing was stored. + if ( this.setAttribute ) { + this.setAttribute( "class", + className || value === false ? + "" : + dataPriv.get( this, "__className__" ) || "" + ); + } + } + } ); + }, + + hasClass: function( selector ) { + var className, elem, + i = 0; + + className = " " + selector + " "; + while ( ( elem = this[ i++ ] ) ) { + if ( elem.nodeType === 1 && + ( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) { + return true; + } + } + + return false; + } +} ); + + + + +var rreturn = /\r/g; + +jQuery.fn.extend( { + val: function( value ) { + var hooks, ret, valueIsFunction, + elem = this[ 0 ]; + + if ( !arguments.length ) { + if ( elem ) { + hooks = jQuery.valHooks[ elem.type ] || + jQuery.valHooks[ elem.nodeName.toLowerCase() ]; + + if ( hooks && + "get" in hooks && + ( ret = hooks.get( elem, "value" ) ) !== undefined + ) { + return ret; + } + + ret = elem.value; + + // Handle most common string cases + if ( typeof ret === "string" ) { + return ret.replace( rreturn, "" ); + } + + // Handle cases where value is null/undef or number + return ret == null ? "" : ret; + } + + return; + } + + valueIsFunction = isFunction( value ); + + return this.each( function( i ) { + var val; + + if ( this.nodeType !== 1 ) { + return; + } + + if ( valueIsFunction ) { + val = value.call( this, i, jQuery( this ).val() ); + } else { + val = value; + } + + // Treat null/undefined as ""; convert numbers to string + if ( val == null ) { + val = ""; + + } else if ( typeof val === "number" ) { + val += ""; + + } else if ( Array.isArray( val ) ) { + val = jQuery.map( val, function( value ) { + return value == null ? "" : value + ""; + } ); + } + + hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ]; + + // If set returns undefined, fall back to normal setting + if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) { + this.value = val; + } + } ); + } +} ); + +jQuery.extend( { + valHooks: { + option: { + get: function( elem ) { + + var val = jQuery.find.attr( elem, "value" ); + return val != null ? + val : + + // Support: IE <=10 - 11 only + // option.text throws exceptions (#14686, #14858) + // Strip and collapse whitespace + // https://html.spec.whatwg.org/#strip-and-collapse-whitespace + stripAndCollapse( jQuery.text( elem ) ); + } + }, + select: { + get: function( elem ) { + var value, option, i, + options = elem.options, + index = elem.selectedIndex, + one = elem.type === "select-one", + values = one ? null : [], + max = one ? index + 1 : options.length; + + if ( index < 0 ) { + i = max; + + } else { + i = one ? index : 0; + } + + // Loop through all the selected options + for ( ; i < max; i++ ) { + option = options[ i ]; + + // Support: IE <=9 only + // IE8-9 doesn't update selected after form reset (#2551) + if ( ( option.selected || i === index ) && + + // Don't return options that are disabled or in a disabled optgroup + !option.disabled && + ( !option.parentNode.disabled || + !nodeName( option.parentNode, "optgroup" ) ) ) { + + // Get the specific value for the option + value = jQuery( option ).val(); + + // We don't need an array for one selects + if ( one ) { + return value; + } + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + }, + + set: function( elem, value ) { + var optionSet, option, + options = elem.options, + values = jQuery.makeArray( value ), + i = options.length; + + while ( i-- ) { + option = options[ i ]; + + /* eslint-disable no-cond-assign */ + + if ( option.selected = + jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1 + ) { + optionSet = true; + } + + /* eslint-enable no-cond-assign */ + } + + // Force browsers to behave consistently when non-matching value is set + if ( !optionSet ) { + elem.selectedIndex = -1; + } + return values; + } + } + } +} ); + +// Radios and checkboxes getter/setter +jQuery.each( [ "radio", "checkbox" ], function() { + jQuery.valHooks[ this ] = { + set: function( elem, value ) { + if ( Array.isArray( value ) ) { + return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 ); + } + } + }; + if ( !support.checkOn ) { + jQuery.valHooks[ this ].get = function( elem ) { + return elem.getAttribute( "value" ) === null ? "on" : elem.value; + }; + } +} ); + + + + +// Return jQuery for attributes-only inclusion + + +support.focusin = "onfocusin" in window; + + +var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/, + stopPropagationCallback = function( e ) { + e.stopPropagation(); + }; + +jQuery.extend( jQuery.event, { + + trigger: function( event, data, elem, onlyHandlers ) { + + var i, cur, tmp, bubbleType, ontype, handle, special, lastElement, + eventPath = [ elem || document ], + type = hasOwn.call( event, "type" ) ? event.type : event, + namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : []; + + cur = lastElement = tmp = elem = elem || document; + + // Don't do events on text and comment nodes + if ( elem.nodeType === 3 || elem.nodeType === 8 ) { + return; + } + + // focus/blur morphs to focusin/out; ensure we're not firing them right now + if ( rfocusMorph.test( type + jQuery.event.triggered ) ) { + return; + } + + if ( type.indexOf( "." ) > -1 ) { + + // Namespaced trigger; create a regexp to match event type in handle() + namespaces = type.split( "." ); + type = namespaces.shift(); + namespaces.sort(); + } + ontype = type.indexOf( ":" ) < 0 && "on" + type; + + // Caller can pass in a jQuery.Event object, Object, or just an event type string + event = event[ jQuery.expando ] ? + event : + new jQuery.Event( type, typeof event === "object" && event ); + + // Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true) + event.isTrigger = onlyHandlers ? 2 : 3; + event.namespace = namespaces.join( "." ); + event.rnamespace = event.namespace ? + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) : + null; + + // Clean up the event in case it is being reused + event.result = undefined; + if ( !event.target ) { + event.target = elem; + } + + // Clone any incoming data and prepend the event, creating the handler arg list + data = data == null ? + [ event ] : + jQuery.makeArray( data, [ event ] ); + + // Allow special events to draw outside the lines + special = jQuery.event.special[ type ] || {}; + if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) { + return; + } + + // Determine event propagation path in advance, per W3C events spec (#9951) + // Bubble up to document, then to window; watch for a global ownerDocument var (#9724) + if ( !onlyHandlers && !special.noBubble && !isWindow( elem ) ) { + + bubbleType = special.delegateType || type; + if ( !rfocusMorph.test( bubbleType + type ) ) { + cur = cur.parentNode; + } + for ( ; cur; cur = cur.parentNode ) { + eventPath.push( cur ); + tmp = cur; + } + + // Only add window if we got to document (e.g., not plain obj or detached DOM) + if ( tmp === ( elem.ownerDocument || document ) ) { + eventPath.push( tmp.defaultView || tmp.parentWindow || window ); + } + } + + // Fire handlers on the event path + i = 0; + while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) { + lastElement = cur; + event.type = i > 1 ? + bubbleType : + special.bindType || type; + + // jQuery handler + handle = ( dataPriv.get( cur, "events" ) || Object.create( null ) )[ event.type ] && + dataPriv.get( cur, "handle" ); + if ( handle ) { + handle.apply( cur, data ); + } + + // Native handler + handle = ontype && cur[ ontype ]; + if ( handle && handle.apply && acceptData( cur ) ) { + event.result = handle.apply( cur, data ); + if ( event.result === false ) { + event.preventDefault(); + } + } + } + event.type = type; + + // If nobody prevented the default action, do it now + if ( !onlyHandlers && !event.isDefaultPrevented() ) { + + if ( ( !special._default || + special._default.apply( eventPath.pop(), data ) === false ) && + acceptData( elem ) ) { + + // Call a native DOM method on the target with the same name as the event. + // Don't do default actions on window, that's where global variables be (#6170) + if ( ontype && isFunction( elem[ type ] ) && !isWindow( elem ) ) { + + // Don't re-trigger an onFOO event when we call its FOO() method + tmp = elem[ ontype ]; + + if ( tmp ) { + elem[ ontype ] = null; + } + + // Prevent re-triggering of the same event, since we already bubbled it above + jQuery.event.triggered = type; + + if ( event.isPropagationStopped() ) { + lastElement.addEventListener( type, stopPropagationCallback ); + } + + elem[ type ](); + + if ( event.isPropagationStopped() ) { + lastElement.removeEventListener( type, stopPropagationCallback ); + } + + jQuery.event.triggered = undefined; + + if ( tmp ) { + elem[ ontype ] = tmp; + } + } + } + } + + return event.result; + }, + + // Piggyback on a donor event to simulate a different one + // Used only for `focus(in | out)` events + simulate: function( type, elem, event ) { + var e = jQuery.extend( + new jQuery.Event(), + event, + { + type: type, + isSimulated: true + } + ); + + jQuery.event.trigger( e, null, elem ); + } + +} ); + +jQuery.fn.extend( { + + trigger: function( type, data ) { + return this.each( function() { + jQuery.event.trigger( type, data, this ); + } ); + }, + triggerHandler: function( type, data ) { + var elem = this[ 0 ]; + if ( elem ) { + return jQuery.event.trigger( type, data, elem, true ); + } + } +} ); + + +// Support: Firefox <=44 +// Firefox doesn't have focus(in | out) events +// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787 +// +// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1 +// focus(in | out) events fire after focus & blur events, +// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order +// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857 +if ( !support.focusin ) { + jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) { + + // Attach a single capturing handler on the document while someone wants focusin/focusout + var handler = function( event ) { + jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) ); + }; + + jQuery.event.special[ fix ] = { + setup: function() { + + // Handle: regular nodes (via `this.ownerDocument`), window + // (via `this.document`) & document (via `this`). + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ); + + if ( !attaches ) { + doc.addEventListener( orig, handler, true ); + } + dataPriv.access( doc, fix, ( attaches || 0 ) + 1 ); + }, + teardown: function() { + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ) - 1; + + if ( !attaches ) { + doc.removeEventListener( orig, handler, true ); + dataPriv.remove( doc, fix ); + + } else { + dataPriv.access( doc, fix, attaches ); + } + } + }; + } ); +} +var location = window.location; + +var nonce = { guid: Date.now() }; + +var rquery = ( /\?/ ); + + + +// Cross-browser xml parsing +jQuery.parseXML = function( data ) { + var xml, parserErrorElem; + if ( !data || typeof data !== "string" ) { + return null; + } + + // Support: IE 9 - 11 only + // IE throws on parseFromString with invalid input. + try { + xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" ); + } catch ( e ) {} + + parserErrorElem = xml && xml.getElementsByTagName( "parsererror" )[ 0 ]; + if ( !xml || parserErrorElem ) { + jQuery.error( "Invalid XML: " + ( + parserErrorElem ? + jQuery.map( parserErrorElem.childNodes, function( el ) { + return el.textContent; + } ).join( "\n" ) : + data + ) ); + } + return xml; +}; + + +var + rbracket = /\[\]$/, + rCRLF = /\r?\n/g, + rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i, + rsubmittable = /^(?:input|select|textarea|keygen)/i; + +function buildParams( prefix, obj, traditional, add ) { + var name; + + if ( Array.isArray( obj ) ) { + + // Serialize array item. + jQuery.each( obj, function( i, v ) { + if ( traditional || rbracket.test( prefix ) ) { + + // Treat each array item as a scalar. + add( prefix, v ); + + } else { + + // Item is non-scalar (array or object), encode its numeric index. + buildParams( + prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]", + v, + traditional, + add + ); + } + } ); + + } else if ( !traditional && toType( obj ) === "object" ) { + + // Serialize object item. + for ( name in obj ) { + buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add ); + } + + } else { + + // Serialize scalar item. + add( prefix, obj ); + } +} + +// Serialize an array of form elements or a set of +// key/values into a query string +jQuery.param = function( a, traditional ) { + var prefix, + s = [], + add = function( key, valueOrFunction ) { + + // If value is a function, invoke it and use its return value + var value = isFunction( valueOrFunction ) ? + valueOrFunction() : + valueOrFunction; + + s[ s.length ] = encodeURIComponent( key ) + "=" + + encodeURIComponent( value == null ? "" : value ); + }; + + if ( a == null ) { + return ""; + } + + // If an array was passed in, assume that it is an array of form elements. + if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) { + + // Serialize the form elements + jQuery.each( a, function() { + add( this.name, this.value ); + } ); + + } else { + + // If traditional, encode the "old" way (the way 1.3.2 or older + // did it), otherwise encode params recursively. + for ( prefix in a ) { + buildParams( prefix, a[ prefix ], traditional, add ); + } + } + + // Return the resulting serialization + return s.join( "&" ); +}; + +jQuery.fn.extend( { + serialize: function() { + return jQuery.param( this.serializeArray() ); + }, + serializeArray: function() { + return this.map( function() { + + // Can add propHook for "elements" to filter or add form elements + var elements = jQuery.prop( this, "elements" ); + return elements ? jQuery.makeArray( elements ) : this; + } ).filter( function() { + var type = this.type; + + // Use .is( ":disabled" ) so that fieldset[disabled] works + return this.name && !jQuery( this ).is( ":disabled" ) && + rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) && + ( this.checked || !rcheckableType.test( type ) ); + } ).map( function( _i, elem ) { + var val = jQuery( this ).val(); + + if ( val == null ) { + return null; + } + + if ( Array.isArray( val ) ) { + return jQuery.map( val, function( val ) { + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ); + } + + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ).get(); + } +} ); + + +var + r20 = /%20/g, + rhash = /#.*$/, + rantiCache = /([?&])_=[^&]*/, + rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg, + + // #7653, #8125, #8152: local protocol detection + rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/, + rnoContent = /^(?:GET|HEAD)$/, + rprotocol = /^\/\//, + + /* Prefilters + * 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example) + * 2) These are called: + * - BEFORE asking for a transport + * - AFTER param serialization (s.data is a string if s.processData is true) + * 3) key is the dataType + * 4) the catchall symbol "*" can be used + * 5) execution will start with transport dataType and THEN continue down to "*" if needed + */ + prefilters = {}, + + /* Transports bindings + * 1) key is the dataType + * 2) the catchall symbol "*" can be used + * 3) selection will start with transport dataType and THEN go to "*" if needed + */ + transports = {}, + + // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression + allTypes = "*/".concat( "*" ), + + // Anchor tag for parsing the document origin + originAnchor = document.createElement( "a" ); + +originAnchor.href = location.href; + +// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport +function addToPrefiltersOrTransports( structure ) { + + // dataTypeExpression is optional and defaults to "*" + return function( dataTypeExpression, func ) { + + if ( typeof dataTypeExpression !== "string" ) { + func = dataTypeExpression; + dataTypeExpression = "*"; + } + + var dataType, + i = 0, + dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || []; + + if ( isFunction( func ) ) { + + // For each dataType in the dataTypeExpression + while ( ( dataType = dataTypes[ i++ ] ) ) { + + // Prepend if requested + if ( dataType[ 0 ] === "+" ) { + dataType = dataType.slice( 1 ) || "*"; + ( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func ); + + // Otherwise append + } else { + ( structure[ dataType ] = structure[ dataType ] || [] ).push( func ); + } + } + } + }; +} + +// Base inspection function for prefilters and transports +function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) { + + var inspected = {}, + seekingTransport = ( structure === transports ); + + function inspect( dataType ) { + var selected; + inspected[ dataType ] = true; + jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) { + var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR ); + if ( typeof dataTypeOrTransport === "string" && + !seekingTransport && !inspected[ dataTypeOrTransport ] ) { + + options.dataTypes.unshift( dataTypeOrTransport ); + inspect( dataTypeOrTransport ); + return false; + } else if ( seekingTransport ) { + return !( selected = dataTypeOrTransport ); + } + } ); + return selected; + } + + return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" ); +} + +// A special extend for ajax options +// that takes "flat" options (not to be deep extended) +// Fixes #9887 +function ajaxExtend( target, src ) { + var key, deep, + flatOptions = jQuery.ajaxSettings.flatOptions || {}; + + for ( key in src ) { + if ( src[ key ] !== undefined ) { + ( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ]; + } + } + if ( deep ) { + jQuery.extend( true, target, deep ); + } + + return target; +} + +/* Handles responses to an ajax request: + * - finds the right dataType (mediates between content-type and expected dataType) + * - returns the corresponding response + */ +function ajaxHandleResponses( s, jqXHR, responses ) { + + var ct, type, finalDataType, firstDataType, + contents = s.contents, + dataTypes = s.dataTypes; + + // Remove auto dataType and get content-type in the process + while ( dataTypes[ 0 ] === "*" ) { + dataTypes.shift(); + if ( ct === undefined ) { + ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" ); + } + } + + // Check if we're dealing with a known content-type + if ( ct ) { + for ( type in contents ) { + if ( contents[ type ] && contents[ type ].test( ct ) ) { + dataTypes.unshift( type ); + break; + } + } + } + + // Check to see if we have a response for the expected dataType + if ( dataTypes[ 0 ] in responses ) { + finalDataType = dataTypes[ 0 ]; + } else { + + // Try convertible dataTypes + for ( type in responses ) { + if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) { + finalDataType = type; + break; + } + if ( !firstDataType ) { + firstDataType = type; + } + } + + // Or just use first one + finalDataType = finalDataType || firstDataType; + } + + // If we found a dataType + // We add the dataType to the list if needed + // and return the corresponding response + if ( finalDataType ) { + if ( finalDataType !== dataTypes[ 0 ] ) { + dataTypes.unshift( finalDataType ); + } + return responses[ finalDataType ]; + } +} + +/* Chain conversions given the request and the original response + * Also sets the responseXXX fields on the jqXHR instance + */ +function ajaxConvert( s, response, jqXHR, isSuccess ) { + var conv2, current, conv, tmp, prev, + converters = {}, + + // Work with a copy of dataTypes in case we need to modify it for conversion + dataTypes = s.dataTypes.slice(); + + // Create converters map with lowercased keys + if ( dataTypes[ 1 ] ) { + for ( conv in s.converters ) { + converters[ conv.toLowerCase() ] = s.converters[ conv ]; + } + } + + current = dataTypes.shift(); + + // Convert to each sequential dataType + while ( current ) { + + if ( s.responseFields[ current ] ) { + jqXHR[ s.responseFields[ current ] ] = response; + } + + // Apply the dataFilter if provided + if ( !prev && isSuccess && s.dataFilter ) { + response = s.dataFilter( response, s.dataType ); + } + + prev = current; + current = dataTypes.shift(); + + if ( current ) { + + // There's only work to do if current dataType is non-auto + if ( current === "*" ) { + + current = prev; + + // Convert response if prev dataType is non-auto and differs from current + } else if ( prev !== "*" && prev !== current ) { + + // Seek a direct converter + conv = converters[ prev + " " + current ] || converters[ "* " + current ]; + + // If none found, seek a pair + if ( !conv ) { + for ( conv2 in converters ) { + + // If conv2 outputs current + tmp = conv2.split( " " ); + if ( tmp[ 1 ] === current ) { + + // If prev can be converted to accepted input + conv = converters[ prev + " " + tmp[ 0 ] ] || + converters[ "* " + tmp[ 0 ] ]; + if ( conv ) { + + // Condense equivalence converters + if ( conv === true ) { + conv = converters[ conv2 ]; + + // Otherwise, insert the intermediate dataType + } else if ( converters[ conv2 ] !== true ) { + current = tmp[ 0 ]; + dataTypes.unshift( tmp[ 1 ] ); + } + break; + } + } + } + } + + // Apply converter (if not an equivalence) + if ( conv !== true ) { + + // Unless errors are allowed to bubble, catch and return them + if ( conv && s.throws ) { + response = conv( response ); + } else { + try { + response = conv( response ); + } catch ( e ) { + return { + state: "parsererror", + error: conv ? e : "No conversion from " + prev + " to " + current + }; + } + } + } + } + } + } + + return { state: "success", data: response }; +} + +jQuery.extend( { + + // Counter for holding the number of active queries + active: 0, + + // Last-Modified header cache for next request + lastModified: {}, + etag: {}, + + ajaxSettings: { + url: location.href, + type: "GET", + isLocal: rlocalProtocol.test( location.protocol ), + global: true, + processData: true, + async: true, + contentType: "application/x-www-form-urlencoded; charset=UTF-8", + + /* + timeout: 0, + data: null, + dataType: null, + username: null, + password: null, + cache: null, + throws: false, + traditional: false, + headers: {}, + */ + + accepts: { + "*": allTypes, + text: "text/plain", + html: "text/html", + xml: "application/xml, text/xml", + json: "application/json, text/javascript" + }, + + contents: { + xml: /\bxml\b/, + html: /\bhtml/, + json: /\bjson\b/ + }, + + responseFields: { + xml: "responseXML", + text: "responseText", + json: "responseJSON" + }, + + // Data converters + // Keys separate source (or catchall "*") and destination types with a single space + converters: { + + // Convert anything to text + "* text": String, + + // Text to html (true = no transformation) + "text html": true, + + // Evaluate text as a json expression + "text json": JSON.parse, + + // Parse text as xml + "text xml": jQuery.parseXML + }, + + // For options that shouldn't be deep extended: + // you can add your own custom options here if + // and when you create one that shouldn't be + // deep extended (see ajaxExtend) + flatOptions: { + url: true, + context: true + } + }, + + // Creates a full fledged settings object into target + // with both ajaxSettings and settings fields. + // If target is omitted, writes into ajaxSettings. + ajaxSetup: function( target, settings ) { + return settings ? + + // Building a settings object + ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) : + + // Extending ajaxSettings + ajaxExtend( jQuery.ajaxSettings, target ); + }, + + ajaxPrefilter: addToPrefiltersOrTransports( prefilters ), + ajaxTransport: addToPrefiltersOrTransports( transports ), + + // Main method + ajax: function( url, options ) { + + // If url is an object, simulate pre-1.5 signature + if ( typeof url === "object" ) { + options = url; + url = undefined; + } + + // Force options to be an object + options = options || {}; + + var transport, + + // URL without anti-cache param + cacheURL, + + // Response headers + responseHeadersString, + responseHeaders, + + // timeout handle + timeoutTimer, + + // Url cleanup var + urlAnchor, + + // Request state (becomes false upon send and true upon completion) + completed, + + // To know if global events are to be dispatched + fireGlobals, + + // Loop variable + i, + + // uncached part of the url + uncached, + + // Create the final options object + s = jQuery.ajaxSetup( {}, options ), + + // Callbacks context + callbackContext = s.context || s, + + // Context for global events is callbackContext if it is a DOM node or jQuery collection + globalEventContext = s.context && + ( callbackContext.nodeType || callbackContext.jquery ) ? + jQuery( callbackContext ) : + jQuery.event, + + // Deferreds + deferred = jQuery.Deferred(), + completeDeferred = jQuery.Callbacks( "once memory" ), + + // Status-dependent callbacks + statusCode = s.statusCode || {}, + + // Headers (they are sent all at once) + requestHeaders = {}, + requestHeadersNames = {}, + + // Default abort message + strAbort = "canceled", + + // Fake xhr + jqXHR = { + readyState: 0, + + // Builds headers hashtable if needed + getResponseHeader: function( key ) { + var match; + if ( completed ) { + if ( !responseHeaders ) { + responseHeaders = {}; + while ( ( match = rheaders.exec( responseHeadersString ) ) ) { + responseHeaders[ match[ 1 ].toLowerCase() + " " ] = + ( responseHeaders[ match[ 1 ].toLowerCase() + " " ] || [] ) + .concat( match[ 2 ] ); + } + } + match = responseHeaders[ key.toLowerCase() + " " ]; + } + return match == null ? null : match.join( ", " ); + }, + + // Raw string + getAllResponseHeaders: function() { + return completed ? responseHeadersString : null; + }, + + // Caches the header + setRequestHeader: function( name, value ) { + if ( completed == null ) { + name = requestHeadersNames[ name.toLowerCase() ] = + requestHeadersNames[ name.toLowerCase() ] || name; + requestHeaders[ name ] = value; + } + return this; + }, + + // Overrides response content-type header + overrideMimeType: function( type ) { + if ( completed == null ) { + s.mimeType = type; + } + return this; + }, + + // Status-dependent callbacks + statusCode: function( map ) { + var code; + if ( map ) { + if ( completed ) { + + // Execute the appropriate callbacks + jqXHR.always( map[ jqXHR.status ] ); + } else { + + // Lazy-add the new callbacks in a way that preserves old ones + for ( code in map ) { + statusCode[ code ] = [ statusCode[ code ], map[ code ] ]; + } + } + } + return this; + }, + + // Cancel the request + abort: function( statusText ) { + var finalText = statusText || strAbort; + if ( transport ) { + transport.abort( finalText ); + } + done( 0, finalText ); + return this; + } + }; + + // Attach deferreds + deferred.promise( jqXHR ); + + // Add protocol if not provided (prefilters might expect it) + // Handle falsy url in the settings object (#10093: consistency with old signature) + // We also use the url parameter if available + s.url = ( ( url || s.url || location.href ) + "" ) + .replace( rprotocol, location.protocol + "//" ); + + // Alias method option to type as per ticket #12004 + s.type = options.method || options.type || s.method || s.type; + + // Extract dataTypes list + s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ]; + + // A cross-domain request is in order when the origin doesn't match the current origin. + if ( s.crossDomain == null ) { + urlAnchor = document.createElement( "a" ); + + // Support: IE <=8 - 11, Edge 12 - 15 + // IE throws exception on accessing the href property if url is malformed, + // e.g. http://example.com:80x/ + try { + urlAnchor.href = s.url; + + // Support: IE <=8 - 11 only + // Anchor's host property isn't correctly set when s.url is relative + urlAnchor.href = urlAnchor.href; + s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !== + urlAnchor.protocol + "//" + urlAnchor.host; + } catch ( e ) { + + // If there is an error parsing the URL, assume it is crossDomain, + // it can be rejected by the transport if it is invalid + s.crossDomain = true; + } + } + + // Convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) { + s.data = jQuery.param( s.data, s.traditional ); + } + + // Apply prefilters + inspectPrefiltersOrTransports( prefilters, s, options, jqXHR ); + + // If request was aborted inside a prefilter, stop there + if ( completed ) { + return jqXHR; + } + + // We can fire global events as of now if asked to + // Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118) + fireGlobals = jQuery.event && s.global; + + // Watch for a new set of requests + if ( fireGlobals && jQuery.active++ === 0 ) { + jQuery.event.trigger( "ajaxStart" ); + } + + // Uppercase the type + s.type = s.type.toUpperCase(); + + // Determine if request has content + s.hasContent = !rnoContent.test( s.type ); + + // Save the URL in case we're toying with the If-Modified-Since + // and/or If-None-Match header later on + // Remove hash to simplify url manipulation + cacheURL = s.url.replace( rhash, "" ); + + // More options handling for requests with no content + if ( !s.hasContent ) { + + // Remember the hash so we can put it back + uncached = s.url.slice( cacheURL.length ); + + // If data is available and should be processed, append data to url + if ( s.data && ( s.processData || typeof s.data === "string" ) ) { + cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data; + + // #9682: remove data so that it's not used in an eventual retry + delete s.data; + } + + // Add or update anti-cache param if needed + if ( s.cache === false ) { + cacheURL = cacheURL.replace( rantiCache, "$1" ); + uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce.guid++ ) + + uncached; + } + + // Put hash and anti-cache on the URL that will be requested (gh-1732) + s.url = cacheURL + uncached; + + // Change '%20' to '+' if this is encoded form body content (gh-2658) + } else if ( s.data && s.processData && + ( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) { + s.data = s.data.replace( r20, "+" ); + } + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + if ( jQuery.lastModified[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] ); + } + if ( jQuery.etag[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] ); + } + } + + // Set the correct header, if data is being sent + if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) { + jqXHR.setRequestHeader( "Content-Type", s.contentType ); + } + + // Set the Accepts header for the server, depending on the dataType + jqXHR.setRequestHeader( + "Accept", + s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ? + s.accepts[ s.dataTypes[ 0 ] ] + + ( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) : + s.accepts[ "*" ] + ); + + // Check for headers option + for ( i in s.headers ) { + jqXHR.setRequestHeader( i, s.headers[ i ] ); + } + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && + ( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) { + + // Abort if not done already and return + return jqXHR.abort(); + } + + // Aborting is no longer a cancellation + strAbort = "abort"; + + // Install callbacks on deferreds + completeDeferred.add( s.complete ); + jqXHR.done( s.success ); + jqXHR.fail( s.error ); + + // Get transport + transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR ); + + // If no transport, we auto-abort + if ( !transport ) { + done( -1, "No Transport" ); + } else { + jqXHR.readyState = 1; + + // Send global event + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] ); + } + + // If request was aborted inside ajaxSend, stop there + if ( completed ) { + return jqXHR; + } + + // Timeout + if ( s.async && s.timeout > 0 ) { + timeoutTimer = window.setTimeout( function() { + jqXHR.abort( "timeout" ); + }, s.timeout ); + } + + try { + completed = false; + transport.send( requestHeaders, done ); + } catch ( e ) { + + // Rethrow post-completion exceptions + if ( completed ) { + throw e; + } + + // Propagate others as results + done( -1, e ); + } + } + + // Callback for when everything is done + function done( status, nativeStatusText, responses, headers ) { + var isSuccess, success, error, response, modified, + statusText = nativeStatusText; + + // Ignore repeat invocations + if ( completed ) { + return; + } + + completed = true; + + // Clear timeout if it exists + if ( timeoutTimer ) { + window.clearTimeout( timeoutTimer ); + } + + // Dereference transport for early garbage collection + // (no matter how long the jqXHR object will be used) + transport = undefined; + + // Cache response headers + responseHeadersString = headers || ""; + + // Set readyState + jqXHR.readyState = status > 0 ? 4 : 0; + + // Determine if successful + isSuccess = status >= 200 && status < 300 || status === 304; + + // Get response data + if ( responses ) { + response = ajaxHandleResponses( s, jqXHR, responses ); + } + + // Use a noop converter for missing script but not if jsonp + if ( !isSuccess && + jQuery.inArray( "script", s.dataTypes ) > -1 && + jQuery.inArray( "json", s.dataTypes ) < 0 ) { + s.converters[ "text script" ] = function() {}; + } + + // Convert no matter what (that way responseXXX fields are always set) + response = ajaxConvert( s, response, jqXHR, isSuccess ); + + // If successful, handle type chaining + if ( isSuccess ) { + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + modified = jqXHR.getResponseHeader( "Last-Modified" ); + if ( modified ) { + jQuery.lastModified[ cacheURL ] = modified; + } + modified = jqXHR.getResponseHeader( "etag" ); + if ( modified ) { + jQuery.etag[ cacheURL ] = modified; + } + } + + // if no content + if ( status === 204 || s.type === "HEAD" ) { + statusText = "nocontent"; + + // if not modified + } else if ( status === 304 ) { + statusText = "notmodified"; + + // If we have data, let's convert it + } else { + statusText = response.state; + success = response.data; + error = response.error; + isSuccess = !error; + } + } else { + + // Extract error from statusText and normalize for non-aborts + error = statusText; + if ( status || !statusText ) { + statusText = "error"; + if ( status < 0 ) { + status = 0; + } + } + } + + // Set data for the fake xhr object + jqXHR.status = status; + jqXHR.statusText = ( nativeStatusText || statusText ) + ""; + + // Success/Error + if ( isSuccess ) { + deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] ); + } else { + deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] ); + } + + // Status-dependent callbacks + jqXHR.statusCode( statusCode ); + statusCode = undefined; + + if ( fireGlobals ) { + globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError", + [ jqXHR, s, isSuccess ? success : error ] ); + } + + // Complete + completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] ); + + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] ); + + // Handle the global AJAX counter + if ( !( --jQuery.active ) ) { + jQuery.event.trigger( "ajaxStop" ); + } + } + } + + return jqXHR; + }, + + getJSON: function( url, data, callback ) { + return jQuery.get( url, data, callback, "json" ); + }, + + getScript: function( url, callback ) { + return jQuery.get( url, undefined, callback, "script" ); + } +} ); + +jQuery.each( [ "get", "post" ], function( _i, method ) { + jQuery[ method ] = function( url, data, callback, type ) { + + // Shift arguments if data argument was omitted + if ( isFunction( data ) ) { + type = type || callback; + callback = data; + data = undefined; + } + + // The url can be an options object (which then must have .url) + return jQuery.ajax( jQuery.extend( { + url: url, + type: method, + dataType: type, + data: data, + success: callback + }, jQuery.isPlainObject( url ) && url ) ); + }; +} ); + +jQuery.ajaxPrefilter( function( s ) { + var i; + for ( i in s.headers ) { + if ( i.toLowerCase() === "content-type" ) { + s.contentType = s.headers[ i ] || ""; + } + } +} ); + + +jQuery._evalUrl = function( url, options, doc ) { + return jQuery.ajax( { + url: url, + + // Make this explicit, since user can override this through ajaxSetup (#11264) + type: "GET", + dataType: "script", + cache: true, + async: false, + global: false, + + // Only evaluate the response if it is successful (gh-4126) + // dataFilter is not invoked for failure responses, so using it instead + // of the default converter is kludgy but it works. + converters: { + "text script": function() {} + }, + dataFilter: function( response ) { + jQuery.globalEval( response, options, doc ); + } + } ); +}; + + +jQuery.fn.extend( { + wrapAll: function( html ) { + var wrap; + + if ( this[ 0 ] ) { + if ( isFunction( html ) ) { + html = html.call( this[ 0 ] ); + } + + // The elements to wrap the target around + wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true ); + + if ( this[ 0 ].parentNode ) { + wrap.insertBefore( this[ 0 ] ); + } + + wrap.map( function() { + var elem = this; + + while ( elem.firstElementChild ) { + elem = elem.firstElementChild; + } + + return elem; + } ).append( this ); + } + + return this; + }, + + wrapInner: function( html ) { + if ( isFunction( html ) ) { + return this.each( function( i ) { + jQuery( this ).wrapInner( html.call( this, i ) ); + } ); + } + + return this.each( function() { + var self = jQuery( this ), + contents = self.contents(); + + if ( contents.length ) { + contents.wrapAll( html ); + + } else { + self.append( html ); + } + } ); + }, + + wrap: function( html ) { + var htmlIsFunction = isFunction( html ); + + return this.each( function( i ) { + jQuery( this ).wrapAll( htmlIsFunction ? html.call( this, i ) : html ); + } ); + }, + + unwrap: function( selector ) { + this.parent( selector ).not( "body" ).each( function() { + jQuery( this ).replaceWith( this.childNodes ); + } ); + return this; + } +} ); + + +jQuery.expr.pseudos.hidden = function( elem ) { + return !jQuery.expr.pseudos.visible( elem ); +}; +jQuery.expr.pseudos.visible = function( elem ) { + return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length ); +}; + + + + +jQuery.ajaxSettings.xhr = function() { + try { + return new window.XMLHttpRequest(); + } catch ( e ) {} +}; + +var xhrSuccessStatus = { + + // File protocol always yields status code 0, assume 200 + 0: 200, + + // Support: IE <=9 only + // #1450: sometimes IE returns 1223 when it should be 204 + 1223: 204 + }, + xhrSupported = jQuery.ajaxSettings.xhr(); + +support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported ); +support.ajax = xhrSupported = !!xhrSupported; + +jQuery.ajaxTransport( function( options ) { + var callback, errorCallback; + + // Cross domain only allowed if supported through XMLHttpRequest + if ( support.cors || xhrSupported && !options.crossDomain ) { + return { + send: function( headers, complete ) { + var i, + xhr = options.xhr(); + + xhr.open( + options.type, + options.url, + options.async, + options.username, + options.password + ); + + // Apply custom fields if provided + if ( options.xhrFields ) { + for ( i in options.xhrFields ) { + xhr[ i ] = options.xhrFields[ i ]; + } + } + + // Override mime type if needed + if ( options.mimeType && xhr.overrideMimeType ) { + xhr.overrideMimeType( options.mimeType ); + } + + // X-Requested-With header + // For cross-domain requests, seeing as conditions for a preflight are + // akin to a jigsaw puzzle, we simply never set it to be sure. + // (it can always be set on a per-request basis or even using ajaxSetup) + // For same-domain requests, won't change header if already provided. + if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) { + headers[ "X-Requested-With" ] = "XMLHttpRequest"; + } + + // Set headers + for ( i in headers ) { + xhr.setRequestHeader( i, headers[ i ] ); + } + + // Callback + callback = function( type ) { + return function() { + if ( callback ) { + callback = errorCallback = xhr.onload = + xhr.onerror = xhr.onabort = xhr.ontimeout = + xhr.onreadystatechange = null; + + if ( type === "abort" ) { + xhr.abort(); + } else if ( type === "error" ) { + + // Support: IE <=9 only + // On a manual native abort, IE9 throws + // errors on any property access that is not readyState + if ( typeof xhr.status !== "number" ) { + complete( 0, "error" ); + } else { + complete( + + // File: protocol always yields status 0; see #8605, #14207 + xhr.status, + xhr.statusText + ); + } + } else { + complete( + xhrSuccessStatus[ xhr.status ] || xhr.status, + xhr.statusText, + + // Support: IE <=9 only + // IE9 has no XHR2 but throws on binary (trac-11426) + // For XHR2 non-text, let the caller handle it (gh-2498) + ( xhr.responseType || "text" ) !== "text" || + typeof xhr.responseText !== "string" ? + { binary: xhr.response } : + { text: xhr.responseText }, + xhr.getAllResponseHeaders() + ); + } + } + }; + }; + + // Listen to events + xhr.onload = callback(); + errorCallback = xhr.onerror = xhr.ontimeout = callback( "error" ); + + // Support: IE 9 only + // Use onreadystatechange to replace onabort + // to handle uncaught aborts + if ( xhr.onabort !== undefined ) { + xhr.onabort = errorCallback; + } else { + xhr.onreadystatechange = function() { + + // Check readyState before timeout as it changes + if ( xhr.readyState === 4 ) { + + // Allow onerror to be called first, + // but that will not handle a native abort + // Also, save errorCallback to a variable + // as xhr.onerror cannot be accessed + window.setTimeout( function() { + if ( callback ) { + errorCallback(); + } + } ); + } + }; + } + + // Create the abort callback + callback = callback( "abort" ); + + try { + + // Do send the request (this may raise an exception) + xhr.send( options.hasContent && options.data || null ); + } catch ( e ) { + + // #14683: Only rethrow if this hasn't been notified as an error yet + if ( callback ) { + throw e; + } + } + }, + + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432) +jQuery.ajaxPrefilter( function( s ) { + if ( s.crossDomain ) { + s.contents.script = false; + } +} ); + +// Install script dataType +jQuery.ajaxSetup( { + accepts: { + script: "text/javascript, application/javascript, " + + "application/ecmascript, application/x-ecmascript" + }, + contents: { + script: /\b(?:java|ecma)script\b/ + }, + converters: { + "text script": function( text ) { + jQuery.globalEval( text ); + return text; + } + } +} ); + +// Handle cache's special case and crossDomain +jQuery.ajaxPrefilter( "script", function( s ) { + if ( s.cache === undefined ) { + s.cache = false; + } + if ( s.crossDomain ) { + s.type = "GET"; + } +} ); + +// Bind script tag hack transport +jQuery.ajaxTransport( "script", function( s ) { + + // This transport only deals with cross domain or forced-by-attrs requests + if ( s.crossDomain || s.scriptAttrs ) { + var script, callback; + return { + send: function( _, complete ) { + script = jQuery( " + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Binder

+
+

Questions

+
    +

  • Why sharing code alone may not be sufficient.

    • +

  • How to share a computational environment?

    • +

  • What is Binder?

    • +

  • How to binderize my Python repository?

    • +

  • How to publish my Python repository?

    • +
+
+
+

Objectives

+
    +

  • Learn about reproducible computational environments.

    • +

  • Learn to create and share custom computing environments with Binder.

    • +

  • Learn to get a DOI from Zenodo for a repository.

    • +
+
+
+

Why is it sometimes not enough to share your code?

+../_images/python_unmasked.jpg +
+

Exercise 1

+
+

Binder-1: Discuss better strategies than only code sharing (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+
+
+
+

Sharing a computing environment with Binder

+

Binder allows you to create +custom computing environments that can be shared and used by many remote users. +It uses repo2docker to +create a container image (docker image) of a +project using information contained in included configuration files.

+

Repo2docker is a standalone package that you can install locally on your laptop +but an online Binder service is freely available. +This is what we will be using in the tutorial.

+

The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder.

+https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png +

Credit: Juliette Taka, Logilab and the OpenDreamKit project (2017)

+
+

Binder exercise/demo

+

In an earlier episode (Data visualization with Matplotlib) we have created this notebook:

+
import pandas as pd
+import matplotlib.pyplot as plt
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+data_2007 = data[data["year"] == 2007]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xscale("log")
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
+
+

We will now first share it via GitHub “statically”, +then using Binder.

+
+

Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+
+
+
+

How can I get a DOI from Zenodo?

+

Zenodo is a general purpose open-access +repository built and operated by CERN and OpenAIRE that allows researchers to archive and get a +Digital Object Identifier (DOI) to data that they +share.

+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/data-formats/index.html b/branch/rkdarst--dependengi-exercise-time/data-formats/index.html new file mode 100644 index 00000000..a1f49414 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/data-formats/index.html @@ -0,0 +1,1033 @@ + + + + + + + + + + + + + Data formats with Pandas and Numpy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Data formats with Pandas and Numpy

+
+

Questions

+
    +

  • How do you store your data right now?

    • +

  • Are you doing data cleaning / preprocessing every time you load the data?

    • +
+
+
+

Objectives

+
    +

  • Learn the distinguishing characteristics of different data formats.

    • +

  • Learn how you can read and write data in a variety of formats.

    • +
+
+
+

What is a data format?

+

Data format can mean two different things

+
    +

  1. data structure or how you’re storing the data in memory while you’re working on it;

    2. +

  2. file format or the way you’re storing the data in the disk.

    3. +
+

Let’s consider this randomly generated DataFrame with various columns:

+
import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
+dataset.info()
+
+
+

This DataFrame is structured in the tidy data format. +In tidy data format we have multiple columns of data that are collected in a Pandas DataFrame.

+../_images/tidy_data.png +

Let’s consider another example:

+
n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+np.info(data_array)
+
+
+

Here we have a different data structure: we have a two-dimentional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block instead of individual columns. +This also means that the whole array must have one data type.

+
+https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png +
+

Source: Elegant Scipy

+
+
+

Now the question is: Can the data be saved to the disk without changing the data format?

+

For this we need a file format that can easily store our data structure.

+
+

Data type vs. data structure vs. file format

+
    +

  • Data type: Type of a single piece of data (integer, string, float, …).

    • +

  • Data structure: How the data is organized in memory (individual columns, 2D-array, nested dictionaries, …).

    • +

  • File format: How the data is organized when it is saved to the disk (columns of strings, block of binary data, …).

    • +
+

For example, a black and white image stored as a .png-file (file format) +might be stored in memory as an NxM array (data structure) of integers (data type).

+
+
+
+

What to look for in a file format?

+

When deciding which file format you should use for your program, you should remember the following:

+

There is no file format that is good for every use case.

+

Instead, there are various standard file formats for various use cases:

+
+https://imgs.xkcd.com/comics/standards.png +
+

Source: xkcd #927.

+
+
+

Usually, you’ll want to consider the following things when choosing a file format:

+
    +

  1. Is the file format good for my data structure (is it fast/space efficient/easy to use)?

    2. +

  2. Is everybody else / leading authorities in my field recommending a certain format?

    3. +

  3. Do I need a human-readable format or is it enought to work on it using code?

    4. +

  4. Do I want to archive / share the data or do I just want to store it while I’m working?

    5. +
+

Pandas supports many file formats for tidy data and Numpy supports some file formats for array data. +However, there are many other file formats that can be used through other libraries.

+

Table below describes some data formats:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
Name:
+
+
+
Human
+
readable:
+
+
+
Space
+
efficiency:
+
+
+
Arbitrary
+
data:
+
+
+
Tidy
+
data:
+
+
+
Array
+
data:
+
+
+
Long term
+
storage/sharing:
+
+

Pickle

❌

🟨

✅

🟨

🟨

❌

CSV

✅

❌

❌

✅

🟨

✅

Feather

❌

✅

❌

✅

❌

❌

Parquet

❌

✅

🟨

✅

🟨

✅

npy

❌

🟨

❌

❌

✅

❌

HDF5

❌

✅

❌

❌

✅

✅

NetCDF4

❌

✅

❌

❌

✅

✅

JSON

✅

❌

🟨

❌

❌

✅

Excel

❌

❌

❌

🟨

❌

✅

Graph formats

🟨

🟨

❌

❌

❌

🟨

+
+

Important

+
    +

  • ✅ : Good

    • +

  • 🟨 : Ok / depends on a case

    • +

  • ❌ : Bad

    • +
+
+
+
+

Storing arbitrary Python objects

+
+

Pickle

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: None (pickle-module is included with Python).

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: 🟨

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ❌! See warning below.

    • +

  • Best use cases: Saving Python objects for debugging.

    • +
+
+
+

Warning

+

Loading pickles that you have not created is +risky as they can contain arbitrary executable code.

+

Do not unpickle objects from sources that you do not trust!

+
+

Pickle is Python’s own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:

+
import pickle
+
+with open('data_array.pickle', 'wb') as f:
+    pickle.dump(data_array, f)
+
+with open('data_array.pickle', 'rb') as f:
+    data_array_pickle = pickle.load(f)
+
+
+
+
+
+

Exercise 1

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+ +
+
+

Storing tidy data

+
+

CSV (comma-separated values)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: numpy, pandas

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data. Small data. Data that needs to be human-readable.

    • +
+
+

CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you’re working with big data.

+

Pandas has a very nice interface for writing and reading CSV files with to_csv- and read_csv-functions:

+
dataset.to_csv('dataset.csv', index=False)
+
+dataset_csv = pd.read_csv('dataset.csv')
+
+
+

Numpy has routines for saving and loading arrays as CSV files as well:

+
np.savetxt('data_array.csv', data_array)
+
+data_array_csv = np.loadtxt('data_array.csv')
+
+
+
+

Storing data in CSVs can reduce data precision

+
+

When working with floating point numbers you should be careful to save the data with enough decimal places so that you won’t lose precision.

+

For example, double-precision floating point numbers have ~16 decimal places of precision, but if you use normal Python to write these numbers, you can easily lose some of that precision. +Let’s consider the following example:

+
import numpy as np
+test_number = np.sqrt(2)
+# Write the number in a file
+test_file = open('sqrt2.csv', 'w')
+test_file.write('%f' % test_number)
+test_file.close()
+# Read the number from a file
+test_file = open('sqrt2.csv', 'r')
+test_number2 = np.float64(test_file.readline())
+test_file.close()
+# Calculate the distance between these numbers
+print(np.abs(test_number - test_number2))
+
+
+

CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. +We can check whether our written data matches the generated data:

+
dataset.compare(dataset_csv)
+
+np.all(data_array == data_array_csv)
+
+
+

In our case some rows of dataset_csv loaded from CSV do not match the original dataset as the last decimal can sometimes be rounded due to complex technical reasons.

+

Storage of these high-precision CSV files is usually very inefficient storage-wise.

+

Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems.

+
+
+
+
+

Feather

+
+

Requires additional packages

+
+

Using Feather requires pyarrow-package to be installed.

+

You can try installing pyarrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Temporary storage of tidy data.

    • +
+
+

Feather is a file format for storing data frames quickly. +There are libraries for Python, R and Julia.

+

We can work with Feather files with to_feather- and read_feather-functions:

+
dataset.to_feather('dataset.feather')
+dataset_feather = pd.read_feather('dataset.feather')
+
+
+

Feather is not a good format for storing array data, so we won’t present an example of that here.

+
+
+

Parquet

+
+

Requires additional packages

+
+

Using Parquet requires pyarrow-package to be installed.

+

You can try installing PyArrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in tidy data format. Archival of said data.

    • +
+
+

Parquet is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.).

+

We can work with Parquet files with to_parquet- and read_parquet-functions:

+
dataset.to_parquet('dataset.parquet')
+dataset_parquet = pd.read_parquet('dataset.parquet')
+
+
+

Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won’t do that here.

+
+
+
+

Exercise 2

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+ +
+
+

Storing array data

+
+

npy (numpy array format)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Saving numpy arrays temporarily.

    • +
+
+

If you want to temporarily store numpy arrays, you can use the numpy.save()- and numpy.load()-functions:

+
np.save('data_array.npy', data_array)
+data_array_npy = np.load('data_array.npy')
+
+
+

There also exists numpy.savez()-function for storing multiple datasets in a single file:

+
np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array)
+data_arrays = np.load('data_arrays.npz')
+data_arrays['data_array0']
+
+
+

For big arrays it’s good idea to check other binary formats such as HDF5 or NetCDF4.

+

np.save- and np.savez-functions work with +sparse matrices, +but one can also use dedicated +scipy.sparse.save_npz- and +scipy.sparse.load_npz-functions. +Storing sparse matrices using these functions can give huge storage savings.

+
+
+

HDF5 (Hierarchical Data Format version 5)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy, pandas, PyTables, h5py

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format.

    • +
+
+

HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences.

+

Pandas allows you to store tables as HDF5 with PyTables, which uses HDF5 to write the files. +You can create a HDF5 file with to_hdf- and read_parquet-functions:

+
dataset.to_hdf('dataset.h5', key='dataset', mode='w')
+dataset_hdf5 = pd.read_hdf('dataset.h5')
+
+
+

PyTables comes installed with the default Anaconda installation.

+

For writing data that is not a table, you can use the excellent h5py-package:

+
import h5py
+
+# Writing:
+
+# Open HDF5 file
+h5_file = h5py.File('data_array.h5', 'w')
+# Write dataset
+h5_file.create_dataset('data_array', data=data_array)
+# Close file and write data to disk. Important!
+h5_file.close()
+
+# Reading:
+
+# Open HDF5 file again
+h5_file = h5py.File('data_array.h5', 'r')
+# Read the full dataset
+data_array_h5 = h5_file['data_array'][()]
+# Close file
+h5_file.close()
+
+
+

h5py comes with Anaconda as well.

+
+
+

NetCDF4 (Network Common Data Form version 4)

+
+

Requires additional packages

+
+

Using NetCDF4 requires netCDF4- or h5netcdf-package to be installed. +h5netcdf is often mentioned as being faster to the official netCDF4-package, so we’ll be using it in the example.

+

A great NetCDF4 interface is provided by a xarray-package.

+

You can try installing these packages with

+
!pip install h5netcdf xarray
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, netCDF4/h5netcdf, xarray

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets.

    • +
+
+

NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs.

+

NetCDF4 is a common format for storing large data from big simulations in physical sciences.

+

Using interface provided by xarray:

+
# Write tidy data as NetCDF4
+dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf')
+# Read tidy data from NetCDF4
+import xarray as xr
+dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf')
+dataset_netcdf4 = dataset_xarray.to_pandas()
+dataset_xarray.close()
+
+
+

Working with array data is easy as well:

+
# Write array data as NetCDF4
+xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf')
+# Read array data from NetCDF4
+data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf')
+data_array_netcdf4 = data_array_xarray.to_numpy()
+data_array_xarray.close()
+
+
+

The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (x, y, z) or timestamps (t) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis.

+
+
+
+

Exercise 3

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+ +
+
+

Other file formats

+
+

JSON (JavaScript Object Notation)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: None (json-module is included with Python).

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Saving nested/relational data, storing web requests.

    • +
+
+

JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.).

+

You rarely want to keep your data in this format, unless you’re working with +nested data with multiple layers or lots of interconnections.

+

Similarly to other popular files, Pandas can write and read json files with to_json()- and read_json()-functions:

+
dataset.to_json('dataset.json')
+dataset_json = pd.read_json('dataset.json')
+
+
+
+
+

Excel

+
+

Requires additional packages

+

Using Excel files with Pandas requires openpyxl-package to be installed.

+
+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: openpyxl

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: 🟨

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data in many fields. Quick data analysis.

    • +
+
+

Excel is very popular in social sciences and economics. +However, it is not a good format for data science.

+

See Pandas’ documentation on working with Excel files.

+
+
+

Graph formats (adjency lists, gt, GraphML etc.)

+
+

Key features

+
    +

  • Type: Many different formats

    • +

  • Packages needed: Depends on a format.

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: 🟨

    • +

  • Best use cases: Saving graphs or data that can be represented as a graph.

    • +
+
+

There are plenty of data formats for storing graphs. +We won’t list them here as optimal data format depends heavily on the graph structure.

+

One can use functions in libraries such as +networkx, +graph-tool, +igraph +to read and write graphs.

+
+
+
+

Benefits of binary file formats

+

Binary files come with various benefits compared to text files.

+
    +

  1. They can represent floating point numbers with full precision.

    2. +

  2. Storing data in binary format can potentially save lots of space. +This is because you do not need to write numbers as characters. +Additionally some file formats support compression of the data.

    3. +

  3. Data loading from binary files is usually much faster than loading from text files. +This is because memory can be allocated for the data before data is loaded as the type of data in columns is known.

    4. +

  4. You can often store multiple datasets and metadata to the same file.

    5. +

  5. Many binary formats allow for partial loading of the data. +This makes it possible to work with datasets that are larger than your computer’s memory.

    6. +
+

Performance with tidy dataset:

+

For the tidy dataset we had, we can test the performance of the different file formats:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File format

File size [MB]

Write time [ms]

Read time [ms]

Data matches exactly

CSV

4.57

360

81.2

False

Feather

2.2

12.9

6.67

True

Parquet

1.82

35.1

8.96

True

HDF5

4.89

41.7

29.6

True

NetCDF4

6.9

92.9

74.2

True

+

The relatively poor performance of HDF5-based formats in this case is due to the data being mostly one dimensional columns full of character strings.

+

Performance with data array:

+

For the array-shaped data_array we had, we can test the performance of the different file formats:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File format

File size [MB]

Write time [ms]

Read time [ms]

Data matches exactly

CSV

23.8

690

294

True

npy

7.63

13.8

2.72

True

HDF5

7.63

27

3.97

True

NetCDF4

7.64

28.8

12.2

True

+

For this kind of a data, HDF5-based formats perform much better.

+
+
+

Things to remember

+
    +

  1. There is no file format that is good for every use case.

    2. +

  2. Usually, your research question determines which libraries you want to use to solve it. +Similarly, the data format you have determines file format you want to use.

    3. +

  3. However, if you’re using a previously existing framework or tools or you work in a specific field, you should prioritize using the formats that are used in said framework/tools/field.

    4. +

  4. When you’re starting your project, it’s a good idea to take your initial data, clean it, and store the results in a good binary format that works as a starting point for your future analysis. +If you’ve written the cleaning procedure as a script, you can always reproduce it.

    5. +

  5. Throughout your work, you should use code to turn important data to human-readable format (e.g. plots, averages, pandas.DataFrame.head()), not to keep your full data in a human-readable format.

    6. +

  6. Once you’ve finished, you should store the data in a format that can be easily shared to other people.

    7. +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pandas can read and write a variety of data formats.

    • +

  • There are many good, standard formats, and you don’t need to create your own.

    • +

  • There are plenty of other libraries dedicated to various formats.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/data-visualization/index.html b/branch/rkdarst--dependengi-exercise-time/data-visualization/index.html new file mode 100644 index 00000000..13d3465a --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/data-visualization/index.html @@ -0,0 +1,691 @@ + + + + + + + + + + + + + Data visualization with Matplotlib — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Data visualization with Matplotlib

+
+

Questions

+
    +

  • What happens if you can’t automatically produce plots?

    • +

  • When to use Matplotlib for data visualization?

    • +

  • When to prefer other libraries?

    • +
+
+
+

Objectives

+
    +

  • Be able to create simple plots with Matplotlib and tweak them

    • +

  • Know about object-oriented vs pyplot interfaces of Matplotlib

    • +

  • Be able to adapt gallery examples

    • +

  • Know how to look for help

    • +

  • Know that other tools exist

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • Try to minimize manual post-processing. This could bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    + +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative.

    • +
+
+
+

Why are we starting with Matplotlib?

+
    +

  • Matplotlib is perhaps the most popular Python plotting library.

    • +

  • Many libraries build on top of Matplotlib (example: Seaborn).

    • +

  • MATLAB users will feel familiar.

    • +

  • Even if you choose to use another library (see above list), chances are high +that you need to adapt a Matplotlib plot of somebody else.

    • +

  • Libraries that are built on top of Matplotlib may need knowledge of Matplotlib +for custom adjustments.

    • +
+

However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code.

+

Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences.

+
+
+

Getting started with Matplotlib

+

We can start in a Jupyter Notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK.

+

Let us create our first plot using +subplots(), +scatter, and some other methods on the +Axes object:

+
import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
+# uncomment the next line if you would like to save the figure to disk
+# fig.savefig("my-first-plot.png")
+
+
+
+Result of our first plot +
+

This is the result of our first plot.

+
+
+

When running a Matplotlib script on a remote server without a +“display” (e.g. compute cluster), you may need to add the +matplotlib.use call:

+
import matplotlib.pyplot as plt
+matplotlib.use("Agg")
+
+# ... rest of the script
+
+
+
+
+

Exercise: Matplotlib

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y * 2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset. +You can also consult this great +quick start guide.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +

  • Experiment also by using named colors (e.g. “red”) instead of the hex-codes.

    • +
+
+ + +
+
+
+

Matplotlib has two different interfaces

+

When plotting with Matplotlib, it is useful to know and understand that +there are two approaches even though the reasons of this dual approach is +outside the scope of this lesson.

+
    +

  • The more modern option is an object-oriented interface or explicit interface (the +fig and ax objects +can be configured separately and passed around to functions):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
    +
    +
    • +

  • The more traditional option mimics MATLAB plotting and uses the +pyplot interface or implicit interface (plt carries +the global settings):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+plt.scatter(x=data_x, y=data_y, c="#E69F00")
+
+plt.xlabel("we should label the x axis")
+plt.ylabel("we should label the y axis")
+plt.title("some title")
+
    +
    +
    • +
+

When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, we +recommend to learn and use the object oriented interface.

+
+

Why do we emphasize this?

+

One day you may want to write functions which wrap +around Matplotlib function calls and then you can send Figure and Axes +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions.

+

When using the pyplot interface, settings are modified for the entire +matplotlib.pyplot package. The latter is acceptable for simple scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls.

+
+
+
+
+

Styling and customizing plots

+
    +

  • Before you customize plots “manually” using a graphical program, please +consider how this affects reproducibility.

    • +

  • Try to minimize manual post-processing. This might bite you when you +need to regenerate 50 figures one day before submission deadline or +regenerate a set of figures after the person who created them left the group.

    • +

  • Matplotlib and also all the other libraries allow to customize almost every aspect of a plot.

    • +

  • It is useful to study Matplotlib parts of a figure +so that we know what to search for to customize things.

    • +

  • Matplotlib cheatsheets: https://github.com/matplotlib/cheatsheets

    • +

  • You can also select among pre-defined themes/ +style +sheets +with use, for instance:

    +
    plt.style.use('ggplot')
+
    +
    +
    • +
+
+
+

Exercises: Styling and customization

+

Here are 3 exercises where we try to adapt existing scripts to either tweak +how the plot looks (exercises 1 and 2) or to modify the input data (example 3).

+

This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice:

+
    +

  • Select an example that is close to what you have in mind

    • +

  • Being able to adapt it to your needs

    • +

  • Being able to search for help

    • +

  • Being able to understand help request answers (not easy)

    • +
+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = (
+    "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+)
+gapminder_data = pd.read_csv(url).query("year == 2007")
+
+gapminder_data
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP per capita (PPP dollars)")
+ax.set_ylabel("Life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+ +
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+ + + +
+
+

Discussion

+

After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on.

+
+
+
+
+

Matplotlib and pandas DataFrames

+

In the above exercises we have sent individual columns of the gapminder_data DataFrame +into ax.scatter() like this:

+
fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+
+

It is possible to do this instead and let Matplotlib “unpack” the columns:

+
fig, ax = plt.subplots()
+
+ax.scatter(x="gdpPercap", y="lifeExp", alpha=0.5, data=gapminder_data)
+
+
+

Other input types are possible. See Types of inputs to plotting +functions.

+
+
+

Keypoints

+
    +

  • Minimize manual post-processing, script everything.

    • +

  • Browse a number of example galleries to help you choose the library +that fits best your work/style.

    • +

  • Figures for presentation slides and figures for manuscripts have +different requirements.

    • +

  • Think about color-vision deficiencies when choosing colors. Use +existing solutions for this problem.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/dependencies/index.html b/branch/rkdarst--dependengi-exercise-time/dependencies/index.html new file mode 100644 index 00000000..259f217b --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/dependencies/index.html @@ -0,0 +1,657 @@ + + + + + + + + + + + + + Dependency management — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Dependency management

+
+

Questions

+
    +

  • Do you expect your code to work in one year? Five? What if it +uses numpy or tensorflow or random-github-package ?

    • +

  • How can my collaborators get the same results as me? What about +future me?

    • +

  • How can my collaborators easily install my codes with all the necessary dependencies?

    • +

  • How can I make it easy for my colleagues to reproduce my results?

    • +

  • How can I work on two (or more) projects with different and conflicting dependencies?

    • +
+
+
+

Objectives

+
    +

  • Learn how to record dependencies

    • +

  • Be able to communicate the dependencies as part of a report/thesis/publication

    • +

  • Learn how to use isolated environments for different projects

    • +

  • Simplify the use and reuse of scripts and projects

    • +
+
+
+

How do you track dependencies of your project?

+
    +

  • Dependency: Reliance on a external component. In this case, a +separately installed software package such as numpy.

    • +
+
+
+

Exercises 1

+
+

Dependencies-1: Discuss dependency management (5 min)

+

Please discuss in breakout rooms and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+
+
+

PyPI (The Python Package Index) and (Ana)conda

+
    +

  • PyPI (The Python Package Index) and Conda are popular packaging/dependency +management tools.

    • +

  • When you run pip install you typically install from PyPI but you can also pip install from a GitHub +repository and similar.

    • +

  • When you run conda install you typically install from Anaconda Cloud where there are conda channels maintained +by Anaconda Inc. and by various communities.

    • +
+

Why are there two ecosystems?

+
+

PyPI

+
    +

  • Installation tool: pip

    • +

  • Summary: PyPI is traditionally used for Python-only packages or +for Python interfaces to external libraries. There are also packages +that have bundled external libraries (such as numpy).

    • +

  • Amount of packages: Huge number. Old versions are supported for +a long time.

    • +

  • How libraries are handled: If your code depends on external +libraries or tools, these things need to be either included in the +pip-package or provided via some other installation system (like +operating system installer or manual installation).

    • +
  • +
    Pros:
      +

    • Easy to use

      • +

    • Package creation is easy

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Installing packages that need external libraries can be complicated

      • +
    +
    +
    +
    • +
+
+
+

Conda

+
    +

  • Installation tool: conda or mamba

    • +

  • Summary: Conda aims to be a more general package distribution tool +and it tries to provide not only the Python packages, but also libraries +and tools needed by the Python packages. Most scientific software written +in Python uses external libraries to speed up calculations and installing +these libraries can often become complicated without conda.

    • +

  • Amount of packages: Curated list of packages in defaults-channel, huge +number in community managed channels. Other packages can be installed via pip.

    • +

  • How libraries are handled: Required libraries are installed as separate +conda packages.

    • +
  • +
    Pros:
      +

    • Quite easy to use

      • +

    • Easier to manage packages that need external libraries

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Package creation is harder

      • +
    +
    +
    +
    • +
+
+
+

Anaconda vs. miniconda vs. conda vs. mamba vs. Anaconda Cloud vs. conda-forge vs. miniforge

+

Package sources:

+
    +

  • Anaconda Cloud - a package cloud maintained by +Anaconda Inc. It is a free repository that houses conda package channels.

    • +

  • Conda-forge - the largest open source +community channel.

    • +
+

Package managers:

+
    +

  • conda - a package and environment management system +used by Anaconda. It is an open source project maintained by Anaconda Inc..

    • +

  • mamba - a drop in +replacement for conda that does installations faster.

    • +
+

Package manager deployments:

+
    +

  • Anaconda - a distribution of conda packages +made by Anaconda Inc.. It is free for academic and non-commercial use.

    • +

  • Miniconda - a minimal installer that +has conda and uses +default channels +by default.

    • +

  • Miniforge - Miniconda replacement +that uses conda-forge as the default channel. Contains mamba as well.

    • +
+
+

In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages.

+
+
+

Creating isolated environments

+

An isolated environment allows installing packages without +affecting the rest of your operating system or any other projects. +Isolated environments solve a couple of problems:

+
    +

  • You can install specific versions of packages into them.

    • +

  • You can create one environment for each project and you won’t encounter any +problems if the two projects require different versions of packages.

    • +

  • If you make some mistake and install something you did not want or need, you +can remove the environment and create a new one.

    • +

  • You can export a list of packages in an environment and share it with your +code. This makes replicating your results easier.

    • +
+
+
+

Exercises 2

+
+

Dependencies-2: Create a conda environment (15 min)

+
+
+

Chloe just joined your team and will be working on her Master Thesis. She is +quite familiar with Python, still finishing some Python assignments (due in a +few weeks) and you give her a Python code for analyzing and plotting your +favorite data. The thing is that your Python code has been developed by +another Master Student (from last year) and requires a older version of +Numpy (1.24.3) and Matplotlib (3.7.2) (otherwise the code fails). The code +could probably work with a recent version of Python but has been validated with +Python 3.10 only. Having no idea what the code does, she decides that the best +approach is to create an isolated environment with the same dependencies +that were used previously. This will give her a baseline for future upgrade and +developments.

+

For this first exercise, we will be using conda for creating an isolated environment.

+
    +

  1. Create a conda environment:

    +
    $ conda create --name python310-env python=3.10 numpy=1.24.3 matplotlib=3.7.2
+
    +
    +
    2. +
+

Conda environments can also be managed (create, update, delete) from the +anaconda-navigator. Check out the corresponding documentation here.

+
    +

  1. Activate the environment:

    +
    $ conda activate python310-env
+
    +
    +
    +

    conda activate versus source activate

    +

    conda activate will only work if you have run conda init +in the past. Running conda init will make loading environments +easier as you will always have a conda environment loaded.

    +

    However, this can also cause problems as programs in the +main environment will be constantly loaded and they might be used +even when they’re not supposed to be used. A common example is +not having pip installed in a conda environment which results +pip from main environment to be used instead.

    +

    You can always try:

    +
    $ source activate python310-env
+
    +
    +
    +
    2. +

  2. Open a Python console and check that you have effectively the +right version for each package:

    +
    import numpy
+import matplotlib
+
+print('Numpy version: ', numpy.__version__)
+print('Matplotlib version: ', matplotlib.__version__)
+
    +
    +

    Or use the one-liner if you have access to a terminal like bash:

    +
    python -c 'import numpy; print(numpy.__version__)'
+python -c 'import matplotlib;print(matplotlib.__version__)'
+
    +
    +
    3. +

  3. Deactivate the environment:

    +
    $ conda deactivate
+
    +
    +
    4. +

  4. Check Numpy and Matplotlib versions in the default environment to make +sure they are different from python310-env.

    5. +
+

There is no need to specify the conda environment when using deactivate. It +deactivates the current environment.

+
+
+
+

Exercises 3

+
+

Dependencies-3: Create a virtualenv (15 min, optional)

+

This is the same exercise as before but we use virtualenv rather than conda.

+
    +

  1. Create a venv:

    +
    $ python3 -m venv scicomp
+
    +
    +

    Here scicomp is the name of the virtual environment. It creates a new +folder called scicomp.

    +
    2. +

  2. Activate it. To activate your newly created virtual environment locate the +script called activate and source it.

    +
      +

    • Linux/Mac-OSX: look at bin folder in the scicomp folder:

      +
      $ source scicomp/bin/activate
+
      +
      +
      • +

    • Windows: most likely you can find it in the Scripts folder.

      • +
    +
    3. +

  3. Install Numpy 1.24.3 and Matplotlib 3.7.2 into the virtual environment:

    +
    $ pip install numpy==1.24.3
+$ pip install matplotlib==3.7.2
+
    +
    +
    4. +

  4. Deactivate it:

    +
    $ deactivate
+
    +
    +
    5. +
+
+
+
+

Problems that might happen with manual installation

+

Running the install commands manually can result in unexpected behaviour +such as:

+
    +

  • The installer might remove an already installed packages or update them.

    • +

  • The installer might not find a package that works with already installed packages.

    • +
+

The reason for this is that the installer does not know what commands +you ran in the past. It only knows the state of your environment and what +you’re currently telling it to install.

+

These kinds of problems can be mitigated by recording dependencies in an +environment.yml or requirements.txt.

+
+
+

Recording dependencies

+

There are two standard ways to record dependencies for Python projects: +requirements.txt and environment.yml.

+

requirements.txt (used by virtual environment) is a simple +text file which looks like this:

+
numpy
+matplotlib
+pandas
+scipy
+
+
+

environments.yml (for conda) is a yaml-file which looks like this:

+
name: my-environment
+channels:
+  - defaults
+dependencies:
+  - numpy
+  - matplotlib
+  - pandas
+  - scipy
+
+
+

If you need to recreate the exact same environment later on, it can be very +useful to pin dependencies to certain versions. For example, there +is usually a delay between doing research and that research being published. +During this time the dependencies might update and reviewers or interested +researchers might not be able to replicate your results or run your code.

+
+

Conda channels

+
    +

  • Sometimes the package version you would need does not seem to be +available. You may have to select another conda channel.

    +

    Most popular channels are +defaults, +which is managed by +Anaconda Inc. and conda-forge, +which is managed by the open source community. These two channels are +mutually incompatible.

    +

    Channel priority goes from top to bottom.

    +
    • +
+
+

Here are the two files again, but this time with versions pinned:

+

requirements.txt with versions:

+
numpy==1.24.3
+matplotlib==3.7.2
+pandas==2.0.3
+scipy==1.10.1
+
+
+

environments.yml with versions:

+
name: my-environment
+channels:
+  - defaults
+dependencies:
+  - python=3.10
+  - numpy=1.24.3
+  - matplotlib=3.7.2
+  - pandas=2.0.3
+  - scipy=1.10.1
+
+
+ +
+

Putting too strict requirements can be counter-productive

+

Putting exact version numbers can be good for single-use applications, +like replicating a research paper, but it is usually bad for long-term +maintenance because the program won’t update at the same time as it’s +requirements do.

+

If you’re creating a library, adding strict dependencies can also create +a situation where the library cannot coexist with another library.

+
+
+
+

Dependencies 4

+
+

Dependencies-4: Freeze an environment (15 min)

+
    +

  • Create the file environment.yml or requirements.txt

    • +
  • +
    Create an environment based on these dependencies:
      +

    • Conda: $ conda env create --file environment.yml

      • +

    • Virtual environment: First create and activate, then $ pip install -r requirements.txt

      • +
    +
    +
    +
    • +
  • +
    Freeze the environment:
      +

    • Conda: $ conda env export > environment.yml

      • +

    • Virtual environment: $ pip freeze > requirements.txt

      • +
    +
    +
    +
    • +

  • Have a look at the generated (“frozen”) file.

    • +
+
+
+

Hint: Updating packages from dependency files

+

Instead of installing packages with $ pip install somepackage, +you can add somepackage to requirements.txt and re-run +$ pip install -r requirements.txt.

+

With conda, you can add the package to environment.yml and +run $ conda env update --file environment.yml

+
+
+
+

How to communicate the dependencies as part of a report/thesis/publication

+

Each notebook or script or project which depends on libraries should come with +either a requirements.txt or a environment.yml, unless you are creating +and distributing this project as Python package (see next section).

+
    +

  • Attach a requirements.txt or a environment.yml to your thesis.

    • +

  • Even better: put requirements.txt or a environment.yml in your Git repository along your code.

    • +

  • Even better: also binderize your analysis pipeline (more about that in a later session).

    • +
+
+
+

Version pinning for package creators

+

We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in setup.py or pyproject.toml +(PyPI) or meta.yaml (conda).

+

These dependencies will then be used by either other libraries (who in turn +write their own setup.py or pyproject.toml or meta.yaml) or by +people directly (filling out requirements.txt or a environment.yml).

+

Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from setup.py):

+
# ...
+install_requires=[
+   'numpy==1.19.2',
+   'matplotlib==3.3.2'
+   'pandas==1.1.2'
+   'scipy==1.5.2'
+]
+# ...
+
+
+

or you can define a range or keep them undefined like here (example taken from +setup.py):

+
# ...
+install_requires=[
+   'numpy',
+   'matplotlib'
+   'pandas'
+   'scipy'
+]
+# ...
+
+
+

Should we pin the versions here or not?

+
    +

  • Pinning versions here would be good for reproducibility.

    • +

  • However pinning versions may make it difficult for this library to be used in a project alongside other +libraries with conflicting version dependencies.

    • +

  • Therefore as library creator make the version requirements as wide as possible.

    +
      +

    • Set minimum version when you know of a reason: >=2.1

      • +

    • Sometimes set maximum version to next major version (<4) (when +you currently use 3.x.y) when you expect issues with next +major version.

      • +
    +
    • +

  • As the “end consumer” of libraries, define your dependencies as narrowly as possible.

    • +
+
+
+

See also

+

Other tools for dependency management:

+
    +

  • Poetry: dependency management and packaging

    • +

  • Pipenv: dependency management, alternative to Poetry

    • +

  • pyenv: if you need different Python versions for different projects

    • +

  • micropipenv: lightweight tool to “rule them all”

    • +

  • mamba: a drop in replacement for +conda that does installations faster.

    • +

  • miniforge: Miniconda alternative with +conda-forge as the default channel and optionally mamba as the default installer.

    • +

  • micromamba: +tiny version of Mamba as a static C++ executable. Does not need base environment or +Python for installing an environment.

    • +
+

Other resources:

+ +
+

Keypoints

+
    +

  • Install dependencies by first recording them in requirements.txt or +environment.yml and install using these files, then you have a trace.

    • +

  • Use isolated environments and avoid installing packages system-wide.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/exercises/index.html b/branch/rkdarst--dependengi-exercise-time/exercises/index.html new file mode 100644 index 00000000..081c5d44 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/exercises/index.html @@ -0,0 +1,2145 @@ + + + + + + + + + + + + + List of exercises — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

List of exercises

+
+

Full list

+

This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests.

+
+

Jupyter

+

In jupyter.ipynb:

+
+

Exercises: Jupyter-1

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are starting from the navigator, change to the directory you want to use.

      • +

    • If you are starting from the command line, you should navigate to the directory you want to use first.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+

In jupyter.ipynb:

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+

In jupyter.ipynb:

+ +

In jupyter.ipynb:

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

NumPy

+

In numpy.rst:

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-2

+ +
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+

In numpy.rst:

+ +
+
+

Advanced NumPy

+

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lession before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+

In numpy-advanced.rst:

+ +
+
+

Pandas

+

In pandas.rst:

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+

In pandas.rst:

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+

In pandas.rst:

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries (you need to look at the +data and find how countries are written, and replace COUNTRY +with those strings):

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Data visualization with Matplotlib

+

In data-visualization.md:

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y * 2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset. +You can also consult this great +quick start guide.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +

  • Experiment also by using named colors (e.g. “red”) instead of the hex-codes.

    • +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = (
+    "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+)
+gapminder_data = pd.read_csv(url).query("year == 2007")
+
+gapminder_data
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=gapminder_data["gdpPercap"], y=gapminder_data["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP per capita (PPP dollars)")
+ax.set_ylabel("Life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+ +

In data-visualization.md:

+ +
+
+

Data formats with Pandas and Numpy

+

In data-formats.rst:

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+

In data-formats.rst:

+ +
+
+

Productivity tools

+

In productivity.rst:

+
+

Using Pylint

+

The following code uses scikit-learn to fit a simple linear +model to randomly generated data with some error. You can download it +here (see +above for how to easily download and run in JupyterLab).

+

It has four mistakes in it. One of these cannot be found by +Pylint.

+

Fix the following code with Pylint and try to determine why +Pylint did not find the last mistake.

+
"""
+pylint exercise 1
+"""
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn import linear_model
+
+
+def f(x):
+    """
+    Example function:
+
+    f(x) = x/2 + 2
+    """"
+    return 0.5*x + 2
+
+
+# Create example data
+x_data = np.linspace(0, 10, 100)
+err = 2 * np.random.random(x_data.shape[0])
+y_data = f(x_data) + err
+
+# Put data into dataframe
+df = pd.DataFrame({'x': x_data, 'y': y_data})
+
+# Create linear model and fit data
+reg = linear_model.LinearRegression(fit_intercept=True)
+
+reg.fit(df[['x'], df[['y']])
+
+slope = reg.coef_[0][0]
+intercept = reg.intercept_[0]
+
+df['pred'] = reg.predict(df[['x']])
+
+fig, ax = plt.subplots()
+
+ax.scater(df[['x']], df[['y']], alpha=0.5)
+ax.plot(df[['x']], df[['pred']]
+        color='black', linestyle='--',
+        label=f'Prediction with slope {slope:.2f} and intercept {intercept:.2f}')
+ax.set_ylabel('y')
+ax.set_xlabel('x')
+ax.legend()
+
+plt.show()
+
+
+
+

In productivity.rst:

+ +

In productivity.rst:

+
+

Using black to format code

+

Format +this code +with black:

+
import numpy as np
+import matplotlib.pyplot  as plt
+
+def dice_toss(n,m):
+
+    """Throw n dice m times and the total value together."""
+    dice_rolls    = np.random.randint(1,6,size=(m, n))
+
+    roll_averages = np.sum(dice_rolls,axis = -1)
+
+    return roll_averages
+fig,ax = plt.subplots( )
+
+n = int( input('Number of dices to toss:\n'))
+
+bins = np.arange(1, 6 * n+1)
+
+m = 1000
+
+ax.hist(dice_toss(n,m), bins = bins)
+
+ax.set_title(f'Histogram of {n} dice tosses')
+
+ax.set_xlabel('Total value' )
+
+ax.set_ylabel('Number of instances')
+
+plt.show()
+
+
+
+

In productivity.rst:

+ +
+
+

Scripts

+

In scripts.rst:

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and the weather_data file and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Hint: Copy the URL above (right-click) and in JupyterLab, use +File → Open from URL → Paste the URL. It will both download it to +the directory JupyterLab is in and open it for you.

    +
    2. +

  2. Open a terminal in Jupyter: File → New Launcher, then click +“Terminal” there. (if you do it this way, it will be in the right +directory. File → New → Terminal might not be.)

    3. +

  3. Convert the Jupyter script to a Python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+

In scripts.rst:

+
+

Scripts-2

+
    +

  1. Take the Python script (weather_observations.py) we have written in the preceding exercise and use +argparse to specify the input (URL) and output files and allow the start and end dates to be set.

    +
      +

    • Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on.

      • +

    • Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output.

      • +

    • Hint: The start and end dates should be optional parameters with the defaults as they are in the current script.

      • +
    +
    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). +Also try using this data for Cairo: https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv

    3. +
+
+

In scripts.rst:

+ +

In scripts.rst:

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+

In scripts.rst:

+ +
+
+

SciPy

+

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+

In scipy.rst:

+ +

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+

In scipy.rst:

+ +
+
+

Library ecosystem

+

In libraries.rst:

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+

In libraries.rst:

+ +

In libraries.rst:

+
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+

In libraries.rst:

+ +
+
+

Dependency management

+

In dependencies.rst:

+
+

Dependencies-1: Discuss dependency management (5 min)

+

Please discuss in breakout rooms and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+

In dependencies.rst:

+
+

Dependencies-2: Create a conda environment (15 min)

+
+
+

Chloe just joined your team and will be working on her Master Thesis. She is +quite familiar with Python, still finishing some Python assignments (due in a +few weeks) and you give her a Python code for analyzing and plotting your +favorite data. The thing is that your Python code has been developed by +another Master Student (from last year) and requires a older version of +Numpy (1.24.3) and Matplotlib (3.7.2) (otherwise the code fails). The code +could probably work with a recent version of Python but has been validated with +Python 3.10 only. Having no idea what the code does, she decides that the best +approach is to create an isolated environment with the same dependencies +that were used previously. This will give her a baseline for future upgrade and +developments.

+

For this first exercise, we will be using conda for creating an isolated environment.

+
    +

  1. Create a conda environment:

    +
    $ conda create --name python310-env python=3.10 numpy=1.24.3 matplotlib=3.7.2
+
    +
    +
    2. +
+

Conda environments can also be managed (create, update, delete) from the +anaconda-navigator. Check out the corresponding documentation here.

+
    +

  1. Activate the environment:

    +
    $ conda activate python310-env
+
    +
    +
    +

    conda activate versus source activate

    +

    conda activate will only work if you have run conda init +in the past. Running conda init will make loading environments +easier as you will always have a conda environment loaded.

    +

    However, this can also cause problems as programs in the +main environment will be constantly loaded and they might be used +even when they’re not supposed to be used. A common example is +not having pip installed in a conda environment which results +pip from main environment to be used instead.

    +

    You can always try:

    +
    $ source activate python310-env
+
    +
    +
    +
    2. +

  2. Open a Python console and check that you have effectively the +right version for each package:

    +
    import numpy
+import matplotlib
+
+print('Numpy version: ', numpy.__version__)
+print('Matplotlib version: ', matplotlib.__version__)
+
    +
    +

    Or use the one-liner if you have access to a terminal like bash:

    +
    python -c 'import numpy; print(numpy.__version__)'
+python -c 'import matplotlib;print(matplotlib.__version__)'
+
    +
    +
    3. +

  3. Deactivate the environment:

    +
    $ conda deactivate
+
    +
    +
    4. +

  4. Check Numpy and Matplotlib versions in the default environment to make +sure they are different from python310-env.

    5. +
+

There is no need to specify the conda environment when using deactivate. It +deactivates the current environment.

+
+

In dependencies.rst:

+
+

Dependencies-3: Create a virtualenv (15 min, optional)

+

This is the same exercise as before but we use virtualenv rather than conda.

+
    +

  1. Create a venv:

    +
    $ python3 -m venv scicomp
+
    +
    +

    Here scicomp is the name of the virtual environment. It creates a new +folder called scicomp.

    +
    2. +

  2. Activate it. To activate your newly created virtual environment locate the +script called activate and source it.

    +
      +

    • Linux/Mac-OSX: look at bin folder in the scicomp folder:

      +
      $ source scicomp/bin/activate
+
      +
      +
      • +

    • Windows: most likely you can find it in the Scripts folder.

      • +
    +
    3. +

  3. Install Numpy 1.24.3 and Matplotlib 3.7.2 into the virtual environment:

    +
    $ pip install numpy==1.24.3
+$ pip install matplotlib==3.7.2
+
    +
    +
    4. +

  4. Deactivate it:

    +
    $ deactivate
+
    +
    +
    5. +
+
+

In dependencies.rst:

+
+

Dependencies-4: Freeze an environment (15 min)

+
    +

  • Create the file environment.yml or requirements.txt

    • +
  • +
    Create an environment based on these dependencies:
      +

    • Conda: $ conda env create --file environment.yml

      • +

    • Virtual environment: First create and activate, then $ pip install -r requirements.txt

      • +
    +
    +
    +
    • +
  • +
    Freeze the environment:
      +

    • Conda: $ conda env export > environment.yml

      • +

    • Virtual environment: $ pip freeze > requirements.txt

      • +
    +
    +
    +
    • +

  • Have a look at the generated (“frozen”) file.

    • +
+
+
+
+

Binder

+

In binder.rst:

+
+

Binder-1: Discuss better strategies than only code sharing (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+

In binder.rst:

+
+

Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+

In binder.rst:

+ +

In binder.rst:

+ +
+
+

Parallel programming

+

In parallel.rst:

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+

In parallel.rst:

+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+

In parallel.rst:

+
+

Parallel-3, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+

In parallel.rst:

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+
+

Packaging

+

In packaging.rst:

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Web APIs with Python

+

In web-apis.ipynb:

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+

In web-apis.ipynb:

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+

In web-apis.ipynb:

+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/genindex/index.html b/branch/rkdarst--dependengi-exercise-time/genindex/index.html new file mode 100644 index 00000000..3608036d --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/genindex/index.html @@ -0,0 +1,145 @@ + + + + + + Index — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ + +

Index

+ +
+ +
+ + +
+
+
+ +
+ +
+

© Copyright 2020-2023, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/guide/index.html b/branch/rkdarst--dependengi-exercise-time/guide/index.html new file mode 100644 index 00000000..22519f6c --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/guide/index.html @@ -0,0 +1,259 @@ + + + + + + + + + + + + + Instructor’s guide — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Instructor’s guide

+
+

Learner personas

+

A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

+

A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

+

B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

+

Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren’t familiar.

+

Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter

+
+
+

About each section

+

In general, “Python for Scientific Computing could be a multi-year +course. We can’t even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path.

+
    +

  • Python intro: We can’t really replace a Python tutorial, but +here we try to outline some of the main points. We don’t go over +this in the course.

    • +

  • Jupyter: Jupyter is somewhat useful, but the main reason we go +over it is that it provides a convenient user interface for the +other programming lessons (it’s easier to spend a bit of time with +Jupyter than expect people to be able to use some +editor/IDE/shell/etc). So, we do start from the beginning, so that +people can do the other lessons, but also try to teach some advanced +tips and tricks.

    • +

  • Numpy: The basic of much of the rest of scipy, so we need to +cover it. We try to get the main principles out, but if someone +already knows it this can be a bit boring. We try to make sure +everyone comes out with an appreciation for vectorization and +broadcasting.

    • +

  • Pandas: A lot of similar goals to the Numpy section, especially +the concepts behind Dataframes that one needs to know in order to +read other documentation.

    • +

  • Visualization: Matplotlib is getting a bit old, but is still the +backbone of other plotting packages. We try to get forth the ideas +of the matplotlib API that can be seen in other packages and the +importance of scripted plots.

    • +

  • Data formats: Input/output/storage is a common task, and can +easily either be a bottleneck or a huge mess. This lessons tries to +show some best practices with data formats and, as usual, get the +idea to not “do it yourself”. Pandas is used as a common framework, +but we should point out there are plenty of other options.

    • +

  • Scripts: The most important lesson here is to break out of +Jupyter/run buttons of editors. If you can’t make actual programs +with an actual interface, you can’t scale up.

    +
      +

    • This is the first lesson to introduce the command line. We +recommend being as simple as possible: at least demonstrate the +JupyterLab terminal and discuss the bigger picture behind what it +means and why.

      • +

    • This is also the first lesson to use non-Jupyter code editor. We +recommend again being simple: use the JupyterLab code editor to +start off, and carefully explain what is going on.

      • +
    +
    • +

  • Scipy: We don’t cover much here (this is super short), but the +point is scipy exists and the concept of wrapping existing C/fortran +libraries and so on.

    • +

  • Library ecosystem: This was an overview of the types of packages +available in the “scipy ecosystem”, which is a large and ill-defined +thing. But there is another point: choosing what to use. Do you +trust a half-done thing published on someone’s personal webpage? If +it’s on Github? How do you make your code more reusable? When +coming from academic courses, you get a “build it yourself” idea, +which isn’t sustainable in research.

    • +

  • Parallel programming:

    • +

  • Dependencies: The main point here is environments, another thing +you often don’t learn in courses.

    +
      +

    • There is a lot of material here. Consider what you will demo, +what will be done as exercises, and what is advanced/optional. +However, it is the fourth-day lesson that is most interactive, so +it is OK if it take a while to go through everything.

      • +

    • If someone else installs Anaconda for a user (e.g. admin-managed +laptop), the conda environment creations (with --name, +possibly with --prefix too?) may not work. Be prepared for +this and mention it. You don’t need to solve the problem but +acknowledge that the lesson becomes a demo. The virtualenv part +should hopefully work for them.

      • +
    +
    • +

  • Binder: Binder exists and can help make code +reproducible/reusable by others.

    • +

  • Packaging: How to make your code reusable by others. By the +time we get here, people are tired and the topics get involved. We +more explicitly say “you might want to watch and take this as a +demo”.

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/index.html b/branch/rkdarst--dependengi-exercise-time/index.html new file mode 100644 index 00000000..3678328b --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/index.html @@ -0,0 +1,352 @@ + + + + + + + + + + + + + Python for Scientific Computing — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python for Scientific Computing

+
+

Attending the course 7-10.november.2023?

+

See the course page here +and watch at https://twitch.tv/coderefinery. +Whether you are or aren’t, the course material is below. Videos +will appear in this playlist.

+
+

Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, matplotlib for visualization, and so on. In +addition, it talks about how python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write.

+

This course (like any course) can’t teach you Python… it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to.

+
+

Prerequisites

+ +

These are not prerequisites:

+
    +

  • Any external libraries, e.g. numpy

    • +

  • Knowing how to make scripts or use Jupyter

    • +
+
+
+

Videos and archived Q&A

+

Videos and material from past instances:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

(prereq)

Introduction to Python

30 min

Jupyter

60 min

NumPy or Advanced NumPy

60 min

Pandas

60 min

Data visualization with Matplotlib

30 min

Data formats with Pandas and Numpy

60 min

Scripts

30 min

Web APIs with Python

15 min

SciPy

30 min

Library ecosystem

45 min

Parallel programming

30 min

Dependency management

30 min

Binder

60 min

Packaging

+
+
+
+

Reference

+ +
+
+

Who is the course for?

+

The course is targeted towards these learner personas:

+
    +

  • A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able +to do their research more efficiently and make sure that they are +using the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

    • +

  • A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

    • +

  • B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves: they want to know how to reuse tools +that already exist.

    • +
+
+
+

Motivation

+
+

Why Python

+

Python has become popular, largely due to good reasons. It’s very easy +to get started, there’s lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities.

+
+
+

Why not Python for Scientific Computing

+

While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools.

+
    +

  • Implementing performance-critical kernels. Python is a very +slow language, which often doesn’t matter if you can offload the +heavy lifting to fast compiled code, e.g. by using Numpy array +operations. But if what you’re trying to do isn’t vectorizable +then you’re out of luck. An alternative to Python, albeit much less +mature and with a smaller ecosystem, but which provides very fast +generated code, is Julia.

    • +

  • Creating libraries that can be called from other languages. In this +case you’ll often want to create a library with a C interface, which +can then be called from most languages. Suitable languages for this +sort of task, depending on what you are doing, could be Rust, C, +C++, or Fortran.

    • +

  • You really like static typing, or functional programming +approaches. Haskell might be what you’re looking for.

    • +
+
+
+

Python 2 vs Python 3

+

Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard.

+

At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2.

+
+
+
+

Credits

+

This course was originally designed by Janne Blomqvist.

+

In 2020 it was completely redesigned by a team of the following:

+
    +

  • Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, …

    • +

  • Editor:

    • +

  • Testers and advisors: Enrico Glerean

    • +
+

We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

+
+
+

See also

+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/installation/index.html b/branch/rkdarst--dependengi-exercise-time/installation/index.html new file mode 100644 index 00000000..06ba51a8 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/installation/index.html @@ -0,0 +1,356 @@ + + + + + + + + + + + + + Software installation — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Software installation

+

This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or some other way access to it. For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line for some lessons).

+

If you need installation help, show this page to someone around you +and they can probably do all you need

+
+

Generic list of tools required

+

Note: The actual installation instructions are below. This is a +generic description which will help those who already understand all +of the tools.

+
    +

  • Python 3 (Anaconda is recommended, it will include everything)

    +
      +

    • With some extra packages installed. They are all included in +Aanconda, and are listed in the environment.yml file you can +find under miniconda below.

      • +
    +
    • +

  • Text editor (several lessons, can also be done through Jupyterlab)

    • +

  • Command-line shell (several lessons, can also be done through Jupyterlab)

    • +

  • git (not needed, this lesson is usually done as a demo)

    • +
+
+

Generic instructions with miniconda and an environment file (advanced)

+

This is the advanced, minimal method of installing the Python +packages. For most people, we recommend Anaconda (below). You +will actually learn about miniconda during the workshop. This +doesn’t provide the graphical Anaconda navigator, so you’ll need to +activate the miniconda environment using the command line.

+

You can read how to install miniconda from the CodeRefinery +installation instructions.

+

Then this environment file +contains all packages needed, and can be installed with:

+
$ conda env create -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml
+
+
+

Each time you start a new shell, you need to activate miniconda (if +you don’t do run conda init), and then you need to activate the +proper environment with conda activate python-for-scicomp.

+

We might have missed some packages, though, which can be later +installed with conda install.

+
+
+
+

Python

+

We expect you to have a working Python installation with some common +libraries. We recommend that you install the Anaconda python +distribution. The +Anaconda Navigator +provides a convenient way to access the software.

+
+

Other options

+

We recommend Anaconda, Anaconda Navigator, and JupyterLab in these +instructions because it is simple and can be used by everyone. As +you advance in your career, we +recommend that you explore other options as well, but +that can come later.

+

Any other Python distribution which you can install libraries into +would work, but because there are so many different ways to do this, +we don’t support them. You would need the extra libraries mentioned +in the Miniconda instructions above.

+
+
+

JupyterLab

+

We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). If you install the full +Anaconda distribution, this will be available and can be started +either through Anaconda Navigator or command line.

+
+
+

Verification of Python and JupyterLab

+
+

Watch the video

+

See this verification in video form - if you can do this, you are +ready to go for day one. Your exact steps may be a bit different.

+
+

You should be able to start JupyterLab. You can do this from the +Anaconda Navigator (recommended if you have it):

+
+../_images/anaconda-navigator-jupyterlab.png +
+

Starting JupyterLab from the Anaconda Navigator.

+
+
+

… or you can start JupyterLab from the command line:

+
$ jupyter-lab
+(... Jupyter starts in a web browser)
+
+
+

Verify that you can start a Jupyter notebook. We will learn how to +do this in day 1, but you can try running print("Hello, world!") +if you want.

+
+../_images/jupyterlab-notebook.png +
+

Starting a Jupyter Notebook from JupyterLab.

+
+
+
+
+
+

Text editor

+

For one portion of the course, you will need a text editor. If you +don’t know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.

+
+

Other editors

+

Because we need to be simple in our teaching, we only teach the +most basic editors. We encourage you to try out more advanced ones +yourself.

+

For other editors, see the CodeRefinery instructions. You don’t +exactly need a terminal editor - the graphical ones, such as VSCode or +whatever you use now, will work as well.

+
+
+
+

Command line

+

You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed. If you want to +test in advance:

+
    +

  • You can start it from JupyterLab (recommended):

    +
    +../_images/jupyterlab-terminal.png +
    +

    From the JupyterLab launcher, select “Terminal”.

    +
    +
    +
    • +
+
+

Other ways to access the command line

+
    +

  • From the Anaconda Navigator:

    +
    +../_images/anaconda-prompt.png +
    +

    From the Anaconda Navigator, you can select “environments” on the +left, then click on one, then the arrow, then “Open terminal”.

    +
    +
    +
    • +

  • From your operating system’s terminal applications, if you activate +Anaconda.

    • +
+
+
+

Verification of the command line

+

To verify command line usage, type the following commands (without the +$), and you should see the corresponding output that lists the +Python version:

+
$ python -V
+Python 3.8.3
+
+## Or python3...
+$ python3 -V
+Python 3.8.3
+
+
+

Any version of Python 3 through a recent Anaconda should work for the +course.

+
+
+
+

Zoom

+

If this is an online workshop, it might use Zoom. You can see +CodeRefinery instructions for it.

+
+
+

Need help?

+

If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up!

+
+
+

See also

+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/jupyter/index.html b/branch/rkdarst--dependengi-exercise-time/jupyter/index.html new file mode 100644 index 00000000..89abc055 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/jupyter/index.html @@ -0,0 +1,439 @@ + + + + + + + + + + + + + Jupyter — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Jupyter

+
+

Questions

+
    +

  • What is the purpose of a “Computational narrative”?

    • +

  • What role does Jupyter play in development?

    • +

  • When is Jupyter not a good tool?

    • +
+
+
+

Objectives

+

This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.

+
    +

  • Be able to use Jupyter to run examples for the rest of the course.

    • +

  • Be able to run Jupyter in a directory do your own work.

    • +

  • You won’t be a Jupyter expert after this, but should be able to do the rest of the course.

    • +
+
+
+

What is Jupyter?

+

Jupyter is a web-based interactive computing system. It is most well known for having the notebook file format and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a computational narrative.

+

Jupyter is good for data exploration and interactive work.

+

We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.

+
+
+

Getting started with Jupyter

+
    +

  • Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run jupyter-lab. You can also start in from Anaconda Navigator.

    • +
+

For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need.

+

Here, we see a tour of the JupyterLab interface:

+

Main UI tour

+
+
+

Exercises 1

+
+

Exercises: Jupyter-1

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are starting from the navigator, change to the directory you want to use.

      • +

    • If you are starting from the command line, you should navigate to the directory you want to use first.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+
+
+

Running code in Jupyter

+

A notebook is divided into cells. Each cell has some input, and when it is executed an output appears right below it.

+

There are different types of cells: primarily code cells and markdown cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving style to text - you can check out this reference. For example the previous sentence is:

+
Markdown is a lightweight way of giving *style* to `text` - you 
+can check out [this reference](https://commonmark.org/help/).
+
+
+

notebook UI

+

When using keyboard shortcuts, you can switch between edit mode and command mode with Enter and Esc.

+

You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:

+
    +

  • Ctrl-Enter: Run cell

    • +

  • Shift-Enter: Run cell and select cell below

    • +

  • Alt-Enter: Run cell and insert new cell below

    • +

  • a / b: insert new cell above/below

    • +

  • m / y: markdown cell / code cell

    • +

  • x: cut cell

    • +

  • c: copy cell

    • +

  • v: paste cell

    • +

  • d, d: delete cell

    • +
+

Now, let’s look at some code samples:

+
+
+
for i in range(3):
+    print(i)
+
+
+
+
+
0
+1
+2
+
+
+
+
+
+
+
print(sum(range(5)))
+
+
+
+
+
10
+
+
+
+
+

By convention, if the last thing in a cell is an object, that object gets printed:

+
+
+
sum(range(5))
+sum(range(10))
+
+
+
+
+
45
+
+
+
+
+

In addition to raw cells, there are magics, which exist outside of Python. They are a property of the runtime itself (in Python’s case, they come from IPython. For example, the following cell magic %%timeit will use the timeit module to time a cell by running it multiple times):

+
+
+
%%timeit
+for x in range(1000000):
+    x**2
+
+
+
+
+
54.1 ms ± 993 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
+
+
+
+
+

Another example is %%bash which will turn the cell into a shell script (This will only work on operating systems with the Bash shell installed - MacOS and Linux at least):

+
+
+
%%bash
+for x in $(seq 3) ; do
+    echo $x
+done
+
+
+
+
+
1
+2
+3
+
+
+
+
+
    +

  • A cell magic starts with %%, goes on the first line of a cell, and applies to the whole cell

    • +

  • A line magic starts with %, goes on any line, and applies to that line.

    • +
+
+
+

Exercises 2

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+ +
+
+

Why Jupyter?

+
    +

  • Being able to edit, check, re-edit quickly is great for prototyping and testing new ideas

    +
      +

    • Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.

      • +
    +
    • +

  • You can make a complete story - in one place. No more having code, figures, and description in different places.

    +
      +

    • Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.

      • +
    +
    • +

  • Notebook as an interactive publication itself - for example the discovery of gravitational waves data is released as a notebook.

    • +

  • Jupyter Notebooks display on Github - low-barrier way to share your analysis.

    • +

  • Teaching - great for getting difficult software distribution out of the way.

    • +
+
+
+

Why not Jupyter?

+

Jupyter is great for many things, but there are some problems if not used well:

+
    +

  • They don’t promote modularity, and once you get started in a +notebook it can be hard to migrate to modules.

    • +

  • They are difficult to test. There are things to run notebooks as +unit tests like nbval, but it’s not +perfect.

    • +

  • Notebooks can be version controlled +(nbdime helps with that), but +there are still limitations.

    • +

  • You can change code after you run it and run code out of order. +This can make debugging hard and results irreproducible if you +aren’t careful.

    • +

  • Notebooks aren’t named by default and tend to acquire a bunch of +unrelated stuff. Be careful with organization!

    • +

  • Once lots of code is in notebooks, it can be hard to change to +proper programs that can be scripted.

    • +
+

You can read more about these downsides https://scicomp.aalto.fi/scicomp/jupyter-pitfalls/.

+

But these downsides aren’t specific to Jupyter! They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.

+
+
+

Exercises 3

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Jupyter is powerful and can be used for interactive work

    • +

  • … but not the end solution when you need to scale up.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/libraries/index.html b/branch/rkdarst--dependengi-exercise-time/libraries/index.html new file mode 100644 index 00000000..e31656ad --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/libraries/index.html @@ -0,0 +1,492 @@ + + + + + + + + + + + + + Library ecosystem — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Library ecosystem

+
+

Questions

+
    +

  • What happens when you need some method Beyond what we discuss in this course, what is available?

    • +

  • How do you decide what to build on for your work?

    • +
+
+
+

Objectives

+
    +

  • Know of some other available packages, but don’t necessarily know +how to use them.

    • +

  • Be able to evaluate what you should reuse and what you should +develop yourself.

    • +
+
+

You can’t do everything yourself. In fact, once we heard a quote such +as this:

+
+

When you are a student, you are expected to do everything +yourself, and that is how you are evaluated. When you become a +researcher, you have to be able to reuse what others have done. +We don’t have much practice in doing this. +– A student

+
+

In this lesson, we’ll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types:

+
    +

  • Well-maintained libraries that are used by many others.

    • +

  • A wide variety of public code that might work but isn’t necessarily +well-maintained (for example, code from articles).

    • +
+

We’ll start with the first then go to the second.

+
+

Glossary

+
+
Library

A collection of code used by a program.

+
+
Package

A library that has been made easily installable and reusable. +Often published on public repositories such as the Python Package +Index

+
+
Dependency

A requirement of another program, not included in that program.

+
+
+
+
+

The Python/SciPy ecosystem

+

This section is nothing more than a tour of what exists in Python. +You aren’t expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work.

+

The “core” packages could be considered. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy):

+
    +

  • Python

    • +

  • Numpy - arrays, everything builds on this

    • +

  • Scipy - scientific functions (not necessarily a lot builds on this)

    • +

  • matplotlib - plotting, many other plotting tools build on this

    • +

  • pandas - data structures

    • +

  • IPython / Jupyter: interactive work

    • +
+
+

Core numerics libraries

+
    +

  • numpy - arrays and array math.

    • +

  • scipy - software +for math, science, and engineering.

    • +
+
+
+

Plotting

+
    +

  • matplotlib - base plotting package, +somewhat low level but almost everything builds on it.

    • +

  • seaborn - higher level plotting +interface; statistical graphics.

    • +

  • mayavi - 3D plotting

    • +

  • PIL - image manipulation. The +original PIL is no longer maintained, the new “Pillow” is a drop-in +replacement.

    • +
+
+
+

Data analysis and other important core packages

+ +
+
+

Interactive computing and human interface

+
    +

  • Interactive computing

    +
      +

    • IPython - nicer interactive interpreter

      • +

    • Jupyter (notebook, lab, hub, …) - +web-based interface to IPython and other languages

      • +
    +
    • +

  • Testing

    +
      +

    • pytest - automated testing interface

      • +
    +
    • +

  • Documentation

    +
      +

    • Sphinx - documentation generator +(also used for this lesson…)

      • +
    +
    • +

  • Development environments

    +
      +

    • Spyder - interactive Python +development environment.

      • +
    +
    • +

  • Binder - load any git repository in +Jupyter automatically, good for reproducible research

    • +
+
+
+

Speeding up code and parallelism

+
    +

  • PyMPI - Message +Passing Interface (MPI) in Python for parallelizing jobs.

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • numba - just in time compiling of +functions for speed-up

    • +

  • PyPy - Python written in Python so that +it can internally optimize more.

    • +

  • Dask - distributed array data structure for +distributed computation

    • +

  • Joblib - easy embarrassingly +parallel computing

    • +

  • IPyParallel - easy +parallel task engine

    • +

  • numexpr - Fast evaluation of +array expressions by automatically compiling the arithmetic.

    • +
+
+
+

Machine learning

+

If you need some machine learning, you probably already know what you +need and this list is short and irrelevant.

+ +
+
+
+

Connecting Python to other languages

+

As we discussed with Scipy, very many of the above packages aren’t +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things:

+
    +

  • Extending Python by writing your own modules in C.

    +
      +

    • It’s actually common to first have (or write) an analysis package +in C or C++, then make the Python interface. Then it can be +supported by other languages, too.

      • +

    • Or one starts an analysis package in Python, and slowly moves bits +of it to C over time as there is need.

      • +
    +
    • +

  • Embedding Python, where you have another primary application +that uses Python under the hood as an internal scripting language.

    • +
+

These features aren’t exactly unique to Python, but Python does +support them very well. Read more: Extending and embedding Python.

+
+

Tools for interfacing with other languages

+

These days, one rarely directly extends the Python interpreter, but uses

+
    +

  • cffi and ctypes - interface to C +and compatible libraries

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • f2py - interface to Fortran +code

    • +

  • swig - connect to a variety of programming languages.

    • +

  • Boost.python - Another Python/C++ interface

    • +

  • TODO: Julia modules for Python?

    • +
+
+
+
+

Evaluating Python packages for reuse

+

Above, we talked about well-maintained mainstream packages. Do you +trust random code you find online (for example included in a paper)?

+

Especially consider scientific results, which have to be correct. +Still, you also can’t build everything yourself, so you have to +carefully evaluate the situation.

+

Below are some things to consider:

+
    +

  • Are there releases? Have they been going on for a while?

    • +

  • Are releases installable without copy-paste?

    • +

  • Are dependencies handled well?

    • +

  • Does the code randomly change, so that it no longer works with your +code. Is this relevant?

    • +

  • Is there good documentation, that not just tells how to use it but +how it works?

    • +

  • Is there automated testing? What’s your evaluation of the risk of +undetectable scientific errors?

    • +

  • Is there a community, or is it one person? Is it backed by some +organization? Does it have a permanent home?

    • +

  • Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) +where a community could form?

    • +

  • Do others post issues and make contributions? Are these issues +dealt with in a timely manner? Can you search past bug reports?

    • +

  • Is the software citeable?

    • +
+
+
+

Is your work reuseable?

+

Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a CodeRefinery workshop will make +sure you have the tools to produce high-quality, reusable code.

+
+
+

What’s next?

+
    +

  • The CodeRefinery workshop mentioned +above will prepare you for others to reuse your code and for you to +contribute to other code.

    • +

  • The upcoming Dependency management lesson will teach you how to +record and manage dependencies so that anyone can seamlessly reuse +your code.

    • +
+
+
+

Exercises

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+ +
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • Almost everything you need can already be found, except your +incremental work.

    • +

  • When do you build on that other work, and when do you create +things yourself?

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/numpy-advanced/index.html b/branch/rkdarst--dependengi-exercise-time/numpy-advanced/index.html new file mode 100644 index 00000000..9cafb0f4 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/numpy-advanced/index.html @@ -0,0 +1,575 @@ + + + + + + + + + + + + + Advanced NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Advanced NumPy

+
+

Questions

+
    +

  • How can NumPy be so fast?

    • +

  • Why are some things fast and some things slow?

    • +

  • How can I control whether NumPy makes a copy or operates in-place?

    • +
+
+
+

Objectives

+
    +

  • Understand why NumPy has so many specialized functions for specific operations

    • +

  • Understand the underlying machinery of the Numpy ndarray object

    • +

  • Understand when and why NumPy makes a copy of the data rather than a view

    • +
+

This is intended as a follow-up to the basic NumPy lesson. The intended +audience for this advanced lesson is those who have used NumPy before and +now want to learn how to get the most out of this amazing package.

+
+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +Guide to NumPy by +Travis E. Oliphant, its initial creator.

+
+

NumPy can be really fast

+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast.

+

How fast can NumPy be? Let’s race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:

+
#include <stdlib.h>
+#include <stdio.h>
+#define N_ELEMENTS 100000000
+int main(int argc, char** argv) {
+    double* a = (double*) malloc(sizeof(double) * N_ELEMENTS);
+    int i;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        a[i] = (double) rand() / RAND_MAX;
+    }
+    double sum = 0;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        sum += a[i];
+    }
+    printf("%f", sum);
+    return 0;
+}
+
+
+
+
+

Exercise 1

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lession before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+ +
+
+

The libraries behind the curtain: MKL and BLAS

+

NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel’s Math Kernel Library (MKL), +which are in turn derived from a Fortran library called +Basic Linear Algebra Subprograms (BLAS). +BLAS for Fortran was published in 1979 +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +specialized CPU instructions for manipulating arrays. +In other words, they are fast.

+

One of the functions inside the BLAS library is a +function +to compute the “norm” of a vector, which is the same as computing its length, using the +Pythagorean theorem: +\(\sqrt(a[0]^2 + a[1]^2 + \ldots)\).

+

Let’s race the BLAS function versus a naive “manual” version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:

+
import numpy as np
+rng = np.random.default_rng(seed=0)
+a = rng.random(100_000_000)
+
+
+

We now implement the Pythagorean theorem using basic NumPy functionality and +use %%timeit to record how long it takes to execute:

+
%%timeit
+l = np.sqrt(np.sum(a ** 2))
+print(l)
+
+
+

And here is the version using the specialized BLAS function norm():

+
%%timeit
+l = np.linalg.norm(a)
+print(l)
+
+
+
+
+

NumPy tries to avoid copying data

+

Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy’s +numpy.ndarray datastructure works behind the scenes.

+
+

An example: matrix transpose

+

Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let’s see how long NumPy’s +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +rand() matrix:

+
import numpy as np
+a = np.random.rand(10_000, 20_000)
+print(f'Matrix `a` takes up {a.nbytes / 10**6} MB')
+
+
+

Let’s time the transpose() method:

+
%%timeit
+b = a.transpose()
+
+
+

It takes mere nanoseconds to transpose 1600 MB of data! How?

+
+
+

The ndarray exposed

+

The first thing you need to know about numpy.ndarray is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector.

+../_images/01_memory_layout.svg

NumPy is faking the second dimension behind the scenes! When we request the +element at say, [2, 3], NumPy converts this to the correct index in the +long 1D array [11].

+
+
    +

  • Converting [2, 3] → [11] is called “raveling”

    • +

  • The reverse, converting [11] → [2, 3] is called “unraveling”

    • +
+
+

The implications of this are many, so take let’s take some time to understand +it properly by writing our own ravel() function.

+
+
+
+

Exercise 2

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+ +
+
+

Strides

+

As seen in the exercise, to get to the next row, we have to skip over +n_cols indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of “strides”:

+
np.zeros((4, 8)).strides           # (64, 8)
+np.zeros((4, 5, 6, 7, 8)).strides  # (13440, 2688, 448, 64, 8)
+
+
+

The strides attribute contains for each dimension, the number of bytes (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes.

+

So now we know the mystery behind the speed of transpose(). NumPy can avoid +copying any data by just modifying the strides of the array:

+
import numpy as np
+
+a = np.random.rand(10_000, 20_000)
+b = a.transpose()
+
+print(a.strides)  # (160000, 8)
+print(b.strides)  # (8, 160000)
+
+
+
+

Another example: reshaping

+

Modifying the shape of an array through numpy.reshape() is also +accomplished without any copying of data by modifying the strides:

+
a = np.random.rand(20_000, 10_000)
+print(f'{a.strides=}')  # (80000, 8)
+b = a.reshape(40_000, 5_000)
+print(f'{b.strides=}')  # (40000, 8)
+c = a.reshape(20_000, 5_000, 2)
+print(f'{c.strides=}')  # (80000, 16, 8)
+
+
+
+
+
+

Exercises 3

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+ +
+
+

A fast thing + a fast thing = a fast thing?

+

If numpy.transpose() is fast, and numpy.reshape() is fast, then +doing them both must be fast too, right?:

+
# Create a large array
+a = np.random.rand(10_000, 20_000)
+
+
+

Measuring the time it takes to first transpose and then reshape:

+
%%timeit -n 1 -r 1
+a.T.reshape(40_000, 5_000)
+
+
+

In this case, the data actually had to be copied and it’s super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the strides:

+
a = np.array([[1, 2, 3], [4, 5, 6]])
+
+print('Original array:')
+print(a)
+
+print('\nTransposed:')
+print(a.T)
+
+print('\nTransposed and then reshaped:')
+print(a.T.reshape(2, 3))
+
+
+
+
+

Copy versus view

+

Whenever NumPy constructs a new array by modifying the strides instead of +copying data, we way it created a “view”. This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +numpy.ndarray object will have a reference to the original array in +its base attribute:

+
a = np.zeros((5, 5))
+print(a.base)  # None
+b = a[:2, :2]
+print(b.base.shape)  # (5, 5)
+
+
+
+

Warning

+

When you create a large array and select only a portion of it, the large +array will stay in memory if a view was created!

+
+

The new array b object has a pointer to the same memory buffer as the array +it has been derived from:

+
print(a.__array_interface__['data'])
+print(b.__array_interface__['data'])
+
+
+

Views are created by virtue of modifying the value of the shape attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:

+
b = a[1:3, 1:3]   # This view does not start at the beginning
+offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0]
+print('Offset:', offset, 'bytes')  # Offset: 48 bytes
+
+
+../_images/02_views.svg

Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:

+
b[0, 0] = 1.
+print(a)  # Original matrix was modified
+
+
+

Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:

+
c = a[[0, 2]]  # Select rows 0 and 2
+print(c.base)  # None. So not a view.
+
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • The best way to make your code more efficient is to learn more about the +NumPy API and use specialized functions whenever possible.

    • +

  • NumPy will avoid copying data whenever it can. Whether it can depends on +what kind of layout the data is currently in.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/numpy/index.html b/branch/rkdarst--dependengi-exercise-time/numpy/index.html new file mode 100644 index 00000000..3b1728ab --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/numpy/index.html @@ -0,0 +1,643 @@ + + + + + + + + + + + + + NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

NumPy

+
+

Questions

+
    +

  • Why use NumPy instead of pure python?

    • +

  • How to use basic NumPy?

    • +

  • What is vectorization?

    • +
+
+
+

Objectives

+
    +

  • Understand the Numpy array object

    • +

  • Be able to use basic NumPy functionality

    • +

  • Understand enough of NumPy to seach for answers to the rest of your questions ;)

    • +
+

We expect most people to be able to do all the basic exercises +here. It is probably quite easy for many people; we have advanced +exercises at the end in that case.

+
+

So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible.

+
+

What is an array?

+

For example, consider [1, 2.5, 'asdf', False, [1.5, True]] - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately.

+

NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it.

+

An array is a ‘grid’ of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has:

+
    +

  • dtype - data type. Arrays always contain one type

    • +

  • shape - shape of the data, for example 3×2 or 3×2×500 or even +500 (one dimensional) or [] (zero dimensional).

    • +

  • data - raw data storage in memory. This can be passed to C or +Fortran code for efficient calculations.

    • +
+

To test the performance of pure Python vs NumPy we can write in our jupyter notebook:

+

Create one list and one ‘empty’ list, to store the result in

+
a = list(range(10000))
+b = [ 0 ] * 10000
+
+
+

In a new cell starting with %%timeit, loop through the list a and fill the second list b with a squared

+
%%timeit
+for i in range(len(a)):
+  b[i] = a[i]**2
+
+
+

That looks and feels quite fast. But let’s take a look at how NumPy performs for the same task.

+

So for the NumPy example, create one array and one ‘empty’ array to store the result in

+
import numpy as np
+a = np.arange(10000)
+b = np.zeros(10000)
+
+
+

In a new cell starting with %%timeit, fill b with a squared

+
%%timeit
+b = a ** 2
+
+
+

We see that compared to working with numpy arrays, working with traditional python lists is actually slow.

+
+
+

Creating arrays

+

There are different ways of creating arrays (numpy.array(), numpy.ndarray.shape, numpy.ndarray.size):

+
a = np.array([1,2,3])               # 1-dimensional array (rank 1)
+b = np.array([[1,2,3],[4,5,6]])     # 2-dimensional array (rank 2)
+
+b.shape                             # the shape (rows,columns)
+b.size                              # number of elements
+
+
+

In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (numpy.zeros(), numpy.ones(), numpy.full(), numpy.eye(), numpy.arange(), numpy.linspace()):

+
np.zeros((2, 3))             # 2x3 array with all elements 0
+np.ones((1,2))               # 1x2 array with all elements 1
+np.full((2,2),7)             # 2x2 array with all elements 7
+np.eye(2)                    # 2x2 identity matrix
+
+np.arange(10)                # Evenly spaced values in an interval
+np.linspace(0,9,10)          # same as above, see exercise
+
+c = np.ones((3,3))
+d = np.ones((3, 2), 'bool')  # 3x2 boolean array
+
+
+

Arrays can also be stored and read from a (.npy) file (numpy.save(), numpy.load()):

+
np.save('x.npy', a)           # save the array a to a .npy file
+x = np.load('x.npy')          # load an array from a .npy file and store it in variable x
+
+
+

In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (numpy.ndarray.dtype, numpy.ndarray.astype()):

+
d.dtype                    # datatype of the array
+d.astype('int')            # change datatype from boolean to integer
+
+
+

In the last example, .astype('int'), it will make a copy of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed.

+
+
+

Exercises 1

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+ +
+
+

Array maths and vectorization

+

Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do.

+

By default, basic arithmetic (+, -, *, /) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is “vectorized” +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop.

+

Note that unlike Matlab, where * means matrix multiplication, NumPy uses +* to perform element-by-element multiplication and uses the @ symbol to +perform matrix multiplication:

+
a = np.array([[1,2],[3,4]])
+b = np.array([[5,6],[7,8]])
+
+# Addition
+c = a + b
+d = np.add(a,b)
+
+# Matrix multiplication
+e = a @ b
+f = np.dot(a, b)
+
+
+

Other common mathematical operations include: - (numpy.subtract), * (numpy.multiply), / (numpy.divide), .T (numpy.transpose()), numpy.sqrt, numpy.sum(), numpy.mean(), …

+
+
+

Exercises 2

+
+

Exercises: Numpy-2

+ +
+ +
+
+

Indexing and Slicing

+
+

See also

+

Numpy basic indexing docs

+
+

NumPy has many ways to extract values out of arrays:

+
    +

  • You can select a single element

    • +

  • You can select rows or columns

    • +

  • You can select ranges where a condition is true.

    • +
+

Clever and efficient use of these operations is a key to NumPy’s +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C.

+
a = np.arange(16).reshape(4, 4)  # 4x4 matrix from 0 to 15
+a[0]                             # first row
+a[:,0]                           # first column
+a[1:3,1:3]                       # middle 2x2 array
+
+a[(0, 1), (1, 1)]                # second element of first and second row as array
+
+
+

Boolean indexing on above created array:

+
idx = (a > 0)      # creates boolean matrix of same size as a
+a[idx]             # array with matching values of above criterion
+
+a[a > 0]           # same as above in one line
+
+
+
+
+

Exercises 3

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+ +
+
+

Types of operations

+

There are different types of standard operations in NumPy:

+

ufuncs, “universal functions”: These are element-by-element +functions with standardized arguments:

+
    +

  • One, two, or three input arguments

    • +

  • For example, a + b is similar to np.add(a, b) but the ufunc +has more control.

    • +

  • out= output argument, store output in this array (rather than +make a new array) - saves copying data!

    • +

  • See the full reference

    • +

  • They also do broadcasting (ref). Can you add a 1-dimensional array of shape (3) +to an 2-dimensional array of shape (3, 2)? With broadcasting you +can!

    +
    a = np.array([[1, 2, 3],
+              [4, 5, 6]])
+b = np.array([10, 10, 10])
+a + b                       # array([[11, 12, 13],
+                            #        [14, 15, 16]])
+
    +
    +

    Broadcasting is smart and consistent about what it does, which I’m +not clever enough to explain quickly here: the manual page on +broadcasting. +The basic idea is that it expands dimensions of the smaller array so +that they are compatible in shape.

    +
    • +
+

Array methods do something to one array:

+
    +

  • Some of these are the same as ufuncs:

    +
    x = np.arange(12)
+x.shape = (3, 4)
+x                    #  array([[ 0,  1,  2,  3],
+                     #         [ 4,  5,  6,  7],
+                     #         [ 8,  9, 10, 11]])
+x.max()              #  11
+x.max(axis=0)        #  array([ 8,  9, 10, 11])
+x.max(axis=1)        #  array([ 3,  7, 11])
+
    +
    +
    • +
+

Other functions: there are countless other functions covering +linear algebra, scientific functions, etc.

+
+
+

Exercises 4

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+ +
+
+

Linear algebra and other advanced math

+

In general, you use arrays (n-dimensions), not matrixes +(specialized 2-dimensional) in NumPy.

+

Internally, NumPy doesn’t invent its own math routines: it relies on +BLAS +and LAPACK to do this kind +of math - the same as many other languages.

+
    +

  • Linear algebra in numpy

    • +

  • Many, many other array functions

    • +

  • Scipy has even +more functions

    • +

  • Many other libraries use NumPy arrays as the standard data +structure: they take data in this format, and return it similarly. +Thus, all the other packages you may want to use are compatible

    • +

  • If you need to write your own fast code in C, NumPy arrays can be +used to pass data. This is known as extending Python.

    • +
+
+
+

Additional exercises

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally.

    • +

  • Be aware of some NumPy specific peculiarities

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/objects.inv b/branch/rkdarst--dependengi-exercise-time/objects.inv new file mode 100644 index 00000000..6a5684cf Binary files /dev/null and b/branch/rkdarst--dependengi-exercise-time/objects.inv differ diff --git a/branch/rkdarst--dependengi-exercise-time/packaging/index.html b/branch/rkdarst--dependengi-exercise-time/packaging/index.html new file mode 100644 index 00000000..9dd1c012 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/packaging/index.html @@ -0,0 +1,495 @@ + + + + + + + + + + + + + Packaging — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Packaging

+
+

Questions

+
    +

  • How to organize Python projects larger than one script?

    • +

  • What is a good file and folder structure for Python projects?

    • +

  • How can you make your Python functions most usable by your collaborators?

    • +

  • How to prepare your code to make a Python package?

    • +

  • How to publish your Python package?

    • +
+
+
+

Objectives

+
    +

  • Learn to identify the components of a Python package

    • +

  • Learn to create a Python package

    • +

  • Learn to publish a Python package

    • +
+
+
+

Organizing Python projects

+

Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file.

+

In the Scripts episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further.

+

Recommendations:

+ +

To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: scipy.

+

These are the 3 files:

+
+
adding.py
+
def add(x, y):
+    return x + y
+
+
+
+
+
subtracting.py
+
def subtract(x, y):
+    return x - y
+
+
+
+
+
integrating.py
+
from scipy import integrate
+
+
+def integral(function, lower_limit, upper_limit):
+    return integrate.quad(function, lower_limit, upper_limit)
+
+
+
+

We will add a fourth file:

+
+
__init__.py
+
"""
+Example calculator package.
+"""
+
+from .adding import add
+from .subtracting import subtract
+from .integrating import integral
+
+__version__ = "0.1.0"
+
+
+
+

This __init__.py file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using relative imports +(with the dot).

+

This is how we will arrange the files in the project folder/repository:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+└── README.md
+
+
+

Now we are ready to test the package. For this we need to be in the “root” +folder, what we have called the project-folder. We also need to have +scipy available in our environment:

+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+

The package is not yet pip-installable, though. We will make this possible in +the next section.

+
+
+

Testing a local pip install

+

To make our example package pip-installable we need to add one more file:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+├── README.md
+└── pyproject.toml
+
+
+

This is how pyproject.toml looks:

+
+
pyproject.toml
+
[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "calculator-myname"
+description = "A small example package"
+version = "0.1.0"
+readme = "README.md"
+authors = [
+    { name = "Firstname Lastname", email = "firstname.lastname@example.org" }
+]
+dependencies = [
+    "scipy"
+]
+
+
+
+

Note how our package requires scipy and we decided to not pin the version +here (see Version pinning for package creators).

+

Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see PyPI (The Python Package Index) and (Ana)conda)

+
+
+

Exercises 1

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Sharing packages via PyPI

+

Once we are able to pip-install the example package locally, we are ready for +upload.

+

We exercise by uploading to test-PyPI, not the +real PyPI, so that if we mess things up, nothing bad +happens.

+

We need two more things:

+
    +

  • We will do this using Twine so you need +to pip install that, too.

    • +

  • You need an account on test-PyPI.

    • +
+

Let’s try it out. First we create the distribution package:

+
$ python3 -m build
+
+
+

We need twine:

+
$ pip install twine
+
+
+

And use twine to upload the distribution files to test-PyPI:

+
$ twine upload -r testpypi dist/*
+
+Uploading distributions to https://test.pypi.org/legacy/
+Enter your username:
+Enter your password:
+
+
+

Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt “myname”):

+
$ pip install -i https://test.pypi.org/simple/ calculator-myname
+
+
+
+
+

Tools that simplify sharing via PyPI

+

The solution that we have used to create the example package (using +setuptools and twine) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using pyproject.toml as more general +alternative to the previous setup.py.

+

There are at least two tools which try to make the packaging and PyPI interaction easier:

+ +
+
+

Building a conda package and share it

+
+

Demo

+

Most people will watch and observe this, due to speed which we will +move.

+
+
+

Prerequisites

+

To create a conda package, conda-build package is required. You may install it with Anaconda Navigator or from the command line:

+
$ conda install conda-build
+
+
+
+

The simplest way for creating a conda package for your python script is to +first publish it in PyPI following the steps explained +above.

+
+

Building a python package with conda skeleton pypi

+

Once build, the conda package can be installed locally. For this example, we +will use runtest. runtest is a numerically tolerant end-to-end test +library for research software.

+
    +

  1. Create pypi skeleton:

    +
    $ conda skeleton pypi runtest
+
    +
    +

    The command above will create a new folder called runtest containing a file meta.yaml, the conda recipe for runtest.

    +
    2. +

  2. Edit meta.yaml and update requirements:

    +
    requirements:
+  host:
+    - pip
+    - python
+    - flit
+  run:
+    - python
+    - flit
+
    +
    +

    In the requirements above, we specified what is required for the host and for running the package.

    +
    +

    Remark

    +

    For pure python recipes, this is all you need for building a python package with conda. +If your package needs to be built (for instance compilation), you would need additional files e.g. build.sh (to build on Linux/Mac-OSX) and bld.bat (to build on Windows systems). You can also add test scripts for testing your package. See documentation

    +
    +
    3. +

  3. Build your package with conda

    +

    Your package is now ready to be build with conda:

    +
    $ conda-build runtest
+
    +
    +
    +

    Conda package location

    +

    Look at the messages produced while building. The location of the local conda package is given (search for anaconda upload):

    +
    ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2
+
    +
    +

    The prefix ~/anaconda3/ may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder win-64 differs too (for instance linux-64 on Linux machines).

    +

    The conda package we have created is specific to your platform (here win-64). It can be converted to other platforms using conda convert.

    +
    +
    4. +

  4. Check within new environment

    +

    It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments.

    +
    $ conda create -n local-runtest --use-local runtest
+
    +
    +

    We can then check runtest has been successfully installed in local-runtest conda environment. Open a new Terminal with local-runtest environment (either from the command line:

    +
    $ conda activate local-runtest
+
    +
    +

    or via Anaconda Navigator (Open Terminal), import runtest and +check its version:

    +
    import runtest
+print(runtest.__version__)
+
    +
    +
    5. +
+
+

Building a conda package from scratch

+

It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the conda-build documentation for more information.

+
+

To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a conda channel (see below).

+
+
+

Publishing a python package

+
    +

  • Upload your package to Anaconda.org: see instructions here. +Please note that you will have to create an account on Anaconda.

    • +

  • Upload your package to conda-forge: +conda-forge is a conda channel: it contains community-led collection of +recipes, build infrastructure and distributions for the conda package +manager. Anyone can public conda packages to conda-forge if certain +guidelines are respected.

    • +

  • Upload your package to bioconda: bioconda is +a very popular channel for the conda package manager specializing in +bioinformatics software. As for conda-forge, you need to follow their +guidelines when +building conda recipes.

    • +
+

You can also create your own conda channel +for publishing your packages.

+
+

Keypoints

+
    +

  • It is worth it to organize your code for publishing, even if only +you are using it.

    • +

  • PyPI is a place for Python packages

    • +

  • conda is similar but is not limited to Python

    • +
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/pandas/index.html b/branch/rkdarst--dependengi-exercise-time/pandas/index.html new file mode 100644 index 00000000..2fbeffc4 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/pandas/index.html @@ -0,0 +1,751 @@ + + + + + + + + + + + + + Pandas — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Pandas

+
+

Questions

+
    +

  • How do I learn a new Python package?

    • +

  • How can I use pandas dataframes in my research?

    • +
+
+
+

Objectives

+
    +

  • Learn simple and some more advanced usage of pandas dataframes

    • +

  • Get a feeling for when pandas is useful and know where to find more information

    • +

  • Understand enough of pandas to be able to read its documentation.

    • +
+
+

Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including:

+ +
+

A quick Pandas preview

+

Let’s get a flavor of what we can do with pandas (you won’t be able to follow everything yet). We will be working with an example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:

+
import pandas as pd
+
+
+

We can download the data from this GitHub repository +by visiting the page and saving it to disk, or by directly reading into +a DataFrame:

+
url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv"
+titanic = pd.read_csv(url, index_col='Name')
+
+
+

We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:

+
# print the first 5 lines of the dataframe
+titanic.head()
+
+
+
# print summary statistics for each column
+titanic.describe()
+
+
+

Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38% of passengers survived, etc.

+

Let’s say we’re interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn’t survive, and plot corresponding histograms of +the age distribution (pandas.DataFrame.groupby(), pandas.DataFrame.hist()):

+
print(titanic.groupby("Survived")["Age"].mean())
+
+
+
titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10),
+             layout=(2,1), zorder=2, sharex=True, rwidth=0.9);
+
+
+

Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let’s get back to basics.

+
+

Getting help

+

Series and DataFrames have a lot functionality, but +how can we find out what methods are available and how they work? One way is to visit +the API reference +and reading through the list. +Another way is to use the autocompletion feature in Jupyter and type e.g. +titanic["Age"]. in a notebook and then hit TAB twice - this should open +up a list menu of available methods and attributes.

+

Jupyter also offers quick access to help pages (docstrings) which can be +more efficient than searching the internet. Two ways exist:

+
    +

  • Write a function name followed by question mark and execute the cell, e.g. +write titanic.hist? and hit SHIFT + ENTER.

    • +

  • Write the function name and hit SHIFT + TAB.

    • +

  • Right click and select “Show contextual help”. This tab will +update with help for anything you click.

    • +
+
+
+
+

What’s in a dataframe?

+

As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +pandas.DataFrame +is composed of rows and columns:

+../_images/01_table_dataframe.svg

Each column of a dataframe is a pandas.Series object +- a dataframe is thus a collection of series:

+
# print some information about the columns
+titanic.info()
+
+
+

Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type int64 or of type object.

+

Let’s inspect one column of the Titanic passanger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):

+
titanic["Age"]
+titanic.Age          # same as above
+
+
+
type(titanic["Age"]) # a pandas Series object
+
+
+

The columns have names. Here’s how to get them (columns):

+
titanic.columns
+
+
+

However, the rows also have names! This is what Pandas calls the index:

+
titanic.index
+
+
+

We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and +values. We can refer to columns and rows either by their name +(loc, at) or by +their index (iloc, +iat):

+
titanic.loc['Lam, Mr. Ali',"Age"]          # select single value by row and column
+titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"]  # slice the dataframe by row and column *names*
+titanic.iloc[0:2,3:6]                      # same slice as above by row and column *numbers*
+
+titanic.at['Lam, Mr. Ali',"Age"] = 42      # set single value by row and column *name* (fast)
+titanic.at['Lam, Mr. Ali',"Age"]           # select single value by row and column *name* (fast)
+titanic.iat[0,5]                           # select same value by row and column *number* (fast)
+
+titanic["is_passenger"] = True             # set a whole column
+
+
+

Dataframes also support boolean indexing, just like we saw for numpy +arrays:

+
titanic[titanic["Age"] > 70]
+# ".str" creates a string object from a column
+titanic[titanic.index.str.contains("Margaret")]
+
+
+

What if your dataset has missing data? Pandas uses the value numpy.nan +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:

+
titanic.isna()                    # returns boolean mask of NaN values
+titanic.dropna()                  # drop missing values
+titanic.dropna(how="any")         # or how="all"
+titanic.dropna(subset=["Cabin"])  # only drop NaNs from one column
+titanic.fillna(0)                 # replace NaNs with zero
+titanic.fillna(method='ffill')    # forward-fill NaNs
+
+
+
+
+

Exercises 1

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+
+
+

Tidy data

+

The above analysis was rather straightforward thanks to the fact +that the dataset is tidy.

+../_images/tidy_data.png +

In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data.

+

What would untidy data look like? Here’s an example from +some run time statistics from a 1500 m running event:

+
runners = pd.DataFrame([
+              {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240},
+              {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300},
+              {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360},
+          ])
+
+
+

What makes this data untidy is that the column names 400, 800, 1200, 1500 +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row.

+

To make untidy data tidy, a common operation is to “melt” it, +which is to convert it from wide form to a long form:

+
runners = pd.melt(runners, id_vars="Runner",
+              value_vars=[400, 800, 1200, 1500],
+              var_name="distance",
+              value_name="time"
+          )
+
+
+

In this form it’s easier to filter, group, join +and aggregate the data, and it’s also easier to model relationships +between variables.

+

The opposite of melting is to pivot data, which can be useful to +view data in different ways as we’ll see below.

+

For a detailed exposition of data tidying, have a look at +this article.

+
+
+

Working with dataframes

+

We saw above how we can read in data into a dataframe using the read_csv() function. +Pandas also understands multiple other formats, for example using read_excel, +read_hdf, read_json, etc. (and corresponding methods to write to file: +to_csv, to_excel, to_hdf, to_json, etc.)

+

But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +DataFrame docs):

+
import numpy as np
+dates = pd.date_range('20130101', periods=6)
+df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD'))
+df
+
+
+

or a dictionary (see same docs):

+
df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'],
+                   'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'],
+                   'C': np.array([3] * 8, dtype='int32'),
+                   'D': np.random.randn(8),
+                   'E': np.random.randn(8)})
+df
+
+
+

There are many ways to operate on dataframes. Let’s look at a +few examples in order to get a feeling of what’s possible +and what the use cases can be.

+

We can easily split and concatenate dataframes:

+
sub1, sub2, sub3 = df[:2], df[2:4], df[4:]
+pd.concat([sub1, sub2, sub3])
+
+
+

When pulling data from multiple dataframes, a powerful pandas.DataFrame.merge method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:

+
age = pd.DataFrame([
+    {"Runner": "Runner 4", "Age": 18},
+    {"Runner": "Runner 2", "Age": 21},
+    {"Runner": "Runner 1", "Age": 23},
+    {"Runner": "Runner 3", "Age": 19},
+])
+
+
+

We now want to use this table to annotate the original runners table from +before with their age. Note that the runners and age dataframes have a +different ordering to it, and age has an entry for Dave which is not +present in the runners table. We can let Pandas deal with all of it using +the merge method:

+
# Add the age for each runner
+runners.merge(age, on="Runner")
+
+
+

In fact, much of what can be done in SQL +is also possible with pandas.

+

groupby is a powerful method which splits a dataframe and aggregates data +in groups. To see what’s possible, let’s return to the Titanic dataset. Let’s +test the old saying “Women and children first”. We start by creating a new +column Child to indicate whether a passenger was a child or not, based on +the existing Age column. For this example, let’s assume that you are a +child when you are younger than 12 years:

+
titanic["Child"] = titanic["Age"] < 12
+
+
+

Now we can test the saying by grouping the data on Sex and then creating further sub-groups based on Child:

+
titanic.groupby(["Sex", "Child"])["Survived"].mean()
+
+
+

Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +std, min, +max, cumsum, +median, skew, +var etc.

+
+
+

Exercises 2

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+
+
+

Time series superpowers

+

An introduction of pandas wouldn’t be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv .

+

Unfortunately this API does not allow “non-browser requests”, so +pandas.read_csv will not work directly on it. Instead, we put a +local copy on Github which we can access (the original data is CC-0, +so we are allowed to do this). (Aside: if you do JupyterLab → +File → Open from URL → paste the URL above, it will open it in +JupyterLab and download a copy for your use.)

+

We can then load and explore the data:

+
nobel = pd.read_csv("https://github.com/AaltoSciComp/python-for-scicomp/raw/master/resources/data/laureate.csv")
+nobel.head()
+
+
+

This dataset has three columns for time, “born”/”died” and “year”. +These are represented as strings and integers, respectively, and +need to be converted to datetime format. pandas.to_datetime() +makes this easy:

+
# the errors='coerce' argument is needed because the dataset is a bit messy
+nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce')
+nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce')
+nobel["year"] = pd.to_datetime(nobel["year"], format="%Y")
+
+
+

Pandas knows a lot about dates (using .dt accessor):

+
print(nobel["born"].dt.day)
+print(nobel["born"].dt.year)
+print(nobel["born"].dt.weekday)
+
+
+

We can add a column containing the (approximate) lifespan in years rounded +to one decimal:

+
nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1)
+
+
+

and then plot a histogram of lifespans:

+
nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9)
+
+
+

Finally, let’s see one more example of an informative plot (boxplot()) +produced by a single line of code:

+
nobel.boxplot(column="lifespan", by="category")
+
+
+
+
+

Exercises 3

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries (you need to look at the +data and find how countries are written, and replace COUNTRY +with those strings):

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y=subset["year"].dt.year, x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Beyond the basics

+

Larger DataFrame operations might be faster using eval() with string expressions, see:

+
import pandas as pd
+# Make some really big dataframes
+nrows, ncols = 100000, 100
+rng = np.random.RandomState(42)
+df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols))
+                      for i in range(4))
+
+
+

Adding dataframes the pythonic way yields:

+
%timeit df1 + df2 + df3 + df4
+# 80ms
+
+
+

And by using eval():

+
%timeit pd.eval('df1 + df2 + df3 + df4')
+# 40ms
+
+
+

We can assign function return lists as dataframe columns:

+
def fibo(n):
+    """Compute Fibonacci numbers. Here we skip the overhead from the
+    recursive function calls by using a list. """
+    if n < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif n < 2:
+        return n
+    memo = [0]*(n+1)
+    memo[0] = 0
+    memo[1] = 1
+    for i in range(2, n+1):
+        memo[i] = memo[i-1] + memo[i-2]
+    return memo
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = fibo(99)  # Assigns list to column
+
+
+

There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its API. You should try to get good at +searching the web for an example showing what you can do. And when +there is not, you can always +apply your own functions to the data using apply:

+
from functools import lru_cache
+
+@lru_cache
+def fib(x):
+    """Compute Fibonacci numbers. The @lru_cache remembers values we
+    computed before, which speeds up this function a lot."""
+    if x < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif x < 2:
+        return x
+    else:
+        return fib(x - 2) + fib(x - 1)
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = df['Generation'].apply(fib)
+
+
+

Note that the numpy precisision for integers caps at int64 while python ints are unbounded – +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df[‘Number of Rabbits’][99] given by both functions above +is in fact <class ‘int’>.

+
+

Keypoints

+
    +

  • pandas dataframes are a good data structure for tabular data

    • +

  • Dataframes allow both simple and advanced analysis in very compact form

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/parallel-pi-multiprocessing/index.html b/branch/rkdarst--dependengi-exercise-time/parallel-pi-multiprocessing/index.html new file mode 100644 index 00000000..a77ad081 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/parallel-pi-multiprocessing/index.html @@ -0,0 +1,361 @@ + + + + + + + + + + + + + Python multithreading solution — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python multithreading solution

+

Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare).

+
+
+
import random
+
+
+
+
+
+
+
def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+    
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+
+
+
+
+
%%timeit
+# Do it just for timing
+n, n_inside_circle = sample(10**6)
+
+
+
+
+
296 ms ± 751 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do the actual calculation (the previous result doesn't get saved)
+n, n_inside_circle = sample(10**6)
+
+
+
+
+

This is the “calculate answer” phase.

+
+
+
pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+
+
+
3.14114
+
+
+
+
+
+

Do it in parallel with multiprocessing

+

This divides the calculation into 10 tasks and runs sample on each of them. Then it re-combines the results.

+
+
+
import multiprocessing.pool
+pool = multiprocessing.pool.Pool()
+# The default pool makes one process per CPU
+
+
+
+
+
+
+
%%timeit
+# Do it once to time it
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
147 ms ± 1.59 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
pool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.141364
+
+
+
+
+
+
+

Do it in “parallel” with threads

+

To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process.

+
+
+
threadpool = multiprocessing.pool.ThreadPool()
+
+
+
+
+
+
+
%%timeit -o
+# Do it once to time it
+threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
296 ms ± 2.42 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
<TimeitResult : 296 ms ± 2.42 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)>
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
threadpool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.140572
+
+
+
+
+
+
+

Future ideas

+

You could make a separate calculate function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.

+

Notice the similarity to split-apply-combine or map-reduce which is a specialization of split-apply-combine.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/parallel/index.html b/branch/rkdarst--dependengi-exercise-time/parallel/index.html new file mode 100644 index 00000000..07140fd7 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/parallel/index.html @@ -0,0 +1,632 @@ + + + + + + + + + + + + + Parallel programming — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Parallel programming

+
+

Questions

+
    +

  • When you need more than one processor, what do you do?

    • +

  • How can we use more than one processor/core in Python?

    • +
+
+
+

Objectives

+
    +

  • Understand the major strategies of parallelizing code

    • +

  • Understand mechanics of the multiprocessing package

    • +

  • Know when to use more advanced packages or approaches

    • +
+
+
+

Modes of parallelism

+

You realize you do have more computation to do than you can on one processor? +What do you do?

+
    +

  1. Profile your code, identify the actual slow spots.

    2. +

  2. Can you improve your code in those areas? Use an existing library?

    3. +

  3. Are there are any low-effort optimizations that you can make?

    4. +

  4. Consider using numba or +cython to accelerate key functions.

    5. +

  5. Think about parallelizing.

    6. +
+

Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers).

+

Parallel computing is when many different tasks are carried out +simultaneously. There are three main models:

+
    +

  • Embarrassingly parallel: the code does not need to +synchronize/communicate with other instances, and you can run +multiple instances of the code separately, and combine the results +later. If you can do this, great! (array jobs, task queues, +workflow management tools)

    • +

  • Multithreading: Parallel threads need to communicate and do so via +the same memory (variables, state, etc). (OpenMP, threading)

    • +

  • Multiprocessing, message passing: Different processes manage +their own memory segments. They share data by communicating (passing +messages) as needed. (multiprocessing, MPI).

    • +
+
+

Warning

+

Parallel programming is not magic, but many things can go wrong and +you can get unexpected results or difficult to debug problems. +Parallel programming is a fascinating world to get involved in, but +make sure you invest enough time to do it well.

+

See the video by Raymond Hettinger (“See Also” at bottom +of page) for an entertaining take on this.

+
+
+
+

Multithreading and the GIL

+

The designers of the Python language made the choice +that only one thread in a process can run actual Python code +by using the so-called global interpreter lock (GIL). +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. But it’s not all bad!:

+
    +

  • External libraries (NumPy, SciPy, Pandas, etc), written in C or other +languages, can release the lock and run multi-threaded.

    • +

  • Most input/output releases the GIL, and input/output is slow. The +threading library can be used to multithread I/O.

    • +

  • Python libraries like multiprocessing and mpi4py run multiple +Python processes and this circumvents the GIL.

    • +
+

Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix:

+
import numpy as np
+import time
+
+A = np.random.random((4000,4000))
+A = A * A.T
+time_start = time.time()
+np.linalg.inv(A)
+time_end = time.time()
+print("time spent for inverting A is", round(time_end - time_start,2), 's')
+
+
+

If we run this in a Jupyter notebook or through a Python script, it +will automatically use multithreading through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either export OMP_NUM_THREADS=1 or export MKL_NUM_THREADS=1, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime.

+
+

See also

+ +
+
+
+

multiprocessing

+

As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +multiprocessing module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock.

+

To show an example, +the split-apply-combine +or map-reduce paradigm is +quite useful for many scientific workflows. Consider you have this:

+
def square(x):
+    return x*x
+
+
+

You can apply the function to every element in a list using the +map() function:

+
>>> list(map(square, [1, 2, 3, 4, 5, 6]))
+[1, 4, 9, 16, 25, 36]
+
+
+

The multiprocessing.pool.Pool class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list:

+
>>> from multiprocessing import Pool
+>>> with Pool() as pool:
+...     pool.map(square, [1, 2, 3, 4, 5, 6])
+[1, 4, 9, 16, 25, 36]
+
+
+
+

Warning

+

Running the above example interactively in a Jupyter notebook +or through an Python/IPython terminal may or may not work on your +computer! This is a feature and not a bug, as covered in the +documentation.

+

Fortunately, there is a fork of multiprocesssing called +multiprocess which does +work in interactive environments. All we have to do is install it +by pip install multiprocess and change the import statement: +from multiprocess import Pool.

+
+
+
+

Exercises, multiprocessing

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+
+
+

MPI

+

The message passing interface (MPI) approach to parallelization +is that:

+
    +

  • Tasks (cores) have a rank and are numbered 0, 1, 2, 3, …

    • +

  • Each task (core) manages its own memory

    • +

  • Tasks communicate and share data by sending messages

    • +

  • Many higher-level functions exist to distribute information to other tasks +and gather information from other tasks

    • +

  • All tasks typically run the entire code and we have to be careful to avoid +that all tasks do the same thing

    • +
+

Introductory MPI lessons where Python is included:

+ +

These blog posts are good for gentle MPI/mpi4py introduction:

+ +

Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together.

+

Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work:

+
import random
+import time
+from mpi4py import MPI
+
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x ** 2 + y ** 2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+comm = MPI.COMM_WORLD
+size = comm.Get_size()
+rank = comm.Get_rank()
+
+n = 10 ** 7
+
+if size > 1:
+    n_task = int(n / size)
+else:
+    n_task = n
+
+t0 = time.perf_counter()
+_, n_inside_circle = sample(n_task)
+t = time.perf_counter() - t0
+
+print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+n_inside_circle = comm.gather(n_inside_circle, root=0)
+print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+
+if rank == 0:
+    pi_estimate = 4.0 * sum(n_inside_circle) / n
+    print(
+        f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds"
+    )
+
+
+
+
+

Exercises, MPI

+
+

Parallel-3, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+
+
+

Coupling to other languages

+

As mentioned further up in “Multithreading and the GIL”, Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP “directly”.

+

However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don’t +need parallelism, but need to make an optimized algorithm for a small part of the code.

+

Two strategies are common:

+
    +

  • Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization:

    +
    +
      +

    • C: use the cffi package (C foreign function interface). ctypes is a similar but slightly more primitive module that is in the standard library.

      • +

    • C++: use pybind11

      • +

    • Fortran: create a C interface using iso_c_binding and then couple the C layer to Python +using cffi

      • +

    • Rust: use PyO3

      • +
    +
    +
    • +

  • Let compiled languages do the shared-memory parallelization part (as in above +point) and let Python do the MPI work and distribute tasks across nodes using +an mpi4py layer.

    • +
+

Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course.

+

Before you take this route, profile the application first to be sure where +the bottleneck is.

+

Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason.

+
+
+

Dask and task queues

+

There are other strategies that go completely beyond the manual +parallelization methods above. We won’t go into much detail.

+
+

Dask

+

Dask is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs.

+

Dask is very popular for data analysis and is used by a number of high-level Python libraries:

+
    +

  • Dask arrays scale NumPy (see also xarray

    • +

  • Dask dataframes scale Pandas workflows

    • +

  • Dask-ML scales Scikit-Learn

    • +
+

Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block.

+
+

Example from dask.org

+
# Arrays implement the Numpy API
+import dask.array as da
+x = da.random.random(size=(10000, 10000),
+                     chunks=(1000, 1000))
+x + x.T - x.mean(axis=0)
+# It runs using multiple threads on your machine.
+# It could also be distributed to multiple machines
+
+
+
+
+
+
+

Exercises, Dask

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+

Task queues

+

A task queue has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for embarrassingly parallel jobs.

+

There are different descriptions of task queues in Python. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant.

+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pure Python is not very good for highly parallel code.

    • +

  • Luckily it interfaces to many things which are good, and give +you the full control you need.

    • +

  • Combining vectorized functions (NumPy, Scipy, pandas, etc.) with +the parallel strategies listed here will get you very far.

    • +

  • Another popular framework similar to multiprocessing is +joblib.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/productivity/index.html b/branch/rkdarst--dependengi-exercise-time/productivity/index.html new file mode 100644 index 00000000..397ba706 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/productivity/index.html @@ -0,0 +1,661 @@ + + + + + + + + + + + + + Productivity tools — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Productivity tools

+
+

Questions

+
    +

  • Do you have preferences on the visual aspects of the code +and how it should look?

    • +

  • Do you use any tools that help you create better looking +code faster?

    • +
+
+
+

Objectives

+
    +

  • Learn tools that can help you be more productive.

    • +

  • Learn how to follow standards that other people have created +and how to pick your own favorite.

    • +
+
+
+

Spotting code problems with linters

+

Python as a programming language has a syntax that specifies the +rules that the code must follow. If the code is not written with +valid syntax, you will get an error.

+
# Valid syntax, returns 1
+a = 1
+print(a)
+
+# Invalid syntax, returns SyntaxError
+True = 1
+
+
+

Spotting syntax errors can be time consuming and to help this +programmers have created linters. Linters are tools that +check whether code’s syntax is correct.

+

Some popular linters include:

+ +

In the following example lets use pylint to check the following +script (lint_example.py: to easily download +to JupyterLab, use File → Open from URL → Paste URL → It will download +and open in a window.):

+
import numpy
+import matplotlib.pyplot as plt
+
+x = np.linspace(0, np.pi, 100))
+y = np.sin(x)
+
+plt.plot(x, y)
+
+plt.show()
+
+
+

To run pylint from the terminal in JupyterLab, File → New → +Terminal. Make sure you are in the right directory, then you can run +pylint:

+
$ pylint lint_example.py
+************* Module lint_example
+lint_example.py:4:31: E0001: Parsing failed: 'unmatched ')' (<unknown>, line 4)' (syntax-error)
+
+
+

From here we can see that pylint says that there is a unmatched bracket +on line 4. We also get an message code E0001 (syntax-error). We can find +description for the message from +Pylint’s messages list +and look at the +specific error page to see an example that describes the error.

+

After fixing the problem with the bracket and running pylint again we +get more errors:

+
$ pylint lint_example.py
+************* Module lint_example
+lint_example.py:1:0: C0114: Missing module docstring (missing-module-docstring)
+lint_example.py:4:4: E0602: Undefined variable 'np' (undefined-variable)
+lint_example.py:4:19: E0602: Undefined variable 'np' (undefined-variable)
+lint_example.py:5:4: E0602: Undefined variable 'np' (undefined-variable)
+lint_example.py:1:0: W0611: Unused import numpy (unused-import)
+
+------------------------------------------------------------------
+Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)
+
+
+

Here we see the following suggestions:

+
    +

  • On line 1 we’re missing a module docstring. This is a warning that we’re +going against a coding convetion and thus we get a CXXXX message code. +This is not critical, so let’s not focus on this for now.

    • +

  • On lines 4 and 5 we have undefined variable np. This will create +error if we would execute the code and thus we get a EXXXX message code.

    • +

  • On line 1 we have unused import for numpy module. This won’t create an +error, but Pylint flags this as unnecessary and will give a warning +with WXXX message code.

    • +
+

At the end Pylint will give a rating for the code. In this case the +errors will give an overall rating of 0.00/10 as the code won’t execute +correctly.

+

From these messages we can deduce that the main problem is that the import +statement does not use import numpy as np and thus np is undefined.

+

After changing the import stamement, the code works correctly and running +pylint lint_example.py will only warn about the missing docstring. +You can also notice that the changes have increased the rating and +Pylint will show the improvement since last run.

+
$ pylint lint_example.py
+************* Module lint_example
+lint_example.py:1:0: C0114: Missing module docstring (missing-module-docstring)
+
+------------------------------------------------------------------
+Your code has been rated at 8.33/10 (previous run: 0.00/10, +8.33)
+
+
+
+
+

Exercise 1

+
+

Using Pylint

+

The following code uses scikit-learn to fit a simple linear +model to randomly generated data with some error. You can download it +here (see +above for how to easily download and run in JupyterLab).

+

It has four mistakes in it. One of these cannot be found by +Pylint.

+

Fix the following code with Pylint and try to determine why +Pylint did not find the last mistake.

+
"""
+pylint exercise 1
+"""
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn import linear_model
+
+
+def f(x):
+    """
+    Example function:
+
+    f(x) = x/2 + 2
+    """"
+    return 0.5*x + 2
+
+
+# Create example data
+x_data = np.linspace(0, 10, 100)
+err = 2 * np.random.random(x_data.shape[0])
+y_data = f(x_data) + err
+
+# Put data into dataframe
+df = pd.DataFrame({'x': x_data, 'y': y_data})
+
+# Create linear model and fit data
+reg = linear_model.LinearRegression(fit_intercept=True)
+
+reg.fit(df[['x'], df[['y']])
+
+slope = reg.coef_[0][0]
+intercept = reg.intercept_[0]
+
+df['pred'] = reg.predict(df[['x']])
+
+fig, ax = plt.subplots()
+
+ax.scater(df[['x']], df[['y']], alpha=0.5)
+ax.plot(df[['x']], df[['pred']]
+        color='black', linestyle='--',
+        label=f'Prediction with slope {slope:.2f} and intercept {intercept:.2f}')
+ax.set_ylabel('y')
+ax.set_xlabel('x')
+ax.legend()
+
+plt.show()
+
+
+
+ +
+
+

Enforcing consistent code style

+

Python is a very flexible language which makes it possible to use +all kinds of coding styles.

+

For example, one could use the following naming styles for variables:

+
# Different variable styles
+myvariable = 1   # Lowercase
+myVariable = 1   # Camel case
+MyVariable = 1   # Pascal case
+my_variable = 1  # Snake case
+
+
+

Everyone has their own preference to what style to use and everybody +has freedom to use their preferred style, but to improve legibility +of code there are official style guides for +code (PEP 8) and for +docstrings (PEP 257).

+

There are many code checkers that give you suggestions on how +to modify your code or do the modifications automatically:

+ +

Let’s use black and flake8 (with pep8-naming-extension) to modify +code_style_example.py:

+
import  numpy  as np
+
+def  PI_estimate(n):
+    """This function calculates an estimate of pi with dart thrower algorithm.
+    """
+
+    pi_Numbers =  np.random.random(size = 2*n)
+    x = pi_Numbers[ :n ]
+    y = pi_Numbers[ n: ]
+
+    return 4*np.sum((x * x + y*y ) < 1)/n
+
+
+for number  in range(1,8):
+
+    n = 10** number
+
+    print(f'Estimate for PI with {n:8d} dart throws: {PI_estimate( n )}')
+
+
+

Running flake8 to check for style problems we get the following output:

+
$ flake8 code_style_example.py
+code_style_example.py:1:7: E271 multiple spaces after keyword
+code_style_example.py:1:14: E272 multiple spaces before keyword
+code_style_example.py:3:1: E302 expected 2 blank lines, found 1
+code_style_example.py:3:4: E271 multiple spaces after keyword
+code_style_example.py:3:6: N802 function name 'PI_estimate' should be lowercase
+code_style_example.py:7:6: N806 variable 'pi_Numbers' in function should be lowercase
+code_style_example.py:7:17: E222 multiple spaces after operator
+code_style_example.py:7:40: E251 unexpected spaces around keyword / parameter equals
+code_style_example.py:7:42: E251 unexpected spaces around keyword / parameter equals
+code_style_example.py:8:20: E201 whitespace after '['
+code_style_example.py:8:23: E202 whitespace before ']'
+code_style_example.py:9:20: E201 whitespace after '['
+code_style_example.py:9:23: E202 whitespace before ']'
+code_style_example.py:11:33: E202 whitespace before ')'
+code_style_example.py:14:11: E272 multiple spaces before keyword
+code_style_example.py:14:23: E231 missing whitespace after ','
+code_style_example.py:16:11: E225 missing whitespace around operator
+code_style_example.py:18:67: E201 whitespace after '('
+code_style_example.py:18:69: E202 whitespace before ')'
+
+
+

There are plenty of errors and warnings. We could fix these manually, but +instead let’s use black to format the code. Black is an “uncompromising +Python code formatter” from Python Software Foundation and it automatically +modifies your code to match their recommended coding style.

+

It should fix most of the errors automatically without changing the +functionality.

+

After running black code_style_example.py the code looks like this:

+
import numpy as np
+
+
+def PI_estimate(n):
+    """This function calculates an estimate of pi with dart thrower algorithm."""
+
+    pi_Numbers = np.random.random(size=2 * n)
+    x = pi_Numbers[:n]
+    y = pi_Numbers[n:]
+
+    return 4 * np.sum((x * x + y * y) < 1) / n
+
+
+for number in range(1, 8):
+    n = 10**number
+
+    print(f"Estimate for PI with {n:8d} dart throws: {PI_estimate( n )}")
+
+
+

Much cleaner. If we want to check for variable naming syntax we can still run +flake8 code_style_example.py:

+
$ flake8 code_style_example.py
+code_style_example.py:4:6: N802 function name 'PI_estimate' should be lowercase
+code_style_example.py:5:80: E501 line too long (81 > 79 characters)
+code_style_example.py:7:6: N806 variable 'pi_Numbers' in function should be lowercase
+code_style_example.py:17:67: E201 whitespace after '('
+code_style_example.py:17:69: E202 whitespace before ')'
+
+
+

Fixing these problems we get the final piece of code:

+
import numpy as np
+
+
+def pi_estimate(n):
+    """
+    This function calculates an estimate of pi with dart thrower algorithm.
+    """
+
+    pi_numbers = np.random.random(size=2 * n)
+    x = pi_numbers[:n]
+    y = pi_numbers[n:]
+
+    return 4 * np.sum((x * x + y * y) < 1) / n
+
+
+for number in range(1, 8):
+    n = 10**number
+
+    print(f"Estimate for PI with {n:8d} dart throws: {pi_estimate(n)}")
+
+
+

Comparing the fixed one to the original one the code is much more legible.

+
+

Problems with styles and writing your own kind of code

+

There style black uses is +a bit different to PEP 8 +and one can definitely argue that it +does not handle mathematical expressions in the optimal way.

+

However, one can turn formatting off for math heavy sections with # fmt: on- +and # fmt: off-comments. Alternatively, you can use formatter such as +yapf, which supports formatting based on +arithmetic precedence:

+
$ yapf --style='{based_on_style: pep8, arithmetic_precedence_indication=true}' --diff code_style_example.py
+--- code_style_example.py       (original)
++++ code_style_example.py       (reformatted)
+@@ -10,7 +10,7 @@
+     x = pi_numbers[:n]
+     y = pi_numbers[n:]
+
+-    return 4 * np.sum((x * x + y * y) < 1) / n
++    return 4 * np.sum((x*x + y*y) < 1) / n
+
+
+ for number in range(1, 8):
+
+
+

From this diff we see that yapf would change the multiplications to +match the arithmetic precedence.

+

All formatters allow for massive amounts of style changes and you can +configure them by creating a configuration file in your repository.

+

If the formatter makes a change that you do not like you can usually +disable the change by changing the configuration of the formatter.

+
+
+
+

Exercise 2

+
+

Using black to format code

+

Format +this code +with black:

+
import numpy as np
+import matplotlib.pyplot  as plt
+
+def dice_toss(n,m):
+
+    """Throw n dice m times and the total value together."""
+    dice_rolls    = np.random.randint(1,6,size=(m, n))
+
+    roll_averages = np.sum(dice_rolls,axis = -1)
+
+    return roll_averages
+fig,ax = plt.subplots( )
+
+n = int( input('Number of dices to toss:\n'))
+
+bins = np.arange(1, 6 * n+1)
+
+m = 1000
+
+ax.hist(dice_toss(n,m), bins = bins)
+
+ax.set_title(f'Histogram of {n} dice tosses')
+
+ax.set_xlabel('Total value' )
+
+ax.set_ylabel('Number of instances')
+
+plt.show()
+
+
+
+ +
+
+

Integrating productivity tools with git

+

If you’re using version control you can easily add tools such as +pylint, flake8, black and ruff as automatic using tools like +pre-commit.

+

Pre-commit is a tool that makes it easy to automatically run various +code checkers when you’re doing a new commit to the repository.

+

For more information see their website.

+
+
+

Other nice tools

+ +
+

Keypoints

+
    +

  • Using linters and formatters can help you write cleaner code.

    • +

  • You should adapt your own code and documentation style based +on standards that other people use.

    • +

  • Using pre-commit with your git repository can make many of the +checks automatic.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/python/index.html b/branch/rkdarst--dependengi-exercise-time/python/index.html new file mode 100644 index 00000000..d6d65ddf --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/python/index.html @@ -0,0 +1,309 @@ + + + + + + + + + + + + + Introduction to Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Introduction to Python

+
+

Questions

+
    +

  • What are the basic blocks of Python language?

    • +

  • How are functions and classes defined in Python?

    • +
+
+
+

Objectives

+
    +

  • Get a very short introduction to Python types and syntax

    • +

  • Be able to follow the rest of the examples in the course, even if you don’t understand everything perfectly.

    • +
+

We expect everyone to be able to know the following basic material +to follow the course (though it is not everything you need to +know about Python).

+
+

If you are not familiar with Python, here is a very short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise.

+
+

See also

+

This page contains an overview of the basics of Python. You can +also refer to This Python overview from a different lesson +which is slightly more engaging.

+
+
+

Scalars

+

Scalar types, that is, single elements of various types:

+
i = 42       # integer
+i = 2**77    # Integers have arbitrary precision
+g = 3.14     # floating point number
+c = 2 - 3j   # Complex number
+b = True     # boolean
+s = "Hello!" # String (Unicode)
+q = b'Hello' # bytes (8-bit values)
+
+
+

Read more: int, float, complex, +bool, str, bytes.

+
+
+

Collections

+

Collections are data structures capable of storing multiple values.

+
l = [1, 2, 3]                      # list
+l[1]                               # lists are indexed by int
+l[1] = True                        # list elements can be any type
+d = {"Janne": 123, "Richard": 456} # dictionary
+d["Janne"]
+s = set(("apple", "cherry", "banana", "apple")) # Set of unique values
+s
+
+
+

Read more: list, tuple, dict, set.

+
+
+

Control structures

+

Python has the usual control structures, that is conditional +statements and loops. For example, the The if statement statement:

+
x = 2
+if x == 3:
+    print('x is 3')
+elif x == 2:
+    print('x is 2')
+else:
+    print('x is something else')
+
+
+

While loops loop until some condition is met:

+
x = 0
+while x < 42:
+    print('x is ', x)
+    x += 0.2
+
+
+

For loops loop over some collection of values:

+
xs = [1, 2, 3, 4]
+for x in xs:
+    print(x)
+
+
+

Often you want to loop over a sequence of integers, in that case the +range function is useful:

+
for x in range(9):
+    print(x)
+
+
+

Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the enumerate() +function:

+
xs = [1, 'hello', 'world']
+for ii, x in enumerate(xs):
+    print(ii, x)
+
+
+
+
+

Functions and classes

+

Python functions are defined by the Function definitions keyword. They take a +number of arguments, and return a number of return values.

+
def hello(name):
+    """Say hello to the person given by the argument"""
+    print('Hello', name)
+    return 'Hello ' + name
+
+hello("Anne")
+
+
+

Classes are defined by the Class definitions keyword:

+
class Hello:
+    def __init__(self, name):
+        self._name = name
+    def say(self):
+        print('Hello', self._name)
+
+h = Hello("Richard")
+h.say()
+
+
+
+
+

Python type system

+

Python is strongly and dynamically typed.

+

Strong here means, roughly, that it’s not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior).

+
x = 42
+type(x)
+x + "hello"
+
+
+

Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type:

+
x = 42
+x = "hello"
+
+
+

Jargon: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation.

+

??? (lesson here)

+
+

Keypoints

+
    +

  • Python offers a nice set of basic types as many other programming languages

    • +

  • Python is strongly typed and dynamically typed

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/quick-reference/index.html b/branch/rkdarst--dependengi-exercise-time/quick-reference/index.html new file mode 100644 index 00000000..d53ed09e --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/quick-reference/index.html @@ -0,0 +1,164 @@ + + + + + + + + + + + + + Quick reference — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/scipy/index.html b/branch/rkdarst--dependengi-exercise-time/scipy/index.html new file mode 100644 index 00000000..85226059 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/scipy/index.html @@ -0,0 +1,322 @@ + + + + + + + + + + + + + SciPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

SciPy

+
+

Questions

+
    +

  • When you need more advanced mathematical functions, where do you +look?

    • +
+
+
+

Objectives

+
    +

  • Understand that SciPy exists and what kinds of things it has.

    • +

  • Understand the importance of using external libraries and how to +use them.

    • +

  • Understand the purpose of wrapping existing C/Fortran code.

    • +

  • Non-objective: know details of everything (or anything) in SciPy.

    • +
+
+
+

See also

+ +
+

SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms.

+
+

What’s in SciPy?

+

Briefly, it contains functionality for

+
    +

  • Special functions (Bessel, Gamma, etc.)

    • +

  • Numerical integration

    • +

  • Optimization

    • +

  • Interpolation

    • +

  • Fast Fourier Transform (FFT)

    • +

  • Signal processing

    • +

  • Linear algebra (more complete than in NumPy)

    • +

  • Sparse matrices

    • +

  • Statistics

    • +

  • More I/O routine, e.g. Matrix Market format for sparse matrices, +MATLAB files (.mat), etc.

    • +
+

Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages.

+

Most functions are documented ridiculously well from a scientific +standpoint: you aren’t just using some unknown function, but have a +full scientific description and citation to the method and +implementation.

+
+
+

Exercises: use SciPy

+

These exercises do not exist because you might need these +functions someday. They are because you will need to read +documentation and understand documentation of an an external library +eventually.

+
+

1: Numerical integration

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+ +
+
+

2: Sparse matrices

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+ +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • When you need advance math or scientific functions, let’s just +admit it: you do a web search first.

    • +

  • But when you see something in SciPy come up, you know your +solutions are in good hands.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/scripts/index.html b/branch/rkdarst--dependengi-exercise-time/scripts/index.html new file mode 100644 index 00000000..6359323f --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/scripts/index.html @@ -0,0 +1,554 @@ + + + + + + + + + + + + + Scripts — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Scripts

+
+

Questions

+
    +

  • Why are command line programs useful, compared to Jupyter +notebooks and similar?

    • +

  • How to create a Python script?

    • +

  • How to generalize a Python script?

    • +
+
+
+

Objectives

+
    +

  • Learn how to streamline your Python notebooks by creating repeatable Python scripts

    • +

  • Learn how to import other Python files

    • +

  • Learn to parse command line arguments in Python

    • +
+
+
+

Why scripts?

+

So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work.

+

But after several weeks of hard work with Python, you may end up:

+
    +

  • either with 10 different notebooks (so that you can run them concurrently)

    • +

  • or with a very long notebook which is becoming hardly readable!

    • +
+

Let’s imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks?

+

In this episode, we will learn how to automate your work using Python scripts so that

+
    +

  • you do not need to manually configure your notebooks to be able to run with different parameters

    • +

  • can easily run you work via other tools, such as on computing clusters.

    • +
+
+
+

From Jupyter notebooks to Python scripts

+
+
+

Save as Python script

+

Jupyter notebooks can be parameterized for instance using papermill. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See CodeRefinery’s lesson on Modular code development.

+

Within JupyterLab, you can export any Jupyter notebook to a Python script:

+
+https://jupyterlab.readthedocs.io/en/stable/_images/exporting-menu.png +
+

Select File (top menu bar) → Export Notebook as → Export notebook to Executable Script.

+
+
+

Actually, you could also export your notebook in many other formats. +Check the JupyterLab documentation for more information. +If you are working by the command line (File → New → Terminal), you can also convert files in the terminal by running:

+
$ jupyter nbconvert --to script your_notebook_name.ipynb
+
+
+
+
+

Exercises 1

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and the weather_data file and upload them to your Jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Hint: Copy the URL above (right-click) and in JupyterLab, use +File → Open from URL → Paste the URL. It will both download it to +the directory JupyterLab is in and open it for you.

    +
    2. +

  2. Open a terminal in Jupyter: File → New Launcher, then click +“Terminal” there. (if you do it this way, it will be in the right +directory. File → New → Terminal might not be.)

    3. +

  3. Convert the Jupyter script to a Python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+
+
+

Command line arguments with sys.argv

+

We now have a Python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +What we need is to allow the code to do something different based on something outside the code itself: in this case, to +plot information for different time ranges. This can be achieved by +using Pythons sys package, which provides access to arguments given to the Python interpreter at +startup in the sys.argv list. The first (i.e. sys.argv[0] entry of this array is the script that is running, +and any further argument (separated by space) is appended to this list, like such:

+
$ python my_script.py A B
+$ # sys.argv[1] is 'A'
+$ # sys.argv[2] is 'B'
+
+
+

Lets see how it works: We modify the weather_observations.py script such that we allow start +and end times as well as the output file to be passed in as arguments +to the function. Open it (find the .py file from the JupyterLab +file browser) and make these edits:

+
import sys
+import pandas as pd
+
+# define the start and end time for the plot
+start_date = pd.to_datetime(sys.argv[1], dayfirst=True)
+end_date = pd.to_datetime(sys.argv[2], dayfirst=True)
+...
+
+# select the data
+weather = weather[weather['Local time'].between(start_date,end_date)]
+...
+
+# save the figure
+output_file_name = sys.argv[3]
+fig.savefig(output_file_name)
+
+
+

We can try it out (see the file spring_in_tapiola.png made in the +file browser):

+
$ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png
+
+
+
+

Discussion

+
    +

  • Does it work?

    • +

  • Why is this better than modifying the script every time I want it to +plot data for a different period?

    • +

  • What problems do you expect when using this approach (using sys.argv)?

    • +
+
+

This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time:

+
    +

  • argparse: +built-in to Python, this is the one that we will show below.

    • +

  • doctopt: you write the help text and this generates a parser for you.

    • +

  • click: another nice +library for command line interfaces - very easy to use.

    • +
+
+
+

Parsing command line arguments with argparse

+

Argparse not only gives you descriptive command line arguments, it also automatically +generates a --help option for you. To use argparse you first set up a parser +by calling parser = argparse.ArgumentParser() and then you add arguments using +parser.add_argument(args). There are two different types of arguments:

+
    +

  • Positional arguments

    • +

  • Optional arguments

    • +
+

Positional arguments are detected by their order, while optional arguments need to be +given with their respective flags ( like --name or -n). +The following example would parse a positional argument Name of type string +and an optional argument date of type string which defaults to 01/01/2000.

+
import argparse
+
+parser = argparse.ArgumentParser()
+# One positional and one optional argument
+parser.add_argument('name', type=str, metavar="N",
+                    help="The name of the subject")
+parser.add_argument('-d', '--date', type=string, default="01/01/2000",
+                    help="Birth date of the subject")
+
+args = parser.parse_args()
+
+print(args.name + " was born on " + args.date)
+
+
+

If this code was in birthday.py and we would call python birthday.py --help it +would show the following message:

+
$ python birthday.py --help
+usage: birthday.py [-h] [-d DATE] N
+
+positional arguments:
+  N                     The name of the subject
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d DATE, --date DATE  Birth date of the subject
+
+
+
+
+

Exercises 2

+
+

Scripts-2

+
    +

  1. Take the Python script (weather_observations.py) we have written in the preceding exercise and use +argparse to specify the input (URL) and output files and allow the start and end dates to be set.

    +
      +

    • Hint: try not to do it all at once, but add one or two arguments, test, then add more, and so on.

      • +

    • Hint: The input and output filenames make sense as positional arguments, since they must always be given. Input is usually first, then output.

      • +

    • Hint: The start and end dates should be optional parameters with the defaults as they are in the current script.

      • +
    +
    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from May 2020 to October 2020). +Also try using this data for Cairo: https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv

    3. +
+
+ +
+

Discussion

+

What was the point of doing this?

+

Now you can do this:

+
$ python weather_observations.py --help
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png
+$ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png
+$ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output temperature_cairo.png
+
+
+
    +

  • We can now process different input files without changing the script.

    • +

  • We can select multiple time ranges without modifying the script.

    • +

  • We can easily save these commands to know what we did.

    • +

  • This way we can also loop over file patterns (using shell loops or similar) or use +the script in a workflow management system and process many files in parallel.

    • +

  • By changing from sys.argv to argparse we made the script more robust against +user input errors and also got a help text (accessible via --help).

    • +
+
+
+
+

Load larger option lists using config files

+

In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line:

+
$ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021
+
+
+

This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple Parameter = Value +format, and parse it yourself, or you can use e.g. the JSON or YAML formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won’t go into the details of the formats, and will only give +a short example using YAML here.

+

The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (yaml) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the json package).

+

The Python module optionsparser.py provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values.

+

In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation …), set the labels and titles explicitly etc.

+

In the YAML format, names and values are separated by :. Our above example would therefore translate to the following YAML file:

+
input:        https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv
+output:       rain_in_cairo.png
+xlabel:       Days in June
+ylabel:       Rainfall in mm
+title:        Rainfall in Cairo
+data_column:  RRR
+start:        01/06/2021
+end:          30/06/2021
+
+
+
+
+

Exercises 3 (optional)

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab (Hint: in JupyterLab, File → Open from URL). +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+ +

What did this config file parser get us? Now, we have separated the +code from the configuration. We could save all the configuration in +version control - separately and have one script that runs them. If +done right, our work could be much more reproducible and +understandable.

+
+

Further reading

+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/search/index.html b/branch/rkdarst--dependengi-exercise-time/search/index.html new file mode 100644 index 00000000..9c8aef3b --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/search/index.html @@ -0,0 +1,159 @@ + + + + + + Search — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+
+ +
+ +
+

© Copyright 2020-2023, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/searchindex.js b/branch/rkdarst--dependengi-exercise-time/searchindex.js new file mode 100644 index 00000000..fe0ad839 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"docnames": ["binder", "data-formats", "data-visualization", "dependencies", "exercises", "guide", "index", "installation", "jupyter", "libraries", "numpy", "numpy-advanced", "packaging", "pandas", "parallel", "parallel-pi-multiprocessing", "productivity", "python", "quick-reference", "scipy", "scripts", "web-apis"], "filenames": ["binder.rst", "data-formats.rst", "data-visualization.md", "dependencies.rst", "exercises.md", "guide.rst", "index.rst", "installation.rst", "jupyter.ipynb", "libraries.rst", "numpy.rst", "numpy-advanced.rst", "packaging.rst", "pandas.rst", "parallel.rst", "parallel-pi-multiprocessing.ipynb", "productivity.rst", "python.rst", "quick-reference.rst", "scipy.rst", "scripts.rst", "web-apis.ipynb"], "titles": ["Binder", "Data formats with Pandas and Numpy", "Data visualization with Matplotlib", "Dependency management", "List of exercises", "Instructor\u2019s guide", "Python for Scientific Computing", "Software installation", "Jupyter", "Library ecosystem", "NumPy", "Advanced NumPy", "Packaging", "Pandas", "Parallel programming", "Python multithreading solution", "Productivity tools", "Introduction to Python", "Quick reference", "SciPy", "Scripts", "Web APIs with Python"], "terms": {"alon": 0, "mai": [0, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 20, 21], "suffici": [0, 4, 21], "what": [0, 2, 3, 4, 5, 6, 7, 11, 12, 14, 16, 17, 20, 21], "my": [0, 1, 2, 3, 4, 9, 10, 13], "python": [0, 2, 5, 8, 10, 11, 13, 14, 16, 19], "publish": [0, 3, 4, 5, 9, 11], "learn": [0, 1, 2, 3, 4, 5, 6, 7, 11, 12, 13, 14, 16, 18, 20, 21], "about": [0, 2, 3, 4, 6, 7, 8, 9, 10, 11, 13, 14, 16, 17, 19, 20], "custom": [0, 9, 20, 21], "lea": [0, 4], "phd": [0, 4, 5, 6], "student": [0, 3, 4, 5, 6, 9], "biologi": [0, 4], "after": [0, 2, 4, 8, 10, 11, 14, 16, 20], "year": [0, 2, 3, 4, 5, 6, 9, 11, 13, 21], "intens": [0, 4], "work": [0, 1, 2, 3, 5, 6, 7, 8, 10, 11, 14, 16, 20], "she": [0, 3, 4], "final": [0, 2, 4, 6, 10, 11, 13, 14, 15, 16], "readi": [0, 2, 4, 7, 12], "her": [0, 3, 4], "first": [0, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 19, 20, 21], "paper": [0, 3, 4, 9, 10], "The": [0, 1, 2, 4, 5, 6, 7, 8, 10, 12, 13, 14, 15, 16, 17, 19, 20, 21], "ha": [0, 1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21], "us": [0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 21], "analyz": [0, 3, 21], "data": [0, 3, 5, 6, 8, 10, 14, 16, 17, 20], "avail": [0, 3, 4, 5, 7, 9, 11, 12, 13, 16, 19, 20, 21], "supervisor": [0, 4], "who": [0, 2, 3, 4, 5, 7, 9, 11, 13, 14], "an": [0, 1, 5, 6, 8, 9, 12, 13, 14, 15, 16, 17, 19, 20, 21], "advoc": [0, 4], "open": [0, 1, 3, 4, 6, 7, 9, 12, 13, 16, 19, 20, 21], "scienc": [0, 1, 4, 6, 9, 13, 14, 21], "told": [0, 4], "possibli": [0, 4, 5, 6], "just": [0, 1, 2, 3, 4, 6, 9, 10, 11, 13, 14, 15, 19, 20], "problem": [0, 1, 2, 4, 5, 8, 14, 20], "you": [0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21], "anticip": [0, 4], "5": [0, 2, 6, 8, 11, 13, 14, 15, 16, 19], "now": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 20], "we": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21], "form": [0, 4, 6, 7, 9, 13], "small": [0, 1, 2, 4, 5, 9, 10, 11, 12, 14, 21], "group": [0, 2, 4, 8, 9, 13, 21], "person": [0, 2, 4, 5, 9, 17], "If": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 14, 16, 17, 20, 21], "workshop": [0, 4, 7, 9], "onlin": [0, 4, 7, 9], "each": [0, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 15, 19, 20, 21], "join": [0, 3, 4, 13], "breakout": [0, 3, 4], "room": [0, 3, 4], "possibl": [0, 1, 2, 3, 4, 5, 8, 10, 11, 12, 13, 14, 16, 17, 21], "practic": [0, 2, 3, 4, 5, 6, 8, 9, 12, 20, 21], "document": [0, 1, 3, 4, 5, 8, 9, 12, 13, 14, 16, 19, 20, 21], "thi": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21], "collabor": [0, 3, 4, 6, 12], "write": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 12, 13, 14, 20, 21], "summari": [0, 3, 4, 13], "bullet": [0, 4, 8], "point": [0, 1, 2, 4, 5, 6, 8, 9, 10, 11, 14, 15, 17, 20, 21], "provid": [0, 1, 2, 3, 4, 5, 6, 7, 10, 13, 14, 20, 21], "instructor": [0, 4, 6], "allow": [0, 1, 2, 3, 4, 11, 13, 14, 16, 19, 20, 21], "mani": [0, 1, 2, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "remot": [0, 2, 7], "user": [0, 2, 4, 5, 13, 14, 20, 21], "It": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 12, 14, 16, 17, 19, 20, 21], "repo2dock": 0, "contain": [0, 1, 3, 4, 7, 8, 10, 11, 12, 13, 17, 19, 20, 21], "imag": [0, 1, 4, 9, 11], "docker": 0, "project": [0, 1, 2, 4, 6, 9], "inform": [0, 4, 9, 12, 13, 14, 16, 19, 20, 21], "includ": [0, 1, 3, 4, 7, 9, 10, 11, 13, 14, 16, 19], "configur": [0, 2, 16, 20], "file": [0, 4, 6, 8, 9, 10, 12, 13, 14, 16, 19, 21], "standalon": 0, "packag": [0, 2, 5, 6, 7, 10, 11, 13, 14, 20, 21], "instal": [0, 1, 2, 4, 5, 6, 8, 9, 13, 14, 21], "local": [0, 4, 13, 20], "laptop": [0, 5], "servic": 0, "freeli": 0, "tutori": [0, 5, 13, 14], "main": [0, 2, 3, 4, 5, 6, 8, 11, 14, 16, 19], "fork": [0, 14], "add": [0, 1, 2, 3, 4, 8, 10, 11, 12, 13, 16, 20], "requir": [0, 2, 4, 9, 12, 13, 14, 20], "credit": 0, "juliett": 0, "taka": 0, "logilab": 0, "opendreamkit": 0, "2017": 0, "In": [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 16, 17, 20, 21], "earlier": 0, "episod": [0, 3, 12, 20], "visual": [0, 1, 5, 6, 13, 16], "matplotlib": [0, 3, 5, 6, 9, 16, 18, 20], "have": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21], "import": [0, 1, 2, 3, 4, 5, 8, 10, 11, 12, 13, 14, 15, 16, 19, 20, 21], "panda": [0, 3, 5, 6, 9, 14, 16, 18, 20], "pd": [0, 1, 2, 4, 13, 16, 20], "pyplot": [0, 2, 4, 16, 20], "plt": [0, 2, 4, 16, 20], "url": [0, 2, 4, 13, 16, 20, 21], "http": [0, 2, 3, 4, 6, 7, 8, 9, 12, 13, 14, 20, 21], "raw": [0, 2, 4, 6, 7, 8, 10, 13, 20, 21], "githubusercont": [0, 2, 4, 7, 13, 20], "com": [0, 2, 4, 7, 9, 13, 20, 21], "plotli": [0, 2, 4], "dataset": [0, 1, 2, 20], "master": [0, 2, 3, 4, 7, 11, 13, 20], "gapminder_with_cod": [0, 2, 4], "csv": [0, 2, 4, 13, 20], "read_csv": [0, 1, 2, 4, 13, 20], "data_2007": 0, "2007": [0, 2, 4], "fig": [0, 2, 4, 16, 20], "ax": [0, 2, 4, 16, 20], "subplot": [0, 2, 4, 16, 20], "scatter": [0, 2, 4, 16], "x": [0, 1, 2, 3, 4, 8, 10, 12, 13, 14, 15, 16, 17, 19, 20, 21], "gdppercap": [0, 2, 4], "y": [0, 1, 2, 3, 4, 8, 10, 12, 13, 14, 15, 16, 20], "lifeexp": [0, 2, 4], "alpha": [0, 2, 4, 13, 16], "0": [0, 1, 2, 3, 4, 6, 8, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21], "set_xscal": [0, 2, 4], "log": [0, 21], "set_xlabel": [0, 2, 4, 16, 20], "gdp": [0, 2, 4], "usd": [0, 13], "per": [0, 2, 4, 8, 14, 15], "capita": [0, 2, 4], "set_ylabel": [0, 2, 4, 16, 20], "life": [0, 2, 4], "expect": [0, 2, 3, 4, 5, 6, 7, 9, 10, 16, 17, 20], "via": [0, 3, 4, 9, 14, 18, 20, 21], "static": [0, 3, 4, 6, 17], "demonstr": [0, 2, 4, 5], "upload": [0, 4, 12, 20], "Then": [0, 2, 4, 7, 9, 13, 14, 15, 19], "look": [0, 2, 3, 4, 6, 8, 9, 10, 11, 12, 13, 14, 16, 19, 20, 21], "render": [0, 4], "version": [0, 4, 6, 7, 8, 11, 12, 14, 16, 20], "txt": [0, 3, 4], "which": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20], "commit": [0, 4, 16], "push": [0, 4, 8], "also": [0, 2, 4, 5, 12, 13, 16, 17, 20, 21], "visit": [0, 4, 13, 21], "mybind": [0, 4, 14], "org": [0, 2, 4, 6, 8, 9, 12, 13, 18, 21], "copi": [0, 4, 8, 9, 10, 13, 14, 20], "past": [0, 3, 4, 6, 8, 9, 13, 16, 20], "under": [0, 4, 7, 9, 13, 14], "text": [0, 1, 3, 4, 6, 8, 13, 20, 21], "below": [0, 1, 2, 4, 6, 7, 8, 9, 11, 12, 13, 14, 19, 20, 21], "readm": [0, 3, 4, 12], "md": [0, 4, 8, 12], "check": [0, 1, 3, 4, 8, 9, 10, 12, 14, 16, 19, 20, 21], "launch": [0, 4], "badg": [0, 4], "try": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 16, 20, 21], "click": [0, 4, 7, 13, 20], "button": [0, 4, 5, 8], "see": [0, 2, 4, 12, 13, 16, 20, 21], "take": [0, 1, 4, 5, 8, 10, 11, 12, 13, 14, 15, 17, 19, 20, 21], "minut": [0, 4, 13], "two": [0, 1, 3, 4, 8, 9, 10, 12, 13, 14, 20], "expor": [0, 4], "execut": [0, 1, 3, 4, 8, 10, 11, 13, 16, 20], "cloud": [0, 4], "enjoi": [0, 4], "being": [0, 1, 3, 4, 5, 10, 11], "fulli": [0, 1, 4, 20], "gener": [0, 1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 19, 20, 21], "purpos": [0, 8, 19], "access": [0, 3, 4, 13, 15, 20, 21], "built": [0, 2, 4, 12, 20], "oper": [0, 3, 4, 6, 7, 8, 11, 12, 13, 14, 16], "cern": 0, "openair": 0, "research": [0, 1, 3, 5, 6, 7, 9, 12, 13, 20], "archiv": [0, 1, 4], "digit": 0, "identifi": [0, 12, 14], "thei": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 17, 19, 20], "everyth": [0, 2, 4, 5, 6, 7, 8, 9, 13, 14, 15, 17, 19, 20], "deposit": [0, 4], "meant": [0, 4, 6], "kept": [0, 4], "long": [0, 1, 3, 4, 7, 9, 11, 13, 16, 19, 20, 21], "term": [0, 1, 2, 3, 4], "therefor": [0, 3, 4, 20], "recommend": [0, 1, 2, 4, 5, 7, 11, 12, 14, 16, 20, 21], "sandbox": [0, 4], "test": [0, 1, 2, 4, 6, 7, 8, 9, 10, 11, 13, 14, 19, 20, 21], "area": [0, 4, 6, 14, 21], "instead": [0, 1, 2, 3, 4, 8, 10, 11, 13, 14, 16, 19, 20], "go": [0, 2, 4, 5, 6, 7, 9, 12, 14, 16, 20, 21], "real": [0, 2, 4, 12], "later": [0, 1, 3, 4, 7, 11, 14, 21], "account": [0, 4, 12], "Be": [0, 2, 3, 4, 5, 8, 9, 10, 17], "awar": [0, 4, 10, 14], "need": [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 17, 19, 20, 21], "author": [0, 1, 4, 6, 9, 12], "applic": [0, 1, 3, 4, 7, 9, 14, 21], "redirect": [0, 4], "back": [0, 1, 4, 9, 11, 13], "choos": [0, 1, 2, 4, 5], "webhook": [0, 4], "drop": [0, 3, 4, 9, 13], "down": [0, 4, 8, 14, 21], "menu": [0, 4, 8, 13, 20], "next": [0, 2, 3, 4, 8, 10, 11, 12, 14, 21], "email": [0, 4, 12], "address": [0, 4], "top": [0, 2, 3, 4, 10, 13, 19, 20], "page": [0, 4, 6, 7, 8, 10, 13, 14, 16, 17, 19, 20, 21], "select": [0, 2, 3, 4, 7, 8, 10, 11, 13, 20], "present": [0, 1, 2, 4, 6, 13, 21], "list": [0, 2, 3, 6, 8, 9, 10, 11, 14, 15, 16, 17, 21], "all": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 20, 21], "repo": [0, 4], "want": [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 13, 14, 16, 17, 20, 21], "toggl": [0, 4], "ou": [0, 4], "reserv": [0, 4], "releas": [0, 4, 8, 9, 14], "": [0, 1, 2, 3, 4, 6, 7, 8, 10, 11, 12, 14, 15, 16, 17, 20, 21], "trigger": [0, 4], "automat": [0, 2, 4, 9, 14, 16, 20, 21], "download": [0, 4, 6, 13, 16, 20, 21], "zip": [0, 4], "ball": [0, 4], "new": [0, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 20], "regist": [0, 4, 21], "should": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 15, 16, 20], "give": [0, 1, 2, 3, 4, 8, 10, 11, 13, 14, 16, 20, 21], "number": [0, 1, 2, 3, 4, 8, 10, 11, 13, 14, 16, 17, 19, 20], "v1": [0, 4, 13], "descript": [0, 4, 7, 8, 12, 14, 16, 19, 20], "time": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 14, 15, 16, 17, 19, 20, 21], "To": [0, 2, 3, 4, 7, 10, 11, 12, 13, 14, 15, 16, 20, 21], "ensur": [0, 4, 5, 6, 13], "set": [0, 2, 3, 4, 7, 11, 13, 14, 17, 20], "correspond": [0, 3, 4, 7, 13, 21], "find": [0, 2, 3, 4, 6, 7, 8, 9, 13, 14, 16, 20, 21], "ad": [0, 3, 4, 12, 13, 21], "edit": [0, 4, 6, 7, 8, 12, 20], "softwar": [0, 3, 4, 6, 8, 9, 12, 16], "fill": [0, 3, 4, 10, 11, 13], "other": [0, 2, 3, 4, 5, 6, 8, 11, 12, 13, 17, 20, 21], "metadata": [0, 1, 4], "manual": [0, 2, 4, 7, 10, 11, 14, 16, 20, 21], "json": [0, 4, 20, 21], "citat": [0, 4, 19], "cff": [0, 4], "infer": [0, 4], "public": [0, 8, 9, 12], "updat": [0, 4, 12, 13], "newli": [0, 3, 4], "rather": [0, 3, 4, 10, 11, 13, 20], "specifi": [0, 3, 4, 12, 14, 16, 20, 21], "when": [0, 1, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 16, 19, 20, 21], "exist": [0, 1, 2, 4, 5, 6, 8, 9, 11, 13, 14, 19, 20], "5281": [0, 4], "3886864": [0, 4], "start": [0, 1, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 20], "shown": [0, 4], "anim": [0, 4], "good": [0, 1, 2, 3, 4, 6, 8, 9, 10, 12, 13, 14, 19, 20], "both": [0, 2, 4, 6, 8, 9, 10, 11, 13, 14, 15, 20], "easi": [0, 1, 2, 3, 6, 8, 9, 10, 13, 16, 20], "wai": [0, 1, 3, 4, 8, 10, 11, 12, 13, 14, 16, 19, 20, 21], "run": [0, 2, 3, 5, 7, 11, 12, 13, 15, 16, 20], "without": [0, 1, 2, 3, 4, 6, 7, 9, 10, 11, 12, 13, 15, 16, 17, 20, 21], "up": [0, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 19, 20], "dedic": [0, 1], "server": [0, 2, 7, 21], "perman": [0, 9], "how": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20], "do": [1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "your": [1, 2, 5, 6, 7, 8, 10, 11, 12, 13, 14, 19, 20, 21], "right": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 16, 20], "ar": [1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "clean": 1, "preprocess": [1, 4, 20], "everi": [1, 2, 9, 10, 14, 20], "load": [1, 3, 4, 9, 10, 13, 14, 21], "distinguish": 1, "characterist": 1, "differ": [1, 3, 6, 7, 8, 10, 12, 13, 14, 16, 17, 19, 20], "read": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 17, 19, 21], "varieti": [1, 4, 9, 19, 20], "mean": [1, 4, 5, 6, 8, 10, 11, 13, 14, 15, 17], "re": [1, 3, 4, 6, 8, 9, 10, 13, 14, 15, 16, 20], "memori": [1, 4, 10, 11, 13, 14], "while": [1, 4, 5, 6, 9, 10, 11, 12, 13, 17, 20], "disk": [1, 2, 4, 9, 13], "let": [1, 2, 4, 6, 8, 10, 11, 12, 13, 14, 16, 19, 20, 21], "consid": [1, 2, 4, 5, 9, 10, 14, 21], "randomli": [1, 4, 9, 16, 21], "datafram": [1, 5, 14, 16], "variou": [1, 2, 3, 4, 12, 16, 17], "column": [1, 2, 4, 10, 11, 13], "np": [1, 2, 4, 10, 11, 13, 14, 16], "n_row": [1, 4, 11], "100000": [1, 4, 13], "string": [1, 4, 12, 13, 17, 20, 21], "random": [1, 2, 3, 4, 9, 10, 11, 13, 14, 15, 16, 19, 21], "choic": [1, 3, 4, 6, 13, 14], "appl": [1, 4, 17, 21], "banana": [1, 4, 17], "carrot": [1, 4], "size": [1, 2, 4, 10, 13, 14, 16, 19], "timestamp": [1, 4], "date_rang": [1, 4, 13], "20130101": [1, 4, 13], "period": [1, 4, 13, 20], "freq": [1, 4, 13], "integ": [1, 4, 10, 11, 13, 17], "rang": [1, 3, 4, 8, 10, 13, 14, 15, 16, 17, 20, 21], "10": [1, 2, 3, 8, 9, 10, 11, 13, 14, 15, 16, 19, 20], "float": [1, 4, 10, 11, 17], "uniform": [1, 4], "info": [1, 13], "multipl": [1, 4, 8, 10, 11, 13, 14, 15, 16, 17, 20], "collect": [1, 4, 9, 11, 12, 13, 14, 21], "anoth": [1, 2, 3, 4, 5, 8, 9, 10, 12, 13, 14, 17, 20, 21], "exampl": [1, 3, 6, 7, 8, 9, 10, 12, 13, 16, 17, 19, 20, 21], "n": [1, 2, 4, 8, 10, 11, 12, 13, 14, 15, 16, 20, 21], "1000": [1, 4, 14, 16, 20, 21], "data_arrai": [1, 4], "here": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 20, 21], "diment": 1, "one": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 20, 21], "contigu": 1, "block": [1, 4, 12, 14, 17, 19], "individu": [1, 2, 7, 21], "whole": [1, 2, 4, 8, 13, 19], "must": [1, 4, 11, 16, 20], "sourc": [1, 6, 8, 9, 12, 13, 19, 21], "eleg": 1, "scipi": [1, 3, 5, 6, 10, 12, 14], "save": [1, 2, 4, 8, 10, 13, 15], "chang": [1, 2, 4, 6, 8, 9, 10, 11, 13, 14, 16, 20, 21], "For": [1, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "easili": [1, 3, 4, 5, 8, 9, 13, 16, 17, 20], "our": [1, 2, 4, 7, 10, 11, 12, 13, 14, 15, 20, 21], "singl": [1, 3, 4, 6, 10, 11, 12, 13, 17, 20, 21], "piec": [1, 4, 14, 16], "organ": [1, 8, 9], "2d": [1, 4, 10, 11], "nest": 1, "dictionari": [1, 2, 4, 13, 17, 20, 21], "black": 1, "white": 1, "png": [1, 2, 4, 20], "might": [1, 2, 4, 5, 6, 7, 9, 12, 13, 19, 20, 21], "nxm": 1, "decid": [1, 3, 4, 9, 10, 12], "program": [1, 2, 3, 5, 6, 8, 9, 11, 16, 17, 20, 21], "follow": [1, 3, 4, 6, 7, 8, 11, 12, 13, 14, 16, 17, 19, 20], "There": [1, 2, 3, 4, 5, 8, 10, 12, 13, 14, 16, 20], "case": [1, 3, 4, 6, 8, 10, 11, 13, 14, 16, 17, 20, 21], "standard": [1, 2, 3, 4, 6, 7, 10, 11, 14, 16], "xkcd": 1, "927": 1, "usual": [1, 3, 4, 5, 7, 8, 16, 17, 20, 21], "ll": [1, 4, 6, 7, 9, 13, 20], "fast": [1, 4, 6, 9, 10, 13, 14, 19], "space": [1, 6, 10, 16, 20], "effici": [1, 5, 6, 10, 11, 13], "everybodi": [1, 16], "els": [1, 2, 4, 5, 13, 14, 17, 21], "lead": [1, 20], "field": 1, "certain": [1, 3, 12], "human": [1, 21], "readabl": [1, 20], "enought": 1, "code": [1, 2, 3, 5, 6, 10, 11, 12, 13, 14, 19, 20, 21], "share": [1, 3, 8, 11, 14], "m": [1, 2, 3, 4, 8, 10, 12, 13, 15, 16], "support": [1, 3, 4, 7, 9, 13, 14, 16, 19], "some": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 16, 17, 19, 20, 21], "howev": [1, 2, 3, 4, 5, 13, 14, 16, 20, 21], "through": [1, 4, 5, 7, 10, 11, 13, 14], "librari": [1, 2, 3, 5, 6, 7, 10, 12, 13, 14, 19, 20, 21], "tabl": [1, 4, 13], "describ": [1, 4, 6, 12, 13, 16], "name": [1, 2, 3, 4, 5, 8, 12, 13, 14, 16, 17, 19, 20, 21], "storag": [1, 5, 10], "ok": [1, 2, 5, 13], "depend": [1, 2, 5, 6, 9, 10, 11, 12, 14], "bad": [1, 3, 4, 9, 11, 12, 14], "none": [1, 4, 11, 14, 21], "modul": [1, 4, 8, 9, 11, 12, 14, 16, 19, 20, 21], "warn": [1, 16], "best": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 19], "debug": [1, 8, 14], "creat": [1, 2, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 19, 20, 21], "riski": 1, "unpickl": 1, "from": [1, 2, 5, 6, 7, 8, 9, 10, 11, 13, 16, 17, 19], "trust": [1, 5, 9], "own": [1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 20, 21], "serial": 1, "suit": 1, "variabl": [1, 2, 4, 8, 10, 13, 14, 16, 17, 19], "inspect": [1, 13, 21], "wb": [1, 4], "f": [1, 4, 7, 10, 11, 14, 16, 19, 21], "dump": [1, 4], "rb": [1, 4], "data_array_pickl": 1, "match": [1, 4, 10, 16], "origin": [1, 4, 6, 9, 10, 11, 13, 16, 20, 21], "my_object": [1, 4], "my_pickled_object": [1, 4], "print": [1, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "far": [1, 14, 20], "most": [1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 14, 16, 19], "popular": [1, 2, 3, 6, 12, 14, 16], "shareabl": 1, "big": [1, 4, 9, 11, 13], "veri": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 17, 20, 21], "nice": [1, 4, 13, 17, 20, 21], "interfac": [1, 3, 4, 5, 6, 8, 12, 14, 19, 20, 21], "to_csv": [1, 4, 13], "function": [1, 2, 4, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 20, 21], "index": [1, 2, 4, 9, 11, 12, 13, 17], "fals": [1, 4, 10], "dataset_csv": [1, 4], "routin": [1, 10, 19], "well": [1, 3, 6, 7, 8, 9, 14, 19, 20, 21], "savetxt": 1, "data_array_csv": 1, "loadtxt": 1, "care": [1, 8, 14], "enough": [1, 4, 5, 6, 10, 13, 14, 17, 20], "decim": [1, 4, 10, 13], "place": [1, 3, 4, 8, 10, 11, 12, 21], "so": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 20], "won": [1, 3, 8, 13, 14, 16, 20], "t": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 19, 20, 21], "lose": 1, "doubl": [1, 11], "16": [1, 4, 10, 11, 14, 16, 20], "normal": [1, 2, 4, 14, 19, 21], "test_numb": 1, "sqrt": [1, 10, 11], "test_fil": 1, "sqrt2": 1, "w": [1, 21], "close": [1, 2, 4, 8, 15], "r": [1, 2, 3, 4, 10, 11, 12, 21], "test_number2": 1, "float64": [1, 4, 10], "readlin": 1, "calcul": [1, 3, 4, 10, 12, 13, 14, 15, 16, 19], "distanc": [1, 13, 21], "between": [1, 3, 4, 8, 10, 13, 20, 21], "ab": 1, "avoid": [1, 3, 4, 10, 12, 14], "even": [1, 2, 3, 4, 5, 9, 10, 12, 14, 15, 17, 20, 21], "infal": 1, "whether": [1, 4, 6, 11, 13, 16, 19], "written": [1, 3, 4, 9, 10, 13, 14, 16, 19, 20], "compar": [1, 4, 10, 14, 15, 16, 19, 20], "row": [1, 4, 10, 11, 13], "last": [1, 3, 4, 8, 10, 16], "sometim": [1, 3, 4, 13, 14], "round": [1, 4, 10, 13, 14], "due": [1, 3, 4, 6, 10, 12], "complex": [1, 17, 20], "technic": [1, 7], "reason": [1, 2, 3, 5, 6, 14], "high": [1, 2, 4, 5, 6, 9, 10, 13, 14], "ineffici": 1, "wise": 1, "where": [1, 2, 3, 4, 5, 6, 9, 10, 11, 13, 14, 19], "repres": [1, 4, 11, 13, 19], "nativ": 1, "suffer": 1, "pyarrow": 1, "pip": [1, 3, 4, 14], "demo": [1, 5, 7, 14, 21], "temporari": 1, "frame": 1, "quickli": [1, 4, 8, 10], "julia": [1, 6, 9], "to_feath": 1, "read_feath": 1, "dataset_feath": 1, "said": [1, 21], "columnar": [1, 9], "commonli": 1, "usabl": [1, 4, 9, 12], "languag": [1, 2, 6, 8, 10, 11, 16, 17, 19], "c": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 17, 19], "java": 1, "matlab": [1, 2, 10, 19], "to_parquet": 1, "read_parquet": 1, "dataset_parquet": 1, "more": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "complic": [1, 3], "complet": [1, 4, 6, 8, 11, 13, 14, 19], "same": [1, 3, 4, 8, 10, 11, 13, 14, 15, 17, 20, 21], "cannot": [1, 3, 4, 16], "result": [1, 2, 3, 4, 8, 9, 10, 11, 13, 14, 15, 16, 19], "error": [1, 4, 9, 10, 13, 16, 20, 21], "temporarili": 1, "data_array_npi": [1, 4], "savez": 1, "npz": 1, "data_array0": 1, "data_array1": 1, "idea": [1, 3, 4, 5, 8, 9, 10, 13, 14], "spars": [1, 4], "matric": [1, 4], "save_npz": 1, "load_npz": 1, "huge": [1, 3, 5, 6, 11], "pytabl": [1, 9], "h5py": [1, 9], "perform": [1, 4, 6, 10, 11, 13, 14, 19], "larg": [1, 4, 5, 6, 9, 11, 14, 20], "amount": [1, 3, 6, 11, 16, 21], "especi": [1, 5, 9, 10], "multidimension": [1, 10], "physic": [1, 4, 13], "to_hdf": [1, 13], "h5": 1, "mode": [1, 8, 21], "dataset_hdf5": 1, "read_hdf": [1, 13], "come": [1, 2, 3, 5, 7, 8, 11, 19], "default": [1, 3, 4, 8, 10, 13, 14, 15, 20, 21], "anaconda": [1, 2, 4, 5, 6, 7, 8, 12], "h5_file": 1, "create_dataset": 1, "again": [1, 3, 4, 5, 8, 10, 15, 16, 21], "full": [1, 7, 10, 14, 19], "data_array_h5": 1, "h5netcdf": 1, "often": [1, 2, 3, 4, 5, 6, 9, 10, 12, 13, 14, 17, 21], "mention": [1, 5, 7, 9, 13, 14], "faster": [1, 3, 4, 10, 11, 13, 14, 15, 16], "offici": [1, 16], "A": [1, 2, 3, 4, 5, 8, 9, 10, 12, 14, 20, 21], "great": [1, 2, 4, 8, 9, 14], "xarrai": [1, 14], "spatial": 1, "tempor": 1, "dimens": [1, 10, 11], "those": [1, 4, 7, 10, 11, 13, 14], "its": [1, 2, 4, 10, 11, 12, 13, 14, 21], "relat": [1, 6, 12], "make": [1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 20, 21], "simul": 1, "to_xarrai": 1, "to_netcdf": 1, "nc": 1, "engin": [1, 9], "xr": 1, "dataset_xarrai": 1, "open_dataset": 1, "dataset_netcdf4": 1, "to_panda": 1, "dataarrai": 1, "data_array_xarrai": 1, "open_dataarrai": 1, "data_array_netcdf4": 1, "to_numpi": 1, "advantag": [1, 4, 11, 14], "e": [1, 2, 4, 5, 6, 10, 11, 12, 13, 14, 19, 20, 21], "g": [1, 2, 4, 5, 6, 10, 12, 13, 14, 17, 19, 20, 21], "z": [1, 4, 10], "tell": [1, 3, 4, 9, 11, 13, 21], "grid": [1, 10], "situat": [1, 3, 4, 9, 14], "As": [1, 3, 7, 9, 11, 12, 13, 14], "further": [1, 6, 12, 13, 14, 21], "analysi": [1, 2, 3, 6, 8, 11, 13, 14], "doe": [1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 16, 19, 20, 21], "web": [1, 2, 6, 7, 8, 9, 12, 13, 19], "request": [1, 2, 9, 11, 13, 14], "deal": [1, 13], "rest": [1, 2, 3, 4, 5, 8, 10, 17], "api": [1, 5, 6, 11, 13, 14], "rare": [1, 9], "keep": [1, 3, 4, 9, 10, 21], "unless": [1, 3, 4, 8, 9, 10, 14], "layer": [1, 14], "lot": [1, 4, 5, 6, 8, 9, 13, 14, 19, 20], "interconnect": 1, "similarli": [1, 10, 13, 21], "to_json": [1, 13], "read_json": [1, 13], "dataset_json": 1, "openpyxl": 1, "quick": [1, 2, 4, 6, 19], "social": [1, 21], "econom": 1, "plenti": [1, 5, 16], "them": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 19, 20, 21], "optim": [1, 9, 11, 14, 16, 19], "heavili": [1, 11], "One": [1, 2, 4, 10, 11, 13, 16, 20], "networkx": [1, 4, 9], "tool": [1, 2, 3, 5, 6, 8, 10, 13, 14, 20, 21], "igraph": 1, "potenti": 1, "becaus": [1, 3, 4, 6, 7, 8, 10, 11, 13, 14, 15, 19], "charact": [1, 4, 16, 21], "addition": 1, "compress": 1, "much": [1, 2, 4, 5, 6, 8, 9, 12, 13, 14, 16, 20, 21], "than": [1, 3, 5, 6, 9, 10, 11, 12, 13, 14, 17, 19, 20], "alloc": [1, 10], "befor": [1, 2, 3, 4, 7, 10, 11, 12, 13, 14, 16], "known": [1, 4, 8, 10, 11], "partial": 1, "larger": [1, 2, 4, 12, 13, 21], "comput": [1, 2, 3, 4, 5, 7, 8, 10, 11, 13, 14, 15, 19, 20, 21], "had": [1, 4, 5, 6, 9, 11], "mb": [1, 11], "exactli": [1, 4, 7, 9, 10], "57": 1, "360": [1, 13], "81": [1, 2, 4, 13, 16], "12": [1, 2, 4, 10, 13, 14, 20], "9": [1, 2, 4, 10, 13, 14, 16, 17], "6": [1, 2, 4, 10, 11, 13, 14, 15, 16], "67": [1, 16], "true": [1, 4, 10, 13, 16, 17, 20], "82": [1, 2, 4], "35": 1, "8": [1, 2, 4, 7, 10, 11, 13, 16, 17, 20, 21], "96": [1, 2, 4, 13], "89": 1, "41": 1, "7": [1, 2, 3, 4, 8, 10, 11, 13, 14, 15, 16], "29": [1, 13], "92": 1, "74": [1, 2, 4], "rel": [1, 2, 4, 9, 12], "poor": [1, 4, 13], "base": [1, 2, 3, 4, 8, 9, 11, 13, 16, 20], "mostli": 1, "dimension": [1, 2, 4, 10], "shape": [1, 4, 10, 11, 16], "23": [1, 13, 16], "690": 1, "294": 1, "63": 1, "13": [1, 2, 4, 10], "72": 1, "27": 1, "97": 1, "64": [1, 11, 12, 13], "28": [1, 20, 21], "kind": [1, 3, 4, 10, 11, 13, 19], "better": [1, 3, 6, 8, 9, 16, 19, 20], "determin": [1, 4, 16, 17], "solv": [1, 3, 4, 5, 8], "previous": [1, 3, 4], "framework": [1, 5, 6, 10, 14], "specif": [1, 3, 8, 10, 11, 12, 14, 16, 19, 20], "priorit": 1, "initi": [1, 4, 10, 11, 21], "futur": [1, 3, 4, 8, 9, 14], "ve": [1, 4, 14], "procedur": [1, 2], "script": [1, 2, 3, 5, 6, 8, 9, 11, 12, 14, 16], "alwai": [1, 3, 4, 10, 11, 13, 20, 21], "reproduc": [1, 3, 5, 6, 9, 20], "throughout": 1, "turn": [1, 3, 8, 11, 16], "plot": [1, 3, 5, 8, 13, 16, 20], "averag": [1, 4, 13], "head": [1, 4, 8, 13, 21], "onc": [1, 4, 8, 9, 12, 15, 20], "finish": [1, 3, 4, 14], "peopl": [1, 2, 3, 4, 5, 7, 8, 10, 12, 13, 16, 21], "io": [1, 3, 14, 21], "comparison": [1, 12], "notebook": [1, 2, 3, 7, 8, 9, 10, 12, 13, 14, 21], "don": [1, 4, 5, 6, 7, 8, 9, 11, 13, 14, 17, 21], "happen": [2, 4, 6, 8, 9, 10, 11, 12, 14], "can": [2, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 19, 20, 21], "produc": [2, 4, 9, 11, 12, 13, 16], "prefer": [2, 4, 9, 16, 21], "abl": [2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 17, 20], "simpl": [2, 3, 4, 5, 7, 8, 9, 12, 13, 14, 15, 16, 20, 21], "tweak": 2, "know": [2, 3, 4, 5, 6, 7, 9, 10, 11, 13, 14, 17, 19, 20], "orient": [2, 4, 6], "v": [2, 4, 7, 8, 10, 19], "help": [2, 4, 5, 8, 16, 20], "clau": 2, "o": [2, 4, 10, 14, 15, 19], "wilk": 2, "fundament": 2, "thing": [2, 3, 4, 5, 6, 8, 9, 10, 12, 14, 19], "i": [2, 3, 4, 5, 7, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21], "over": [2, 4, 5, 9, 10, 11, 13, 17, 20, 21], "autom": [2, 4, 9, 12, 20], "friend": [2, 21], "think": [2, 14, 20], "figur": [2, 4, 8, 19, 20], "autogener": 2, "part": [2, 4, 5, 8, 10, 11, 14, 21], "pipelin": [2, 3], "out": [2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 19, 20, 21], "sent": 2, "printer": 2, "post": [2, 9, 14], "process": [2, 4, 9, 11, 14, 15, 19, 20, 21], "minim": [2, 3, 4, 7, 8, 9, 10], "could": [2, 3, 4, 5, 6, 7, 9, 10, 14, 15, 16, 20, 21], "bite": 2, "regener": 2, "50": 2, "dai": [2, 4, 5, 6, 7, 9, 13, 20], "submiss": 2, "deadlin": 2, "left": [2, 4, 6, 7, 8, 10, 11], "perfect": [2, 4, 8, 9], "within": [2, 12, 20], "probabl": [2, 3, 4, 7, 9, 10, 13, 14, 19], "wide": [2, 3, 4, 9, 13], "seaborn": [2, 4, 9, 13], "level": [2, 4, 5, 6, 9, 10, 14], "statist": [2, 4, 9, 13, 19], "vega": [2, 4], "altair": [2, 4], "declar": [2, 4], "entir": [2, 4, 14], "lesson": [2, 4, 5, 6, 7, 8, 9, 11, 13, 14, 17, 20], "interact": [2, 4, 5, 6, 8, 12, 14], "graph": [2, 4, 9], "bokeh": [2, 4], "plotnin": [2, 4], "implement": [2, 4, 6, 10, 11, 14, 19], "grammar": [2, 4], "graphic": [2, 4, 7, 9], "ggplot2": [2, 4], "ggplot": [2, 4], "home": [2, 4, 7, 9], "pyngl": [2, 4], "weather": [2, 4, 20], "forecast": [2, 4], "commun": [2, 4, 6, 9, 12, 13, 14, 21], "k3d": [2, 4], "jupyt": [2, 5, 6, 7, 9, 10, 12, 13, 14, 21], "extens": [2, 4, 8, 9, 14, 16], "3d": [2, 4, 9, 21], "famili": [2, 4, 13, 21], "perhap": [2, 9], "build": [2, 5, 9, 11, 19], "feel": [2, 4, 9, 10, 13], "familiar": [2, 3, 4, 5, 6, 17], "abov": [2, 4, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 20, 21], "chanc": [2, 10, 13], "somebodi": 2, "knowledg": [2, 11], "adjust": [2, 4, 10, 20], "low": [2, 4, 8, 9, 13, 14], "draw": 2, "abstract": 2, "qualiti": [2, 9], "type": [2, 4, 5, 6, 7, 8, 9, 13, 19, 20, 21], "line": [2, 4, 5, 6, 8, 10, 12, 13, 14, 16, 19, 21], "strength": 2, "matter": [2, 6], "sinc": [2, 4, 10, 11, 13, 15, 16, 20, 21], "typic": [2, 3, 4, 5, 14, 17], "fit": [2, 4, 14, 16], "But": [2, 4, 5, 6, 8, 9, 10, 13, 14, 19, 20], "u": [2, 4, 11, 13, 14, 19, 20, 21], "method": [2, 4, 7, 9, 10, 11, 13, 14, 19, 21], "en": [2, 4, 21], "wikipedia": [2, 4, 20], "wiki": [2, 4], "anscomb": [2, 4], "27s_quartet": [2, 4], "data_x": [2, 4], "11": [2, 4, 10, 11, 14, 16], "14": [2, 4, 10, 16, 17], "4": [2, 6, 11, 13, 14, 15, 16, 17, 19], "data_i": [2, 4], "04": [2, 4], "95": [2, 4], "58": [2, 4], "33": [2, 4, 16], "24": [2, 3, 4], "26": [2, 4], "84": [2, 4], "68": [2, 4], "e69f00": [2, 4], "label": [2, 4, 16, 20], "axi": [2, 4, 10, 14, 16], "set_titl": [2, 4, 16, 20], "titl": [2, 4, 8, 20, 21], "uncom": [2, 4], "would": [2, 3, 4, 7, 9, 10, 11, 12, 13, 14, 16, 17, 20], "like": [2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 16, 20, 21], "savefig": [2, 4, 20], "displai": [2, 8, 21], "cluster": [2, 20], "call": [2, 3, 4, 6, 8, 11, 12, 13, 14, 20, 21], "agg": 2, "valu": [2, 4, 10, 11, 13, 14, 16, 17, 20, 21], "56b4e9": [2, 4], "data2_i": [2, 4], "77": [2, 4, 17], "009e73": [2, 4], "second": [2, 4, 9, 10, 11, 14, 21], "multipli": [2, 4, 10, 11, 19], "element": [2, 4, 10, 11, 14, 17, 19], "data2_y_sc": [2, 4], "legend": [2, 4, 16], "search": [2, 4, 9, 12, 13, 19, 21], "clue": [2, 4], "consult": [2, 4], "guid": [2, 4, 6, 11, 13, 16], "At": [2, 4, 6, 14, 16], "end": [2, 3, 4, 8, 10, 11, 12, 14, 16, 20, 21], "experi": [2, 4, 14, 20], "red": [2, 4], "hex": [2, 4], "qualit": 2, "palett": [2, 4], "opim": 2, "vision": 2, "defici": 2, "clauswilk": 2, "dataviz": 2, "pitfal": [2, 8], "html": [2, 4, 6, 21], "okab": 2, "k": 2, "ito": 2, "2008": [2, 6], "univers": [2, 6, 10, 21], "design": [2, 4, 6, 14, 15], "cud": 2, "That": [2, 4, 10], "friendli": 2, "colorblind": 2, "understand": [2, 4, 7, 10, 11, 13, 14, 17, 19, 20, 21], "approach": [2, 3, 4, 6, 12, 14, 20], "though": [2, 4, 7, 12, 14, 15, 17], "dual": 2, "outsid": [2, 4, 8, 12, 20], "scope": [2, 14], "modern": [2, 6, 11], "option": [2, 5, 8, 10, 13, 19], "explicit": 2, "separ": [2, 3, 10, 13, 14, 15, 20], "pass": [2, 4, 9, 10, 14, 20, 21], "around": [2, 4, 7, 11, 13, 14, 16, 19, 21], "tradit": [2, 10], "mimic": 2, "implicit": 2, "carri": [2, 10, 14, 21], "global": [2, 4, 14, 19], "xlabel": [2, 4, 20], "ylabel": [2, 4, 20], "internet": [2, 13], "mix": 2, "although": 2, "compact": [2, 13], "wrap": [2, 5, 19], "send": [2, 8, 14, 21], "less": [2, 4, 6, 8, 10, 11, 21], "risk": [2, 9], "unrel": [2, 8], "modifi": [2, 4, 11, 16, 19, 20], "latter": 2, "accept": [2, 21], "yield": [2, 13], "surpris": 2, "introduc": [2, 5, 6], "enhanc": 2, "pleas": [2, 3, 4, 7, 12], "affect": [2, 3, 11], "almost": [2, 6, 9], "aspect": [2, 16], "studi": [2, 8, 21], "cheatsheet": [2, 13, 18], "github": [2, 3, 5, 8, 9, 13, 14], "among": [2, 4, 13], "pre": [2, 16], "defin": [2, 3, 4, 5, 11, 13, 17, 19, 20, 21], "theme": 2, "sheet": 2, "instanc": [2, 4, 6, 12, 14, 16, 17, 20], "either": [2, 3, 4, 5, 7, 8, 12, 13, 14, 20], "input": [2, 4, 5, 8, 10, 11, 14, 15, 16, 20], "imposs": [2, 4, 8], "rememb": [2, 9, 13], "strategi": [2, 8, 14], "mind": 2, "Being": [2, 8], "answer": [2, 3, 4, 10, 14, 15], "fetch": [2, 4], "gapminder_data": [2, 4], "queri": [2, 4, 21], "snippet": [2, 4], "overview": [2, 4, 5, 13, 17], "linear": [2, 4, 11, 16, 19], "ppp": [2, 4], "dollar": [2, 4], "realiz": [2, 4, 14], "ideal": [2, 4], "task": [2, 4, 5, 6, 9, 10, 15, 20], "switch": [2, 4, 8], "arriv": [2, 4], "transpar": [2, 4], "slide": [2, 4], "screen": [2, 4], "onli": [2, 3, 6, 7, 8, 11, 12, 13, 14, 16, 20, 21], "few": [2, 3, 4, 10, 13, 14, 20], "centimet": [2, 4], "inch": [2, 4], "font": [2, 4, 21], "tickmark": [2, 4], "too": [2, 4, 5, 8, 9, 11, 12, 14, 16], "tick_param": [2, 4], "fontsiz": [2, 4], "major": [2, 3, 4, 14], "length": [2, 4, 11, 21], "minor": [2, 4], "labels": [2, 4], "doubt": [2, 4], "brows": [2, 4, 8], "link": [2, 9, 20], "recent": [2, 3, 4, 7, 12], "simpli": [2, 4], "interest": [2, 3, 4, 12, 13, 14], "note": [2, 4, 7, 10, 12, 13, 14, 20, 21], "addit": [2, 4, 6, 8, 11, 12, 20], "order": [2, 4, 5, 8, 10, 13, 20], "itself": [2, 4, 8, 10, 20], "ani": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 20], "structur": [2, 4, 9, 10, 12, 13, 20], "numpi": [2, 3, 5, 6, 9, 13, 14, 16, 18, 19], "arrai": [2, 4, 6, 9, 11, 13, 14, 19, 20], "bit": [2, 4, 5, 6, 7, 9, 13, 14, 16, 17], "feed": [2, 4], "simplifi": [2, 3, 4], "kei": [2, 4, 8, 10, 14, 21], "imagin": [2, 4, 6, 12, 20], "were": [2, 3, 4, 6, 9, 16, 21], "pydata": [2, 4, 18], "And": [2, 4, 6, 11, 12, 13], "caught": [2, 4], "ey": [2, 4, 10], "simple_violinplot": [2, 4], "d": [2, 4, 8, 10, 13, 17, 19, 20], "seem": [2, 3, 4, 9, 19], "sn": [2, 4, 13], "violinplot": [2, 4, 13], "set_them": [2, 4], "across": [2, 4, 14], "sever": [2, 4, 6, 7, 9, 20], "default_rng": [2, 4, 11], "p": [2, 4, 21], "40": [2, 4, 11, 16], "arang": [2, 4, 10, 13, 16], "show": [2, 4, 5, 6, 7, 9, 12, 13, 14, 16, 20, 21], "distribut": [2, 3, 4, 6, 7, 8, 9, 12, 13, 14], "violin": [2, 4], "light": [2, 4], "inner": [2, 4, 13], "h": [2, 4, 11, 17, 20], "reveal": [2, 4], "25146044": [2, 4], "27005437": [2, 4], "78778386": [2, 4], "27832843": [2, 4], "88147169": [2, 4], "76439276": [2, 4], "87844934": [2, 4], "49695422": [2, 4], "59252953": [2, 4], "00342116": [2, 4], "26038963": [2, 4], "15118015": [2, 4], "69725111": [2, 4], "60361933": [2, 4], "22137264": [2, 4], "86174242": [2, 4], "45950762": [2, 4], "32352988": [2, 4], "56724895": [2, 4], "42215312": [2, 4], "34419915": [2, 4], "46123886": [2, 4], "56953795": [2, 4], "95292133": [2, 4], "clutter": [2, 4], "remov": [2, 3, 4], "l1": [2, 4], "l2": [2, 4], "focu": [2, 4, 16], "set_yticklabel": [2, 4], "clarifi": 2, "move": [2, 9, 11, 12], "unpack": 2, "manuscript": 2, "five": 3, "tensorflow": [3, 9], "get": [3, 4, 5, 6, 7, 9, 10, 11, 14, 15, 16, 17, 19, 20, 21], "me": 3, "necessari": [3, 11, 12, 14], "colleagu": [3, 7], "conflict": 3, "reus": [3, 4, 6, 14], "relianc": 3, "extern": [3, 5, 6, 12, 14, 19], "compon": [3, 12], "Into": [3, 4], "yml": [3, 4, 7], "why": [3, 4, 5, 10, 11, 14, 16, 21], "ever": [3, 4, 21], "experienc": [3, 4], "ye": [3, 4, 11], "did": [3, 4, 8, 14, 16, 20, 21], "repositori": [3, 9, 12, 13, 16], "similar": [3, 4, 5, 9, 10, 12, 14, 15, 20, 21], "maintain": [3, 4, 8, 9], "inc": 3, "ecosystem": [3, 5, 6], "tradition": 3, "bundl": 3, "old": [3, 4, 5, 6, 8, 9, 13], "handl": [3, 9, 10, 13, 14, 16], "system": [3, 4, 7, 8, 12, 14, 20, 21], "pro": 3, "creation": [3, 5], "con": 3, "aim": 3, "tri": [3, 5], "scientif": [3, 4, 5, 9, 10, 14, 19], "speed": [3, 10, 11, 12, 13], "becom": [3, 4, 5, 6, 9, 10, 11, 20], "curat": 3, "quit": [3, 4, 10, 11, 14, 20], "easier": [3, 4, 5, 6, 12, 13, 20, 21], "harder": 3, "free": [3, 21], "hous": 3, "largest": [3, 4, 13], "replac": [3, 4, 5, 9, 13], "deploy": 3, "made": [3, 4, 9, 13, 14, 20, 21], "academ": [3, 5], "non": [3, 4, 5, 8, 10, 13, 19], "commerci": 3, "meet": 3, "coupl": 3, "encount": 3, "mistak": [3, 4, 16], "someth": [3, 10, 14, 17, 19, 20], "export": [3, 4, 14, 20], "replic": [3, 4, 21], "chloe": [3, 4], "team": [3, 4, 6], "still": [3, 4, 5, 6, 8, 9, 10, 12, 16, 20], "assign": [3, 4, 8, 13], "week": [3, 4, 20], "favorit": [3, 4, 16], "been": [3, 4, 5, 6, 9, 11, 12, 14, 16, 20], "develop": [3, 4, 6, 8, 9, 11, 13, 20, 21], "older": [3, 4, 9], "otherwis": [3, 4, 17], "fail": [3, 4, 16], "valid": [3, 4, 16, 21], "baselin": [3, 4, 5, 6], "upgrad": [3, 4, 6], "python310": [3, 4], "env": [3, 4, 7, 20], "delet": [3, 4, 8], "navig": [3, 4, 7, 8, 12], "init": [3, 4, 7], "caus": [3, 4], "constantli": [3, 4], "suppos": [3, 4, 20], "common": [3, 4, 5, 7, 9, 10, 11, 13, 14, 17, 19, 21], "consol": [3, 4], "effect": [3, 4], "__version__": [3, 4, 12], "Or": [3, 4, 7, 9], "liner": [3, 4, 13], "termin": [3, 4, 5, 7, 12, 14, 16, 20], "bash": [3, 4, 8], "deactiv": [3, 4], "sure": [3, 4, 5, 6, 7, 9, 14, 16], "current": [3, 4, 11, 20], "venv": [3, 4], "python3": [3, 4, 7, 12, 20], "scicomp": [3, 4, 7, 8, 13, 20], "virtual": [3, 4, 12], "folder": [3, 4, 12, 20], "locat": [3, 4, 9], "linux": [3, 4, 8, 12], "mac": [3, 4, 12], "osx": [3, 4, 12], "bin": [3, 4, 13, 16, 20], "window": [3, 4, 12, 16], "command": [3, 4, 5, 6, 8, 12, 13], "unexpect": [3, 14, 16], "behaviour": 3, "alreadi": [3, 4, 5, 6, 7, 9, 10, 13, 20], "ran": [3, 13], "state": [3, 14, 21], "These": [3, 4, 6, 9, 10, 11, 12, 13, 14, 19, 21], "mitig": 3, "yaml": [3, 12, 20], "recreat": 3, "exact": [3, 7], "delai": [3, 14], "dure": [3, 4, 7, 11, 17], "review": 3, "mutual": 3, "incompat": 3, "prioriti": 3, "goe": [3, 4, 6, 8, 9, 10, 12, 14], "bottom": [3, 4, 10, 14, 21], "refer": [3, 4, 8, 10, 11, 13, 17], "section": [3, 4, 8, 9, 12, 16], "coderefineri": [3, 6, 7, 8, 9, 20], "mainten": 3, "coexist": 3, "frozen": [3, 4], "somepackag": 3, "With": [3, 7, 10, 13, 21], "attach": 3, "git": [3, 7, 9], "along": [3, 8, 11, 17, 20], "binder": [3, 5, 6, 9], "session": [3, 4, 7, 8, 14], "talk": [3, 6, 9, 21], "express": [3, 4, 9, 13, 16, 21], "setup": [3, 12], "py": [3, 4, 8, 12, 14, 16, 20], "pyproject": [3, 12], "toml": [3, 12], "meta": [3, 4, 12, 21], "directli": [3, 4, 9, 10, 11, 13, 14, 20], "difficult": [3, 8, 14, 21], "narrowli": 3, "taken": [3, 4, 14], "install_requir": 3, "19": [3, 4, 11, 13, 16], "undefin": [3, 16, 17], "alongsid": 3, "minimum": 3, "maximum": [3, 13], "issu": [3, 9, 21], "consum": [3, 16], "poetri": [3, 12], "pipenv": 3, "altern": [3, 6, 12, 16], "pyenv": 3, "micropipenv": 3, "lightweight": [3, 8, 21], "rule": [3, 4, 11, 16, 19], "micromamba": 3, "tini": 3, "resourc": [3, 4, 9, 13, 20], "aalto": [3, 8], "fi": [3, 8, 21], "trace": 3, "mainli": 4, "helper": 4, "teach": [4, 5, 6, 7, 8, 9], "event": [4, 13], "cover": [4, 5, 6, 10, 13, 14], "subset": [4, 13], "ipynb": [4, 20], "directori": [4, 8, 16, 20], "cours": [4, 5, 7, 8, 9, 10, 11, 14, 17], "stuff": [4, 8], "done": [4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 20], "browser": [4, 7, 8, 13, 20, 21], "editor": [4, 5, 6, 8], "begin": [4, 5, 8, 11], "independ": [4, 8], "trivial": [4, 8, 11], "slightli": [4, 6, 8, 14, 17, 20], "ten": [4, 8], "fibonacci": [4, 8, 13], "markdown": [4, 8], "cell": [4, 8, 10, 13, 14, 15], "bold": [4, 8], "ital": [4, 8], "inlin": [4, 8, 13], "timeit": [4, 8, 10, 11, 13, 14, 15, 19], "magic": [4, 8, 14, 15], "fastest": [4, 8], "sum": [4, 8, 10, 11, 13, 14, 15, 16], "1000000": [4, 8], "tab": [4, 8, 13, 21], "hint": [4, 8, 13, 20], "thin": [4, 8], "sidebar": [4, 8], "shut": [4, 8], "kernel": [4, 6, 8, 11], "b": [4, 5, 6, 8, 10, 11, 13, 17, 20, 21], "repeat": [4, 8, 10, 11, 20], "increment": [4, 8, 9], "tupl": [4, 8, 10, 17], "new_a": [4, 8], "new_b": [4, 8], "statement": [4, 8, 14, 16, 17], "hand": [4, 8, 19], "comment": [4, 8, 16, 20], "output": [4, 5, 7, 8, 10, 11, 14, 16, 20], "relet": [4, 8], "395": [4, 8], "loop": [4, 8, 10, 15, 17, 20, 21], "std": [4, 8, 13, 15], "dev": [4, 8, 13, 15], "becam": [4, 6, 8], "spread": [4, 8], "On": [4, 8, 16], "success": [4, 8], "prevent": [4, 8, 14], "rst": 4, "datatyp": [4, 10], "linspac": [4, 10, 16], "3x2": [4, 10], "int": [4, 10, 11, 13, 14, 16, 17], "astyp": [4, 10], "reshap": [4, 10], "numpyi": [4, 10], "npy": [4, 10], "dtype": [4, 10, 13], "int64": [4, 10, 13], "argument": [4, 10, 13, 14, 15, 17, 19, 21], "eg": [4, 10], "zero": [4, 10, 11, 13, 19], "mayb": [4, 10], "cast": [4, 10], "randint": [4, 10, 16], "matrix": [4, 10, 14, 19], "dot": [4, 10, 12, 19], "leav": [4, 10], "paramet": [4, 10, 13, 16, 20], "elementwis": [4, 10], "enabl": [4, 10, 13], "given": [4, 10, 12, 13, 14, 17, 20], "view": [4, 10, 13], "mere": [4, 10, 11], "henc": [4, 10, 13], "ufunc": [4, 10, 11], "id": [4, 5, 10, 21], "third": [4, 10], "notic": [4, 9, 10, 14, 15, 16], "return": [4, 10, 11, 12, 13, 14, 15, 16, 17, 19, 21], "wa": [4, 5, 6, 9, 10, 11, 13, 20, 21], "actual": [4, 5, 7, 9, 10, 11, 14, 15, 20, 21], "slower": [4, 10], "10000": [4, 10, 14, 19], "squar": [4, 10, 14, 15], "extra": [4, 7, 10, 16, 21], "revers": [4, 10, 11], "vector": [4, 5, 11, 14, 19], "border": [4, 10, 21], "insid": [4, 10, 11], "ceil": [4, 10], "floor": [4, 10], "trunc": [4, 10], "particular": [4, 10, 19, 21], "behav": [4, 10], "neg": [4, 10, 13], "recal": [4, 10], "ident": [4, 10, 14], "sin": [4, 10, 16], "co": [4, 10], "4x4": [4, 10], "equal": [4, 10, 16], "allclos": [4, 10], "1d": [4, 10, 11], "sort": [4, 6, 9, 10, 16], "np_arrai": [4, 10], "question": 4, "indirect": [4, 10], "indic": [4, 10, 11, 13], "ones": [4, 7, 10, 11], "combin": [4, 8, 10, 13, 14, 15], "8x4": [4, 10], "content": [4, 8, 10, 21], "4x8": [4, 10], "rand": [4, 10, 11, 13, 19], "100": [4, 10, 11, 13, 16, 21], "halfwai": [4, 10], "nearest": [4, 10], "posit": [4, 10, 20], "75": [4, 10], "trun": [4, 10], "oo": [4, 10], "s2c2": [4, 10], "argsort": [4, 10], "concaten": [4, 10, 11, 13], "slow": [4, 6, 8, 10, 11, 14, 19], "million": [4, 11, 21], "100000000": [4, 11], "togeth": [4, 6, 11, 14, 16, 18], "beat": [4, 11], "troubl": [4, 11], "basic": [4, 5, 6, 7, 10, 11, 14, 15, 17, 19, 21], "lession": [4, 11], "continu": [4, 11], "live": [4, 11], "worri": [4, 11, 14], "watch": [4, 5, 6, 11, 12], "100_000_000": [4, 11], "ravel": [4, 11], "appropri": [4, 11], "remind": [4, 11], "yourself": [4, 5, 6, 7, 9, 11, 20], "col": [4, 11, 13], "total": [4, 11, 16], "n_col": [4, 11], "desir": [4, 11], "3_465": [4, 11], "18_923": [4, 11], "10_000": [4, 11], "20_000": [4, 11], "69_318_923": [4, 11], "def": [4, 11, 12, 13, 14, 15, 16, 17, 19], "littl": [4, 5, 6, 9, 11], "featur": [4, 9, 11, 13, 14], "stride_trick": [4, 11], "stride": 4, "attribut": [4, 11, 13, 21], "plai": [4, 8, 11, 13], "educ": [4, 6, 11, 21], "transpos": [4, 10], "lib": [4, 11], "as_strid": [4, 11], "000": [4, 11, 21], "obtain": [4, 11, 20], "By": [4, 5, 8, 10, 11, 14, 15, 20, 21], "infinit": [4, 11], "100_000_000_000": [4, 11], "autocomplet": [4, 13], "docstr": [4, 12, 13, 16], "piqu": [4, 13], "ag": [4, 13], "slice": [4, 13], "boolean": [4, 10, 13, 17], "surviv": [4, 13], "rate": [4, 13, 16], "iloc": [4, 13], "loc": [4, 13], "nasser": [4, 13], "mr": [4, 13], "nichola": [4, 13], "adel": [4, 13], "achem": [4, 13], "investig": [4, 13], "sibsp": [4, 13], "uniqu": [4, 9, 13, 17, 21], "histogram": [4, 13, 16], "split": [4, 13, 14, 15], "fare": [4, 13], "lambda": [4, 12, 13], "hist": [4, 13, 16], "fly": [4, 13], "df": [4, 13, 16], "rich": [4, 13], "member": [4, 13], "class": [4, 5, 6, 10, 11, 13, 14], "rwidth": [4, 13], "countri": [4, 13, 21], "receiv": [4, 13], "borncountrycod": [4, 13], "laureat": [4, 13], "step": [4, 7, 12, 13, 14], "lifespan": [4, 13], "extract": [4, 10, 13, 21], "country1": [4, 13], "country2": [4, 13], "country3": [4, 13], "country4": [4, 13], "borncountri": [4, 13], "isin": [4, 13], "groupbi": [4, 13], "categori": [4, 13], "pivot": [4, 13], "spreadsheet": [4, 13], "count": [4, 13], "pivot_t": [4, 13], "aggfunc": [4, 13], "heatmap": [4, 13], "linewidth": [4, 13], "dt": [4, 13], "stick": [4, 13], "swarmplot": [4, 13], "subset_physchem": [4, 13], "chemistri": [4, 13], "catplot": [4, 13], "swarm": [4, 13], "956": [4, 13], "287": [4, 13], "born": [4, 13, 20], "datetim": [4, 13], "to_datetim": [4, 13, 20], "coerc": [4, 13], "age_nobel": [4, 13], "365": [4, 13], "25": [4, 11, 13, 14, 21], "figsiz": [4, 13], "sweden": [4, 13], "firstnam": [4, 12, 13], "surnam": [4, 13], "color": [4, 16, 21], "arbitrari": [4, 11, 17], "object": [4, 6], "pickl": 4, "store": [4, 10, 11, 17, 19, 20, 21], "scikit": [4, 9, 14, 16, 18], "model": [4, 13, 14, 16], "jupyterlab": [4, 5, 8, 13, 16, 18, 20], "four": [4, 16], "found": [4, 9, 16, 21], "fix": [4, 16], "sklearn": [4, 16], "linear_model": [4, 16], "x_data": [4, 16], "err": [4, 16], "y_data": [4, 16], "put": [4, 9, 10, 13, 16, 20], "reg": [4, 16], "linearregress": [4, 16], "fit_intercept": [4, 16], "slope": [4, 16], "coef_": [4, 16], "intercept": [4, 16], "intercept_": [4, 16], "pred": [4, 16], "predict": [4, 9, 16], "scater": [4, 16], "linestyl": [4, 16], "2f": [4, 16, 21], "syntax": [4, 5, 6, 16, 17, 20], "30": [4, 6, 16, 20, 21], "miss": [4, 5, 7, 9, 13, 16], "bracker": [4, 16], "comma": [4, 16], "39": [4, 16], "misspel": [4, 16], "thu": [4, 9, 10, 13, 16, 19, 21], "dice_toss": [4, 16], "throw": [4, 16], "dice": [4, 16], "dice_rol": [4, 16], "roll_averag": [4, 16], "toss": [4, 16], "exercise2": [4, 16], "weather_observ": [4, 20], "weather_data": [4, 20], "temperatur": [4, 20], "tapiola": [4, 20], "espoo": [4, 20], "rp5": [4, 20], "kz": [4, 20], "lectur": [4, 20], "launcher": [4, 7, 20], "convert": [4, 11, 12, 13, 19, 20], "nbconvert": [4, 20], "preced": [4, 16, 20], "argpars": 4, "date": [4, 9, 13, 20, 21], "filenam": [4, 20], "sens": [4, 20], "interv": [4, 10, 19, 20], "januari": [4, 20], "2019": [4, 14, 20], "june": [4, 20], "2020": [4, 6, 10, 20], "octob": [4, 20], "cairo": [4, 20], "aaltoscicomp": [4, 7, 13, 20], "weather_cairo": [4, 20], "parser": [4, 20, 21], "argumentpars": [4, 20], "add_argu": [4, 20], "str": [4, 13, 17, 20], "01": [4, 19, 20], "dd": [4, 20], "mm": [4, 20], "yyyi": [4, 20], "2021": [4, 6, 20], "arg": [4, 20], "parse_arg": [4, 20], "start_dat": [4, 20], "dayfirst": [4, 20], "end_dat": [4, 20], "observ": [4, 12, 13, 20], "celsiu": [4, 20], "nicer": [4, 9, 20], "autofmt_xd": [4, 20], "optionspars": [4, 20], "config": 4, "sy": 4, "argv": [4, 11], "usr": [4, 20], "utf": [4, 20, 21], "get_paramet": [4, 20], "confg": [4, 20], "06": [4, 20, 21], "data_column": [4, 20], "pars": [4, 16], "relev": [4, 9, 19, 21], "integr": [4, 8, 12], "quad": [4, 12, 19], "vari": [4, 19], "myfunct": [4, 19], "fortran": [4, 5, 6, 9, 10, 11, 14, 19], "quadpack": [4, 19], "assum": [4, 6, 13, 19], "pretti": [4, 9, 19], "doc": [4, 6, 10, 13, 19], "05": [4, 19, 20, 21], "algebra": [4, 11, 19], "macro": [4, 19], "measur": [4, 11, 13, 19, 21], "dens": [4, 19], "thumb": [4, 19], "worth": [4, 11, 12, 19], "represent": [4, 19], "densiti": [4, 19], "csc": [4, 19], "spare": [4, 19], "bsr": [4, 19], "coo": [4, 19], "csr": [4, 19], "etc": [4, 5, 6, 9, 10, 11, 13, 14, 19, 20, 21], "fairli": [4, 14, 19], "lil": [4, 19], "dok": [4, 19], "sai": [4, 5, 9, 10, 11, 13, 16, 17, 19, 21], "insert": [4, 8, 19], "7m": [4, 19], "42m": [4, 19], "1600m": [4, 19], "toarrai": [4, 19], "64m": [4, 19], "time_spars": [4, 19], "matrix2": [4, 19], "time_ful": [4, 19], "3f": [4, 19], "wish": [4, 9], "hackmd": [4, 9], "anyth": [4, 9, 13, 19], "footnot": [4, 9], "rkdarst": [4, 9], "pcd": [4, 9], "dftlib": [4, 9], "numgrid": [4, 9], "dynbench": [4, 9], "vpython": [4, 9], "doesn": [4, 6, 7, 9, 10, 14, 15], "fine": [4, 9], "action": [4, 9], "workflow": [4, 9, 14, 20], "green": [4, 9], "correct": [4, 9, 11, 16], "clearli": [4, 9, 10, 13], "anymor": [4, 9], "ancient": [4, 9, 21], "pull": [4, 9, 13], "websit": [4, 9, 16, 21], "disappear": [4, 9], "everyon": [4, 5, 7, 8, 9, 16, 17], "somewher": [4, 9, 11, 13, 21], "improv": [4, 9, 14, 16], "isn": [4, 5, 6, 9], "pypi": [4, 9], "track": 4, "record": [4, 9, 11], "thesi": 4, "isol": [4, 12], "doi": 4, "pi": [4, 14, 15, 16], "stochast": [4, 14, 15], "algorithm": [4, 11, 14, 16, 19], "realli": [4, 5, 6, 13, 14], "1x1": [4, 14], "fall": [4, 14], "circl": [4, 14], "highlight": [4, 14], "sampl": [4, 8, 14, 15, 21], "trial": [4, 14, 15, 21], "number_in_circl": [4, 14, 15], "n_inside_circl": [4, 14, 15], "pool": [4, 14, 15], "threadpool": [4, 14, 15], "thread": [4, 14], "multithread": 4, "longer": [4, 9, 11, 14], "pure": [4, 10, 12, 14], "simultan": [4, 14], "cpu": [4, 10, 11, 14, 15], "node": [4, 14], "schedul": [4, 14], "permiss": [4, 14, 21], "upset": [4, 14], "slurm": [4, 14], "slurm_cpus_per_task": [4, 14], "whatev": [4, 7, 8, 13, 14], "hood": [4, 9, 14], "mpi4pi": [4, 14], "openmpi": [4, 14], "core": [4, 14], "mpiexec": [4, 14], "guess": [4, 14], "comm": [4, 14], "gather": [4, 14], "rank": [4, 10, 14], "_": [4, 14], "n_task": [4, 14], "7854305": [4, 14], "dart": [4, 14, 16], "10000000": [4, 14], "estim": [4, 14, 16], "141722": [4, 14], "spent": [4, 14], "parallelis": [4, 14], "mpirun": [4, 14], "mpi_test": [4, 14], "3926634": [4, 14], "3925910": [4, 14], "1410176": [4, 14], "twice": [4, 13, 14], "onto": [4, 14], "root": [4, 12, 14], "convention": [4, 14], "condit": [4, 10, 14, 17], "underscor": [4, 14], "unimport": [4, 14], "illustr": [4, 11, 14, 21], "usag": [4, 7, 10, 13, 14, 20], "path": [4, 5, 9, 12, 21], "subtract": [4, 10, 12], "www": [4, 14, 21], "boredapi": [4, 21], "j": [4, 21], "particip": [4, 21], "price": [4, 13, 21], "expressj": [4, 21], "3943506": [4, 21], "regard": [4, 21], "encod": [4, 21], "gzip": [4, 21], "identif": [4, 21], "agent": [4, 21], "password": [4, 12, 21], "token": [4, 21], "beauti": [4, 21], "soup": [4, 21], "bs4": [4, 21], "earli": [5, 6], "career": [5, 6, 7], "theoret": [5, 6], "themselv": [5, 6], "aren": [5, 6, 8, 9, 15, 19], "direct": [5, 6], "a2": [5, 6], "hasn": [5, 6], "comprehens": [5, 6, 9], "introduct": [5, 6, 11, 13, 14, 19], "mid": [5, 6], "late": [5, 6], "undergradu": [5, 6], "manner": [5, 6, 9], "prerequisit": 5, "crash": [5, 6], "Not": [5, 13], "multi": [5, 14], "pretend": 5, "fraction": 5, "intro": [5, 13], "outlin": 5, "somewhat": [5, 9], "conveni": [5, 7, 20], "spend": 5, "shell": [5, 7, 8, 20], "advanc": [5, 6, 8, 13, 19], "tip": 5, "trick": [5, 11], "principl": 5, "someon": [5, 7], "bore": 5, "appreci": 5, "broadcast": [5, 10], "goal": 5, "concept": [5, 10, 11], "behind": 5, "backbon": 5, "forth": 5, "seen": [5, 11], "format": [5, 6, 8, 9, 10, 13, 19, 20, 21], "bottleneck": [5, 14], "mess": [5, 12], "break": 5, "scale": [5, 6, 8, 14, 21], "least": [5, 8, 12, 17], "discuss": [5, 6, 8, 9], "bigger": 5, "pictur": 5, "off": [5, 11, 16], "carefulli": [5, 9], "explain": [5, 10, 12], "super": [5, 11], "short": [5, 6, 9, 13, 17, 20], "ill": 5, "half": 5, "webpag": [5, 9], "reusabl": [5, 9], "sustain": 5, "parallel": [5, 6, 20], "environ": [5, 8, 9, 12, 14], "materi": [5, 6, 13, 17], "exercis": [5, 6], "fourth": [5, 12], "admin": 5, "manag": [5, 6, 9, 11, 12, 14, 20], "conda": [5, 7], "prefix": [5, 12], "prepar": [5, 6, 9, 12], "acknowledg": 5, "virtualenv": 5, "hopefulli": 5, "tire": 5, "topic": [5, 9, 11], "involv": [5, 11, 14], "explicitli": [5, 20], "twitch": 6, "tv": 6, "appear": [6, 8], "playlist": 6, "util": 6, "numer": [6, 12, 13], "broader": [6, 9], "expert": [6, 8], "youtub": 6, "2022": 6, "1": [6, 7, 15, 17], "prereq": 6, "min": [6, 13], "60": 6, "15": [6, 10, 11, 16, 21], "45": [6, 8], "target": 6, "toward": [6, 12], "learner": [6, 14], "persona": 6, "particularli": [6, 9], "basi": 6, "excel": [6, 13], "glue": 6, "battl": [6, 19], "machin": [6, 12, 14], "deep": 6, "embrac": 6, "anybodi": 6, "bother": 6, "acquir": [6, 8], "licens": [6, 12], "extrem": 6, "todai": [6, 11], "certainli": 6, "critic": [6, 16], "offload": 6, "heavi": [6, 11, 16], "lift": [6, 11], "compil": [6, 9, 12, 14, 17, 19], "vectoriz": 6, "luck": 6, "albeit": 6, "matur": 6, "smaller": [6, 10, 11], "suitabl": 6, "rust": [6, 14], "haskel": 6, "came": 6, "septemb": 6, "ignor": 6, "until": [6, 14, 17], "reduc": [6, 14, 15], "transit": 6, "plan": 6, "adopt": 6, "unsupport": 6, "defacto": 6, "activ": [6, 7, 8, 9, 12], "unmaintain": 6, "compat": [6, 9, 10], "jann": [6, 17], "blomqvist": 6, "redesign": 6, "radovan": 6, "bast": 6, "richard": [6, 17], "darst": 6, "ann": [6, 17], "fouilloux": 6, "thor": 6, "wikfeldt": 6, "tester": 6, "advisor": [6, 8], "enrico": 6, "glerean": 6, "carpentri": 6, "conduct": 6, "topic_fold": 6, "polici": 6, "analyt": [6, 14], "logic": 6, "depth": 6, "3": [7, 12, 15, 16, 17, 19], "aanconda": 7, "proper": [7, 8, 11], "explor": [7, 8, 10, 11, 14], "lab": [7, 8, 9], "verifi": [7, 11], "hello": [7, 17], "world": [7, 14, 17], "portion": [7, 11], "encourag": 7, "vscode": 7, "arrow": 7, "ask": [7, 14, 21], "definit": [7, 11, 16, 17, 21], "hour": 7, "narr": 8, "role": [8, 10], "interleav": 8, "tour": [8, 9, 21], "divid": [8, 10, 14, 15], "primarili": 8, "bar": [8, 20], "style": [8, 20, 21], "previou": [8, 12, 15, 16, 20], "sentenc": 8, "commonmark": 8, "keyboard": 8, "shortcut": 8, "enter": [8, 12, 13], "esc": 8, "ctrl": 8, "shift": [8, 13], "alt": 8, "cut": 8, "convent": 8, "properti": 8, "runtim": [8, 14, 17], "ipython": [8, 9, 14, 21], "54": 8, "993": 8, "\u00b5": [8, 15], "maco": 8, "seq": 8, "echo": 8, "appli": [8, 11, 13, 14, 15, 21], "prototyp": [8, 20], "tend": 8, "phase": [8, 15], "stori": 8, "No": 8, "discoveri": 8, "gravit": 8, "wave": 8, "barrier": 8, "promot": 8, "modular": [8, 20], "hard": [8, 11, 20], "migrat": 8, "unit": 8, "nbval": 8, "control": [8, 10, 11, 14, 16, 20, 21], "nbdime": 8, "limit": [8, 12, 13], "irreproduc": 8, "bunch": 8, "downsid": 8, "balanc": 8, "power": [8, 10, 13, 21], "beyond": [9, 14], "necessarili": 9, "fact": [9, 13, 21], "heard": 9, "quot": 9, "classifi": 9, "articl": [9, 13, 19], "noth": [9, 12], "conform": 9, "math": [9, 11, 16, 19], "higher": [9, 14], "mayavi": 9, "pil": 9, "manipul": [9, 11], "pillow": 9, "statsmodel": 9, "sympi": 9, "symbol": [9, 10], "network": 9, "hdf5": 9, "dateutil": 9, "pytz": 9, "arithmet": [9, 10, 16], "timezon": 9, "databas": 9, "convers": [9, 20], "interpret": [9, 11, 14, 20], "hub": 9, "pytest": 9, "sphinx": 9, "spyder": 9, "pympi": 9, "messag": [9, 12, 14, 16, 20], "mpi": 9, "job": [9, 14], "cython": [9, 14], "numba": [9, 14], "intern": [9, 10], "dask": 9, "joblib": [9, 14], "embarrassingli": [9, 14], "ipyparallel": 9, "numexpr": 9, "irrelev": 9, "pytorch": 9, "nltk": 9, "natur": [9, 10], "contribut": [9, 13], "extend": [9, 10], "slowli": 9, "embed": 9, "primari": 9, "cffi": [9, 14], "ctype": [9, 14], "f2py": 9, "swig": 9, "boost": 9, "todo": 9, "mainstream": 9, "undetect": 9, "host": [9, 12], "site": 9, "gitlab": 9, "bitbucket": 9, "dealt": 9, "bug": [9, 14, 20], "report": [9, 20, 21], "citeabl": 9, "upcom": 9, "anyon": [9, 12], "seamlessli": 9, "detail": [9, 12, 13, 14, 19, 20], "except": 9, "seach": 10, "flexibl": [10, 16], "asdf": 10, "background": [10, 14, 21], "500": 10, "empti": 10, "len": 10, "ndarrai": 10, "2x3": 10, "1x2": 10, "2x2": 10, "evenli": 10, "bool": [10, 17], "occas": 10, "special": [10, 11, 12, 13, 15, 19], "instruct": [10, 11, 12], "greatli": 10, "outperform": 10, "regular": 10, "unlik": [10, 13], "mathemat": [10, 11, 16, 19], "clever": [10, 11], "cleverli": 10, "selector": 10, "benefit": [10, 20], "middl": [10, 11], "idx": 10, "criterion": 10, "three": [10, 13, 14, 21], "ref": 10, "smart": 10, "consist": [10, 11, 12], "expand": 10, "max": [10, 13, 21], "countless": 10, "invent": 10, "reli": 10, "bla": 10, "lapack": 10, "scientist": 10, "peculiar": 10, "underli": 11, "machineri": 11, "intend": 11, "audienc": 11, "amaz": 11, "impract": 11, "seriou": [11, 21], "yet": [11, 12, 13], "dive": 11, "scene": 11, "serv": [11, 14], "travi": 11, "oliph": 11, "creator": [11, 12], "race": 11, "against": [11, 16, 20, 21], "contest": 11, "stdlib": 11, "stdio": 11, "n_element": 11, "argc": 11, "char": 11, "malloc": 11, "sizeof": 11, "rand_max": 11, "printf": 11, "outsourc": 11, "intel": 11, "deriv": [11, 20], "subprogram": 11, "1979": 11, "effort": [11, 14], "word": 11, "norm": 11, "pythagorean": 11, "theorem": 11, "ldot": 11, "naiv": 11, "decent": 11, "rng": [11, 13], "seed": 11, "l": [11, 17], "linalg": [11, 14], "expens": 11, "cheap": 11, "surprisingli": 11, "closer": 11, "datastructur": 11, "diagon": 11, "20": [11, 16], "nbyte": 11, "nanosecond": 11, "1600": 11, "flat": 11, "fake": 11, "unravel": 11, "implic": 11, "properli": 11, "skip": [11, 13], "13440": 11, "2688": 11, "448": 11, "byte": [11, 17], "ahead": 11, "precis": [11, 17], "boi": 11, "mysteri": 11, "160000": 11, "accomplish": 11, "80000": 11, "40_000": 11, "5_000": 11, "40000": 11, "laid": 11, "inevit": 11, "transposit": 11, "ntranspos": 11, "whenev": [11, 20], "construct": [11, 21], "stai": 11, "pointer": 11, "buffer": 11, "__array_interface__": 11, "virtu": 11, "offset": 11, "48": 11, "attempt": 11, "succe": 11, "layout": [11, 13], "grow": 12, "cake": 12, "concret": 12, "lower_limit": 12, "upper_limit": 12, "__init__": [12, 17], "hold": 12, "arrang": 12, "2": [12, 15, 17], "setuptool": 12, "61": 12, "backend": 12, "build_meta": 12, "mynam": 12, "lastnam": 12, "pin": 12, "ana": 12, "twine": 12, "testpypi": 12, "dist": 12, "legaci": 12, "usernam": 12, "adapt": [12, 16], "solut": 12, "achiev": [12, 20], "confus": 12, "trend": 12, "flit": 12, "simplest": 12, "runtest": 12, "toler": 12, "recip": 12, "sh": 12, "bld": 12, "bat": 12, "anaconda3": 12, "win": 12, "py38_0": 12, "tar": 12, "bz2": 12, "sub": [12, 13], "platform": 12, "successfulli": 12, "anywher": 12, "channel": 12, "forg": 12, "led": 12, "infrastructur": 12, "guidelin": 12, "respect": [12, 13, 20], "bioconda": 12, "bioinformat": 12, "brief": 13, "train": 13, "flash": 13, "thorough": 13, "cookbook": 13, "flavor": 13, "kaggl": 13, "competit": 13, "index_col": 13, "ticket": 13, "sibl": 13, "spous": 13, "512": 13, "38": 13, "didn": 13, "zorder": 13, "sharex": 13, "hit": 13, "offer": [13, 17], "mark": [13, 21], "contextu": 13, "saw": 13, "tabular": 13, "compos": 13, "passang": 13, "datafil": 13, "iat": 13, "lam": 13, "ali": 13, "42": [13, 15, 16, 17], "is_passeng": 13, "70": 13, "margaret": 13, "nan": 13, "forward": 13, "backward": 13, "isna": 13, "mask": 13, "dropna": 13, "cabin": 13, "fillna": 13, "ffill": 13, "straightforward": 13, "thank": 13, "untidi": 13, "1500": 13, "runner": [13, 14], "400": 13, "800": 13, "128": 13, "1200": 13, "192": 13, "240": 13, "80": [13, 16], "160": 13, "300": [13, 21], "288": 13, "pair": [13, 21], "melt": 13, "id_var": 13, "value_var": 13, "var_nam": 13, "value_nam": 13, "filter": 13, "aggreg": 13, "relationship": 13, "opposit": 13, "exposit": [13, 14], "read_excel": 13, "to_excel": 13, "scratch": 13, "randn": 13, "abcd": 13, "dog": 13, "cat": [13, 21], "int32": 13, "sub1": 13, "sub2": 13, "sub3": 13, "concat": 13, "merg": 13, "act": 13, "sql": 13, "athlet": 13, "18": [13, 16], "21": 13, "annot": 13, "entri": [13, 20], "dave": 13, "women": 13, "children": 13, "child": 13, "younger": 13, "sex": 13, "chose": 13, "summar": 13, "cumsum": 13, "median": 13, "skew": 13, "var": 13, "wouldn": 13, "abil": 13, "organis": 13, "nobelpr": 13, "unfortun": 13, "cc": 13, "asid": 13, "di": 13, "messi": 13, "accessor": 13, "weekdai": 13, "approxim": [13, 14], "boxplot": 13, "eval": 13, "nrow": 13, "ncol": 13, "randomst": 13, "df1": 13, "df2": 13, "df3": 13, "df4": 13, "80m": 13, "40m": 13, "fibo": 13, "overhead": 13, "recurs": 13, "rais": 13, "notimplementederror": 13, "elif": [13, 17], "memo": 13, "rabbit": 13, "99": 13, "functool": 13, "lru_cach": 13, "fib": 13, "precisis": 13, "cap": 13, "unbound": 13, "erron": 13, "processor": 14, "mechan": 14, "profil": 14, "spot": 14, "acceler": 14, "hardwar": 14, "supercomput": 14, "synchron": 14, "openmp": 14, "segment": 14, "wrong": 14, "fascin": 14, "invest": 14, "video": 14, "raymond": 14, "hetting": 14, "entertain": 14, "lock": 14, "glanc": 14, "circumv": [14, 17], "symmetr": 14, "invers": 14, "4000": 14, "time_start": 14, "inv": 14, "time_end": 14, "invert": 14, "forc": [14, 20], "omp_num_thread": 14, "mkl_num_thread": 14, "significantli": 14, "shouldn": 14, "unix": 14, "embark": 14, "oppos": 14, "map": [14, 15], "paradigm": 14, "36": 14, "equival": [14, 21], "fortun": 14, "multiprocesss": 14, "introductori": 14, "rantahar": 14, "pdc": 14, "blog": 14, "gentl": 14, "kth": 14, "se": 14, "08": 14, "comm_world": 14, "get_siz": 14, "get_rank": 14, "t0": 14, "perf_count": 14, "pi_estim": [14, 16], "nnumber": 14, "workaround": 14, "foreign": 14, "primit": 14, "pybind11": 14, "iso_c_bind": 14, "pyo3": 14, "rout": 14, "Of": 14, "overcom": 14, "ml": 14, "chunk": 14, "lazi": 14, "proce": 14, "stream": 14, "fashion": 14, "da": 14, "redund": 14, "concurr": [14, 20], "safe": 14, "scalabl": 14, "highli": 14, "luckili": 14, "296": 15, "751": 15, "14114": 15, "147": 15, "59": 15, "n_sum": 15, "n_inside_circle_sum": 15, "141364": 15, "timeitresult": 15, "140572": 15, "regardless": 15, "pick": 16, "invalid": 16, "syntaxerror": 16, "programm": 16, "ruff": 16, "flake8": 16, "lint_exampl": 16, "31": [16, 20, 21], "e0001": 16, "unmatch": 16, "unknown": [16, 19], "bracket": 16, "c0114": 16, "e0602": 16, "w0611": 16, "unus": 16, "00": 16, "suggest": 16, "convet": 16, "cxxxx": 16, "exxxx": 16, "flag": [16, 20], "unnecessari": [16, 20], "wxxx": 16, "overal": 16, "correctli": 16, "deduc": 16, "stamement": 16, "increas": 16, "myvari": 16, "lowercas": 16, "camel": 16, "pascal": 16, "my_vari": 16, "snake": 16, "freedom": 16, "legibl": 16, "pep": 16, "257": 16, "checker": 16, "modif": 16, "yapf": 16, "pep8": 16, "code_style_exampl": 16, "thrower": 16, "pi_numb": 16, "8d": 16, "e271": 16, "keyword": [16, 17, 21], "e272": 16, "e302": 16, "blank": 16, "n802": 16, "n806": 16, "17": [16, 21], "e222": 16, "e251": 16, "e201": 16, "whitespac": 16, "e202": 16, "e231": 16, "e225": 16, "69": 16, "uncompromis": 16, "formatt": 16, "foundat": 16, "cleaner": 16, "e501": 16, "79": 16, "argu": 16, "fmt": 16, "based_on_styl": 16, "arithmetic_precedence_ind": 16, "diff": 16, "reformat": 16, "massiv": 16, "disabl": 16, "isort": 16, "jupyterlab_code_formatt": 16, "perfectli": 17, "engag": 17, "3j": 17, "unicod": 17, "q": 17, "capabl": [17, 21], "123": 17, "456": 17, "cherri": 17, "dict": [17, 20, 21], "met": 17, "sequenc": 17, "iter": 17, "enumer": 17, "ii": 17, "self": 17, "_name": 17, "strongli": [17, 20], "dynam": 17, "strong": 17, "roughli": 17, "invok": 17, "behavior": 17, "redefin": 17, "jargon": 17, "associ": 17, "rvalu": 17, "lvalu": 17, "reifi": 17, "datacamp": 18, "briefli": 19, "bessel": 19, "gamma": 19, "interpol": 19, "fourier": 19, "transform": 19, "fft": 19, "signal": 19, "market": 19, "mat": 19, "ridicul": 19, "standpoint": 19, "somedai": 19, "eventu": 19, "product": 19, "admit": 19, "streamlin": 20, "hardli": 20, "willing": 20, "rerun": 20, "parameter": 20, "papermil": 20, "attract": 20, "soon": 20, "your_notebook_nam": 20, "callabl": 20, "hpc": 20, "startup": 20, "append": [20, 21], "my_script": 20, "output_file_nam": 20, "spring_in_tapiola": 20, "03": [20, 21], "brittl": 20, "robust": 20, "doctopt": 20, "detect": 20, "2000": 20, "metavar": 20, "subject": 20, "birth": 20, "birthdai": 20, "exit": 20, "weather_tapiola": 20, "temperature_tapiola": 20, "temperature_tapiola_dec": 20, "temperature_tapiola_feb": 20, "temperature_cairo": 20, "pattern": 20, "got": 20, "rain_in_tapiola": 20, "rainfal": 20, "rrr": 20, "scroll": 20, "inconveni": 20, "precipit": 20, "translat": 20, "rain_in_cairo": 20, "jupytext": 20, "emb": 21, "readthedoc": 21, "latest": 21, "homepag": 21, "ifram": 21, "requests_documentation_url": 21, "connect": 21, "cycl": 21, "authent": 21, "apipheni": 21, "catfact": 21, "ninja": 21, "endpoint": 21, "response_cont": 21, "rub": 21, "affection": 21, "territori": 21, "scent": 21, "gland": 21, "face": 21, "tail": 21, "paw": 21, "u2019": 21, "174": 21, "decod": 21, "response_json": 21, "beforehand": 21, "finnish": 21, "hipolab": 21, "finland": 21, "domain": 21, "abo": 21, "alpha_two_cod": 21, "provinc": 21, "akademi": 21, "web_pag": 21, "cou": 21, "central": 21, "ostrobothnia": 21, "param": 21, "prone": 21, "bubbl": 21, "bath": 21, "relax": 21, "2581372": 21, "narrow": 21, "kotlin": 21, "kotlinlang": 21, "3950821": 21, "minpric": 21, "maxpric": 21, "haven": 21, "6081071": 21, "deflat": 21, "aliv": 21, "cowboi": 21, "heroku": 21, "nel": 21, "max_ag": 21, "3600": 21, "1699510623": 21, "sid": 21, "67ff5de4": 21, "ad2b": 21, "4112": 21, "9289": 21, "cf96be89ef": 21, "sxhy5ewfcrcsqeno70drfoaoyy2k5kniad": 21, "2fe": 21, "2fthxx": 21, "report_to": 21, "success_fract": 21, "005": 21, "failure_fract": 21, "response_head": 21, "charset": 21, "175": 21, "etag": 21, "af": 21, "votohlohcknisxut": 21, "o7qfbzgp": 21, "09": 21, "nov": 21, "2023": 21, "gmt": 21, "vegur": 21, "br": 21, "restrict": 21, "imgur": 21, "doctyp": 21, "equiv": 21, "viewport": 21, "width": 21, "devic": 21, "css": 21, "bodi": 21, "f0f0f2": 21, "margin": 21, "pad": 21, "ui": 21, "blinkmacsystemfont": 21, "sego": 21, "san": 21, "helvetica": 21, "neue": 21, "arial": 21, "serif": 21, "div": 21, "600px": 21, "5em": 21, "auto": 21, "2em": 21, "fdfdff": 21, "radiu": 21, "box": 21, "shadow": 21, "2px": 21, "3px": 21, "7px": 21, "rgba": 21, "02": 21, "38488f": 21, "decor": 21, "media": 21, "700px": 21, "h1": 21, "literatur": 21, "prior": 21, "coordin": 21, "href": 21, "iana": 21, "beautifulsoup": 21, "find_al": 21, "get_text": 21, "longitud": 21, "jsonlin": 21, "excess": 21, "hundr": 21, "thousand": 21, "writer": 21, "jsonl": 21, "sleep": 21, "reader": 21, "obj": 21, "egypt": 21, "mummi": 21, "embalm": 21, "mice": 21, "tomb": 21, "citi": 21, "158": 21, "whisker": 21, "air": 21, "pressur": 21, "134": 21, "nose": 21, "fingerprint": 21, "51": 21}, "objects": {}, "objtypes": {}, "objnames": {}, "titleterms": {"binder": [0, 4], "question": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "object": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 20, 21], "why": [0, 2, 6, 8, 20], "i": [0, 1, 6, 8, 9, 10], "sometim": 0, "enough": 0, "share": [0, 4, 12], "your": [0, 3, 4, 9, 16], "code": [0, 4, 8, 9, 16], "exercis": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 16, 19, 20, 21], "1": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 16, 19, 20, 21], "discuss": [0, 2, 3, 4, 20], "better": [0, 4], "strategi": [0, 4], "than": [0, 4], "onli": [0, 4], "10": [0, 4, 6], "min": [0, 2, 3, 4], "comput": [0, 6, 9], "environ": [0, 3, 4, 7], "demo": [0, 4, 12], "2": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 13, 14, 16, 19, 20, 21], "make": [0, 4], "notebook": [0, 4, 20], "reproduc": [0, 2, 4], "anyon": [0, 4], "15": [0, 2, 3, 4], "how": [0, 3], "can": [0, 1, 3, 11], "get": [0, 2, 8, 13], "doi": 0, "from": [0, 3, 4, 12, 14, 20, 21], "zenodo": [0, 4], "3": [0, 1, 2, 3, 4, 6, 8, 10, 11, 13, 14, 20, 21], "link": [0, 4, 21], "github": [0, 4], "repositori": [0, 4], "option": [0, 3, 4, 7, 14, 20], "creat": [0, 3, 4, 10], "4": [0, 1, 3, 4, 10], "keypoint": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21], "data": [1, 2, 4, 9, 11, 13, 21], "format": [1, 4, 16], "panda": [1, 2, 4, 13], "numpi": [1, 4, 10, 11], "what": [1, 8, 9, 10, 13, 19], "type": [1, 10, 17], "v": [1, 3, 6], "structur": [1, 17], "file": [1, 3, 7, 20], "look": 1, "store": 1, "arbitrari": 1, "python": [1, 3, 4, 6, 7, 9, 12, 15, 17, 20, 21], "pickl": 1, "kei": 1, "featur": 1, "solut": [1, 2, 4, 8, 10, 11, 13, 14, 15, 16, 19, 20], "tidi": [1, 13], "csv": 1, "comma": 1, "separ": 1, "valu": 1, "reduc": 1, "precis": 1, "feather": 1, "requir": [1, 3, 7, 21], "addit": [1, 10], "packag": [1, 3, 4, 9, 12], "parquet": 1, "arrai": [1, 10], "npy": 1, "hdf5": 1, "hierarch": 1, "version": [1, 3], "5": [1, 3, 4, 10], "netcdf4": 1, "network": 1, "common": 1, "form": 1, "other": [1, 7, 9, 10, 14, 16], "json": 1, "javascript": 1, "notat": 1, "excel": 1, "graph": 1, "adjenc": 1, "list": [1, 4, 7, 13, 20], "gt": 1, "graphml": 1, "etc": 1, "benefit": 1, "binari": 1, "thing": [1, 11], "rememb": 1, "see": [1, 3, 6, 7, 8, 9, 10, 11, 14, 19], "also": [1, 3, 6, 7, 8, 9, 10, 11, 14, 19], "visual": [2, 4], "matplotlib": [2, 4], "repeat": 2, "ar": 2, "we": 2, "start": [2, 8], "extend": [2, 4], "previou": [2, 4], "exampl": [2, 4, 11, 14], "color": 2, "ha": 2, "two": 2, "differ": [2, 4, 21], "interfac": [2, 9], "do": [2, 3, 15], "emphas": 2, "thi": 2, "style": [2, 16], "custom": [2, 4], "plot": [2, 4, 9], "log": [2, 4], "scale": [2, 4], "prepar": [2, 4], "public": [2, 3, 4], "adapt": [2, 4], "galleri": [2, 4], "an": [2, 3, 4, 7, 10, 11], "explor": [2, 4, 13], "datafram": [2, 4, 13], "depend": [3, 4], "manag": [3, 4], "you": 3, "track": 3, "project": [3, 12], "pypi": [3, 12], "The": [3, 9, 11], "index": [3, 10], "ana": 3, "conda": [3, 4, 12], "anaconda": 3, "miniconda": [3, 7], "mamba": 3, "cloud": 3, "forg": 3, "miniforg": 3, "isol": 3, "activ": [3, 4, 21], "versu": [3, 4, 11], "sourc": [3, 4], "virtualenv": [3, 4], "problem": [3, 16], "might": 3, "happen": 3, "manual": 3, "instal": [3, 7, 12], "record": 3, "channel": 3, "put": 3, "too": 3, "strict": 3, "counter": 3, "product": [3, 4, 16], "freez": [3, 4], "hint": 3, "updat": 3, "commun": 3, "part": 3, "report": 3, "thesi": 3, "pin": 3, "creator": 3, "full": 4, "jupyt": [4, 8, 20], "advanc": [4, 7, 10, 11, 14, 21], "analyz": [4, 13], "titan": [4, 13], "passeng": [4, 13], "dataset": [4, 13], "nobel": [4, 13], "prize": [4, 13], "tool": [4, 7, 9, 12, 16], "us": [4, 16, 19, 20], "pylint": [4, 16], "black": [4, 16], "script": [4, 20], "scipi": [4, 9, 19], "librari": [4, 9, 11], "ecosystem": [4, 9], "work": [4, 9, 13], "evalu": [4, 9], "parallel": [4, 9, 14, 15], "program": [4, 14], "multiprocess": [4, 14, 15], "run": [4, 8, 14], "cluster": [4, 14], "mpi": [4, 14], "dask": [4, 14], "web": [4, 21], "api": [4, 21], "webapi": [4, 21], "request": [4, 21], "suggest": [4, 21], "bore": [4, 21], "examin": [4, 21], "respons": [4, 21], "header": [4, 21], "scrape": [4, 21], "webpag": [4, 21], "instructor": 5, "": [5, 9, 13, 19], "guid": 5, "learner": 5, "persona": 5, "about": 5, "each": 5, "section": 5, "scientif": 6, "attend": 6, "cours": 6, "7": 6, "novemb": 6, "2023": 6, "prerequisit": [6, 12], "video": [6, 7], "archiv": 6, "q": 6, "A": [6, 11, 13], "refer": [6, 18], "who": 6, "motiv": 6, "credit": 6, "softwar": 7, "gener": 7, "instruct": 7, "jupyterlab": 7, "verif": 7, "watch": 7, "text": 7, "editor": 7, "command": [7, 20], "line": [7, 20], "wai": 7, "access": 7, "zoom": 7, "need": 7, "help": [7, 13], "glossari": 9, "core": 9, "numer": [9, 19], "analysi": 9, "import": 9, "interact": 9, "human": 9, "speed": 9, "up": [9, 21], "machin": 9, "learn": 9, "connect": 9, "languag": [9, 14], "reus": 9, "reuseabl": 9, "next": 9, "math": 10, "vector": 10, "slice": 10, "oper": 10, "linear": 10, "algebra": 10, "realli": 11, "fast": 11, "behind": 11, "curtain": 11, "mkl": 11, "bla": 11, "tri": 11, "avoid": 11, "copi": 11, "matrix": 11, "transpos": 11, "ndarrai": 11, "expos": 11, "stride": 11, "anoth": 11, "reshap": 11, "view": 11, "organ": 12, "test": 12, "local": 12, "pip": 12, "via": 12, "simplifi": 12, "build": 12, "skeleton": 12, "remark": 12, "locat": 12, "scratch": 12, "publish": 12, "quick": [13, 18], "preview": 13, "time": 13, "seri": 13, "superpow": 13, "beyond": 13, "basic": 13, "mode": 14, "multithread": [14, 15], "gil": 14, "coupl": 14, "task": 14, "queue": 14, "org": 14, "thread": 15, "futur": 15, "idea": 15, "spot": 16, "linter": 16, "enforc": 16, "consist": 16, "write": 16, "own": 16, "kind": 16, "integr": [16, 19], "git": 16, "nice": 16, "introduct": 17, "scalar": 17, "collect": 17, "control": 17, "function": 17, "class": 17, "system": 17, "spars": 19, "matric": 19, "save": [20, 21], "argument": 20, "sy": 20, "argv": 20, "pars": 20, "argpars": 20, "load": 20, "larger": 20, "config": 20, "further": 20, "read": 20, "retriev": 21, "which": 21, "paramet": 21, "after": 21, "disk": 21, "wrap": 21}, "envversion": {"sphinx.domains.c": 2, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 8, "sphinx.domains.index": 1, "sphinx.domains.javascript": 2, "sphinx.domains.math": 2, "sphinx.domains.python": 3, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.todo": 2, "sphinx.ext.intersphinx": 1, "sphinx": 57}, "alltitles": {"Binder": [[0, "binder"], [4, "binder"]], "Questions": [[0, "questions-0"], [1, "questions-0"], [2, "questions-0"], [3, "questions-0"], [8, "questions-0"], [9, "questions-0"], [10, "questions-0"], [11, "questions-0"], [12, "questions-0"], [13, "questions-0"], [14, "questions-0"], [16, "questions-0"], [17, "questions-0"], [19, "questions-0"], [20, "questions-0"], [21, "questions-0"]], "Objectives": [[0, "objectives-0"], [1, "objectives-0"], [2, "objectives-0"], [3, "objectives-0"], [8, "objectives-0"], [9, "objectives-0"], [10, "objectives-0"], [11, "objectives-0"], [12, "objectives-0"], [13, "objectives-0"], [14, "objectives-0"], [16, "objectives-0"], [17, "objectives-0"], [19, "objectives-0"], [20, "objectives-0"], [21, "objectives-0"]], "Why is it sometimes not enough to share your code?": [[0, "why-is-it-sometimes-not-enough-to-share-your-code"]], "Exercise 1": [[0, "exercise-1"], [1, "exercise-1"], [11, "exercise-1"], [16, "exercise-1"]], "Binder-1: Discuss better strategies than only code sharing (10 min)": [[0, "exercise-0"], [4, "exercise-0"]], "Sharing a computing environment with Binder": [[0, "sharing-a-computing-environment-with-binder"]], "Binder exercise/demo": [[0, "binder-exercise-demo"]], "Binder-2: Exercise/demo: Make your notebooks reproducible by anyone (15 min)": [[0, "exercise-1"], [4, "exercise-1"]], "How can I get a DOI from Zenodo?": [[0, "how-can-i-get-a-doi-from-zenodo"]], "Binder-3: Link a Github repository with Zenodo (optional)": [[0, "exercise-2"], [4, "exercise-2"]], "Create a Binder link for your Zenodo DOI": [[0, "create-a-binder-link-for-your-zenodo-doi"]], "Binder-4: Link Binder with Zenodo (10 min)": [[0, "exercise-3"], [4, "exercise-3"]], "Keypoints": [[0, "keypoints-0"], [1, "keypoints-0"], [2, "keypoints-0"], [3, "keypoints-0"], [8, "keypoints-0"], [9, "keypoints-0"], [10, "keypoints-0"], [11, "keypoints-0"], [12, "keypoints-0"], [13, "keypoints-0"], [14, "keypoints-0"], [16, "keypoints-0"], [17, "keypoints-0"], [19, "keypoints-0"], [21, "keypoints-0"]], "Data formats with Pandas and Numpy": [[1, "data-formats-with-pandas-and-numpy"], [4, "data-formats-with-pandas-and-numpy"]], "What is a data format?": [[1, "what-is-a-data-format"]], "Data type vs. data structure vs. file format": [[1, null]], "What to look for in a file format?": [[1, "what-to-look-for-in-a-file-format"]], "Storing arbitrary Python objects": [[1, "storing-arbitrary-python-objects"]], "Pickle": [[1, "pickle"]], "Key features": [[1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null]], "Exercise": [[1, "exercise-0"], [1, "exercise-1"], [1, "exercise-2"], [4, "exercise-0"], [4, "exercise-1"], [4, "exercise-2"], [4, "exercise-0"], [4, "exercise-1"], [19, "exercise-0"], [19, "exercise-1"]], "Solution": [[1, "solution-0"], [1, "solution-1"], [1, "solution-2"], [2, "solution-0"], [2, "solution-1"], [2, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [13, "solution-0"], [13, "solution-1"], [13, "solution-2"], [14, "solution-0"], [14, "solution-1"], [14, "solution-2"], [16, "solution-0"], [16, "solution-1"], [19, "solution-0"], [19, "solution-1"], [20, "solution-0"], [20, "solution-1"]], "Storing tidy data": [[1, "storing-tidy-data"]], "CSV (comma-separated values)": [[1, "csv-comma-separated-values"]], "Storing data in CSVs can reduce data precision": [[1, null]], "Feather": [[1, "feather"]], "Requires additional packages": [[1, null], [1, null], [1, null], [1, null]], "Parquet": [[1, "parquet"]], "Exercise 2": [[1, "exercise-2"], [11, "exercise-2"], [16, "exercise-2"]], "Storing array data": [[1, "storing-array-data"]], "npy (numpy array format)": [[1, "npy-numpy-array-format"]], "HDF5 (Hierarchical Data Format version 5)": [[1, "hdf5-hierarchical-data-format-version-5"]], "NetCDF4 (Network Common Data Form version 4)": [[1, "netcdf4-network-common-data-form-version-4"]], "Exercise 3": [[1, "exercise-3"]], "Other file formats": [[1, "other-file-formats"]], "JSON (JavaScript Object Notation)": [[1, "json-javascript-object-notation"]], "Excel": [[1, "excel"]], "Graph formats (adjency lists, gt, GraphML etc.)": [[1, "graph-formats-adjency-lists-gt-graphml-etc"]], "Benefits of binary file formats": [[1, "benefits-of-binary-file-formats"]], "Things to remember": [[1, "things-to-remember"]], "See also": [[1, "see-also"], [3, "see-also"], [6, "see-also"], [7, "see-also"], [8, "see-also"], [9, "see-also"], [10, "see-also"], [11, "see-also"], [14, "see-also"], [19, "see-also"]], "Data visualization with Matplotlib": [[2, "data-visualization-with-matplotlib"], [4, "data-visualization-with-matplotlib"]], "Repeatability/reproducibility": [[2, "repeatability-reproducibility"]], "Why are we starting with Matplotlib?": [[2, "why-are-we-starting-with-matplotlib"]], "Getting started with Matplotlib": [[2, "getting-started-with-matplotlib"]], "Exercise: Matplotlib": [[2, "exercise-matplotlib"]], "Exercise Matplotlib-1: extend the previous example (15 min)": [[2, "exercise-0"], [4, "exercise-0"]], "Why these colors?": [[2, "discussion-0"]], "Matplotlib has two different interfaces": [[2, "matplotlib-has-two-different-interfaces"]], "Why do we emphasize this?": [[2, "discussion-1"]], "Styling and customizing plots": [[2, "styling-and-customizing-plots"]], "Exercises: Styling and customization": [[2, "exercises-styling-and-customization"]], "Exercise Customization-1: log scale in Matplotlib (15 min)": [[2, "exercise-1"], [4, "exercise-1"]], "Exercise Customization-2: preparing a plot for publication (15 min)": [[2, "exercise-2"], [4, "exercise-2"]], "Exercise Customization-3: adapting a gallery example": [[2, "exercise-3"], [4, "exercise-3"]], "An example exploration": [[2, "solution-3"], [4, "solution-3"]], "Discussion": [[2, "discussion-2"], [20, "discussion-0"], [20, "discussion-1"]], "Matplotlib and pandas DataFrames": [[2, "matplotlib-and-pandas-dataframes"]], "Dependency management": [[3, "dependency-management"], [4, "dependency-management"]], "How do you track dependencies of your project?": [[3, "how-do-you-track-dependencies-of-your-project"]], "Exercises 1": [[3, "exercises-1"], [8, "exercises-1"], [10, "exercises-1"], [12, "exercises-1"], [13, "exercises-1"], [20, "exercises-1"], [21, "exercises-1"]], "Dependencies-1: Discuss dependency management (5 min)": [[3, "exercise-0"], [4, "exercise-0"]], "PyPI (The Python Package Index) and (Ana)conda": [[3, "pypi-the-python-package-index-and-ana-conda"]], "PyPI": [[3, null]], "Conda": [[3, null]], "Anaconda vs. miniconda vs. conda vs. mamba vs. Anaconda Cloud vs. conda-forge vs. miniforge": [[3, null]], "Creating isolated environments": [[3, "creating-isolated-environments"]], "Exercises 2": [[3, "exercises-2"], [8, "exercises-2"], [10, "exercises-2"], [13, "exercises-2"], [20, "exercises-2"], [21, "exercises-2"]], "Dependencies-2: Create a conda environment (15 min)": [[3, "exercise-1"], [4, "exercise-1"]], "conda activate versus source activate": [[3, "callout-0"], [4, "callout-0"]], "Exercises 3": [[3, "exercises-3"], [8, "exercises-3"], [10, "exercises-3"], [11, "exercises-3"], [13, "exercises-3"], [21, "exercises-3"]], "Dependencies-3: Create a virtualenv (15 min, optional)": [[3, "exercise-2"], [4, "exercise-2"]], "Problems that might happen with manual installation": [[3, "problems-that-might-happen-with-manual-installation"]], "Recording dependencies": [[3, "recording-dependencies"]], "Conda channels": [[3, "callout-1"]], "Putting too strict requirements can be counter-productive": [[3, null]], "Dependencies 4": [[3, "dependencies-4"]], "Dependencies-4: Freeze an environment (15 min)": [[3, "exercise-3"], [4, "exercise-3"]], "Hint: Updating packages from dependency files": [[3, null]], "How to communicate the dependencies as part of a report/thesis/publication": [[3, "how-to-communicate-the-dependencies-as-part-of-a-report-thesis-publication"]], "Version pinning for package creators": [[3, "version-pinning-for-package-creators"]], "List of exercises": [[4, "list-of-exercises"]], "Full list": [[4, "full-list"]], "Jupyter": [[4, "jupyter"], [8, "jupyter"]], "Exercises: Jupyter-1": [[4, "exercise-0"], [8, "exercise-0"]], "Exercises: Jupyter-2": [[4, "exercise-1"], [8, "exercise-1"]], "Solutions: Jupyter-2": [[4, "solution-0"], [8, "solution-0"]], "Exercises: Jupyter-3": [[4, "exercise-2"], [8, "exercise-2"]], "NumPy": [[4, "numpy"], [10, "numpy"]], "Exercises: Numpy-1": [[4, "exercise-0"], [10, "exercise-0"]], "Solutions: Numpy-1": [[4, "solution-0"], [10, "solution-0"]], "Exercises: Numpy-2": [[4, "exercise-1"], [10, "exercise-1"]], "Solutions: Numpy-2": [[4, "solution-1"], [10, "solution-1"]], "Exercise: Numpy-3": [[4, "exercise-2"], [10, "exercise-2"]], "Solution: Numpy-3": [[4, "solution-2"], [10, "solution-2"]], "Exercises: Numpy-4": [[4, "exercise-3"], [10, "exercise-3"]], "Solution: Numpy-4": [[4, "solution-3"], [10, "solution-3"]], "Numpy-5": [[4, "exercise-4"], [10, "exercise-4"]], "Solution Numpy-5": [[4, "solution-4"], [10, "solution-4"]], "Advanced NumPy": [[4, "advanced-numpy"], [11, "advanced-numpy"]], "Exercises: Numpy-Advanced-1": [[4, "exercise-0"], [11, "exercise-0"]], "Solutions: Numpy-Advanced-1": [[4, "solution-0"], [11, "solution-0"]], "Exercises: Numpy-Advanced-2": [[4, "exercise-1"], [11, "exercise-1"]], "Solutions: Numpy-Advanced-2": [[4, "solution-1"], [11, "solution-1"]], "Exercises: Numpy-Advanced-3": [[4, "exercise-2"], [11, "exercise-2"]], "Solutions: Numpy-Advanced-3": [[4, "solution-2"], [11, "solution-2"]], "Pandas": [[4, "pandas"], [13, "pandas"]], "Exploring dataframes": [[4, "exercise-0"], [13, "exercise-0"]], "Analyze the Titanic passenger list dataset": [[4, "exercise-1"], [13, "exercise-1"]], "Analyze the Nobel prize dataset": [[4, "exercise-2"], [13, "exercise-2"]], "Productivity tools": [[4, "productivity-tools"], [16, "productivity-tools"]], "Using Pylint": [[4, "exercise-0"], [16, "exercise-0"]], "Using black to format code": [[4, "exercise-1"], [16, "exercise-1"]], "Scripts": [[4, "scripts"], [20, "scripts"]], "Scripts-1": [[4, "exercise-0"], [20, "exercise-0"]], "Scripts-2": [[4, "exercise-1"], [20, "exercise-1"]], "Scripts-3": [[4, "exercise-2"], [20, "exercise-2"]], "SciPy": [[4, "scipy"], [19, "scipy"]], "Library ecosystem": [[4, "library-ecosystem"], [9, "library-ecosystem"]], "Libraries 1.1: Libraries in your work": [[4, "exercise-0"], [9, "exercise-0"]], "Libraries 1.1": [[4, "solution-0"], [9, "solution-0"]], "Libraries 1.2: Evaluating packages": [[4, "exercise-1"], [9, "exercise-1"]], "Libraries 1.2": [[4, "solution-1"], [9, "solution-1"]], "Parallel programming": [[4, "parallel-programming"], [14, "parallel-programming"]], "Parallel-1, multiprocessing": [[4, "exercise-0"], [14, "exercise-0"]], "(advanced) Parallel-2 Running on a cluster": [[4, "exercise-1"], [14, "exercise-1"]], "Parallel-3, MPI": [[4, "exercise-2"], [14, "exercise-2"]], "Dask-Examples (optional)": [[4, "exercise-3"], [14, "exercise-3"]], "Packaging": [[4, "packaging"], [12, "packaging"]], "Packaging-1": [[4, "exercise-0"], [12, "exercise-0"]], "Web APIs with Python": [[4, "web-apis-with-python"], [21, "web-apis-with-python"]], "Exercise WebAPIs-1: Request different activity suggestions from the Bored API": [[4, "exercise-0"], [21, "exercise-0"]], "Exercise WebAPIs-2: Examine request and response headers": [[4, "exercise-1"], [21, "exercise-1"]], "Exercise WebAPIs-3: Scrape links from a webpage (Advanced)": [[4, "exercise-2"], [21, "exercise-2"]], "Instructor\u2019s guide": [[5, "instructor-s-guide"]], "Learner personas": [[5, "learner-personas"]], "About each section": [[5, "about-each-section"]], "Python for Scientific Computing": [[6, "python-for-scientific-computing"]], "Attending the course 7-10.november.2023?": [[6, null]], "Prerequisites": [[6, "prerequisites-0"], [12, "callout-0"]], "Videos and archived Q&A": [[6, null]], "Reference": [[6, null]], "Who is the course for?": [[6, "who-is-the-course-for"]], "Motivation": [[6, "motivation"]], "Why Python": [[6, "why-python"]], "Why not Python for Scientific Computing": [[6, "why-not-python-for-scientific-computing"]], "Python 2 vs Python 3": [[6, "python-2-vs-python-3"]], "Credits": [[6, "credits"]], "Software installation": [[7, "software-installation"]], "Generic list of tools required": [[7, "generic-list-of-tools-required"]], "Generic instructions with miniconda and an environment file (advanced)": [[7, null]], "Python": [[7, "python"]], "Other options": [[7, null]], "JupyterLab": [[7, "jupyterlab"]], "Verification of Python and JupyterLab": [[7, "verification-of-python-and-jupyterlab"]], "Watch the video": [[7, null]], "Text editor": [[7, "text-editor"]], "Other editors": [[7, null]], "Command line": [[7, "command-line"]], "Other ways to access the command line": [[7, null]], "Verification of the command line": [[7, "verification-of-the-command-line"]], "Zoom": [[7, "zoom"]], "Need help?": [[7, "need-help"]], "What is Jupyter?": [[8, "what-is-jupyter"]], "Getting started with Jupyter": [[8, "getting-started-with-jupyter"]], "Running code in Jupyter": [[8, "running-code-in-jupyter"]], "Why Jupyter?": [[8, "why-jupyter"]], "Why not Jupyter?": [[8, "why-not-jupyter"]], "Glossary": [[9, "glossary"]], "The Python/SciPy ecosystem": [[9, "the-python-scipy-ecosystem"]], "Core numerics libraries": [[9, "core-numerics-libraries"]], "Plotting": [[9, "plotting"]], "Data analysis and other important core packages": [[9, "data-analysis-and-other-important-core-packages"]], "Interactive computing and human interface": [[9, "interactive-computing-and-human-interface"]], "Speeding up code and parallelism": [[9, "speeding-up-code-and-parallelism"]], "Machine learning": [[9, "machine-learning"]], "Connecting Python to other languages": [[9, "connecting-python-to-other-languages"]], "Tools for interfacing with other languages": [[9, "tools-for-interfacing-with-other-languages"]], "Evaluating Python packages for reuse": [[9, "evaluating-python-packages-for-reuse"]], "Is your work reuseable?": [[9, "is-your-work-reuseable"]], "What\u2019s next?": [[9, "what-s-next"]], "Exercises": [[9, "exercises"]], "What is an array?": [[10, "what-is-an-array"]], "Creating arrays": [[10, "creating-arrays"]], "Array maths and vectorization": [[10, "array-maths-and-vectorization"]], "Indexing and Slicing": [[10, "indexing-and-slicing"]], "Types of operations": [[10, "types-of-operations"]], "Exercises 4": [[10, "exercises-4"]], "Linear algebra and other advanced math": [[10, "linear-algebra-and-other-advanced-math"]], "Additional exercises": [[10, "additional-exercises"]], "NumPy can be really fast": [[11, "numpy-can-be-really-fast"]], "The libraries behind the curtain: MKL and BLAS": [[11, "the-libraries-behind-the-curtain-mkl-and-blas"]], "NumPy tries to avoid copying data": [[11, "numpy-tries-to-avoid-copying-data"]], "An example: matrix transpose": [[11, "an-example-matrix-transpose"]], "The ndarray exposed": [[11, "the-ndarray-exposed"]], "Strides": [[11, "strides"]], "Another example: reshaping": [[11, "another-example-reshaping"]], "A fast thing + a fast thing = a fast thing?": [[11, "a-fast-thing-a-fast-thing-a-fast-thing"]], "Copy versus view": [[11, "copy-versus-view"]], "Organizing Python projects": [[12, "organizing-python-projects"]], "Testing a local pip install": [[12, "testing-a-local-pip-install"]], "Sharing packages via PyPI": [[12, "sharing-packages-via-pypi"]], "Tools that simplify sharing via PyPI": [[12, "tools-that-simplify-sharing-via-pypi"]], "Building a conda package and share it": [[12, "building-a-conda-package-and-share-it"]], "Demo": [[12, "demo-0"]], "Building a python package with conda skeleton pypi": [[12, "building-a-python-package-with-conda-skeleton-pypi"]], "Remark": [[12, "callout-1"]], "Conda package location": [[12, "callout-2"]], "Building a conda package from scratch": [[12, "callout-3"]], "Publishing a python package": [[12, "publishing-a-python-package"]], "A quick Pandas preview": [[13, "a-quick-pandas-preview"]], "Getting help": [[13, "callout-0"]], "What\u2019s in a dataframe?": [[13, "what-s-in-a-dataframe"]], "Tidy data": [[13, "tidy-data"]], "Working with dataframes": [[13, "working-with-dataframes"]], "Time series superpowers": [[13, "time-series-superpowers"]], "Beyond the basics": [[13, "beyond-the-basics"]], "Modes of parallelism": [[14, "modes-of-parallelism"]], "Multithreading and the GIL": [[14, "multithreading-and-the-gil"]], "multiprocessing": [[14, "multiprocessing"]], "Exercises, multiprocessing": [[14, "exercises-multiprocessing"]], "MPI": [[14, "mpi"]], "Exercises, MPI": [[14, "exercises-mpi"]], "Coupling to other languages": [[14, "coupling-to-other-languages"]], "Dask and task queues": [[14, "dask-and-task-queues"]], "Dask": [[14, "dask"]], "Example from dask.org": [[14, "discussion-0"]], "Exercises, Dask": [[14, "exercises-dask"]], "Task queues": [[14, "task-queues"]], "Python multithreading solution": [[15, "python-multithreading-solution"]], "Do it in parallel with multiprocessing": [[15, "do-it-in-parallel-with-multiprocessing"]], "Do it in \u201cparallel\u201d with threads": [[15, "do-it-in-parallel-with-threads"]], "Future ideas": [[15, "future-ideas"]], "Spotting code problems with linters": [[16, "spotting-code-problems-with-linters"]], "Enforcing consistent code style": [[16, "enforcing-consistent-code-style"]], "Problems with styles and writing your own kind of code": [[16, null]], "Integrating productivity tools with git": [[16, "integrating-productivity-tools-with-git"]], "Other nice tools": [[16, "other-nice-tools"]], "Introduction to Python": [[17, "introduction-to-python"]], "Scalars": [[17, "scalars"]], "Collections": [[17, "collections"]], "Control structures": [[17, "control-structures"]], "Functions and classes": [[17, "functions-and-classes"]], "Python type system": [[17, "python-type-system"]], "Quick reference": [[18, "quick-reference"]], "What\u2019s in SciPy?": [[19, "what-s-in-scipy"]], "Exercises: use SciPy": [[19, "exercises-use-scipy"]], "1: Numerical integration": [[19, "numerical-integration"]], "2: Sparse matrices": [[19, "sparse-matrices"]], "Why scripts?": [[20, "why-scripts"]], "From Jupyter notebooks to Python scripts": [[20, "from-jupyter-notebooks-to-python-scripts"]], "Save as Python script": [[20, "save-as-python-script"]], "Command line arguments with sys.argv": [[20, "command-line-arguments-with-sys-argv"]], "Parsing command line arguments with argparse": [[20, "parsing-command-line-arguments-with-argparse"]], "Load larger option lists using config files": [[20, "load-larger-option-lists-using-config-files"]], "Exercises 3 (optional)": [[20, "exercises-3-optional"]], "Further reading": [[20, null]], "Requests": [[21, "requests"]], "Retrieve data from API": [[21, "retrieve-data-from-api"]], "API which requires parameters": [[21, "api-which-requires-parameters"]], "After exercises: Saving retrieved data to disk": [[21, "after-exercises-saving-retrieved-data-to-disk"]], "Wrap-up": [[21, "wrap-up"]]}, "indexentries": {}}) \ No newline at end of file diff --git a/branch/rkdarst--dependengi-exercise-time/web-apis/index.html b/branch/rkdarst--dependengi-exercise-time/web-apis/index.html new file mode 100644 index 00000000..d43143d6 --- /dev/null +++ b/branch/rkdarst--dependengi-exercise-time/web-apis/index.html @@ -0,0 +1,815 @@ + + + + + + + + + + + + + Web APIs with Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Web APIs with Python

+
+

Questions

+
    +

  • Have you ever needed to get some data from somewhere else on the web?

    • +
+
+
+

Objectives

+
    +

  • Understand a web server and API and why might you need to talk to one.

    • +

  • Basics of the requests Python library

    • +

  • Some lightweight recommendations on saving data when you get to more serious data download.

    • +
+
+
+

Requests

+

Requests is a Python library that makes requests to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.

+

First, let’s take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: https://requests.readthedocs.io/en/latest/

+
+
+
# Embed the requests homepage
+from IPython.display import IFrame
+requests_documentation_url = "https://requests.readthedocs.io/en/latest/"
+IFrame(requests_documentation_url, '100%', '30%')
+
+
+
+
+
+ +
+
+
+
+

Retrieve data from API

+

An API (Application Programming Interface) is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the request-response cycle.

+

We can find a list of some free APIs (available without authentication) at https://apipheny.io/free-api/#apis-without-key . These APIs can be used for developing and testing our code.

+

Let’s make a request to the Cat Fact API. If we go to https://catfact.ninja/, it gives us the definitions:

+
    +

  • GET /fact is the API endpoint.

    • +

  • GET is the type of request we make and

    • +

  • /fact is the path.

    • +
+

You can even test this in your web browser: https://catfact.ninja/fact

+

Using the Requests library, we do this with get().

+
+
+
# Import
+import requests
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make a request
+response = requests.get(url)
+
+
+
+
+

The requests.Response object tells us what the server said. We can access the response content using content.

+
+
+
response_content = response.content
+
+# Display
+display(response_content)
+
+
+
+
+
b'{"fact":"A cat rubs against people not only to be affectionate but also to mark out its territory with scent glands around its face. The tail area and paws also carry the cat\\u2019s scent.","length":174}'
+
+
+
+
+

The response content is in the JSON format and Requests gives us the json() method that decodes it and returns the corresponding data as Python objects. This is equivalent to json.load().

+
+
+
response_json = response.json()
+
+# Display
+display(response_json)
+
+
+
+
+
{'fact': 'A cat rubs against people not only to be affectionate but also to mark out its territory with scent glands around its face. The tail area and paws also carry the cat’s scent.',
+ 'length': 174}
+
+
+
+
+

(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)

+
+
+

API which requires parameters

+

Let’s then examine another API which accepts parameters to specify the information request. In particular, we will request a list of Finnish universities from http://universities.hipolabs.com using the /search end point and a parameter country with value Finland, like this: +http://universities.hipolabs.com/search?country=Finland .

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search?country=Finland'
+
+# Make a request
+response = requests.get(url)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+
[{'domains': ['abo.fi'],
+  'alpha_two_code': 'FI',
+  'state-province': None,
+  'name': 'Abo Akademi University',
+  'web_pages': ['http://www.abo.fi/'],
+  'country': 'Finland'},
+ {'domains': ['cou.fi'],
+  'alpha_two_code': 'FI',
+  'state-province': None,
+  'name': 'Central Ostrobothnia University of Applied Sciences',
+  'web_pages': ['http://www.cou.fi/'],
+  'country': 'Finland'}]
+
+
+
+
+

URLs containing parameters can always be constructed manually using the & character and then listing the parameter (key, value) pairs as above.

+

However, Requests allows us to provide the parameters as a dictionary of strings, using the params keyword argument to get(). This is easier to read and less error-prone.

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search'
+
+# Make the parameter dictionary
+parameters = {'country' : 'Finland'}
+
+# Get response
+response = requests.get(url, params=parameters)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+
[{'domains': ['abo.fi'],
+  'alpha_two_code': 'FI',
+  'state-province': None,
+  'name': 'Abo Akademi University',
+  'web_pages': ['http://www.abo.fi/'],
+  'country': 'Finland'},
+ {'domains': ['cou.fi'],
+  'alpha_two_code': 'FI',
+  'state-province': None,
+  'name': 'Central Ostrobothnia University of Applied Sciences',
+  'web_pages': ['http://www.cou.fi/'],
+  'country': 'Finland'}]
+
+
+
+
+
+
+

Exercises 1

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+
+
+
# Import module
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Send the request using the get() function
+response = requests.get(url)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+
+
+
+
+
{'activity': 'Take a bubble bath',
+ 'type': 'relaxation',
+ 'participants': 1,
+ 'price': 0.15,
+ 'link': '',
+ 'key': '2581372',
+ 'accessibility': 0.1}
+
+
+
+
+

Next, let’s try to narrow down the suggestions by adding some parameters

+
    +

  • type

    • +

  • participants

    • +
+

All possible parameter values are presented at the bottom of the bored documentation page. Relevant parts in the Requests documentation

+
+
+
# Define some parameters
+params = {
+    'type' : 'education',
+    'participants' : 1,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display("Response")
+display(response.json())
+
+
+
+
+
'Response'
+
+
+
{'activity': 'Learn Kotlin',
+ 'type': 'education',
+ 'participants': 1,
+ 'price': 0,
+ 'link': 'https://kotlinlang.org/',
+ 'key': '3950821',
+ 'accessibility': 0.8}
+
+
+
+
+

Let’s narrow the request further with more parameters

+
    +

  • price range

    • +

  • accessibility range

    • +
+

(All possible parameter values are again presented at the bottom of the document page.)

+
+
+
# Define some parameters
+params = {
+    'type' : 'social',
+    'participants' : 2,
+    'minprice' : 0,
+    'maxprice' : 1000,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+display("")
+
+
+
+
+
{'activity': "Text a friend you haven't talked to in a long time",
+ 'type': 'social',
+ 'participants': 2,
+ 'price': 0.05,
+ 'link': '',
+ 'key': '6081071',
+ 'accessibility': 0.2}
+
+
+
''
+
+
+
+
+
+
+

Exercises 2

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+
+
+
# Import modules
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Make the request using the get() function
+response = requests.get(url)
+
+
+
+
+

We can access the headers of the original request

+
+
+
display("Request headers")
+display(dict(response.request.headers))
+
+
+
+
+
'Request headers'
+
+
+
{'User-Agent': 'python-requests/2.31.0',
+ 'Accept-Encoding': 'gzip, deflate',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive'}
+
+
+
+
+

We can also access the headers of the response

+
+
+
display("Response headers")
+display(dict(response.headers))
+
+
+
+
+
'Response headers'
+
+
+
{'Server': 'Cowboy',
+ 'Report-To': '{"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1699510623&sid=67ff5de4-ad2b-4112-9289-cf96be89efed&s=SxHy5EwfCRcSqENo70DRfoaOyY2K5kNIAd%2Fe%2F%2FthxXs%3D"}]}',
+ 'Reporting-Endpoints': 'heroku-nel=https://nel.heroku.com/reports?ts=1699510623&sid=67ff5de4-ad2b-4112-9289-cf96be89efed&s=SxHy5EwfCRcSqENo70DRfoaOyY2K5kNIAd%2Fe%2F%2FthxXs%3D',
+ 'Nel': '{"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]}',
+ 'Connection': 'keep-alive',
+ 'X-Powered-By': 'Express',
+ 'Access-Control-Allow-Origin': '*',
+ 'Access-Control-Allow-Headers': 'Origin, X-Requested-With, Content-Type, Accept',
+ 'Content-Type': 'application/json; charset=utf-8',
+ 'Content-Length': '175',
+ 'Etag': 'W/"af-VOTohlOHcKniSxUt/o7qFbzgP+8"',
+ 'Date': 'Thu, 09 Nov 2023 06:17:03 GMT',
+ 'Via': '1.1 vegur'}
+
+
+
+
+

In many cases, the default headers

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive'}
+
+
+

added automatically by Requests are sufficient. However, similarly to parameters, we can pass custom headers to the get function as an argument.

+

This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive',
+ 'example-user-id' : 'example-password'}
+
+
+

For examples of APIs using this type of authentication, see

+ +

For more on authentication, see also Requests documentation.

+
+
+

Exercises 3

+ +
+
+
# Import module
+import requests
+
+# Define webpage to scrape
+url = "http://www.example.com/"
+
+# Make a request for the URL
+response = requests.get(url)
+
+# Examine the response
+display(response.content)
+
+
+
+
+
b'<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n    <meta charset="utf-8" />\n    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1" />\n    <style type="text/css">\n    body {\n        background-color: #f0f0f2;\n        margin: 0;\n        padding: 0;\n        font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;\n        \n    }\n    div {\n        width: 600px;\n        margin: 5em auto;\n        padding: 2em;\n        background-color: #fdfdff;\n        border-radius: 0.5em;\n        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n    }\n    a:link, a:visited {\n        color: #38488f;\n        text-decoration: none;\n    }\n    @media (max-width: 700px) {\n        div {\n            margin: 0 auto;\n            width: auto;\n        }\n    }\n    </style>    \n</head>\n\n<body>\n<div>\n    <h1>Example Domain</h1>\n    <p>This domain is for use in illustrative examples in documents. You may use this\n    domain in literature without prior coordination or asking for permission.</p>\n    <p><a href="https://www.iana.org/domains/example">More information...</a></p>\n</div>\n</body>\n</html>\n'
+
+
+
+
+
+
+
# Looks like HTML :) Let's access it using the text attribute
+html = response.text
+
+print(html)
+
+
+
+
+
<!doctype html>
+<html>
+<head>
+    <title>Example Domain</title>
+
+    <meta charset="utf-8" />
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style type="text/css">
+    body {
+        background-color: #f0f0f2;
+        margin: 0;
+        padding: 0;
+        font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+        
+    }
+    div {
+        width: 600px;
+        margin: 5em auto;
+        padding: 2em;
+        background-color: #fdfdff;
+        border-radius: 0.5em;
+        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);
+    }
+    a:link, a:visited {
+        color: #38488f;
+        text-decoration: none;
+    }
+    @media (max-width: 700px) {
+        div {
+            margin: 0 auto;
+            width: auto;
+        }
+    }
+    </style>    
+</head>
+
+<body>
+<div>
+    <h1>Example Domain</h1>
+    <p>This domain is for use in illustrative examples in documents. You may use this
+    domain in literature without prior coordination or asking for permission.</p>
+    <p><a href="https://www.iana.org/domains/example">More information...</a></p>
+</div>
+</body>
+</html>
+
+
+
+
+
+
+
# Import beautiful soup module
+from bs4 import BeautifulSoup
+
+# Create soup
+soup = BeautifulSoup(html, 'html.parser')
+
+
+
+
+
+
+
# Extract page title from the HTML
+print(f"Found title: {soup.title.text}")
+
+
+
+
+
Found title: Example Domain
+
+
+
+
+
+
+
# Extract links (hrefs) from the HTML
+for link in soup.find_all('a'):
+    print(f"Found link: {link.get('href')}")
+
+
+
+
+
Found link: https://www.iana.org/domains/example
+
+
+
+
+
+
+
# Extract all text from the HTML
+print(f"Found text: {soup.get_text()}")    
+
+
+
+
+
Found text: 
+
+
+Example Domain
+
+
+
+
+
+
+
+Example Domain
+This domain is for use in illustrative examples in documents. You may use this
+    domain in literature without prior coordination or asking for permission.
+More information...
+
+
+
+
+
+
+

After exercises: Saving retrieved data to disk

+

Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudal study.

+

To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don’t, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).

+

For example, let’s retrieve three cat facts and save them to a JSONLINES file using the jsonlines library.

+
+
+
# Import
+import requests
+import jsonlines
+import time
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make three requests in loop and make a list of response JSON objects
+for i in range(3):
+
+    # Logging
+    print(f"Make request {i}")
+
+    # Make a request
+    response = requests.get(url)
+    
+    # Decode to JSON
+    response_json = response.json()
+                
+    # Open a jsonlines writer in 'append' mode 
+    with jsonlines.open('catfacts.jsonl', mode='a') as writer:
+
+        # Write
+        writer.write(response_json)
+        
+    # Sleep for one second between requests
+    time.sleep(1)
+
+
+
+
+
Make request 0
+
+
+
Make request 1
+
+
+
Make request 2
+
+
+
+
+

We can then read the objects from the disk using the same library.

+
+
+
# Open a jsonlines reader
+with jsonlines.open('catfacts.jsonl', mode='r') as reader:
+    
+    # Read and display
+    for obj in reader:
+        display(obj)
+
+
+
+
+
{'fact': 'In ancient Egypt, mummies were made of cats, and embalmed mice were placed with them in their tombs. In one ancient city, over 300,000 cat mummies were found.',
+ 'length': 158}
+
+
+
{'fact': 'A cat uses its whiskers for measuring distances.  The whiskers of a cat are capable of registering very small changes in air pressure.',
+ 'length': 134}
+
+
+
{'fact': "A cat's nose is as unique as a human's fingerprint.", 'length': 51}
+
+
+
+
+
+
+

Wrap-up

+
+

Keypoints

+
    +

  • Requests is a common tool

    • +

  • Web APIs may often require some trial and error, but actually getting data is usually not that difficult

    • +

  • Storing all the data and processing it well can be a much larger issue.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb b/branch/rkdarst--remove-catfacts-jsonl/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb new file mode 100644 index 00000000..4a5e214a --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_downloads/4b858dab9366f77b3641c99adece5fd2/weather_observations.ipynb @@ -0,0 +1,96 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "url = \"https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv\"\n", + "weather = pd.read_csv(url,comment='#')\n", + "\n", + "# define the start and end time for the plot \n", + "start_date=pd.to_datetime('01/06/2021',dayfirst=True)\n", + "end_date=pd.to_datetime('01/10/2021',dayfirst=True)\n", + "\n", + "# The date format in the file is in a day-first format, which matplotlib does nto understand.\n", + "# so we need to convert it.\n", + "weather['Local time'] = pd.to_datetime(weather['Local time'],dayfirst=True)\n", + "# select the data\n", + "weather = weather[weather['Local time'].between(start_date,end_date)]\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, we have the data loaded, and adapted to our needs. So lets get plotting" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYUAAAEcCAYAAAAoSqjDAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAABtDElEQVR4nO2dd7gcVdnAf+/evSU9pBcggRCE0CHSpSNKERQbKkX9wM+GYPsQsWBFUSwgIgLSwYIoItKbhBJCS0JNgJBCSC83N7lt93x/zJzZs7Nnd2f7bHJ+z3Ofuzs7O/vu7Mx5z1vO+4pSCofD4XA4ABKNFsDhcDgc8cEpBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA4HA5HgFMKDkcDEZHJIqJEJNloWUpBRD4pIvc2Wg5H9XFKwWFFRDYYf2kR2WQ8/2Sj5SsHEVkgIkfV+TOnicgdIrJORDpF5CERObCeMlSKTXEppW5SSr23kXI5aoNTCg4rSqnB+g9YCJxgbLup0fKFqcdMu9TPEJEpwAxgDrAdMAG4HbhXRA6ovoR55RARcfe6IxLuQnGUhIgkROQ8EXldRFaJyF9EZIT/mp5RflpEFonIGhH5XxF5t4jMFpG1InKZcawzRGSGiFzmz6RfEZEjjdeHicjVIrJURJaIyI9EpCX03l+JyCrg+yIyRUQe9OVaKSI3ichwf/8bgG2Bf/nWzjdF5DARWRz6foE1ISLfF5G/iciNIrIeOKOQTBa+DzyhlPq2Umq1UqpTKfVb4AbgZ6F9PyMib/vH/bohz74iMktE1ovIMhG5xHhtfxF53D+vL4jIYcZrD4vIj0VkBrAR+IaIzAp913NF5A7/8XEi8pz/OYtE5PvGro/6/9f65+4A//w/ZhzrQBF52v8dnzatIV+WH/q/V6eI3Csio/zXOvzzu8r/Hk+LyNg859NRD5RS7s/9FfwDFgBH+Y+/AjwJbA20A38AbvFfmwwo4AqgA3gv0A38AxgDTASWA4f6+58B9APnAq3Ax4B1wAj/9dv94w/y3z8T+FzovV8GksAAYAfgaF+u0XiD2a9t38N/fhiwuMB3/T7QB5yEN4EaUEgmy3l7B/i0ZfvhQMo/nj5nt/jH3A1YYcjwBHCq/3gwsL//eCKwCjjWl+1o//lo//WH8Sy8XfzzMwzoBKYacjwNfNw4F7v5x9odWAacFPpdk8Z7zwAe8x+PANYAp/qfdYr/fKQhy+vAjv53fhi4yH/tc8C/gIFAC7APMLTR1/yW/OcsBUep/C/wbaXUYqVUD97A+eGQa+WHSqlupdS9QBee0liulFoC/BfYy9h3Od7A3aeU+jPwKnCcP1s8FjhHKdWllFoO/Ar4uPHet5VSlyql+pVSm5RS85VS9ymlepRSK4BLgEMr/L5PKKX+oZRKA0MjyGQyClhq2b4Ub/AdYWy70D/mHOBPeAMreEppBxEZpZTaoJR60t/+KeAupdRdSqm0Uuo+YJYvn+ZapdSL/vlZB/xTH1dEpgI7AXcAKKUeVkrN8Y81G09JRT13xwHzlFI3+J91C/AKcIKxz5+UUq8ppTYBfwH2NL7fSGAHpVRKKfWMUmp9xM911ACnFBylMgm43Tf11wIv4816TZN/mfF4k+X5YOP5EqWUWZXxLTzf+yQ862Gp8Vl/wJudaxaZgonIWBG51XfrrAduxBuYK8H8jCgymawExlu2jwfSeLNp2+focwDwWbwZ9iu+a+V4Q5aPaDl8WQ4OfV7W+QFuJqNsPgH8Qym1EUBE9hMvCL5CRNbhKf+o526CL7PJW3jWjOYd4/FGMtfADcA9wK2+++znItIa8XMdNcApBUepLALer5Qabvx1+FZAOUwUETGebwu87X9ODzDK+JyhSqldjH3DJX5/4m/bTSk1FG82LQX278JzWwDgxwZGh/Yx3xNFJpP7gY9Ytn8UzwLZaGzbxniszwFKqXlKqVPwFM/PgL+JyCBflhtCv8MgpdRFBb7vfcBoEdkTTzncbLx2M57VsI1SahieC1Cfu2KllN/GU1Im2wJFrwnfQrxQKTUNOBA4Hjit2PsctcMpBUepXAH8WEQmAYjIaBE5sYLjjQHOFpFWEfkIsDOeW2QpcC/wSxEZKl6Ae4qIFHJpDAE2AOtEZCLwjdDry4DtjeevAR1+kLUVuAAvHmGlDJkuBA70A74jRGSIiHwZb9D7v9C+3xGRgSKyC/Bp4M8AIvIpERntu6/W+vum8aygE0TkGBFp8QO2h4nI1gXk7wP+ClyM57q6z3h5CLBaKdUtIvviWRKaFf5nmufO5C5gRxH5hIgkReRjwDTgznyyaETkcBHZzVfI6/HcSeli73PUDqcUHKXyG7wZ5b0i0okXdN6vguM9BUzFc7X8GPiwUmqV/9ppQBvwEp6r5W/Y3TGaC4G98YLV/wb+Hnr9p8AFvrvl676f/QvAVXiz2i5gMYWJLJNSah6eS2cPvAD2UuBk4Bil1IzQ7o8A84EHgF/48RiA9wEvisgGvHP/cT9+sgg4ETgfb9BehKcEi93TNwNHAX9VSvUb278A/MD/Tb+L5/fX32Mj3m8zwz93+4e+5yq8Gf7X8ILd3wSOV0qtLCILwDi8c7gezxX5CJ5LydEgJNud63DUDxE5A/gfpdTBjZbF4XB4OEvB4XA4HAFOKTgcDocjwLmPHA6HwxHgLAWHw+FwBDRVud4wo0aNUpMnT260GA6Hw9FUPPPMMyuVUuE1OUCTK4XJkycza9as4js6HA6HI0BEwivQA5z7yOFwOBwBTik4HA6HI8ApBYfD4XAEOKXgcDgcjgCnFBwOh8MR4JSCw+FwOAKcUnA0HU++sYrnFq4pvqPD4SiZpl6n4Ngy+fiVXkfKBRcd12BJHI7ND2cpOBwOhyOg7krB7xA1U0ReEJEXReRCf/t2IvKUiMwXkT+LSFu9ZXM4HI4tnUZYCj3AEUqpPYA9gff5nZx+BvxKKbUDXkerzzZANofD4diiqbtSUB4b/Ket/p8CjsBrywdwHXBSvWVrVv40401+dOdLjRbD4XBsBjQkpuA3Gn8eWI7XPPx1YK3RM3YxMDHPe88SkVkiMmvFihV1kTfuXPivl7jqsTcbLYbD4dgMaIhSUEqllFJ7AlsD+wI7lfDeK5VS05VS00ePtlZ+dWyGvLWqixnzo/SBdzgcldDQlFSl1FoReQg4ABguIknfWtgaWNJI2Rzx4tCLHwZcGqrDUWsakX00WkSG+48HAEcDLwMPAR/2dzsd+Ge9ZXM4HI4tnUa4j8YDD4nIbOBp4D6l1J3A/wFfFZH5wEjg6gbI1nQ0e4/t+cs7uWvO0sj796fSweNX3+nkvpeW1UIsh2OLpe7uI6XUbGAvy/Y38OILjhJIGzohlVa0JKRxwpTBBy6bwcbeFG/85FgSEWTf2JcKHh/z60cB51JyOKqJW9Hc5PQZM+fe/nSBPePJxl5vkF/e2RNp//Wb+nK2Nbu15HDECacUmpyUYSr09KcK7BlPRg1uB2DJ2o2R9u/s7s/Z1tXbfN/b4YgrTik0Of0pUyk0n6XQnvQuwa6e3IF9fXcfk8/7N3+dtSjYtmZjb85+6yzWg8PhKA+nFJqUnv4Ui1ZvpC+dUQTdfc03Y25t8eIImyyyL169CYCrjYV5y9fnupnWbXRKweGoFk4pNCnf/Nts3vPzh+jqybhT+tPN51vXgXGbQhNL3HnZ+u6cbc3oNnM44opTCk3Kw696JT5MH3szBlyTCe8StCkF/XXMr2ULSKeb8Hs7HHHFKYUmRWdv9hrZR/98/m3e8/MHSTeRxaAthU2WYHF/OjdGsmpDrlIw4yq1ZPbitVmBfYdjc8QphSbFNphe+uB8Fq3eRFdvboZOXMnEFHIVgA6cKzIDsS37KFUHS+H5RWv5wGUz+P3D82v+WQ5HI3FKoUlJ+A73jZYZti1oG1dE8geabesubPtZDIqq8846L5Yxe/G62n+Yw9FAnFJoUrSlsNFiFdhcMXFFu2N6LIO9DiCbhoBNCdrcTNVGu+uc98ixudPQKqmO8tGWgk0B2HL+44pekd1niQtYLQXL961loHljb39gJdT6sxyOOOAshSYlYynY3EfNE1PQSsE22NoW4220fLdUDQ2FL938HEf88hHeWuWtuHZKwbG545RCkxIEmi1ulxffXl9vccpGr60opBTMV2yWQqqG7qMHX1kOwDv++gjnPnJs7jil0KRoH7ctpvDdf75YZ2k8+lNpPnj5DB55LXqb1D5/4LeletqsCJtlVEtLQbPBz3pqxrUgDkcpOKXQJOhBM51WKKWs2UeD2loA2G+7EfUXEFi7qY/nFq7l3D8/H/k9fYGlkPua/s6mwrAqhToM1Bv8lePNVprc4SgVpxSagDdXdjHl/Lv49+ylbH/+XXzr73Os6xR0sFZXHi2Xfz6/hLfXbir5fXps7iuhMJ9ummNbcJfJTCp8vHos1gtcWc5QcGzmOKXQBDz+utew/pHXPP/2rU8vsloKenVzJatue/vTfOXW5znwogcjv+eGJxZw5C8fzmQSpdOs29TH/OWdRd+rFZktpqC/R7F1F2bNp9/cP4+P/uGJyLJHpRrn1uFoBlxKahOgZ+0Thg8ItulicbaaQZVkyJRTXO47fgxDp5D2pRQf/v3jzFu+oWhXNK1Iwi6g9d19kZWCaSn86v7XShM+Ir3+eemtRwDD4WggzlJoAvS6g8HtuTq82+KqqUQp2NYLREWXoEilFfOWb4j4ebnuowdeXsbu37+XmW+uBop3lKtHTEHL0Izd7RyOUnBKoQnQVoGtNLZtJfDTC9Yw+bx/s2h1tG5mJpUMems35TbAKUQqrYIAs/nVdPbSCxFLStSjZLhWln3OUnBs5tRdKYjINiLykIi8JCIvishX/O3fF5ElIvK8/3dsvWWLK4KnFfotA5JtgZfuRPb0gtUlf1Y5SiHpB73XWJrdFErhNAdYc7avA8u6WF4xbIFm27mqBC2rsxQcmzuNsBT6ga8ppaYB+wNfFJFp/mu/Ukrt6f/d1QDZYkmikKVQYJAa0tFa8mf1pjKWR9Sc/Da/peZaS6vMQoFZ8/uk04rfPTSft9duotv33ycjKgXbZ9jcapWQiZc4peDYvKm7UlBKLVVKPes/7gReBibWW45mQruPzAFJb7O5jzRDOkrPIzCVjBlUfW1ZJ3OX2N05GaWQaynYFNmm3hSTz/s3f3z0jWDb/OUbuPieV/n8Tc8GlkLC1nqN3I5sKzf0MPm8f3P7c4uDbdVuTdrjYgqOLYSylYKITBGRdv/xYSJytogML/EYk4G9gKf8TV8Skdkico2IbJXnPWeJyCwRmbViRfSVs9Vk+fpuDrroQd5YES2YWim6vLQtX7+QpZCMsNDqV/e9xgX/mBM8Nwc9cw3Ee3/1KMdf+pj1GG0t3mW0xmIp2JSCXgj2mwfmBdu0wuvq6Q8yoPIN7K2J7Mv2jRVdAPz2gUyvg2orBa0ge+vU0MfhaBSVWAq3ASkR2QG4EtgGuDnqm0VksH+Mc5RS64HfA1OAPYGlwC9t71NKXamUmq6Umj569OgKxC+fu+YsZcnaTVz3+IK6fJ6eGdvSIQulkEaJv/7mgXnc+ORC7/j96azso+4ii8Y07a3eZbTOYin09ae54B9z+OusRcE2m7vHVEZakeT7/LBbSdclMvtVR5U9KpmYQvNUoHU4yqESpZBWSvUDHwQuVUp9Axgf5Y0i0oqnEG5SSv0dQCm1TCmVUkqlgT8C+1YgW02p+1zR/0CrpVBg8CulTs+cxevY8YL/8MDLy4JtOrX18fkrC763kKWwvLOHG59cyDf+NjvYZvPLd/lWiWAsWsvTFyJsAS1d563jGGy4y6puKRhrMByOzZlKFq/1icgpwOnACf62opFN8XwhVwMvK6UuMbaPV0ot9Z9+EJhbgWw14bzbZrNyQw8HThkFZNw6tUYPkjZLobtCS0Fzv68MHjMUgFYKr6/sKvjetqRXc8mWfbS6K6MolFLMemsNIwe15eynZ/kihb8vQGtL9lzGXjm18sHbzGoK1im4QLNjM6cSS+HTwAHAj5VSb4rIdsANEd53EHAqcEQo/fTnIjJHRGYDhwPnViBbTbj16UXc//Lyun+uHptMV1FQZ6jAzLUUS2GZ74IZYQzY+u260F6+FNF2P9CsU2FNzIykO154m49c8QR/fWZxzn5ZmUhF5A67j/RAbVpN1VjQ1pfOdWml0ipQON19Kc798/NZTXgcjmanbEtBKfUScLbx/E3gZxHe9xhgG11cCmoe9CBp+t2jTISL7WPOhPVqZDPjR4+rxWbd2ptjcx+tNrYtXuO5eQr1exCk6OclQ4FmrRjNMuKVWgr3vvgOA9vst0dfKk1LooX7XlrG7c8tobc/ze8+uXdFn+dwxIWylYKIvInFva6U2r4iiRw5BNVCDaUQpbFMsRm36QrRfY7NOkP6/fYGOClueWohB+0wKphF21JSzW3aotjQnbufRqS4iyZssejzYxYH7C/i++/pT/Hoays5aucxVjfgWTc8k/e9vak0Ha0tgRxu7YJjc6KSmMJ043EH8BGgMYX8a8zKDT0M9F0oUP9Asx6Us5VCcSmKKQVzMNODqOmf1+/Xu5mH+91Dr/NbP6V05/FD836G6VJqb/XOYaEe0qm0Klq2Itli93r2ZFlShY/xpZuf476XlnHfuYcwdeyQgvuG0aXBtcVSjzIbDke9qMR9tCq06dci8gzw3cpEih/Tf3Q/O4wZHDzXvvo6xZnLVgqFxkWlVJY7Ss+yTReMfrv2z5uHW2MEkAuVlDCP1+4P5ht6srvFtSUTgSy2Jjphoqy/KDZQP+rXVyq0ziMf2pJJOkvBsRlSifvIdKIm8CyHzbYU93xL1U+xhkaqT5CN019aIDXfbHnhqo0ccvFD/PRDuwXb9OBtWgpa+enYgxm4HjesI3hcaAA2B3kdKO8KtRBtN5RCZ3dfsEI6H8VeN2XOR6He0MUUbl+/97qOvxRzVTkczUQlg7i5uKwfWAB8tCJpHFb0GGUunErlGYhaEplAbb6x7YXFawG41FhRrAPNZkzh7bXdjBzUbh0kTXfayg09eWU3lYzuuxA+XnuyhU68z1/f3c+A1hYKUQ1LQctg28/W99pE14fScZj+CPEdh6NZqMR9dHg1BXHkJ20JNJuDWUIyCqAjmQgWginl9XPuS6ms2bVOPzV982t937+pFE67ZiZtLQm++b535chkWi1aodgo1iAHMgHoqO8JZx/ZiBKIB7tFUcyF1duvy2hn/3c4NgdKVgoi8iml1I0i8lXb6+aCtM0V7XGIElO4/6VlbD96ENuPHlx85zykrCmpmYGoLZkIyjq0t7YESiGt4Cd3vcwf//smr//kWOYuWUdnd3/Qp6CjNTO46sVj4fIQval0MKs2h76ofvQoMYL21tKWy0SpnhrVzW+zgrp6ilkK2RVTnaXg2Jwox1IY5P8vLWWjSSllAZiN/7l+FkDRtpSFyCxes1sKrS0ZpdBhzLqVUtz0lFfXqLO7jxN/NwOAHcd6CspUAIUCrrb4RdRqobYBNjw7b08WdhdpWluEvpTKm31kEnWgtimFfJZKW0uC3lQ6owx0f2mnExybESUrBaXUH/z/F1ZfnPhRKOhYbL5aqULRpG2BZsNl0Z5M0KkfG/74tIKO1hY29qaConGQSQmNWh8oE2j2Zscbe1KRq4XaLIWwAgq7j/KRTCToS6VojRBTiNqS1Kbw8hXTa096SsGVvHBszlRSOvvnIjJURFpF5AERWSEin6qmcHHA5i9WEVcqVGvQyCxeMzN5Msc2awGZA2xaqSBo+/SCNcF2nf0TVSmYX+N7d7zIHj+4t6iLRRNOP4Xc4G5kpeC7jaK4j6JmBNmUfr4eFdrN1RuyFOIWUXj0tRVByq3DUSqV1D56r1/y+ni8zKMdgG9UQ6g40VfAN1AsprCxwCKtUsisLM5sMxWOGUTuyLIUVDCQvfZOZ7B9gx8YjtqdzJxN6yqqs95aY903nC4aRXl0FMk20mjlZ7qP2vK4kiJbCtaubXmUgu/minsXttOumclp18xstBiOJqUSpaBdT8cBf1VKReuy3mTYZpzFxptnF67hhEsfY2YZPZJtFBvgzIHRDB4rRWApmGmj/RZ3VMHPNwbOYQO8Qrjv+OWqwwxqyx7gowSaB7VHUwo6FdV0H+WzMkxrpKunP2/arFUpFHAfAcxdso6P/uEJOv1yHdVyE67p6uWDl89g0eqNZR+jWrI4tlwqUQp3isgrwD7AAyIyGtjsykXaVusWu+3+M2cpc5as4/6XlhXZMxrFFlNlu4+yLQU9C1+1IbdYXeTPNwaaoM6RpSIqwKD20nMXJg4fEGk/rRRajJTUfJlL5jk75tePMv1H91v3syncfG41bQVd+uB8Zr65Oq+1VC53zn6b5xau5YpHXi/7GKa7zikIRzmUrRSUUucBBwLTlVJ9QBdwYrUEiwu2uIAecPL1U9D+/nJKKNgoVtEi231kxhTslkLJn28IEPjR88g0uAylsPVWAyPtp91GZpw5X+aSqRR0dVYbtsVreS2FkJsraiwkKvq7VHLdmDGwKFaawxGmnHUKH7JsM5/+vRKB4obNfVTMl6zr+q8vUA20FEpxH5mD5Nf/+gJ7bjMcqEwp9GcphcLffUBbNFeQyTYj8lsKOg0UMgFms7x3voE5aulsu/soX0wh+7N0sb/wzzN3yTp2mTC05CZM2uqppGuc+X16+9MMai/7UI4tlHLWKZxQ4DXF5qYULIFmrRTy3fI6S2hDgZW+pVBsgMtnKQA8v2gt4JWPKJesaqpFex2UXg9q6pj8S16SLYKe8Lb6biNzQXN49q6JqhTSSrGpN5WlzPLN1MNKYaXvkjPPzwuL1nLi72bwjWPexRcP3yGSDBqt3CuxFMwJRKEkCYcjH+WsU/h0LQSJK7aU1GIB2g1+1lHYv1vqzPGuOUuZNn5oUUvBHNDyNYapBHPQK5ZN1GJRCmYVVBtbbzWA0w6YxOD2JJc/nO1PN4+XSUXNbMtXHK+Q8jJ97W+t2sjO372bn35oN07Zd1sgvyUYdlVp68t0Mep033tefKdkpdAfpB6XP5ib37saLUkdWx6VrFMYKyJXi8h//OfTROSz1RMtHtjcR8WUwqY+b2AwawKVc6N/4aZnOfKSR4qumDVnsFEzeUrBlL2riJ/aphSKFbgTEX5w4q7sM2mrnNfMILq2QrJjCvndR/OXd7J4TW4mjzlWLvD7T//juSXBtnxKIWyF6QZC5v5a35QT2NfXVT4X3RdvepbPXPu09TWlFI+/vtIa/3E4SqGSSNm1wD3ABP/5a8A5FcoTO2yBZj1I5pvB69LKnUZMIWrQL5VWrDL8/6m0Klom23TZ1MZSiD64mJlBehY/MGKcIWFRKOZ3aw0CzYalkGedQldvP0dd8iifuuqprO0rOnuyZtBaXtOPn2/RYTIh2Lxj5vnRx0kkvHLrZ9/yHOs29vH5G58p2stZf24+g/Lfc5by4Cv2HuF/f3YJn/jjU/x11qJgm2v+4yiHSpTCKKXUX4A0gFKqH2jKdIcn31jFvS++Y33NNmvTN2++mKt+vdNwtURdAfy7h+azz4/uZ3lnZgAppRNZtTNiINNpLArJhARrFYZ2eGsaoioFWzwiy1JoybUUbIoEMhlHC1ZlLIXl67t594/v55L7Xgu2aavOrHeklXqYhEiWPJn9M+dHZy61iHDm9bO444W3ueyhefxn7jtcfM+r1uNqtKVQTp+ON32LZ6GxxiFqpViHw6SSEaRLREbip+2LyP5AUy5g+/iVT+btyWsbkINCaPksBV8pmC9HKSENMNuvYDpj/krj8wrf3MkIi7nClBLeKGXlbkKE+792KM9ccBSDfVdWVOulxSKUWdJC+/TN2Ey+wLYtyK9jPOY6AB3/MS25vN9X7DEM07IILAWRYKDW7rNiZU8CpVDkt3n1nU4mn/dvnluYWSehr1PTinIlvR3lUIlS+CpwBzBFRGYA1wNfLvYmEdlGRB4SkZdE5EUR+Yq/fYSI3Cci8/z/uQ7mOvLi29mrVk36Aksh+6bTg4DNlxs1zXDsUC+HcHVX5nOL+YbNgSp6xdHoP30pNZySCWH8sAGMHNweLGQbO7SD1hZhu1GDGDW4Le97bbN+M0ahffrmwJfIM4Laai7ZlLi24FYb7UXzKYWEiFXpmvvrEhlZ38WXsZjFle88L1vfnWVp/neeV9fon8+/HWyzTRziFmhesnZTVv0uRzypZPHas8CheAvYPgfsopSaHeGt/cDXlFLTgP2BL4rINOA84AGl1FTgAf95XTEH7h/86yVmvrmaJ9/ILVWhB4H/zM24nJ54fRWH/+Jh/vbMYuugctecd/j37KVFZdCDtSlLsdRCXXoCorWqhPy+eBtRymHosdkcxLVSGDmojbkXHsODXzuUySMH2d6e81792LYGwxxv830Nm6VgmznrwXZjb4rH5q3kpqfeyjvDFuxKN60yA7DpPgoT1VIIs99PHuB0o5aRPq9mhzibRRun2kw9/SkOuuhBvvm3KEOEo5GUrBRE5FMicip4cQSl1ItKqbnAx0XkE8Xer5Ra6isUlFKdwMvARLzV0Nf5u10HnFSqbJVizhaHdHg33jpLOQc9aJjtMXUM4Hv/nGu9+a945HW+ePOzeT978nn/5pt/eyFwh2Td8EUsBVMpRCWq8oBomVN6DUGWUvBjCW3JBO3JFkQkbwwAsmf9+jjmOoTAUrAojzDW6qyW82ju96mrn+Lbt8/l9RXZ/bi1WAmRnAwkjR6AtTI3dYKuulpMufZaLFC9ANIsqaFjNF1GwUVtBZmutafeXM3k8/4drFVpJFpJu+qt8accS+HLwO2W7X8HvlbKgURkMrAX8BQwVimlp9LvAGPzvOcsEZklIrNWrKjuBWaa6Ho2ZgZ8NWbMoLc/zezFaxnqD8xdvamig/iarl4WrspNlfzLrMVB0Nic6RaLKQw1lEJUN1VrhPLTpRxTD85Ji6VguqoKrW3LyjTyHw9ozbUURGCncUP4yD5bB9lD4e9jc/vp3som5m8+xJc3PIgGqbCJ3IquegzWA3omLpCRRyueYpZC0DfauH50cTyz0KA+9oaefr59+xy+9fc5wUTFVEY6ecKMTzUKnZ5dLD3Z0XjKUQqtSqkN4Y1KqS4g8pRVRAYDtwHn+CW4zWMp8tSdU0pdqZSarpSaPnr06NIkL4KZg6/dz+s32dwQmSYrn73uaT5w2QxWrO/Jed1GT3+Kw37xMIdc/BDg3djmYirdq8HMXOor4hs2LYVCAW1beqeNsGspiqWQGTgzn6HrILUm88cAzKfZC9U8GcxBRPvzBeHucw7h4o/sgdYFYZltloLte5h1jnbbepjlm5k9oSVHKQzyg+g6XqAHdvMa0EHsYpaCfq+pPPT1N6Qj8xvr4yjgpqcWcsvMhUGmkRk20d83X9ylnmilELVMuqNxlKMUBohIjmNYRIYA+aOI2fu24imEm5RSuizGMhEZ778+HrAnZNeQjcZAogdXW2As07A9zX/nebOwFcbagkIzwg3d/YFLav7yTnb93j38ddbi4HXdUc2cwRazFEylMKFAxVHzhiwUUwg3senuS+WUxA7T0pJrKeiso3bjs8LunnxBY30cc7W2lt9scqSVUGvIHWbTo7ZB2ZY5FMZcNBd2H+nFgvqa0GtKTKUQWAoRlUKfRSbzN9HHMX+mzGro3EZM5ZQeqTbacnNKIf6UoxSuBv4mIpP0Bt8NdKv/WkHEs32vBl5WSl1ivHQHcLr/+HTgn2XIVhFdvSmO+dWj/PSul9nUq5VC/tpH5sCzdmMmHlHIfWQOQnf7gWqz74K+uU1/cSkxhfdOG8vNZ+5n3c8c0Ap1LwtbEd19qaIlsW2WgsZ8r3Z9tFrWHNhKWnQkcy0F83wEPRYiBM5tg7Lpv8+3wFDLIpItDxiWQigeYH5WVwXuIz05MZW4HvjN8xUOdJv7mUp0eWc3LzQgxrA+sBTsv9Pxl/6Xb/19Tj1FcuShZKWglPoF3oD9qIisEpFVwCPAnUqpiyMc4iDgVOAIEXne/zsWuAg4WkTmAUf5z+tCixHcfXVZJ3949I3ghrINJDb30JqNfQVfD14zFka9scJLYR01OFPKUgcMN2S5jzLHs3kChg1o5Y4vHcRtnz8QEeHdk0dYP9ucdetB1Aw46zEm7J/v7ktblYItWyiZNVClsz4LMrNb25qDLKVgCVzrWaZpOdmylPJNjIsNynktBWMldXimO7A9ew2CbbbfVcR9lE4rb6W1xcooZCmYlpXNUtD7mROM826bw4m/m1F0dXW10d+pL6X4/I3P8EYomD93yXpumbmw6p+rlGL5+s2uzUtNKasmglLqCuAK32Wks4iivvcx8hcYPbIceSqlrSXBpnQqeyBO6ZlX7kBhm7lnWQoFYgBmsPNtv3uZmeGUsRSys49E8vcwGDagNcttFPYhtycT9PSnGdia+bn1QN3ekilW19ri7ZdMhCyF/pS1plJLQoJBUL/HNlCZA5p+vaM1wYae7MHcZilklcn2Z5lmjEW/biq3ZIu9AF8x900+S6E1kZElvE5BxzyiWAr5Jgu/eWAev3lgHkfsNMZ7r7GfthTM8iH62KYVq92O5jZtNZjXks6smr98A+OGdVjlqQV6sjNnyTrmLFnH0nXd/OOLB9X8c391/zx++8A8Zp5/JGOG1u/7NjMV1URQSnWWohDiih5slq0zS0vk3nga24zTtBQK0WtYClq5rDeUgr65zc/oT6tg8LFp03AZifBMeZAl4KsHUXPA1gO0uR94ysi2KtnMxU9aYgp6gDQHe20ZaEvBnHknsyyFTMaPRiuylNV9lPs9whQtZGgoBfN4ZhmRsMLXCxa1BagHP/P307GqfJaIdiPqqqtZ7iNfJlOe3mDWbV4j/vVqfIbNBaqvI1sgvpboa0HHpvRCtrvn2svLVIvbnvHidfX+vs1M9QvlNCF6EHnbVAqWmZfGNuMzLYVCmIOFPs7aTZn3Bi6E0OfaUvku/+Te3HzmfjklucPPtdLIKlbXkuue0cHa1kTuZWEGmvVbkhb3UYsxeH1gD69W4v7bjzT28/5rRZwvzqEVgK2khelO0zGMbEvBbogWcx9tNAZUU7EkDUtBy3X2EV5Z7PfvOj7r2P2B+ygzsOsByXTj2OTSVo+5RiWz7iHznWyDvf4Mc5tNebQ3WCloK29FZw8X/ecV/vfGZ5j5Zu4C0WpRSXOpLRWnFMj46U0/a28oxdBk2frcC21tREsh21/sPTbdR7a0RMjMqM3BYdywDg6cMqroZ+pgqDmI60F0pVHiuVDQ1owp6NdNBRAsXjPkO3CHUSy46DimjB4cbAvcPS1aKZiWQq4rybR6RgzyktvMstQtkitzvqBz1OwfsCsZEThkR+98H7LjaBZcdBzH7uYphSD5wD+GLYDdm0pbs9nCcq3v7g+26WvEjKPo68U8lr7+rJatsU1ngkUt0FgttAVlfo/X/ZhaLWXpKXAfO+xUVGdZRA4EJpvHUUpdX6FMdUdbBSs6M4N9qf0P8jWyD2PeoNpfbCoUm08a7FkbhVINj542lvteWgZkgqHmgD3csgq6NY/7yPv87HTWnv501vESlkCzjXC8w/xeNpeNub/u5Wz2SNCKyZzZt+aRoZQaTllKIYiXwIl7TmTf7UYwftiArP30jN42+Jgup66eVE6pDNuMfnVXL+OGdQTXiOl6WuNbpWamUWZbrtLpybIU/MWRdbcUvP/m6ekzYlm1xhUHjE4lTXZuAH4BHAy82/+bXiW56oq+ac21BqUW7oo6E7Hlxa+3WArhi7jDElMotCjp0lP2Ch7rhU8tFkvBJIgzWNxHNivDln5arHyGfo8+52aKZ5Yry3DZfO3oHZk8ciCTRw1EhKyOZi15As02/masBymGebzWwFLw/muFABm33hl/eppl67uLXgf2mkzZq6Eh4/bIKAVTAeRaCmv8Aoo2pdDbn2buknVZ+3dWqVVsVGw9QcK9t2uJra2uw04llsJ0YJpSRTrANAH6RjZrH22K2BSnVGyWgrmSWl+84bhFxn2U2VboZjKzZIb6dZzMsV4f58tH7MClD873jmcJ2mpMy0nP7ExFoR8VVQr+jpNGDGT+8g2csMeE4DWbC0gEvnzkVL585FQA3vzpcVnHa7G4vPKV8HjDDwpHISumYMgSxrR0Hnl1RdGGSLc+vZAJwwdw8t5bc8E/5nL+sTsF14St7Wm3xVLQ16mpKPQAa7Nwl63v5vhLH+PEPScEn9HTn+KWmQtpa0lw8j5bF5S5uy+FSPQKvDbSFmVpU4a1wlkK0alEKcwFxgHFS3/GHNssoljbyXIxb4Cevlx/px4XwlkuepDyGrDoNND8SsGMPWhLwZZKa1obgfvIMtM2ByXtXrIVsCvmCtAz+0kjBzH3wmOyAtimpaDdHLZqo1nHs7itquGOyFpbkcj9vpoBIfmLWQq6B3V7MsFtzy4mIRhKIfPeniCmkNvvYaXv5rS6iiwDrHYVPfjycnYcNwTwrgW9WMymFLr7Ulz/xAI+fdB27PSduxkzpJ2Z3z6q4HcrhO286O8dtSthJRSrCuDIUMndMwp4SUTuEZE79F+1BKsn9exla8sOMcnXLcs2A49a02bogKR/7Mz3/Mj0bdhqYCsf2ntisE3PsE33ywF+5pD5+VpBZa0/sGQB2dDvaW0RBrcn8zbMaS/gojLRSsOWuVQJ7Zbva5PEzApLtkjexkthdOB+fXefsfAsHVgj+jrRFqtZ06rTkmmksQ2+2uro7OkPZufF3Ck3PvkWP7nrFa57fAEAyzsry+KxyaVlMbOtaoVrTRqdSiyF71dLiEailKrrBVOs4mi+AHcw2JruI4vv38aIgV7WTn9a0Zb0FnZtN3IQz333vVn7BaucjQH2tAMm8cQbq/jU/pOCpi5B9pGZkmpJU7Wh1zvYBm5TQZgVUQuRsMzi87nV9HePQpYS1ArKIkw4eyrqBEOXZjd9+739KQa1JdnQ0x/4/00XUZio38VMhdXXn7leZvbitey+9fCs92il9dLbWbUqy8bmVtObamWVm8Spt0TcKVspKKUeqaYgjaLWEZFkQrKUTjGlsN5S8hnsM/CWiAE6ncrZn05z91few9+eWczwgbnZR7pm/wNGc/h9Jm3F/B+/P8t60LK0WNxHxdAz8GKzeVuXNRtJi1KwrbOA0nzX9kBz7n7todTVfJbC4PZkVsaPPl+mUuhLKYZ0ePtpZRC1jWshzM/VmW7rjLUx85ZtyFEK2gLqqtIs3mYp6HO1qYaWQkKymyA5ilOynS0ij/n/O0VkvfHXKSLVmVbUkSiXStQBz0Z41losgG0r1Q2Z/HLzaMX87d96/0588fApwYKl/pRi+9GD+eb7dspZ4GZijmsikpPNY7MU9KBcTMlqBTmgrfClZ+uyZsMWU6hGNkurNdCce1xzmyow+ITLhOjZu7lwsS+VDhYaZiyFVM6K9Sh85qDtrNv19fegofhtbsygEmuVKqzaAs16S75FfdVAy+8CzdEppyDewf7/IUqpocbfEKXU0OqLWDu+9pcXuOaxN4vuZxt8ozapCbt4is381uRZGW2zFIoNfp87dArfOGanYDYbdbZkprPaBoVM7MGiFIocWwf8ilkKZu+EQujPNQfnUrrK5cO+ornwe/rTafKNPYNCZUL0AjRzIV5/WgXuNZ2EsLqrl10mlH5bTRo50Lpdz/yz1gsYSmFFZw+ru3qDtQ1hS+1jf3giUlvZMIXcR7WMKejrwqWkRmeLXtF827OL+fFdLxfdz5bKGTU9LzyoFlMK+fLHbX7tqF2sgpLTEZWCuQLZrhDzu4+KWQq9/qhZVCn47iNVRM1oxWTuFy5al49CPSXM/gz6exZTUN+/48WsFq0mOoagWeZX7gxn3miL4qf/eZln3lrD8s4e9pk0ouDn2shnXRTrM/HuH9/P3j+8L9hmWmB9qTRPvbm6YFvZfNgshcB9VKGLLJVW1uNDRpGHu9n99K6X875nS2eLVgpRMWf72l8ddeAJB16jtssMo2eQps86asMSvV9Un7o5gInxNW/7/AF8dPrWwazXzAzSj4sN4npWWmhA9l73XV5FblxbzKEtosK2WXv6dzUbAyWKWArfev9OgFcy5Mk3Vlu/m9k5DeDttZusx+oIqq4qTv7944AX1ymVUtw+hUpjmL/xxgrcPIUshULB9ChMOf8uTv/TzKxtj7y2gvnLO4Prw7SGvnLrc/zh0Td4aWnTebvrglMKETDvLz0zjeqiKDWmkI+t/MCweQNHvfFHDfYCzflcU2GGGgOYaQ3sM2kEP//wHlY/vv6axSZfn9hvWwAOnlq4ZpNeC1FsNmc7BzaFbTtVtpXPet1BtmvM+58vDHPinhOznrdbSpLotGBNPqVgy97acexgy56FiZIFNaDAZCFo5GP2mvbdPMUUug1b8o9e92pOlMpdC6s7IGpOv2YmR13yaKAUzMmFji+4NFU7FSkFEZkkIkf5jwfo/grNQCnZCNnNX7zH0S2F0mIK+dhqYKROp1bG+WUZ8i0SuuXM/bnlzP2D56alYHNR6XHCnKUfsfNYAPYMZbGE2XvbrVhw0XEF24ZCZuApduMGv42xm01h29xVmcV6RjzCUnNJf0a+4HxY8dvO2ZD2bEshX3C1JXS9tCcTQc0nk2IDczGLDTxXVWuLFAw0m6d/nZ+5VE4g35aVlakoa1YOrnygNhWL/snMxWva+nEZSXbKTkkVkTOBs4ARwBRga+AKGtQop1RKceOYN2rQnKaIi0Kvbg3PZMs1lcM+6VIY7Oec7zrRHrA8YIq3QO2WM/fn2YVrrG4hk8BSMAaHY3YZy8l7T7T2XSgH/fsUO89W95FRhkMPPG1+o6Hs/STYvy+l+xbkZhplgtl2GcIpsOYq50FtLXT1pnJ+v748gc/wWD9l9GCrNTS4I5lVliXM8btP4Nm31tKWTHDDk29Z9xnQ1sLG3lSgAMyBM1MlOLNNp0uX0/PZNgDbij/2p9O0lTBXtR13vRGX07JmWdi++PUor9GMVHIHfxHYF3gKQCk1T0TGVEWqOlDKjN28UfVAaHMRZL/HUwrhG6hcSyGRyAxM5VjYD339sGC9Qj4OmDIyUBAFZdGriI3BMCFSNYUAsMof8EYWkVlbBeZNr624jtaWIEffNrPW7qPWZAJ6U1nvtfWOzrdmIjxzNov8DfCVwtBQVdp87p2wApiax3U0flhHQaUwsK2Fn314dy5/eH7efQa0ttCWTAQzddN6eWaht2bFtNRe8X3w5WR3FVrRbFoHff0KSjCKbfeT2dtEK3mb27UeK6mbkUrcRz1KqeDsi0iSaGn/saAUSyFrtWzEQLNWBrmWQvbnRvXPJkS46X/246GvHRZp/zDbjRrEMEu57HLIZGBlZK9ONru3ghoyN/GYoe2Fdg9iLeYAmbHmchfcmbQalkJ4P3P8179/vgly2DXVYVoKvpU2ONTjOl/zl7Di2WG0XSlsvVV+95tIxtIpdH0NH9hGm9G6tLMns3DytXe8hormYP7IayuA7J7iUbG5j/RvnNV4qsTUUdvAbvYn0fehed9lmhnVfiV1M1LJ1O4RETkfGCAiRwNfAP5VHbFqT7lKIcjRL1JiQgfoclJSQxfi0AHJrEY3+WWAg3Yo3lCnWvzuE3vn9R3r72ZmP0Wtw1SMCz+wCxd+YBdWd/UypD0ZNLHJh461rLHMDos13tGuqWIlLQL3UR7VF85iGmIoAO02GtDm+e/1rHjpOnsz+fB53Da03mCvbYfz3MK1WXGGcPkOMzhcaFY/fdJWvL12U/BeW48F01LQE/rRQ0pXCtaCeJYqqaXWITMzopat7+ampxZykGHtpizBbH1PbupN8ezCNbz2Ticf33fbkj53c6YSpfB/wP8Ac4DPAXcBVxV7k4hcAxwPLFdK7epv+z5wJrDC3+18pdRdFchWlHJ9+0HzF+NeM292TYtlgddA34drMnJQe0SlkDnOC999b9ESzZVy3O75B+NEoBQSOdsqRc9wRw5u51vH7lx0/7F+M/aJwwfwij+7zVRxzexnSz/Vvn9bsb/sQLP3P18Ji3AA2rQK9ORhcHuSViN2kY+wNTIu1Gz+L587gLfXbuK2Z5cE24YPaGV5Z0+gHMw4UCFLYfLIQbQlE7y+sosnXl+Vda3q60s3agKzblLp947t3OlN2YHm0o5tuo++cutzPPnG6qw1GtpqsN3v3f0pPnS5l/brlEKGstxHItICvKyU+qNS6iNKqQ/7j6OMVNcC77Ns/5VSak//r6YKAXKzWgqld5oKwFprx3LjtVj87kM7WukM1TYaOTiaA9Ucd4YNbC0aH6gl+iuZKZ1S1pVUOaOHtHPjZ/fjko/tGWxrswSLbb+RzhIq6j7S2SoFLu+9th0ePB5sBJW1i2TU4PZIGWRh5TpumKcUPrjXRLYdMZDWlgSTRg7K6i6nj6sHQ1tDJBsD2loY2NbCC4vWcsofn8xqAGSbsdvcPVEplOlTiVIw91+02kvzNSdeWhmYloKtkdVm0BamapR1KyulUsCrIlKyelVKPQqsLudzq0m4RHXB3gQUHlysSsESUxg7tD0rMwKi+2erNROvBmZ7Sk0j5Tt46qiseImtNpMtBqTdX+ZrrTZLQYqvmbjpf/YLHps9Inr8wWjEoLZoE4DQaZzop+7+6mN78ug3Dw+2mwp5mB9XGdia23bVphT0MaeOHZyVHNBpuI9sqcA9FVgKhcZ6c3DuT6uSjp/V6tSPL9jiNd3GMbX1YGZbVbqAbnOikvndVsCLIvJAlfopfElEZovINSKSdwmniJwlIrNEZNaKFSvy7VaUsLsnMxjk7mtbvGaLM5jYGs+PCbkCwG4p2GSoVmGyahDMpo0RLA7iTfBn1bbf0mop2NxHRvaRjgfoc18orX1gWzIIercbsZZdJg4DPKUQZQJgXlffPnbnvK1FzWtuvP+9g0G9yPc+Zd9tePrbR7HTuKFZrq7Zi9YWlC2wFCIM2nfOfpul6zIL9Ar1mTCPd+vMRex4wX9YtHpj3v1NTAtEZ32ttPR+0JZCfyoduBlNhbLzd+/mb89Eb9e6OVOJUvgOXmzgB8Avjb9y+D3eWoc98Tq55T2OUupKpdR0pdT00aNHl/lxueZxMogB2FbDGgogketesPYXsCx4sqVX2gYKe6+B3O/QKNosaZtxsGTu+sp7+PfZBwcDZsIyYzZdRQP8mIhNKYgID339MO4555DMqtgiro1tRnjBX9Py+NnJu3H7Fw5k9JB2timQMaRJCJxx4GT23nY4Zx6yfd79zGtkz22GA5kB0rRorM2ZEhIEi03/+1VFikMGMQXjPMxdso4p59+VtUK7pz/Fl25+jk9e9RQAb6zYwO3PLSEfpgvoz08vBGBhRKVg3sf6u9gshaCFaVbnw+z4ztf/+gILSmjZurkSi34KSqkgmiUifwTurNax8xGumqhdItZy1BZLwZw1mj2L9Y1pq6wZTksEu6JobcldaBWHQVdjW+AVB4YPbGP4wLZglmnOToMGQslEMKhZYwpGP+ZRg9sZNbidmW+uAmBFkYQA7dtva0lwxaf2ZurYIQxsS7LXtp7he+AOo7juCftCMk1ChO9/YJei39UMCn90+jYkRFi/qY9f3vda1gy4vUC8C6LXzwK7pXDr0wtJpRX3v7yM0w6YDGTWO7zjZ1j9o4BCgGwl0xVaL1IM01IY6BcTXLY+Vyk889YaNvb2ZykCM3XVJku9+cldL3PUzmPZd7sRDZMBKrAUQv0UukUkVW4/BRExU10+iNf/uaaELYXM7DJ3X3NAfm2ZZ3o++lrGdZW05LvbOoLpomhmUHKQRVHYXEVxUgqZqqul12GqB3qhmOki1JlS5mCjB8Tsjm+5rjGd/rl4TeHZq65w2t6a4H27js+qNgtw1M5j8/Y50ERVtNn9HoTTD5wcNE5KFbEUzN+qlFIPZvbRg68sY+abq4Pr16zuq9t/Fur5bdJncUdFLXdhrmvQSv5t322l70ftBtzQ3Z816NuUQiO58tE3+Ogfnmi0GOUrBbOfAjAAOBm4vNj7ROQW4AngXSKyWEQ+C/xcROaIyGzgcODccuWKSo6lYHE5BDIbj4+z5M3ri89abtl484hB3k07PCsomvt5tm0xGnMzdYlSuTPxOKDrDJm/sV6TYFMKJrZBdN/tRrDdqEGcfeTUgp+rg7b50kBbEsJ3T5hWMCMo6u9sXiP6mm0LlLVdKWhL1aYEo2Aqhc9cO4uP/uEJBvvfucsIUmsF0dqS4OWl65m5wMsrue3zBwb7mPeFTQF05ylBHiYVClJDJtVVTw50gccuo6QHZJTCZw/OKOpGte2MUxnvqtQl8FNR/yEi3wPOK7LvKZbNV1dDjlIIZ1cE9WuKWArH7T4hxwVguo80ZmmE+849hPXd/cxf7lkZ5ie3JBLcetb+tLYkglLJZuaSnsnFyVWjB5q4drPSmUjeIO25EoKS2IYi0IFmZXEzmdsGtSd56OuHRf7cYr9VoYE/qkVoKuGWkFLIt9+wAa1s6OnHnHOcsu+23Pr0IqaOGcy85RsKfqa+ZXqMgXNge65SyJQWEd7/m/8CsMuEoUFAHPT6HO+3sblswv7+fJj3cfYkRYIYw2BDRlMJrvWVghnXy9cjvdbEqWJrJQXxPmQ8TQDTAfsyzRiS6z7SboMMuqCaeZ/aJoHaysi6UY1A89SxXvFYPRjst91IHn51RXC8/bcfGVqan3F16JzrOFkK+nv2p9Nc9om9Ijf7qRfbjBjA147ekeP3mMDhv3gYyFhx5qCg5TbvRz2wFsqWyccn9tuW9Zv6OHLnwiXACg38UX/nrLpTCe2+LGz5jB/WwZK1m7LcR3tsM5w3f3oszy9aywf9hVzFMGfTWsH0GSdxvX8tm5bzhOEDslylxToXdvelue2ZxUwYPqBgPS7T/WXK1ZFsCVyG2n3kKa6MDPOXeUpw6piMm6+nQampcarYWomlcILxuB9YAJxYkTR1JGwmZjp9ZWhtSdCfToVmfsIZB05mx7FDOP/2Od5+Ce07zexnCzTvte1WPPKNwxg+sI2f3f0KkKnAaloZ+jjZSiE+WiFjKaQ5fvcJDZYmFxHhyyFXj3bpmBVM9QzSFpAux4swZfRgLv7IHkX3K/RbRrUIbW4fWyVd05U1YfgAeGtNTuVbEbFWo7WtwIfsgoxdltcfm+/1Nhg7tIO3VnlxmHFDO7JWwBeLQW3qS/Gtv3v314KLjsu7n+kizAqwtyaC76TdSBt7U1nZhZ2+5bCHn70FmT4S9SZO7UIrUQpXKaVmmBtE5CBgeZ79Y0VYMwc3WVZWkbCpL5x6SZAdEiiFZK6lEFQ1DX3upJGDskxtW+G8pJEpk/ncOCqF+MxuiqFlNnsl68BwltshWJNQu+9W6KeM+jPbqvSOG5a7DsZUHvr7FjueVgYD25JFi8bZCtItXuMFes1J0qjB7da+1/nIV5vsrOtnsee2w/nCYTsA2fexmTLc1pIILHitLC99cB5vr812Zuw8fmgQoIcGuo9idC9VEh28NOK2WNKXoxR8/7KxTbd1tFXMNLFlWSQN91EY23oGeyOfzE0cI50QlCYuVtY6TugByszL14Fmc2BJWmIK1cbWuU4TVfnbguQ2pWArCmgbgEzloQOzhZSIRqefmqdr3Sbv+ljZmUnhHTm4LeteiGIp2Lj3pWX8/O5XAVjR2ZP1XUxLoTelgliLVgrPLlzLO+uzlcJuE4dlnSMXUyjDUhCRA4ADgdEi8lXjpaFAvJzLBQgvRLKZ422WjCQJWQ1plfHvtkac2WeX4s4dIJKG+0gTp5RPnWUTpfdCXGi1uI+00jVN98AKquFNGvSjaJGcwSDqz9xhcfcMaU/y4X22ZvvRg4JtprWpz4Etw0afi2RCgoVe244YGLh/8qGDyuYx1/od2sxFZOG6T/naqOpBWXd5y8c9L77D5254hj22HhZsMxVEKp0pDDioQJ+PXSZkN56KGuCuNnGKKZRjKbQBg/EUyhDjbz3w4eqJVlvCsyVbgFEP8rYuXJDxSbclcwd2fQPa3BDFVj4HgeYaVCGtBh/aayJ/Pmt/PrBH/OIJ+bBZc/r8mgOz9nvbcuerhf75beXXo1sKtlXvwi8+skfgWgG7UrBl++j9WlsS/PRDuzF1zGB2mzgsd79QpkWXTSn4gWbdKOmsQ7bnmF3GZr3P9j1NhV2sn/hCX1m97JesgNz4gj7PhZo/TfRXmd/+BS9dtnGWQhPHFPyVzI+IyLVKqcLLM2NMeIamZ+UqK6aQm5FkXss7jRvKzAWrA7+rrRCZbQaQVUvJMjBkAs1mv4ICX6bOJBLCfts3h5Xw0NcP47VlncEgYvq59W9u5q4HzexrmK8uhqWQ77ViRF2J3NqSYOzQdsYO7Qi+u819pL/36QdO5uR9tubkfbbmN/fPy9lvSEcyGOwhE2jW51AplTPLP2aXsXlrOGV9p2QL4L13rXGMhas28ot7X+XnH9492Bbcv8ZX6UupoIx9Kq0CxVPIDTZykJeOuq1foqSWsaRCxMlSqCTQvFFELgZ2AQJnplLqiIqlqgNh95EtxztTW99ITzVUxG9P2YvLHprHmCEdXoqpcT8Hq34tN2Ax36reZs4G47ROoZnYbtQgths1iGtn6Lo+mfM42s9Pnz55q6BImlbEtVzElLEUyl+kWEp5isf+z7slf//w64D9u7UlE8z78futZbd1n2nwYgNZSiFkKWzsTdGbSmf1GNExChPb9Wxe72aNokMufgggyzINlJChFfpTaYZ0tLK6q5d+oz+6aYEAbD9qEG/4NY5GDfHcWnpy1p9SzFm8jjdWbuDEPSfmyFgr4hRTqCTQfBPwCrAdcCFeSurTVZCpLuQLNOdzHw0NFiZl3jNuWAc/Omm3YNGSebO1F7AUTGyzRW3uxq0KaTNjCyCPGdrB/V89lO8en6k11GaxHqqNrcd1+LVi2NxH+WhtSQR/kN8Kam1JhHpQeI/NK3hsqNKvVgr3v7ycB19ZxqlXe0XwdhqX8dWb/alP3X8SZ+Up9GcqOlv2UZeR6bSxTyuj7ECzDiqn0ir4LgNDSuHK06Zz9enTec/UUYGloJti9afTnHDZY3zl1uetMtaKzSX7aKRS6mqgTyn1iFLqM0BTWAmQ20+hcKAZdvcDWp3duSl4elGOufAlU3Kg8OBisxR0ipx5E8QpptCM5Bvsdxgz2FoltZa+Zf1b2mtcRTuGLdBcDD3I9/VHG4AyNa4U0ydtBeQWdTSv0c9cO4tnF64Fsjv3mSmfPzxpV87P01HPXG1uC/iavUi6Lamy/WkVuMF2nTA0WFhnnqs7vnQQO4wZzJE7j+WGz+6XkwnWqBl7nGIKlSgF7fRbKiLHichewIgqyFQX8gWazY5mmZIHcMlH9+QLh01hb6OYnUbfKGa9lkxmSxFLwTIK6EwNcz2DUwqVMdSfQYabHIXRA2dNLYVE9meZj6O6CcML0KJgLjosZf90WgX9wcOTp64ee7bOrhOGcekpe3HpKXtZF8bZpO8wjm1rerPeWPVvWz+RSiveNW4IXzhsCleeNt2a7m02YzLR92GqzjP27r4UP7zzJZaujU8xiEpiCj8SkWHA1/DWJwylDoXsqkV44ZW+UbYa2BY0VQ+CxUoxYlAb33zfTtZjaZN1k3GhthWIKZjYZou6WYt5wzmdUBnar93Z3YdIdkKBSRB8rmlMIXewakl4Pvha/s4f2GMC/3rhbT53qN19E8YssGdbOwOZlFSTc4/akYOnjipZviz3kWVl8XqjlW2+dQzJRCK4T7WCNedl+ZSC/i1qmYps476XlnH1Y2/y4CvxWfNblqXg92ieqpRap5Saq5Q6XCm1j1LqjirLVzPC7qNJI73c7nOOypRHCNJKi1woej/TytCDS7H1BVal4B/HvOHKmRk6Mmi/9vrufp46/0j+/oUDrfsVyuWvFvqXtBW1q6VFOHxgG3/93wODUuDFMFM537frOAA++u5tsvYJW1R/+dwBfOWowtVk82GeD2tMwbgf8rn3zCQnfcuYccIhlqA3eArEU8z1deO8tcoLeK81UnC7+1K8aqTa1puylILfo9lW7bRpCM8IthrYxoKLjuO9u4wLtpk+1UKM8btYnbJvpmV1Ju+7dKWwna+gzCJ5TidUxtZ+PvrR08YyZkgHe/uNb8JM8PsXv3faOOvr1UAslkKm/0bNPrZkhhjxg6ljh7DgouOs7lOzKYytkZSNsO7zFoJm7jOb+2hTb2ZbvomabQ2QmexRaJKWTAidhjVSy1Xtmk1Bm9DMZ512zUyO+fWjDSvjXYn7aIaIXAb8GQh62Cmlnq1YqjrQn0pnuRFsEzRtzhb7cSaPGsTz3z2a4QPbuOAfXn8grRSK5WfbMlB0L+fJIweywM+vz2f2OqIxfGAbs7//3qD+fz5GDW7nhe+9N2tArBXmtWFbxNhobA2gbPKZcYaoSiGMWSYe7JaCWWcp33oCU77vnbALHckWjp421rpvmGRCWLfJ/AwoMqerGJ2cssH4bjPf9PpPbOjuD7wG9aSSK39P//8PjG2KJslA6k8r2oy2l7YJhE77i5IuNnyg/ccrxVIY3J706t0nhPu/eihbDWxlnx/dDxRelemIhi1fXnP2kVN5eel6oPYKWP/iZpJBog7uo1IZbKm6aqO1JcHQjiTru/utlVoL0dbitUdNiGQN9Db3kKko8t2S5gLSsUM7uORje0aWpSUhWW6cvlSalkRtK/fo2IlNx23o6Wfh6o1MHjmIYQPrNymspEfz4dUUpN70pxRtSbMXsmUxjV7IVEa6mDZvi3UkMweGoR2eUhC8VEnwUug2FalU6aicrx69Y90/096UKfr7p40fyivvrK+2WAFRraXWFm8S8/CrKyLPbPXY3e73zG5JSNHKqWZwOZ9rpxL3W7IlkbWSuh7pqYX6NyxZu4mPX/kkR08byx9Pm15zWTSVNNkZC/wEmKCUer+ITAMO8NcuxJ7+dJr2ZAIdzinoPoqY1519/GhKwbQUhg5o5e113VkB5t23Hl7yZzuaA3PhYjmB5ju/fHDVZTLJF5S95KN7MGP+Km57djHgVRMeM7QjJwgdhfbWBJ093vcOrzwOY8YZ8i0KrSQhI5mQrGB2uOpBLegukPo8w+9LoUuR14tK1ilcC9wD6LXnrwHnVChP3ehLqaziXrabMSiOVsbFoW+oSSMKZ3qYs6Mff3BXdho3JKfhu2PzpM0aU4j+/kRCapqVlm+Q/tDeW/OLj2TqEBVzkRZCp7gmpHjpjiz3Ub5AcwXut2RCsj6jPpZCfi/Ayg2eK6ve7c8r+bhRSqm/AGkApVQ/0DR+jlRaZa1ktV1KA3w/fjk56wfvMIrffWJvvvG+dxXcz7QU9pk0grvPOaTojMmxeWDrlxGnmALAf77yHqtFIiLBpClcOTUKuoSLrlTbkhBG5InLaUz3Ub6U1HxKctTgdg7dcXTB47e0SNbM3RZL7Eulg+KKS9dtsjYZCvP22k15XcCFLAXtMdjUm+KR11bw+RufKZoeXw0qUQpdIjISvzSKiOwPrIvyRhG5RkSWi8hcY9sIEblPROb5/+05g1Wgpz/FwtUbs5WC5VrSi8jKqUvSkvCW+ttWc5rEKdvEUV/M668cS6Ee7Dx+KLtaSmhDZmZvKyYZFX1/tCSEc47ekS8enl01YOzQ9uBxdxSlkOcEzrrgKK77zL4FZUkmElmDd18qnTMIX/ivFznk4odY09XLAT99kNOunlnwmAAHXvQgn7nWXhaukKWg3VfdfWm+cutz/GfuO9z69KKin1cplSiFrwJ3AFNEZAZwPfDliO+9FnhfaNt5wANKqanAA/7zmnD9428xf/mGrIU3tmtJ12wpry5JzO5uR2zQFTqzS6jHL/uoGLrOUDmWgo6nmIX9Brcn+cYxO2Vl2n3n+GnBY3PAztdLuRJXSzIhWSupr/rvG2x//l1Z64UeeNlbebzaz1Ka9daagsfUAfEn3lhlfb2QpaDdV5v6Uozz09Qfea32K58ryT56VkQOBd6FNwK+qpQq3C4p895HRWRyaPOJwGH+4+uAh4H/K1e+QuhyuWYdHNuMXaeZltOLuInubUeDMK8r07feLOj1CQPLWJugu6FlmlFlXusI9YvWmANovqydSpRqS0KyUkOve+ItwHMT6TRlnTa7JGLwt5jrOYqlsLG3n1Vd3vd6Z31P3v2rRdl6VUQ6gLOBH+KVzv6iv61cxiqllvqP3wGsK05E5CwRmSUis1asWFHWB43y6+ibBbZsl5IuohYuvRuF4W6xmSMPB/gNisxeANq33ozuxHLuDx030wFjc42CGXAe0JpROKZlb7qPLjguU3W1EqUQLmOvD2UW39Nj/KI1hduUamwrs00KVePVlkJ3X5oVnZ4yeGHRWn5450s1bcpTifvoerwGO5cCl/mPb6iGUMqzuazfWil1pVJqulJq+ujRhQNH+dA11M3sAtvNuO2IQXxor4nc8aWDSv6MEU3U1N5RXw7fybtuzVmpnnU3k/tI3z6DylAK+j06s8/03ZtKJp/C6elPsc2IAZy6/ySmGX2WKzl/4XLk+ljmgjbtDlq4OppSMN1cvf1prnz09azj9fSlGJlnrAhnPW4/yit/c/Vjb3LBP+ZE+vxyqEQp7KqU+qxS6iH/70w8xVAuy0RkPID/v2bOs0kjBzJ55EDOPSqzYMl2KbUlE1zysT3ZYcyQkj+jGWd8jvrQZpRkD7Y1oftIz+4HlLHaXruc9OzfnPgOMCyF9jzNhHr60+w0big/PGnXrDIblcQUwqux9U+xpquPuUvWsXJDT2DF5Ct1PXvxWlZ3mYN+ZmC/7vEF/OSuV7hlZiZY3N2fDvpEhwknuJy8z9bB41tmLsqKdVSTSpTCs37GEQAish8wq4Lj3QGc7j8+HfhnBccqyKD2JA9/4/Csao7mDOM9ZZT91dx9znu45cz9i+/o2GLRHf1Ml0kzWgpa/HLcR+/3q67qYnpmMseAIN4geYPYvf3pYE2CWT+sknUbr4Qqk2pPwsa+FMdf+hgn//7xwO21qsvu2//AZTM48XePBc+1pdCSEF5d5h3fHMx7+lJBscYw4aKdU8cMZsFFx3H5J/cGvFTXWlBJQZ19gMdFZKH/fFvgVRGZg+cB2j3fG0XkFryg8igRWQx8D7gI+IuIfBZ4C/hoBbKVjHkvXl8kda0QZhtCh8NGYCkY27RSaCKdYFgKpSuF90wdzRs/OZY75yzl+ifeygq6a0tBkILprloXmLGASpSqrTcEwKoNngJ4a9VGdh4/1N/Wm7VPXyodWBaLVmcGax1TaEkIC/ysM3Mw7+5PM2FYPkvB3kdeN+Fas7E35z3VoBKlEE4pjYxSKl/Z7SPLPWalmJeSc/04aom+ubPdR7mKIu7okhBbFVl0lo9EQoJuaylLTKE3lS6Y7qoVgK0vRVny5HnvW6sy8QPdh2WloRT+8dwSzvnz88EM3kRbCsmEBGmsnd19nHfbbB6bv5JUWmX1sDbJ1x1yq0He/mu6YuY+Ukq9BawHhgEj9Z9S6i3/tabCKQJHvcj4wDM3va7gum5jbW70WqBTurctUsqlELbSFgPbM9sKWgoF+lKUw5eP2MG6Xc/sE5JJIzbdR7pr2pwluWt3A0tBJMh27OpNcevTi4KaRh154ibhQHN7nSyFSlJSfwjMBn4L/NL/+0WV5Ko7Tic46oWe2ZqzY10VVy9sawZ0n4KtKijrbFMKZonzQgUltTJoNWMKFdzH//Mee5tSHQNIq8xAbVp5Ol1U/zcxMxz1cbpCbqp8VQ/C1ZnbWrz9hg9s5QN7TGCbCpRxISpxH30UmKKUqo26qjNOJzjqxUE7jOKIncZwwXE789CrjwBw0l4TeWzeSv43Yv/kOHDZJ/aiqydVkZVtmyWb/SwKWQr6Y7OqzdYgfctcz2QrjjnXtxCWW5SCTrXt6u0PMqwWrspOZx2eR6nmcx+1J1v47Sl7RZS+dCpRCnOB4dQwdbSe1Nt9NOO8I1yfhC2UjtYWrjnj3VnbBrcnueLUfRokUXm0J1uK1vYqhs1SMJVCoR4LQfaRoRRqcR+b2UK2Omid/sx/+fpMmuqm3hRvrNwQBOPNRKLOkKWQb8YfrqTQXkGNqVKo5FN+CjwnIveIyB36r1qC1Zt654dPHD4gcBk4HFsq4QVjkK0URIRff2xPa4XTINCcqE6gGeChrx/GN47JrmzcZUzeCpWtMN1HX//bCxz328dy1hKY7UpP3ttbd6B7socJ11yrpPBgKVTyKdcBP8NLJf2l8deUuJiCw1F/bOms4TagJ+01kR3H5k6gdFC5Jct9VJk8240axEl7Tcz7eqGKyauMRWtPveH1WTYXsgFMGJ6pBPTDk3Zh9vffm7dbXSqP+6jWVPIpG5VSv/VXMz+i/6omWd1xWsHhqDe2cjC2xXA2N5W27k1LoRruo9YCboNNfamssh75elJrMVaG1jPsMiFThnxgWzIIqn/T0nclHGgeXEbhwXKoRCn8V0R+KiIHiMje+q9qktWZZiov4HBsLtgCwzaXki0grd9ra2taCcki5sZ+fkFDgMPeNca6jw4w64Vvmn0m2dvEfOGwHfjRSbtmbQtbJcU601WLSlSPDn+bNR0UcEQFx2wYbp2Cw9EYfvPxPbN6KNjWGtgtBV3mwlynULk8xTKYRg+2N/4x0VlKYffRiEFtXHDczllF/DThxXP1aAdqo5J+CodXU5BG41SCw9EYTtwzvw9fM3ZYblV+PYiaE7pq1I4q1nPaTCE996gd6e5L0duf5qk3VwfbdbntcGC6JSF510Pk00X7Th7BAVNG2l+sAZUsXhsrIleLyH/859P8ukVNiTMUHI74stc2w3O22QbRaqxTSFrMjW1GZOoTjTIshWkThnLDZ/dj1JD2rP31LL831C+hUIptPoV285n7ce7RO1pfqwWVGFvXAvcAE/znrwHnVChPw2im6pQOx5aGLchqUwDVuI9tA/f2owYH/aJtqeT5ekqEF7sVUlr5RK/32FSyUhAR/euMUkr9BUgDKKX6gaZdjeV0gsMRX2xBVlscsBoDaCIhweCtlVFLQjhyZ6+sh2k1aAbm6SkRXoBms0KCz80je73HpnJiCjOBvYEuERmJX9XL762QWxGqSTBNQoejXjx1/pF0djdPEbx68dDXD8vy7ZureVtbhL6Usq5JqFaZi9YWIZVWnLDHeB59bSVnHzmVaeOHcvzu461Nt/L1lAi7jwrJZ9MXIvVPgilHKWgJv4rXGGeKiMwARgMfrpZg9cYpBUcjGDu0g7FDK2ltvnmy3ajsVb5mRlIykaAvlbLOrKuVWt6aSNBNmonDBzDjvExC5YFTvAZcV58+nQnDMxbDYe8aw+UPv55znLD7KNwHOus1i1ZohFu7HKUwWkS+6j++HbgLT1H0AEfhVU5tGiYOH8CStZtqUkjL4XBUn2SLQF/2rDuZEPrTqqLS2SZ6lXRLHnePdiVp9t1uBOccNZX+lOKyh+YH23tKsBRstY0aMSyVoxRagMHkZnHWpo5rjfn32QfT2W3vuORwOOJHsGjNGDE7WlvY0NNftZl1poFP9OOdc9SOvPpOZ5ZSyLEUCozytjIWjVg/VY5SWKqU+kHVJWkQwwe2MbzMzlEOh6P+BIvWjKBCezLBhp7qrGg2KXUVcbjsRSnZRzal0AhLoZyUVOdncTgcDcO2klkP3tVY0Qyg/JLXlSqF3HUK+QUstGq7npRzChvWR9nhcGy5nHXI9px/7E5B1pGpFNr92kjVGkR1Imm+Vpn5GNyezFrxHE5JLT2m0ARKQSm1uvheDofDUV3OP3ZnzjpkitFcx3QfebPsaiWM6HabtuJ8hRAR9t42U/QuXOai1JhCswSaa4qILAA68RbC9SulpjdWIofDESfEEgTWM/pqj6HlVCbdeqvcxW2aki2FBmiF2CkFn8OVUisbLYTD4YgfemA100X1jD6cAlouetZeqvsIYPyw/Eqh0DoFu6XQBO4jh8PhaCRaKWStePYH73ylrEtluN8StJxuZ/l6JkDhQHObZYl2s2Qf1RoF3Csiz4jIWeEXReQsEZklIrNWrFjRAPEcDkcj0QNl0mIpdPdVx1IY7Vc9Led47568FT87eTerq6hQ97T2iPWdak0clcLBSqm9gfcDXxSRQ8wXlVJXKqWmK6Wmjx6d28zb4XBs3mTcR5kBc/pkb3Y+blh1ytX88qN7cOr+k9hr2+Elv1dE+Ni7t2WcpXxJIXdUXCyF2MUUlFJL/P/LReR2YF/g0cZK5XA44oK2EEz30WcP3o4Dp4yydjQrh/HDBvDDUHvMUrFZCoVm/ub3EfEyoKQBy8JiZSmIyCARGaIfA+8F5jZWKofDESf0bNtMSRWRqimEalEo/dSGqTAG+aW4W5Mu+2gscLt/cpLAzUqpuxsrksPhiBPB6uWY11YoJ0itGdjm1XKyuZRqTayUglLqDWCPRsvhcDjii1YKPVUKKteK7UcP4pV3Ost676D2JHT20NoApRAr95HD4XAUQy/yqtaahFoxeeSg4jvlYahfQ6kSa6NcnFJwOBxNxYBWnX4a7+6/lQzoQwe0Ft+pRsTKfeRwOBzFOO/YnUgpxft3G9doUQpSietnmK8UwgX16oFTCg6Ho6kYM6SD33x8r0aLUZRwg55SivVllEL9XWTOfeRwOBw1IFzSohyl0O+UgsPhcGwehC2FI941JvJ7hzr3kcPhcGxe6MV1yYRw31cPZfyw3LIX+Wik+8gpBYfD4agB5orm7UZFS09tSybo7U+zzVYDAVjV1VsT2Qrh3EcOh8NRA8rJPhriV1GdNNJTCql0/d1HTik4HA5HDdBKoZRhXVd7bU8m+OR+23LVafVvPOncRw6Hw1EDCnVZy8evPrYnzy9ay5ihHfz4g7vVQKriOEvB4XA4akA4+ygKA9uSHDhlVA2kiY5TCg6Hw1EDCrXejDPNKbXD4XDEHO0+Uqr+weJKcErB4XA4akAjeiFUg+aU2uFwOGKOzj5qQFZpRTil4HA4HDVgSEdzJnc6peBwOBw1YFgDeyJUglMKDofDUQMa2SinEpxScDgcjhrQiP7K1SBWUovI+0TkVRGZLyLnNVoeh8PhqISJwwfwuUO3b7QYJRGbSIiItAC/A44GFgNPi8gdSqmXGiuZw+FwlMeM845otAglEydLYV9gvlLqDaVUL3ArcGKDZXI4HI4tijgphYnAIuP5Yn9bFiJylojMEpFZK1asqJtwDofDsSUQJ6UQCaXUlUqp6Uqp6aNHj260OA6Hw7FZESelsATYxni+tb/N4XA4HHUiTkrhaWCqiGwnIm3Ax4E7GiyTw+FwbFHEJvtIKdUvIl8C7gFagGuUUi82WCyHw+HYooiNUgBQSt0F3NVoORwOh2NLRZqt1reJiKwA3irz7aOAlVUUpxLiJIuNOMkXJ1mKERdZ4yJHFOIka5xksVGJfJOUUtZMnaZWCpUgIrOUUvXvim0hTrLYiJN8cZKlGHGRNS5yRCFOssZJFhu1ki9OgWaHw+FwNBinFBwOh8MRsCUrhSsbLYBBnGSxESf54iRLMeIia1zkiEKcZI2TLDZqIt8WG1NwOBwORy5bsqXgcDgcjhBOKTgcDocjwCkFh8PhcAQ4pVAnRORDIrJVo+VoBty5Kh0ROUJEBjVajmbCXWd2NkulICJnisjlIjIlBrJ8SkSeBA4GuhstTxh3rkrH7+nxQxEZEANZPikizwCHA32Nlicf7jqLTqPPVaxqH1WCiAiekvsw8E1gKbCfiCxRStX9h/flOQO4CjhQKfVUvWXIhztXpePLmAT+B/g/vMHkXuC/DZInCZwDfBt4v1LqyUbIUQh3nUUnTudqs7AURKRDeaSAZ4H9gN8DhwA7N0Im5eX6Pg3cAvSISEJETheRhsijceeqdESkzT9nfXjnbGfgD8CnRWRkI2RSSvUD84AbgbdEpE1EThaRCY2QJ4y7zqITt3PV9EpBRL4D3C0iXxaRXZRS85RSq4G/AQK8p15+QxG5UESOMzbNxysFfifwAnAAcI2I/NTfv67n352r0hGR7wE3i8gZIjJCKfWUUmoT3k27NXBUvWQTkfNFZD9j0xN4BSH/gzeYfBC4TkS+7e/fqHPmrrPo8sXmXAUopZr2D/gM8DCeZv0B8A9gsvH6e4HrgCND75MqyzECb3XhGrwLrdV4bWvgAmCK/3wHPNNwgjtX8TxXhjzn4rmIjgRuAH4DjDdePwX4J7B9jeUYD9wGrAXmhV47APgJsLX/fFf/3I5s0Dlz11mTnavwX9NaCr4PbhvgcuX5Bn8OzAV+qvdRSt0LLAB2E5HjROSL/vZqL+PuAv6hlNoKr4XoV43X3gZ+ppR63f/s+cDjwKQqy5AXd65KR0RagL2AC5VSDwA/BDbi+fHx5bsFWA8cKiLvFpFP1kicdcBflVLDgbUiYp6zp30ZF/syzQXuxiurXFfcdRadmJ2rbOqpGWugab8H3Gk8Hw3MBA4zth0ALMe7EM6toSyD/f/vxjNRx1v2GQD8GngIGObOVWzPlS7/cjHwJ/9xwpf3DmAfY9+jgU3AIuCzNZRpiP//YGAV0KblMvZpBS4F/g101OMcxeE6KyBLLK6zOJ2rSPLW40OqcFKPAMaFTzLQDrwEHKK3A2cDPzFO8n+Bq4GBtZDF9uP7n3dV6LXD8GYjv66WLHlk+ASwh3E+GnmusmSJ27kyPm+48dgcZKcC9+ErAf8cXYA/+OO5HZ4E/ljFc2aVJXTO/o7XrtZ87URgVh3PWUse2RpxnbUUeK3h1xkwwJSnkecqkrz1+qAyT+aBwIvA9cAOoROb9B9/EXjKeO2LwNeMk14V32oRWRL+Yy3TaOAVf1A5ANgdGApMrOG5Osq/gJYDZzT4XBWSpeHnypDn/cAjwE3At4ztLf7/Nrz0wD8br/2WjFIYQZ4JQhVlSRiDiD5nY4HVeC6iXYBt8fzkk+twzo7DC9L+BDjIPGcNuM4KydLw6wwvJvA43qD+SWN7st7nqiS56/2BJZzQFuBPwCdC282Z3Hj//4PARXim9T3ANxohC4Y2xwtKpoHngXfX6BwJnvn7F7yA1THA5cAX9MVXr3NVqiz1PlcWefcFngI+ABwK/BXYNbTPaF/W+/HWA0zxz9npDZKlw3h+lX/Ongam1emc7YPn3jgW+DheIPeM0D71uicjydKo68z/vZ4ETsLzLtyBoezrea5Klr2RH17kpG4FXAsMx5uxnYpnrnf4r1+Cp4UnA9sD/4s30/p2g2R5FM93KcDxwJvAN+t0rk40Hn8KeMJ4nsQLYtXrXEWRpWHnypDlXOBi//H2wK14Sk3PMC/Hyywahzcb/zGee+a7DZDld3iZKdPwLIdT8QKQdR088Bbt/dJ/PAAvY+ZZfJcX8Ms6XmdRZGnIdeZ/3q7AH4xt0/Csu9H+87qNXyXL32gBjJN2Np5vVpvmI/0f9VD/5vwL8Ge8RUOD8Mz4rULHaIuDLHgm6rA6nKszQ9tbgIPwZpHb+Nve5V+AtT5XZclS63OVT05gN7yslEuBxf7vey3wHTz3zPWWc9YeB1mA6Rixhzqes32B14AR/vPv4AVov+/fI7+u13VWqix1uCdPB442nk8G5mC4f4Ar8FJMh+BZLTU5VxV/l0YL4J+MM/BMrffhacsL8LT/RXhZAx/19xuCl3mxh/HevEGmBsiSrKYsEeX7FkaePJ6v9Gn8bJXQe2t9rkqRpebnqoCc38Gz+rYCfgWc4O83DS/wt2Mdz1kpsjTynH0bGIOnuO7Eixn9Cc9NeAWGwqzDOStFlpqeM/93+xveOofZ5nfHU+bXGc9H+PfDNrU6V9X4i8s6hSPx8obvBr4GdABfAL6LN/gOAVBKdQI3482eEBFR3tLwuMjSX2VZosjXjuemwZdrNl5dno9puQz5an2uSpGlHucqn5ytwJeVUmvwZpBv+fu9AszA/41FJFGHc1aKLI08Zx3AaUqpL+PdDz9QSn0a6MGb4fb4ctbrnowqS03Pmf+73YtXjuIZvHFC8yXgWBF5t/98A/AcoAz5qn2uKqahSsFYUv4cns8PpdQs4DE8P+544BvAMSJygohcgOeSeMnfV22OspQo35PARBE52N9P8IJVA/yLTlVbvjjJUqacjwOTRGQaXpDvKhEZiDcD3RVvzQFKqfTmKEuZcs4AdhSR9yilFiql7vP3OxZ4Q7+/TtdZ3WXJI5/4D69XSq3Fi0N9SEQm+Z+/HrgQ+I6InI7nddgF6KyHfOVSd6Vg1hYxLvQZQEJEDvGfz8W7GfZRSl2PZxIejJd6d7zyV29uTrJUKN/beEpLX2hjgK4a3aANl6VKci4GdlJKXQK8iucCmAZ8SCm1fHOTpUpyvo0XeEdEDhGRR/Csmys2R1kiyKcnOd3+/6fx6lD92NjnMrz4xj54K6Y/opRaV0sZK6UupbNFZF9gf6XUb80Zj28Sp/GqPb4IfExEZiilFovIGLwfGaXUgyLycDVmS3GSpYryjcMrwaD5ulKqd3OSpQZyjsULfAN8Fi91ce3mJEuN5NS/7QK8dOMXNydZSpRPL0Qzx4LLgL+IyC7ASrx42oMi8kgcXUU2am4piMg5wO3ABSLyfn9bC2TNBDrxgkXtwC9EpBUvgLNCH6dKCiE2stRAvlWGfNVQCLGRpYZyLtMyVkkhxEaWGsq50t9vYZUUQmxkKUM+pZRKi8gAERmsZfH3n4MXFB/qb28KhQDUPvsIb/n9XsDJwCOW1y/EW6yzE57b4Vo83/QfqH4WQ2xkibt8cZKlWeSMkyzNImecZClTvu/hlR3Z3X9+Cl6ywM8xKrM2018tTuIJeFH3/f3nLf5fB3AXcLa/PYGXn30zfglbY3tOCmOzyxJ3+eIkS7PIGSdZmkXOOMlSI/n2B7ar9W9a0+uliidzPPAvPDPvO8DLwDH+a7p2y5F4tc1HWd6f2Bxlibt8cZKlWeSMkyzNImecZKmRfLFbb1D2uajiST0BYwk58Dng9vAPi2f2Xeg/39c86ZujLHGXL06yNIuccZKlWeSMkyzNKF89/yo9kafhlZ9tBwaS3ZXqI2RKwJqF47bBW9C0Dq/eR1VOaJxkibt8cZKlWeSMkyzNImecZGlG+Rr1V3JKqp+GNQ7Pl5YGXgfOBL6ilFoqIq3Ka3A+Hi9DAOVF6AWvyuSf8PKOz1FKzSn18+MqS9zli5MszSJnnGRpFjnjJEszyhcLStSsus78jsCNehteDZK/h/b5F3CU/1gXrRoDHF4NbRYnWeIuX5xkaRY54yRLs8gZJ1maUb64/EWyFPy83B8CLSJyF17ubQq8/FsR+QrwtogcqpR6RETa8PL6XxORHwPHi8jhyludWdEKzTjJEnf54iRLs8gZJ1maRc44ydKM8sWNoovXRORQvEJPW+FVCf0h0AccLt5KP5S3yOT7eDnF4KVvnQE8gFfQ6yil1OpKhY2TLHGXL06yNIuccZKlWeSMkyzNKF8siWByvQc41Xh+OfB5vJP2jL8tgeen+wteW8B98crG7llNsyZOssRdvjjJ0ixyxkmWZpEzTrI0o3xx/ItyUgfiRee1r+2TwE/9x8/jlf0Fr/HHrTX+gWMjS9zli5MszSJnnGRpFjnjJEszyhfHv6LuI6XURqVUj8rU7jiaTB2gTwM7i8idwC14ZppZUraqxEmWuMsXJ1maRc44ydIscsZJlmaUL45ETkn1gzUKr6nMHf7mTuB8vLrvbyqllkBd6pjHRpa4yxcnWQoRJznjJEsh4iRnnGRpRvniRClVUtN4XaJWArv72vU7QFop9Zg+oXUiTrLYiJN8cZKlEHGSM06yFCJOcsZJFhtxly8+lOJrwiv2lMbrRvbZRvq94iRL3OWLkyzNImecZGkWOeMkSzPKF5c/XegpEiKyNXAqcIny+6A2ijjJYiNO8sVJlkLESc44yVKIOMkZJ1lsxF2+uFCSUnA4HA7H5k3dezQ7HA6HI744peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwqOWCIiKRF5XkReFJEXRORrIlLwehWRySLyiSrKcLaIvCwiN0Xc/wwRuaxan18uInKSiEwznv9ARI5qpEyO5qHkzmsOR53YpJTaE0BExuB1yhoKfK/AeyYDn/D3rQZfwCubvLhKxysZEUkqpfpLfNtJwJ3ASwBKqe9WWy7H5ouzFByxR3nNTc4CviQek0XkvyLyrP93oL/rRcB7fAvjXBFpEZGLReRpEZktIp+zHV9Evioic/2/c/xtVwDbA/8RkXND+3eIyJ9EZI6IPCcihxsvbyMiD4vIPBH5nr//IBH5t2/xzBWRj/nb9xGRR0TkGRG5R0TG+9sfFpFfi8gs4Nsi8pa2kvxjLRKRVhE50/9uL4jIbSIy0D8XHwAu9s/DFBG5VkQ+7L//SF/mOSJyjYi0+9sXiMiF/vmcIyI7VfzDOZqTRi+pdn/uz/YHbLBsW4tX0Gwg0OFvmwrM8h8fBtxp7H8WcIH/uB2YBWwXOuY+wBxgEDAYeBHYy39tATDKIsfXgGv8xzsBC8k0ZlkKjAQGAHPxSjKfDPzReP8wvDo8jwOj/W0fM475MHC5sf8/8dtA+vtd5T8eaezzIzJloK8FPmy8di3wYV/GRcCO/vbr8XoN6++q3/8F/Rnub8v7c5aCoxlpBf4oInOAvwLT8uz3XuA0EXkeeApvsJ4a2udg4HalVJdSagPwd7zGLIU4GLgRQCn1CvAWXt9fgPuUUquUUpv8Yx2Mp3SOFpGfich7lFLrgHfhVee8z5fvArwGL5o/hx5/zH/8ceO1XX2LaQ5en4Bdisj9LrxqoK/5z68DDjFe/7v//xk8V5xjC8TFFBxNgYhsj9dXdzleXGEZsAeeC7Q739vwZr/31EVIj3DdGKWUek1E9gaOBX4kIg8AtwMvKqUOyHOcLuPxHcBPRGQEnmXzoL/9WuAkpdQLInIGnqVUCboeUAo3NmyxOEvBEXtEZDRwBXCZUkrhuV+WKq+37qlAi79rJ15PXc09wOdFpNU/zo4iMih0+P8CJ/n++EHAB/1thfgv3swcEdkR2BZ41X/taBEZISID8AK+M0RkArBRKXUjcDGwt7//aBE5wD9Oq4hYZ/q+BfM08Bs895huGDMEWOp/v08abwmfB82rwGQR2cF/firwSJHv6tjCcLMBR1wZ4LtVWoF+4AbgEv+1y4HbROQ04G4ys+rZQEpEXsCbRf8Gzw3yrIgIXsetk8wPUUo9KyLXAjP9TVcppZ4rItvlwO99t00/cIZSqsf7CGYCt+G5gm5USs0SkWPwAr9pvKbxn1dK9frB39+KyDC8e/HXeDENG3/Gc5UdZmz7Dp5bbIX/XyuCW/Hca2fjxRL0d+0WkU8DfxWRJJ6iuaLId3VsYbgqqQ6Hw+EIcO4jh8PhcAQ4peBwOByOAKcUHA6HwxHglILD4XA4ApxScDgcDkeAUwoOh8PhCHBKweFwOBwB/w9rIgmvO/MuNQAAAABJRU5ErkJggg==\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "# start the figure.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(weather['Local time'], weather['T'])\n", + "# label the axes\n", + "ax.set_xlabel(\"Date of observation\")\n", + "ax.set_ylabel(\"Temperature in Celsius\")\n", + "ax.set_title(\"Temperature Observations\")\n", + "# adjust the date labels, so that they look nicer\n", + "fig.autofmt_xdate()\n", + "# save the figure\n", + "fig.savefig('weather.png')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py b/branch/rkdarst--remove-catfacts-jsonl/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py new file mode 100644 index 00000000..8742b5f6 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_downloads/75c4ab69c0f59fbb1589b03be360a485/optionsparser.py @@ -0,0 +1,38 @@ +import yaml + +def get_parameters(config_file, required, defaults): + ''' + Parameters: + Optionfile: FileName of the yaml file containing the options + required: Dict of required argument names and their object types. + defaults: Dict of default parameters mapping to their default values + + Returns: An object with fields named according to required and optional values. + ''' + f = open(config_file) + options = yaml.safe_load(f) + # create a parameters object that allows setting attributes. + parameters = type('Options', (), {})() + # check required arguments + for arg in required: + if not arg in options: + raise Exception("Could not find required Argument " + arg + " aborting...") + else: + if not isinstance(options[arg],required[arg]): + raise Exception("Expected input of type " + str(required[arg]) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + # check the default values. + for arg in defaults: + if arg in options: + if not isinstance(options[arg],type(defaults[arg])): + #Wrong type for the parameter + raise Exception("Expected input of type " + str(type(defaults[arg])) + " but got " + str(type(options[arg]))) + print("Setting " + arg + " to " + str(options[arg])) + setattr(parameters,arg,options[arg]) + else: + print( arg + " not found in option file. Using default: " +str(defaults[arg])) + setattr(parameters,arg,defaults[arg]) + return parameters + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/01_memory_layout.svg b/branch/rkdarst--remove-catfacts-jsonl/_images/01_memory_layout.svg new file mode 100644 index 00000000..93da7c68 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_images/01_memory_layout.svg @@ -0,0 +1,584 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How you see a matrix: + How NumPy sees a matrix: + [0,] + [1,] + [2,] + [3,] + [,0] + [,1] + [,2] + [,3] + [0] + [1] + [2] + [3] + [4] + [5] + [6] + [7] + [8] + [9] + [10] + [11] + [12] + [13] + [14] + [15] + + + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/01_table_dataframe.svg b/branch/rkdarst--remove-catfacts-jsonl/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/02_views.svg b/branch/rkdarst--remove-catfacts-jsonl/_images/02_views.svg new file mode 100644 index 00000000..925354e0 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_images/02_views.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + array "a" + array "b" + .shape.strides + .shape.strides + + + + + data pointer + data pointer + memory buffer + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/anaconda-navigator-jupyterlab.png b/branch/rkdarst--remove-catfacts-jsonl/_images/anaconda-navigator-jupyterlab.png new file mode 100644 index 00000000..4ea0854f Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/anaconda-navigator-jupyterlab.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/anaconda-prompt.png b/branch/rkdarst--remove-catfacts-jsonl/_images/anaconda-prompt.png new file mode 100644 index 00000000..e4fcf79b Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/anaconda-prompt.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/binder.jpg b/branch/rkdarst--remove-catfacts-jsonl/_images/binder.jpg new file mode 100644 index 00000000..d04c467d Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/binder.jpg differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/exercise.png b/branch/rkdarst--remove-catfacts-jsonl/_images/exercise.png new file mode 100644 index 00000000..465f23f2 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/exercise.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-larger-font.png b/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-larger-font.png new file mode 100644 index 00000000..fb11e972 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-larger-font.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-linear.png b/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-linear.png new file mode 100644 index 00000000..4890b46c Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-linear.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-log.png b/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-log.png new file mode 100644 index 00000000..3fff7b2f Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/gapminder-log.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/getting-started.png b/branch/rkdarst--remove-catfacts-jsonl/_images/getting-started.png new file mode 100644 index 00000000..e1a0a81f Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/getting-started.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/jupyterlab-notebook.png b/branch/rkdarst--remove-catfacts-jsonl/_images/jupyterlab-notebook.png new file mode 100644 index 00000000..900fdfd9 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/jupyterlab-notebook.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/jupyterlab-terminal.png b/branch/rkdarst--remove-catfacts-jsonl/_images/jupyterlab-terminal.png new file mode 100644 index 00000000..33a6b02a Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/jupyterlab-terminal.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/main-ui.png b/branch/rkdarst--remove-catfacts-jsonl/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/main-ui.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/notebook-ui.png b/branch/rkdarst--remove-catfacts-jsonl/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/notebook-ui.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_images/tidy_data.png b/branch/rkdarst--remove-catfacts-jsonl/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_images/tidy_data.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/binder.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/binder.rst.txt new file mode 100644 index 00000000..1c841b3b --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/binder.rst.txt @@ -0,0 +1,202 @@ +Binder +====== + +.. questions:: + + - Why sharing code alone may not be sufficient. + - How to share a computational environment? + - What is Binder? + - How to binderize my Python repository? + - How to publish my Python repository? + +.. objectives:: + + - Learn about reproducible computational environments. + - Learn to create and share custom computing environments with Binder. + - Learn to get a DOI from Zenodo for a repository. + + +Why is it sometimes not enough to share your code? +-------------------------------------------------- + +Before we work in groups, +let's take an example from geospatial +analysis where the first ``import`` in the code would be (please note that it is +not necessary to install any of the packages mentioned below):: + + from osgeo import ogr, osr, gdal + +Depending on how you install this python package, it may be necessary to have +`libgdal` and its development headers already installed on your system; with +information on the version you have used, etc. + + +Exercise 1 +~~~~~~~~~~ + +.. challenge:: Binder-1 (10 min) + + Lea is a PhD student in computational biology and after 2 years of intensive + work, she is finally ready to publish her first paper. The code she has used + for analyzing her data is available on GitHub but her supervisor who is an + advocate of open science told her that sharing code is not sufficient. + + **Why is it possibly not enough to share "just" your code? + What problems can you anticipate 2-5 years from now?** + + We form small groups (4-5 persons) and discuss in groups. If the workshop is + online, each group will join a breakout room. + If joining a group is not possible or practical, we use the shared document + to discuss this collaboratively. + + Each group write a summary (bullet points) of the discussion in the workshop + shared document (the link will be provided by your instructors). + + +Sharing a computing environment with Binder +------------------------------------------- + +`Binder `__ allows you to create +custom computing environments that can be shared and used by many remote users. +It uses `repo2docker `__ to +create a container image (`docker `__ image) of a +project using information contained in included configuration files. + +Repo2docker is a standalone package that you can install locally on your laptop +but an `online Binder `__ service is freely available. +This is what we will be using in the tutorial. + +The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder. + +.. image:: https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png + +Credit: `Juliette Taka, Logilab and the OpenDreamKit project (2017) `_ + + +Binder exercise/demo +~~~~~~~~~~~~~~~~~~~~ + +In an earlier episode (Data visualization with Matplotlib) we have created this notebook: + +.. code-block:: python + + import pandas as pd + import matplotlib.pyplot as plt + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + data_2007 = data[data["year"] == 2007] + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xscale("log") + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + +We will now first share it via `GitHub `__ "statically", +then using `Binder `__. + +.. challenge:: Exercise/demo: Making your notebooks reproducible by anyone (15 min) + + Instructor demonstrates this: + + - Creates a GitHub repository + - Uploads the notebook file + - Then we look at the statically rendered version of the notebook on GitHub + - Create a ``requirements.txt`` file which contains:: + + pandas==1.2.3 + matplotlib==3.4.2 + + - Commit and push also this file to your notebook repository. + - Visit https://mybinder.org and copy paste the code under "Copy the text below ..." into your `README.md`: + + .. image:: img/binder/binder.jpg + + - Check that your notebook repository now has a "launch binder" + badge in your `README.md` file on GitHub. + - Try clicking the button and see how your repository is launched + on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud. + - Enjoy being fully reproducible! + + +How can I get a DOI from Zenodo? +--------------------------------- + +`Zenodo `__ is a general purpose open-access +repository built and operated by `CERN `__ and `OpenAIRE +`__ that allows researchers to archive and get a +`Digital Object Identifier (DOI) `__ to data that they +share. + +.. challenge:: Binder-3 (optional) + + **Everything you deposit on Zenodo is meant to be kept (long-term archive). + Therefore we recommend to practice with the Zenodo "sandbox" (practice/test area) + instead: https://sandbox.zenodo.org** + + 1. **Link GitHub with Zenodo**: + + - Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing). + - Log in to Zenodo with your GitHub account. Be aware that you may need to + authorize Zenodo application (Zenodo will redirect you back to GitHub for + Authorization). + - Choose the repository webhooks options. + - From the drop-down menu next to your email address at the top of the page, select GitHub. + - You will be presented with a list of all your Github repositories. + + 2. **Archiving a repo**: + + - Select a repository you want to archive on Zenodo. + - Toggle the "on" button next to the repository ou need to archive. + - Click on the Repo that you want to reserve. + - Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release. + + 3. **Trigger Zenodo to Archive your repository** + + - Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI. + - If this is the first release of your code then you should give it a + version number of v1.0.0. Add description for your release then click the + Publish release button. + - Zenodo takes an archive of your GitHub repository each time you create a new Release. + + 4. **To ensure that everything is working**: + + - Go to https://zenodo.org/account/settings/github/ (or the corresponding + sandbox at https://sandbox.zenodo.org/account/settings/github/), or the + Upload page (https://zenodo.org/deposit), you will find your repo is + listed. + - Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo. + - You can edit the archive on Zenodo and/or publish a new version of your software. + - It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata + manually, you can also add a ``.zenodo.json`` or a ``CITATION.cff`` file to your repo and Zenodo will infer the metadata from this file. + - Your code is now published on a Github public repository and archived on Zenodo. + - Update the README file in your repository with the newly created zenodo badge. + + +Create a Binder link for your Zenodo DOI +---------------------------------------- + +Rather than specifying a GitHub repository when launching binder, you can instead use a Zenodo DOI. + +.. challenge:: Binder-4 (10 min) + + We will be using an existing Zenodo DOI `10.5281/zenodo.3886864 `_ to start Binder: + + - Go to `https://mybinder.org `__ and fill information using Zenodo DOI (as shown on the animation below): + + .. image:: https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif + + - You can also get a Binder badge and update the README file in the + repository. It is good practice to add both the Zenodo badge and the + corresponding Binder badge. + +.. keypoints:: + + - Sharing reproducible computational environments + - Binder + - Zenodo DOI diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/data-formats.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/data-formats.rst.txt new file mode 100644 index 00000000..bfa42c30 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/data-formats.rst.txt @@ -0,0 +1,818 @@ +Data formats with Pandas and Numpy +================================== + +.. questions:: + + - How do you store your data right now? + - Are you doing data cleaning / preprocessing every time you load the data? + +.. objectives:: + + - Learn the distinguishing characteristics of different data formats. + - Learn how you can read and write data in a variety of formats. + +What is a data format? +---------------------- + +Data format can mean two different things + +1. `data structure `__ or how you're storing the data in memory while you're working on it; +2. `file format `__ or the way you're storing the data in the disk. + +Let's consider this randomly generated DataFrame with various columns:: + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.info() + +This DataFrame is structured in the tidy data format. +In tidy data format we have multiple columns of data that are collected in a Pandas DataFrame. + +.. image:: img/pandas/tidy_data.png + +Let's consider another example:: + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + np.info(data_array) + + +Here we have a different data structure: we have a two-dimentional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block instead of individual columns. +This also means that the whole array must have one data type. + + +.. figure:: https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png + + Source: `Elegant Scipy `__ + +Now the question is: **Can the data be saved to the disk without changing the data format?** + +For this we need a **file format** that can easily store our **data structure**. + +.. admonition:: Data type vs. data structure vs. file format + :class: dropdown + + - **Data type:** Type of a single piece of data (integer, string, float, ...). + - **Data structure:** How the data is organized in memory (individual columns, 2D-array, nested dictionaries, ...). + - **File format:** How the data is organized when it is saved to the disk (columns of strings, block of binary data, ...). + + For example, a black and white image stored as a .png-file (**file format**) + might be stored in memory as an NxM array (**data structure**) of integers (**data type**). + +What to look for in a file format? +---------------------------------- + +When deciding which file format you should use for your program, you should remember the following: + +**There is no file format that is good for every use case.** + +Instead, there are various standard file formats for various use cases: + +.. figure:: https://imgs.xkcd.com/comics/standards.png + + Source: `xkcd #927 `__. + +Usually, you'll want to consider the following things when choosing a file format: + +1. Is the file format good for my data structure (is it fast/space efficient/easy to use)? +2. Is everybody else / leading authorities in my field recommending a certain format? +3. Do I need a human-readable format or is it enought to work on it using code? +4. Do I want to archive / share the data or do I just want to store it while I'm working? + +Pandas supports `many file formats `__ for tidy data and Numpy supports `some file formats `__ for array data. +However, there are many other file formats that can be used through other libraries. + +Table below describes some data formats: + +.. list-table:: + :header-rows: 1 + + * - | Name: + - | Human + | readable: + - | Space + | efficiency: + - | Arbitrary + | data: + - | Tidy + | data: + - | Array + | data: + - | Long term + | storage/sharing: + + * - :ref:`Pickle ` + - ❌ + - 🟨 + - ✅ + - 🟨 + - 🟨 + - ❌ + + * - :ref:`CSV ` + - ✅ + - ❌ + - ❌ + - ✅ + - 🟨 + - ✅ + + * - :ref:`Feather ` + - ❌ + - ✅ + - ❌ + - ✅ + - ❌ + - ❌ + + * - :ref:`Parquet ` + - ❌ + - ✅ + - 🟨 + - ✅ + - 🟨 + - ✅ + + * - :ref:`npy ` + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + - ❌ + + * - :ref:`HDF5 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`NetCDF4 ` + - ❌ + - ✅ + - ❌ + - ❌ + - ✅ + - ✅ + + * - :ref:`JSON ` + - ✅ + - ❌ + - 🟨 + - ❌ + - ❌ + - ✅ + + * - :ref:`Excel ` + - ❌ + - ❌ + - ❌ + - 🟨 + - ❌ + - ✅ + + * - :ref:`Graph formats ` + - 🟨 + - 🟨 + - ❌ + - ❌ + - ❌ + - 🟨 + +.. important:: + + - ✅ : Good + - 🟨 : Ok / depends on a case + - ❌ : Bad + + +Storing arbitrary Python objects +-------------------------------- + + +.. _pickle: + +Pickle +****** + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** None (:mod:`pickle`-module is included with Python). + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** 🟨 + - **Array data:** 🟨 + - **Long term archival/sharing:** ❌! See warning below. + - **Best use cases:** Saving Python objects for debugging. + +.. warning:: + + Loading pickles that you have not created is + risky as they can contain arbitrary executable code. + + Do not unpickle objects from sources that you do not trust! + +:mod:`Pickle ` is Python's own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:: + + import pickle + + with open('data_array.pickle', 'wb') as f: + pickle.dump(data_array, f) + + with open('data_array.pickle', 'rb') as f: + data_array_pickle = pickle.load(f) + + +Exercise 1 +---------- + +.. challenge:: + + - Create an arbitrary python object (for example, a string or a list). Pickle it. + + Read the pickled object back in and check if it matches the original one. + +.. solution:: + + .. code-block:: python + + import pickle + + my_object=['test', 1, 2, 3] + + with open('string.pickle', 'wb') as f: + pickle.dump(my_object, f) + + + with open('string.pickle', 'rb') as f: + my_pickled_object = pickle.load(f) + + print(my_object, my_pickled_object) + print(my_object == my_pickled_object) + + +Storing tidy data +----------------- + +.. _csv: + +CSV (comma-separated values) +**************************** + +.. admonition:: Key features + + - **Type:** Text format + - **Packages needed:** numpy, pandas + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data. Small data. Data that needs to be human-readable. + +CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you're working with big data. + +Pandas has a very nice interface for writing and reading CSV files with `to_csv `__- and `read_csv `__-functions:: + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + +Numpy has `routines `__ for saving and loading arrays as CSV files as well:: + + np.savetxt('data_array.csv', data_array) + + data_array_csv = np.loadtxt('data_array.csv') + +.. admonition:: Storing data in CSVs can reduce data precision + :class: dropdown + + When working with floating point numbers you should be careful to save the data with enough decimal places so that you won't lose precision. + + For example, double-precision floating point numbers have `~16 decimal places of precision `__, but if you use normal Python to write these numbers, you can easily lose some of that precision. + Let's consider the following example: + + .. code-block:: python + + import numpy as np + test_number = np.sqrt(2) + # Write the number in a file + test_file = open('sqrt2.csv', 'w') + test_file.write('%f' % test_number) + test_file.close() + # Read the number from a file + test_file = open('sqrt2.csv', 'r') + test_number2 = np.float64(test_file.readline()) + test_file.close() + # Calculate the distance between these numbers + print(np.abs(test_number - test_number2)) + + CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. + We can check whether our written data matches the generated data: + + .. code-block:: python + + dataset.compare(dataset_csv) + + np.all(data_array == data_array_csv) + + In our case some rows of ``dataset_csv`` loaded from CSV do not match the original ``dataset`` as the last decimal can sometimes be rounded due to `complex technical reasons `__. + + Storage of these high-precision CSV files is usually very inefficient storage-wise. + + Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems. + + +.. _feather: + + +Feather +******* + +.. admonition:: Requires additional packages + :class: dropdown + + + Using Feather requires `pyarrow-package `__ to be installed. + + You can try installing pyarrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ✅ + - **Array data:** ❌ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Temporary storage of tidy data. + +`Feather `__ is a file format for storing data frames quickly. +There are libraries for Python, R and Julia. + +We can work with Feather files with :external+pandas:ref:`to_feather- and read_feather-functions `:: + + dataset.to_feather('dataset.feather') + dataset_feather = pd.read_feather('dataset.feather') + +Feather is not a good format for storing array data, so we won't present an example of that here. + + +.. _parquet: + + +Parquet +******* + +.. admonition:: Requires additional packages + :class: dropdown + + Using Parquet requires `pyarrow-package `__ to be installed. + + You can try installing PyArrow with + + .. code-block:: bash + + !pip install pyarrow + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** pandas, pyarrow + - **Space efficiency:** ✅ + - **Arbitrary data:** 🟨 + - **Tidy data:** ✅ + - **Array data:** 🟨 + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in tidy data format. Archival of said data. + +`Parquet `__ is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.). + +We can work with Parquet files with :external+pandas:ref:`to_parquet- and read_parquet-functions `:: + + dataset.to_parquet('dataset.parquet') + dataset_parquet = pd.read_parquet('dataset.parquet') + +Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won't do that here. + + +Exercise 2 +---------- + +.. challenge:: + + - Create the example ``dataset``: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + - Save the dataset ``dataset`` as CSV. Load the dataset into a variable ``dataset_csv``. + - Use ``dataset.compare(dataset_csv)`` to check if loaded dataset matches the original one. + +.. solution:: + + .. code-block:: python + + import pandas as pd + import numpy as np + + n_rows = 100000 + + dataset = pd.DataFrame( + data={ + 'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows), + 'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"), + 'integer': np.random.choice(range(0,10), size=n_rows), + 'float': np.random.uniform(size=n_rows), + }, + ) + + dataset.to_csv('dataset.csv', index=False) + + dataset_csv = pd.read_csv('dataset.csv') + + print(dataset.compare(dataset_csv)) + + Dataset might not be completely the same. Sometimes the CSV format cannot + fully represent a floating point value, which will result in rounding errors. + +Storing array data +------------------ + + +.. _npy: + + +npy (numpy array format) +************************ + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** numpy + - **Space efficiency:** 🟨 + - **Arbitrary data:** ✅ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ❌ + - **Best use cases:** Saving numpy arrays temporarily. + +If you want to temporarily store numpy arrays, you can use the :func:`numpy.save`- and :func:`numpy.load`-functions:: + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + +There also exists :func:`numpy.savez`-function for storing multiple datasets in a single file:: + + np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array) + data_arrays = np.load('data_arrays.npz') + data_arrays['data_array0'] + +For big arrays it's good idea to check other binary formats such as HDF5 or NetCDF4. + +``np.save``- and ``np.savez``-functions work with +`sparse matrices `__, +but one can also use dedicated +`scipy.sparse.save_npz `__- and +`scipy.sparse.load_npz `__-functions. +Storing sparse matrices using these functions can give huge storage savings. + + +.. _hdf5: + + +HDF5 (Hierarchical Data Format version 5) +***************************************** + +.. admonition:: Key features + + - **Type:** Binary format + - **Packages needed:** numpy, pandas, PyTables, h5py + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. + +HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences. + +Pandas allows you to store tables as HDF5 with `PyTables `_, which uses HDF5 to write the files. +You can create a HDF5 file with :external+pandas:ref:`to_hdf- and read_parquet-functions `:: + + dataset.to_hdf('dataset.h5', key='dataset', mode='w') + dataset_hdf5 = pd.read_hdf('dataset.h5') + +PyTables comes installed with the default Anaconda installation. + +For writing data that is not a table, you can use the excellent `h5py-package `__:: + + import h5py + + # Writing: + + # Open HDF5 file + h5_file = h5py.File('data_array.h5', 'w') + # Write dataset + h5_file.create_dataset('data_array', data=data_array) + # Close file and write data to disk. Important! + h5_file.close() + + # Reading: + + # Open HDF5 file again + h5_file = h5py.File('data_array.h5', 'r') + # Read the full dataset + data_array_h5 = h5_file['data_array'][()] + # Close file + h5_file.close() + +h5py comes with Anaconda as well. + + +.. _netcdf4: + + +NetCDF4 (Network Common Data Form version 4) +******************************************** + +.. admonition:: Requires additional packages + :class: dropdown + + Using NetCDF4 requires `netCDF4 `__- or `h5netcdf `__-package to be installed. + h5netcdf is often mentioned as being faster to the official netCDF4-package, so we'll be using it in the example. + + A great NetCDF4 interface is provided by a `xarray-package `__. + + You can try installing these packages with + + .. code-block:: bash + + !pip install h5netcdf xarray + + or you can take this as a demo. + +.. admonition:: Key features + + - **Type**: Binary format + - **Packages needed:** pandas, netCDF4/h5netcdf, xarray + - **Space efficiency:** ✅ + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ✅ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets. + +NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs. + +NetCDF4 is a common format for storing large data from big simulations in physical sciences. + +Using interface provided by ``xarray``:: + + # Write tidy data as NetCDF4 + dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf') + # Read tidy data from NetCDF4 + import xarray as xr + dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf') + dataset_netcdf4 = dataset_xarray.to_pandas() + dataset_xarray.close() + +Working with array data is easy as well:: + + # Write array data as NetCDF4 + xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf') + # Read array data from NetCDF4 + data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf') + data_array_netcdf4 = data_array_xarray.to_numpy() + data_array_xarray.close() + +The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (``x``, ``y``, ``z``) or timestamps (``t``) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis. + +Exercise 3 +---------- + +.. challenge:: + + - Create an example numpy array: + + .. code-block:: python + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + - Store the array as a npy. + - Read the dataframe back in and compare it to the original one. Does the data match? + +.. solution:: + + .. code-block:: python + + import numpy as np + + n = 1000 + + data_array = np.random.uniform(size=(n,n)) + + np.save('data_array.npy', data_array) + data_array_npy = np.load('data_array.npy') + np.all(data_array == data_array_npy) + + +Other file formats +------------------ + + +.. _json: + +JSON (JavaScript Object Notation) +********************************* + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** None (:mod:`json`-module is included with Python). + - **Space efficiency:** ❌ + - **Arbitrary data:** 🟨 + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Saving nested/relational data, storing web requests. + +JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.). + +You rarely want to keep your data in this format, unless you're working with +nested data with multiple layers or lots of interconnections. + +Similarly to other popular files, Pandas can write and read json files with :meth:`~pandas.DataFrame.to_json`- and :func:`~pandas.read_json`-functions:: + + dataset.to_json('dataset.json') + dataset_json = pd.read_json('dataset.json') + + +.. _excel: + +Excel +***** + +.. admonition:: Requires additional packages + :class: dropdown + + Using Excel files with Pandas requires `openpyxl `__-package to be installed. + +.. admonition:: Key features + + - **Type**: Text format + - **Packages needed:** `openpyxl `__ + - **Space efficiency:** ❌ + - **Arbitrary data:** ❌ + - **Tidy data:** 🟨 + - **Array data:** ❌ + - **Long term archival/sharing:** ✅ + - **Best use cases:** Sharing data in many fields. Quick data analysis. + +Excel is very popular in social sciences and economics. +However, it is `not a good format `__ for data science. + +See Pandas' documentation on :external+pandas:ref:`working with Excel files `. + + +.. _graph: + +Graph formats (adjency lists, gt, GraphML etc.) +*********************************************** + +.. admonition:: Key features + + - **Type**: Many different formats + - **Packages needed:** Depends on a format. + - **Space efficiency:** 🟨 + - **Arbitrary data:** ❌ + - **Tidy data:** ❌ + - **Array data:** ❌ + - **Long term archival/sharing:** 🟨 + - **Best use cases:** Saving graphs or data that can be represented as a graph. + +There are plenty of data formats for storing graphs. +We won't list them here as optimal data format depends heavily on the graph structure. + +One can use functions in libraries such as +`networkx `__, +`graph-tool `__, +`igraph `__ +to read and write graphs. + + + +Benefits of binary file formats +------------------------------- + +Binary files come with various benefits compared to text files. + +1. They can represent floating point numbers with full precision. +2. Storing data in binary format can potentially save lots of space. + This is because you do not need to write numbers as characters. + Additionally some file formats support compression of the data. +3. Data loading from binary files is usually much faster than loading from text files. + This is because memory can be allocated for the data before data is loaded as the type of data in columns is known. +4. You can often store multiple datasets and metadata to the same file. +5. Many binary formats allow for partial loading of the data. + This makes it possible to work with datasets that are larger than your computer's memory. + +**Performance with tidy dataset:** + +For the tidy ``dataset`` we had, we can test the performance of the different file formats: + +.. csv-table:: + :file: format_comparison_tidy.csv + :header-rows: 1 + +The relatively poor performance of HDF5-based formats in this case is due to the data being mostly one dimensional columns full of character strings. + + +**Performance with data array:** + +For the array-shaped ``data_array`` we had, we can test the performance of the different file formats: + + +.. csv-table:: + :file: format_comparison_array.csv + :header-rows: 1 + +For this kind of a data, HDF5-based formats perform much better. + + +Things to remember +------------------ + +1. **There is no file format that is good for every use case.** +2. Usually, your research question determines which libraries you want to use to solve it. + Similarly, the data format you have determines file format you want to use. +3. However, if you're using a previously existing framework or tools or you work in a specific field, you should prioritize using the formats that are used in said framework/tools/field. +4. When you're starting your project, it's a good idea to take your initial data, clean it, and store the results in a good binary format that works as a starting point for your future analysis. + If you've written the cleaning procedure as a script, you can always reproduce it. +5. Throughout your work, you should use code to turn important data to human-readable format (e.g. plots, averages, :meth:`pandas.DataFrame.head`), not to keep your full data in a human-readable format. +6. Once you've finished, you should store the data in a format that can be easily shared to other people. + + +See also +-------- + +- `Pandas' IO tools `__ +- `Tidy data comparison notebook `__ +- `Array data comparison notebook `__ + + +.. keypoints:: + + - Pandas can read and write a variety of data formats. + - There are many good, standard formats, and you don't need to create your own. + - There are plenty of other libraries dedicated to various formats. diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/data-visualization.md.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/data-visualization.md.txt new file mode 100644 index 00000000..04b82752 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/data-visualization.md.txt @@ -0,0 +1,518 @@ +# Data visualization with Matplotlib + +```{questions} +- What happens if you can't automatically produce plots? +- When to use Matplotlib for data visualization? +- When to prefer other libraries? +``` + +```{objectives} +- Be able to create simple plots with Matplotlib and tweak them +- Know about object-oriented vs pyplot interfaces of Matplotlib +- Be able to adapt gallery examples +- Know how to look for help +- Know that other tools exist +``` + + +## Repeatability/reproducibility + +From [Claus O. Wilke: "Fundamentals of Data Visualization"](https://clauswilke.com/dataviz/): + +> *One thing I have learned over the years is that automation is your friend. I +> think figures should be autogenerated as part of the data analysis pipeline +> (which should also be automated), and they should come out of the pipeline +> ready to be sent to the printer, no manual post-processing needed.* + +- **No manual post-processing**. This will bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + - [Matplotlib](https://matplotlib.org/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization (R users will be more at home), statistics built in + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/showcase/): + Jupyter notebook extension for 3D visualization + - ... +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative + (using grammar of graphics). + + +## Why are we starting with Matplotlib? + +- Matplotlib is perhaps the most "standard" Python plotting library. +- Many libraries build on top of Matplotlib. +- MATLAB users will feel familiar. +- Even if you choose to use another library (see above list), chances are high + that you need to adapt a Matplotlib plot of somebody else. +- Libraries that are built on top of Matplotlib may need knowledge of Matplotlib + for custom adjustments. + +However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code. + +Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. **Later we will also try other libraries.** + + +## Getting started with Matplotlib + +We can start in a Jupyter notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK. + +Let us create our first plot using +{func}`~matplotlib.pyplot.subplots`, +{obj}`~matplotlib.axes.Axes.scatter`, and some other methods on the +{obj}`~matplotlib.axes.Axes` object: + +```{code-block} python +# this line tells Jupyter to display matplotlib figures in the notebook +%matplotlib inline + +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00") + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("my-first-plot.png") +``` + +```{figure} data-visualization/first-plot/getting-started.png +:alt: Result of our first plot + +This is the result of our first plot. +``` + +When running a Matplotlib script on a remote server without a +"display" (e.g. compute cluster), you may need to add the +{obj}`matplotlib.use` call: + +```python +import matplotlib.pyplot as plt +matplotlib.use("Agg") + +# ... rest of the script +``` + +## Exercise: Matplotlib + +````{challenge} Exercise Matplotlib-1: extend the previous example (15 min) +- Extend the previous plot by also plotting this set of values but this time + using a different color (`#56B4E9`): + ```python + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + ``` + +- Then add another color (`#009E73`) which plots the second dataset, scaled + by 2.0. + ```python + # here we multiply all elements of data2_y by 2.0 + data2_y_scaled = [y*2.0 for y in data2_y] + ``` + +- Try to add a legend to the plot with {meth}`matplotlib.axes.Axes.legend` and searching the web for clues on + how to add labels to each dataset. + +- At the end it should look like this one: + ```{figure} data-visualization/first-plot/exercise.png + :alt: Result of the exercise + ``` +```` + +````{solution} +```{code-block} python +--- +emphasize-lines: 12, 15, 20-21, 26 +--- +# this line tells Jupyter to display matplotlib figures in the notebook +%matplotlib inline + +import matplotlib.pyplot as plt + +# this is dataset 1 from +# https://en.wikipedia.org/wiki/Anscombe%27s_quartet +data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] +data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + +# this is dataset 2 +data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + +# here we multiply all elements of data2_y by 2.0 +data2_y_scaled = [y*2.0 for y in data2_y] + +fig, ax = plt.subplots() + +ax.scatter(x=data_x, y=data_y, c="#E69F00", label='set 1') +ax.scatter(x=data_x, y=data2_y, c="#56B4E9", label='set 2') +ax.scatter(x=data_x, y=data2_y_scaled, c="#009E73", label='set 2 (scaled)') + +ax.set_xlabel("we should label the x axis") +ax.set_ylabel("we should label the y axis") +ax.set_title("some title") +ax.legend() + +# uncomment the next line if you would like to save the figure to disk +# fig.savefig("exercise-plot.png") +``` +```` + +```{discussion} Why these colors? +This qualitative color palette is opimized for all color-vision +deficiencies, see and +[Okabe, M., and K. Ito. 2008. "Color Universal Design (CUD): +How to Make Figures and Presentations That Are Friendly to Colorblind People."](http://jfly.iam.u-tokyo.ac.jp/color/). +``` + +--- + +## Matplotlib has two different interfaces + +When plotting with Matplotlib, it is useful to know and understand that +there are **two approaches** even though the reasons of this dual approach is +outside the scope of this lesson. + +- The more modern option is an **object-oriented interface** (the + {class}`fig ` and {class}`ax ` objects + can be configured separately and passed around to functions): + ```{code-block} python + --- + emphasize-lines: 8-14 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + ``` + +- The more traditional option mimics MATLAB plotting and uses the + **pyplot interface** ({mod}`plt ` carries + the global settings): + ```{code-block} python + --- + emphasize-lines: 8-12 + --- + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + plt.scatter(x=data_x, y=data_y, c="#E69F00") + + plt.xlabel("we should label the x axis") + plt.ylabel("we should label the y axis") + plt.title("some title") + ``` + +When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, **we +recommend to learn and use the object oriented interface.** + +```{discussion} Why do we emphasize this? +One day you may want to write functions which wrap +around Matplotlib function calls and then you can send {class}`~matplotlib.figure.Figure` and {class}`~matplotlib.axes.Axes` +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions. + +When using the pyplot interface, settings are modified for the entire +{mod}`matplotlib.pyplot` package. The latter is acceptable for linear scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls. +``` + +--- + +## Styling and customizing plots + +- **Do not customize "manually"** using a graphical program (not easily repeatable/reproducible). +- **No manual post-processing**. This will bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- Matplotlib and also all the other libraries allow to customize almost every aspect of a plot. +- It is useful to study [Matplotlib parts of a figure](https://matplotlib.org/stable/tutorials/introductory/quick_start.html#parts-of-a-figure) + so that we know what to search for to customize things. +- Matplotlib cheatsheets: +- You can also select among pre-defined themes/ + [style + sheets](https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html) + with {obj}`~matplotlib.style.use`, for instance: + ```python + plt.style.use('ggplot') + ``` + + +## Exercises: Styling and customization + +Here are 3 exercises where we try to adapt existing scripts to either **tweak +how the plot looks** (exercises 1 and 2) or to **modify the input data** (example 3). + +This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice: +- select an example that is close to what you have in mind +- being able to adapt it to your needs +- being able to search for help +- being able to understand help request answers (not easy) + +````{challenge} Exercise Customization-1: log scale in Matplotlib (15 min) +In this exercise we will learn how to use log scales. + +- To demonstrate this we first fetch some data to plot: + ```python + import pandas as pd + + url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv" + data = pd.read_csv(url) + + data_2007 = data[data["year"] == 2007] + + data_2007 + ``` +- Try the above snippet in a notebook and it will give you an overview over the data. + +- Then we can plot the data, first using a linear scale: + ```python + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + + ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + ``` + + This is the result but we realize that a linear scale is not ideal here: + ```{figure} data-visualization/customizing/gapminder-linear.png + :alt: Gapminder data plotted using a linear scale + ``` + +- Your task is to switch to a log scale and arrive at this result: + ```{figure} data-visualization/customizing/gapminder-log.png + :alt: Gapminder data plotted using log scale + ``` + +- What does ``alpha=0.5`` do? +```` + +````{solution} +See {meth}`ax.set_xscale() `. + +```{code-block} python +--- +emphasize-lines: 5 +--- +fig, ax = plt.subplots() + +ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP (USD) per capita") +ax.set_ylabel("life expectancy (years)") +``` +* {obj}`alpha ` sets transparency + of points. +```` + +````{challenge} Exercise Customization-2: preparing a plot for publication (15 min) +Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches. + +For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small. + +Your task is to make the tickmarks and the axis label font larger, using +[Matplotlib parts of a figure](https://matplotlib.org/stable/tutorials/introductory/quick_start.html#parts-of-a-figure) +and web search, and to arrive at this: + +```{figure} data-visualization/customizing/gapminder-larger-font.png +:alt: Gapminder data plotted with larger font and larger ticks +``` +```` + +````{solution} +See {meth}`ax.tick_params `. + +```{code-block} python +--- +emphasize-lines: 7-11 +--- +fig, ax = plt.subplots() + +ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5) + +ax.set_xscale("log") + +ax.set_xlabel("GDP (USD) per capita", fontsize=15) +ax.set_ylabel("life expectancy (years)", fontsize=15) +ax.tick_params(which="major", length=10) +ax.tick_params(which="minor", length=5) +ax.tick_params(labelsize=15) +``` +```` + +````{challenge} Exercise Customization-3: adapting a gallery example +**This is a great exercise which is very close to real life.** + +- Your task is to select one visualization library (some need to be installed first - in + doubt choose Matplotlib or Seaborn since they are part of Anaconda installation): + - [Matplotlib](https://matplotlib.org/stable/gallery/index.html): + probably the most standard and most widely used + - [Seaborn](https://seaborn.pydata.org/examples/index.html): + high-level interface to Matplotlib, statistical functions built in + - [Altair](https://altair-viz.github.io/gallery/index.html): + declarative visualization (R users will be more at home), statistics built in + - [Plotly](https://plotly.com/python/): + interactive graphs + - [Bokeh](https://demo.bokeh.org/): + also here good for interactivity + - [plotnine](https://plotnine.readthedocs.io/): + implementation of a grammar of graphics in Python, it is based on [ggplot2](https://ggplot2.tidyverse.org/) + - [ggplot](https://yhat.github.io/ggpy/): + R users will be more at home + - [PyNGL](https://www.pyngl.ucar.edu/Examples/gallery.shtml): + used in the weather forecast community + - [K3D](https://k3d-jupyter.org/showcase/): + Jupyter notebook extension for 3D visualization + +- Browse the various example galleries (links above). +- Select one example that is close to your recent visualization project or simply interests you. +- First try to reproduce this example in the Jupyter notebook. +- Then try to print out the data that is used in this example just before the call of the plotting function + to learn about its structure. Is it a pandas dataframe? Is it a NumPy array? Is it a dictionary? A list? + a list of lists? +- Then try to modify the data a bit. +- If you have time, try to feed it different, simplified data. + This will be key for adapting the examples to your projects. + +Example "solution" for such an exploration below. +```` + +````{solution} An example exploration +- Let us imagine we were browsing +- And this example plot caught our eye: +- Try to run it in the notebook. +- The `d` seems to be the data. Right before the call to `sns.violinplot`, add a `print(d)`: + ```{code-block} python + --- + emphasize-lines: 12 + --- + import numpy as np + import seaborn as sns + + sns.set_theme() + + # Create a random dataset across several variables + rs = np.random.default_rng(0) + n, p = 40, 8 + d = rs.normal(0, 2, (n, p)) + d += np.log(np.arange(1, p + 1)) * -5 + 10 + + print(d) + + # Show each distribution with both violins and points + sns.violinplot(data=d, palette="light:g", inner="points", orient="h") + ``` +- The print reveals that `d` is a NumPy array and looks like a two-dimensional list: + ```text + [[10.25146044 6.27005437 5.78778386 3.27832843 0.88147169 1.76439276 2.87844934 1.49695422] + [ 8.59252953 4.00342116 3.26038963 3.15118015 -2.69725111 0.60361933 -2.22137264 -1.86174242] + ... many more lines ... + [12.45950762 4.32352988 6.56724895 3.42215312 0.34419915 0.46123886 -1.56953795 0.95292133]] + ``` +- Now let's try with a much simplified two-dimensional list: + ```{code-block} python + --- + emphasize-lines: 12, 13 + --- + # import numpy as np + import seaborn as sns + + sns.set_theme() + + # # Create a random dataset across several variables + # rs = np.random.default_rng(0) + # n, p = 40, 8 + # d = rs.normal(0, 2, (n, p)) + # d += np.log(np.arange(1, p + 1)) * -5 + 10 + + d = [[1.0, 2.0, 2.0, 3.0, 3.0, 3.0], + [1.0, 1.0, 1.0, 2.0, 2.0, 3.0]] + + # Show each distribution with both violins and points + sns.violinplot(data=d, palette="light:g", inner="points", orient="h") + ``` +- Seems to work! And finally we arrive at a working example with our own data with all + the "clutter" removed: + ```python + import seaborn as sns + + # l1 and l2 are note great names but they will do for a quick test + l1 = [1.0, 2.0, 2.0, 3.0, 3.0, 3.0] + l2 = [1.0, 1.0, 1.0, 2.0, 2.0, 3.0] + + sns.violinplot(data=[l1, l2], palette="light:g", inner="points", orient="h") + ``` +- And now we can focus the rest of our work to read our real data. +- Finally we can customize the plot, e.g. web search for "seaborn violin plot axis labels" + and add `ax.set_yticklabels(['dataset 1', 'dataset 2'])`. +```` + +--- + +```{discussion} +After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on. +``` + +--- + +```{keypoints} +- Avoid manual post-processing, script everything. +- Browse a number of example galleries to help you choose the library + that fits best your work/style. +- Figures for presentation slides and figures for manuscripts have + different requirements. +- Think about color-vision deficiencies when choosing colors. Use + existing solutions for this problem. +``` diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/dependencies.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/dependencies.rst.txt new file mode 100644 index 00000000..98fdc642 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/dependencies.rst.txt @@ -0,0 +1,478 @@ +.. _dependency_management: + +Dependency management +===================== + +.. questions:: + + - Do you expect your code to work in one year? Five? What if it + uses ``numpy`` or ``tensorflow`` or ``random-github-package`` ? + - How can my collaborators get the same results as me? What about + future me? + - How can my collaborators easily install my codes with all the necessary dependencies? + - How can I make it easy for my colleagues to reproduce my results? + - How can I work on two (or more) projects with different and conflicting dependencies? + +.. objectives:: + + - Learn how to record dependencies + - Be able to communicate the dependencies as part of a report/thesis/publication + - Learn how to use isolated environments for different projects + - Simplify the use and reuse of scripts and projects + + +How do you track dependencies of your project? +---------------------------------------------- + +* **Dependency**: Reliance on a external component. In this case, a + separately installed software package such as ``numpy``. + + + +Exercises 1 +----------- + +.. challenge:: Dependencies-1 (15 min) + + Please discuss **in breakout rooms** and answer via **collaborative document** the + following questions: + + - How do you install Python packages (libraries) that you use in your work? + From PyPI using pip? From other places using pip? Using conda? + - How do you track/record the dependencies? Do you write them into a file or README? Into + ``requirements.txt`` or ``environment.yml``? + - If you track dependencies in a file, why do you do this? + - Have you ever experienced that a project needed a different version of a Python + library than the one on your computer? If yes, how did you solve it? + + +.. _pypi: + +PyPI (The Python Package Index) and (Ana)conda +---------------------------------------------- + +- PyPI (The Python Package Index) and Conda are popular packaging/dependency + management tools. + +- When you run ``pip install`` you typically install from `PyPI + `__ but one can also ``pip install`` from a GitHub + repository and similar. + +- When you run ``conda install`` you typically install from `Anaconda Cloud + `__ but there are many community-driven conda channels + and you can create your own. + + +Why are there two ecosystems? + + +.. admonition:: PyPI + + - **Installation tool:** ``pip`` + - **Summary:** PyPI is traditionally used for Python-only packages or + for Python interfaces to external libraries. There are also packages + with bundled external libraries (such as numpy). + - **Amount of packages:** Huge number. Old versions are supported for + a long time. + - **How libraries are handled:** If your code depends on external + libraries or tools, these things need to be either included in the + pip-package or provided via some other installation system (like + operating system installer or manual installation). + - **Pros:** + - Easy to use + - Package creation is easy + - **Cons:** + - Installing packages that need external libraries can be complicated + +.. admonition:: Conda + + - **Installation tool:** ``conda`` or ``mamba`` + - **Summary:** Conda aims to be a more general package distribution tool + and it tries to provide not only the Python packages, but also libraries + and tools needed by the Python packages. Most scientific software written + in Python uses external libraries to speed up calculations and installing + these libraries can often become complicated without conda. + - **Amount of packages:** Most popular packages are provided. Other packages + can be installed via pip. + - **How libraries are handled:** Required libraries are installed as separate + conda packages. + - **Pros:** + - Quite easy to use + - Easier to manage packages that need external libraries + - **Cons:** + - Package creation is harder + +.. solution:: Anaconda vs. miniconda vs. conda vs. mamba vs. Anaconda Cloud vs. conda-forge + + - `Anaconda `__ - a distribution of conda packages + made by Anaconda Inc.. It is free for academic and non-commercial use. + - `Miniconda `__ - a minimal installer for conda. + - `conda `__ - a package and environment management system + used by Anaconda. It is an open source project maintained by Anaconda Inc.. + - `mamba `__ - a drop in + replacement for conda that does installations faster. + - `Anaconda Cloud `__ - a package cloud maintained by + Anaconda Inc. It is a free repository that houses conda package channels. + - `Conda-forge `__ - the largest open source + community channel. + +In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages. + + +Creating isolated environments +------------------------------ + +Isolated environments solve a couple of problems: + +- You can install specific, also older, versions of packages into them. + +- You can create one environment for each project and you won't encounter any + problems if the two projects require different versions of packages. + +- If you make some mistake and install something you did not want or need, you + can remove the environment and create a new one. + +- You can export a list of packages in an environment and share it with your + code. This makes replicating your results easier. + + +Exercises 2 +----------- + +.. challenge:: Dependencies-2 (15 min) + + .. highlight:: console + + Chloe just joined your team and will be working on her Master Thesis. She is + quite familiar with Python, still finishing some Python assignments (due in a + few weeks) and you give her a Python code for analyzing and plotting your + favorite data. The thing is that your Python code has been developed by + another Master Student (from last year) and requires a older version of + Numpy (1.18.1) and Matplotlib (3.1.3) (otherwise the code fails). The code + could probably work with a recent version of Python but has been validated with + Python 3.7 only. Having no idea what the code does, she decides that the best + approach is to **create an isolated environment** with the same dependencies + that were used previously. This will give her a baseline for future upgrade and + developments. + + For this first exercise, we will be using conda for creating an isolated environment. + + 1. Create a conda environment:: + + $ conda create --name python37-env python=3.7 numpy=1.18.1 matplotlib=3.1.3 + + Conda environments can also be managed (create, update, delete) from the + **anaconda-navigator**. Check out the corresponding documentation `here + `_. + + 2. Activate the environment:: + + $ conda activate python37-env + + .. callout:: conda activate versus source activate + + If you do not have a recent version of Anaconda or anaconda has not been + setup properly, you may encounter an error. With older version of anaconda, + you can try:: + + $ source activate python37-env + + 3. Open a Python console and check that you have effectively the right version for each package:: + + import numpy + import matplotlib + + print('Numpy version: ', numpy.__version__) + print('Matplotlib version: ', matplotlib.__version__) + + Or use the one-liner if you have access to a terminal like bash + + python -c "import numpy; print(numpy.__version__)" + python -c "import matplotlib;print(matplotlib.__version__)" + + 4. Deactivate the environment:: + + $ conda deactivate + + 5. Check Numpy and Matplotlib versions in the default environment to make + sure they are different from **python37-env**. + + There is no need to specify the conda environment when using deactivate. It + deactivates the current environment. + + .. callout:: Remark + + - Sometimes the package version you would need does not seem to be + available. You may have to select another `conda channel + `_ + for instance `conda-forge `_. Channels can then + be indicated when installing a package:: + + $ conda install -c conda-forge matplotlib=3.1.3 + + - We will see below that rather than specifying the list of dependencies as + argument of ``conda create``, it is recommended to record dependencies in + a file. + + + +Exercises 3 +----------- + +.. challenge:: Dependencies-3 (15 min, optional) + + This is the same exercise as before but we use virtualenv rather than conda. + + + 1. Create a venv:: + + $ python3 -m venv scicomp + + Here ``scicomp`` is the name of the virtual environment. It creates a new + folder called ``scicomp``. + + 2. Activate it. To activate your newly created virtual environment locate the + script called ``activate`` and execute it. + + - **Linux/Mac-OSX**: look at ``bin`` folder in the ``scicomp`` folder:: + + $ source scicomp/bin/activate + + - **Windows**: most likely you can find it in the ``Scripts`` folder. + + 3. Install Numpy 1.18.1 and Matplotlib 3.1.3 into the virtual environment:: + + $ pip install numpy==1.18.1 + $ pip install matplotlib==3.1.3 + + 4. Deactivate it:: + + $ deactivate + +Problems that might happen with manual installation +--------------------------------------------------- + +Running the install commands manually can result in unexpected behaviour +such as: + +- The installer might remove an already installed packages or update them. +- The installer might not find a package that works with already installed packages. + +The reason for this is that the installer does not know what commands +you ran in the past. It only knows the state of your environment and what +you're currently telling it to install. + +For example, check what version of ``scipy`` you'll get if you run + +.. code-block:: shell + + $ pip install scipy + +or + +.. code-block:: shell + + $ conda install scipy + +Depending on your environment you can get ``scipy`` with versions from +``1.6.2`` with no numpy upgrade to ``1.9.3`` with automatic numpy upgrade. + +These kinds of problems can be mitigated by recording dependencies in an +``environment.yml`` or ``requirements.txt``. + +Recording dependencies +---------------------- + +There are two standard ways to record dependencies for Python projects: +``requirements.txt`` and ``environment.yml``. + +``requirements.txt`` (used by virtual environment) is a simple +text file which looks like this:: + + numpy + matplotlib + pandas + scipy + +``environments.yml`` (for conda) is a yaml-file which looks like this: + +.. code-block:: yaml + + name: my-environment + channels: + - defaults + dependencies: + - numpy + - matplotlib + - pandas + - scipy + +If you need to recreate the exact same environment later on, it can be very +useful to **pin dependencies** to certain versions. For example, there +is usually a delay between doing research and that research being published. +During this time the dependencies might update and reviewers or interested +researchers might not be able to replicate your results or run your code. + +Here are the two files again, but this time with versions pinned: + +``requirements.txt`` with versions:: + + numpy==1.18.1 + matplotlib==3.1.3 + pandas==1.1.2 + scipy==1.6.2 + +``environments.yml`` with versions: + +.. code-block:: yaml + + name: my-environment + channels: + - defaults + dependencies: + - python=3.7 + - numpy=1.18.1 + - matplotlib=3.1.3 + - pandas=1.1.2 + - scipy=1.6.2 + +- Conda can also read and write ``requirements.txt``. +- ``requirements.txt`` can also refer to packages on Github. +- ``environments.yml`` can also contain a ``pip`` section. +- See also: https://coderefinery.github.io/reproducible-research/03-dependencies/#dependencies. + +.. admonition:: Putting too strict requirements can be counter-productive + + Putting exact version numbers can be good for single-use applications, + like replicating a research paper, but it is usually bad for long-term + maintenance because the program won't update at the same time as it's + requirements do. + + If you're creating a library, adding strict dependencies can also create + a situation where the library cannot coexist with another library. + +Dependencies 4 +-------------- + +.. challenge:: Dependencies-4 (15 min) + + - Create the file ``environment.yml`` or ``requirements.txt`` + + - Create an environment based on these dependencies: + - Conda: ``$ conda env create --file environment.yml`` + - Virtual environment: First create and activate, then ``$ pip install -r requirements.txt`` + + - Freeze the environment: + - Conda: ``$ conda env export > environment.yml`` + - Virtual environment: ``$ pip freeze > requirements.txt`` + + - Have a look at the generated ("frozen") file. + +.. admonition:: Hint: Updating packages from dependency files + + Instead of installing packages with ``$ pip install somepackage``, + you can add ``somepackage`` to ``requirements.txt`` and re-run + ``$ pip install -r requirements.txt``. + + With conda, you can add the package to ``environment.yml`` and + run ``$ conda env update --file environment.yml`` + + +How to communicate the dependencies as part of a report/thesis/publication +-------------------------------------------------------------------------- + +Each notebook or script or project which depends on libraries should come with +either a ``requirements.txt`` or a ``environment.yml``, unless you are creating +and distributing this project as Python package (see next section). + +- Attach a ``requirements.txt`` or a ``environment.yml`` to your thesis. +- Even better: put ``requirements.txt`` or a ``environment.yml`` in your Git repository along your code. +- Even better: also binderize your analysis pipeline (more about that in a later session). + + +.. _version_pinning: + +Version pinning for package creators +------------------------------------ + +We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in ``setup.py`` or ``pyproject.toml`` +(PyPI) or ``meta.yaml`` (conda). + +These dependencies will then be used by either other libraries (who in turn +write their own ``setup.py`` or ``pyproject.toml`` or ``meta.yaml``) or by +people directly (filling out ``requirements.txt`` or a ``environment.yml``). + +Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from ``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy==1.19.2', + 'matplotlib==3.3.2' + 'pandas==1.1.2' + 'scipy==1.5.2' + ] + # ... + +or you can define a range or keep them undefined like here (example taken from +``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy', + 'matplotlib' + 'pandas' + 'scipy' + ] + # ... + +Should we pin the versions here or not? + +- Pinning versions here would be good for reproducibility. + +- However pinning versions may make it difficult for this library to be used in a project alongside other + libraries with conflicting version dependencies. + +- Therefore **as library creator make the version requirements as wide as possible**. + + - Set minimum version when you know of a reason: ``>=2.1`` + + - Sometimes set maximum version to next major version (``<4``) (when + you currently use ``3.x.y``) when you expect issues with next + major version. + +- As the "end consumer" of libraries, define your dependencies as narrowly as possible. + + +See also +-------- + +Other tools for dependency management: + +- `Poetry `__: dependency management and packaging +- `Pipenv `__: dependency management, alternative to Poetry +- `pyenv `__: if you need different Python versions for different projects +- `micropipenv `__: lightweight tool to "rule them all" +- `mamba `__: a drop in replacement for + conda that does installations faster. +- `miniforge & mambaforge `__: Miniconda alternatives with + conda-forge as the default channel and optionally mamba as the default installer. + +Other resources: + +- https://scicomp.aalto.fi/scicomp/packaging-software/ + + +.. keypoints:: + + - Install dependencies by first recording them in ``requirements.txt`` or + ``environment.yml`` and install using these files, then you have a trace. + - Use isolated environments and avoid installing packages system-wide. diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/exercises.md.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/exercises.md.txt new file mode 100644 index 00000000..61028b90 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/exercises.md.txt @@ -0,0 +1,12 @@ +# List of exercises + +## Full list + +This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests. + +```{exerciselist} +``` diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/guide.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/guide.rst.txt new file mode 100644 index 00000000..3dc6f602 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/guide.rst.txt @@ -0,0 +1,125 @@ +Instructor's guide +================== + +Learner personas +---------------- + +A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don't know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren't sure if they +are going in the right direction. + +A2 can use numpy and pandas, but have learned little bits here and +there and hasn't had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages) + +B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves. + + +Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren't familiar. + +Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter + + + +About each section +------------------ + +In general, "Python for Scientific Computing could be a multi-year +course. We can't even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path. + +* **Python intro:** We can't really replace a Python tutorial, but + here we try to outline some of the main points. We don't go over + this in the course. + +* **Jupyter:** Jupyter is somewhat useful, but the main reason we go + over it is that it provides a convenient user interface for the + other programming lessons (it's easier to spend a bit of time with + Jupyter than expect people to be able to use some + editor/IDE/shell/etc). So, we do start from the beginning, so that + people can do the other lessons, but also try to teach some advanced + tips and tricks. + +* **Numpy:** The basic of much of the rest of scipy, so we need to + cover it. We try to get the main principles out, but if someone + already knows it this can be a bit boring. We try to make sure + everyone comes out with an appreciation for vectorization and + broadcasting. + +* **Pandas:** A lot of similar goals to the Numpy section, especially + the concepts behind Dataframes that one needs to know in order to + read other documentation. + +* **Visualization:** Matplotlib is getting a bit old, but is still the + backbone of other plotting packages. We try to get forth the ideas + of the matplotlib API that can be seen in other packages and the + importance of scripted plots. + +* **Data formats:** Input/output/storage is a common task, and can + easily either be a bottleneck or a huge mess. This lessons tries to + show some best practices with data formats and, as usual, get the + idea to not "do it yourself". Pandas is used as a common framework, + but we should point out there are plenty of other options. + +* **Scripts:** The most important lesson here is to break out of + Jupyter/run buttons of editors. If you can't make actual programs + with an actual interface, you can't scale up. + + * This is the first lesson to introduce the command line. We + recommend being as simple as possible: at least demonstrate the + JupyterLab terminal and discuss the bigger picture behind what it + means and why. + + * This is also the first lesson to use non-Jupyter code editor. We + recommend again being simple: use the JupyterLab code editor to + start off, and carefully explain what is going on. + +* **Scipy:** We don't cover much here (this is super short), but the + point is scipy exists and the concept of wrapping existing C/fortran + libraries and so on. + +* **Library ecosystem:** This was an overview of the types of packages + available in the "scipy ecosystem", which is a large and ill-defined + thing. But there is another point: choosing what to use. Do you + trust a half-done thing published on someone's personal webpage? If + it's on Github? How do you make your code more reusable? When + coming from academic courses, you get a "build it yourself" idea, + which isn't sustainable in research. + +* **Parallel programming:** + +* **Dependencies:** The main point here is environments, another thing + you often don't learn in courses. + + * There is a lot of material here. Consider what you will demo, + what will be done as exercises, and what is advanced/optional. + However, it is the fourth-day lesson that is most interactive, so + it is OK if it take a while to go through everything. + + * If someone else installs Anaconda for a user (e.g. admin-managed + laptop), the conda environment creations (with ``--name``, + possibly with ``--prefix`` too?) may not work. Be prepared for + this and mention it. You don't need to solve the problem but + acknowledge that the lesson becomes a demo. The virtualenv part + should hopefully work for them. + +* **Binder:** Binder exists and can help make code + reproducible/reusable by others. + +* **Packaging:** How to make your code reusable by others. By the + time we get here, people are tired and the topics get involved. We + more explicitly say "you might want to watch and take this as a + demo". + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/index.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/index.rst.txt new file mode 100644 index 00000000..3de654eb --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/index.rst.txt @@ -0,0 +1,213 @@ +=============================== +Python for Scientific Computing +=============================== + +.. admonition:: Attending the course 22-25.november.2022? + + `See the course page here + `__. + Whether you are or aren't, the course material is below. + +Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, matplotlib for visualization, and so on. In +addition, it talks about *how* python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write. + +This course (like any course) can't teach you Python... it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to. + +.. _prerequisites: + +.. prereq:: + + - Knowing basic Python syntax. We assume that you can do some + Python programming, but not much more that that. We don't cover + standard Python programming. `Here a short course on basic Python + syntax, with further references `__. + - Watch or read the `command line crash course + `__, if you aren't + familiar. + - You should be able to use a text editor to edit files some. + - The :doc:`software installation ` described below + (basically, anaconda). + + These are not prerequisites: + + - Any external libraries, e.g. numpy + - Knowing how to make scripts or use Jupyter + + +.. admonition:: Videos + + Videos from the 2021 instance of this course can be found in + `this YouTube playlist `__. + + +.. csv-table:: + :widths: auto + :delim: ; + + (prereq) ; :doc:`python` + 30 min ; :doc:`jupyter` + 60 min ; :doc:`numpy` or :doc:`numpy-advanced` + 60 min ; :doc:`pandas` + 60 min ; :doc:`data-visualization` + 30 min ; :doc:`data-formats` + 60 min ; :doc:`scripts` + 30 min ; :doc:`web-apis` + 15 min ; :doc:`scipy` + 30 min ; :doc:`libraries` + 45 min ; :doc:`parallel` + 30 min ; :doc:`dependencies` + 30 min ; :doc:`binder` + 60 min ; :doc:`packaging` + + +.. toctree:: + :maxdepth: 1 + :caption: The lesson + :hidden: + + python + jupyter + numpy + numpy-advanced + pandas + data-visualization + data-formats + scripts + web-apis + scipy + libraries + parallel + dependencies + binder + packaging + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + installation + quick-reference + exercises + guide + + +.. _learner-personas: + +Who is the course for? +====================== + +The course is targeted towards these learner personas: + +* A is a early career PhD researcher who has been using Python a bit, + but is not sure what they know or don't know. They want to be able + to do their research more efficiently and make sure that they are + using the right tools. A may know that numpy exists, etc. and could + theoretically read some about it themselves, but aren't sure if they + are going in the right direction. + +* A2 can use numpy and pandas, but have learned little bits here and + there and hasn't had a comprehensive introduction. They want to + ensure they are using best practices. (Baseline of high-level + packages) + +* B is a mid-to-late undergraduate student who has used Python in some + classes. They have possibly learned the syntax and enough to use it + in courses, but in a course-like manner where they are expected to + create everything themselves. + + +Motivation +========== + +Why Python +---------- + +Python has become popular, largely due to good reasons. It's very easy +to get started, there's lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities. + + +Why not Python for Scientific Computing +--------------------------------------- + +While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools. + +- Implementing performance-critical kernels. Python is a **very** + slow language, which often doesn't matter if you can offload the + heavy lifting to fast compiled code, e.g. by using Numpy array + operations. But if what you're trying to do isn't *vectorizable* + then you're out of luck. An alternative to Python, albeit much less + mature and with a smaller ecosystem, but which provides very fast + generated code, is *Julia*. + +- Creating libraries that can be called from other languages. In this + case you'll often want to create a library with a C interface, which + can then be called from most languages. Suitable languages for this + sort of task, depending on what you are doing, could be Rust, C, + C++, or Fortran. + +- You really like static typing, or functional programming + approaches. *Haskell* might be what you're looking for. + + +Python 2 vs Python 3 +-------------------- + +Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard. + +At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2. + + + +Credits +======= + +This course was originally designed by Janne Blomqvist. + +In 2020 it was completely redesigned by a team of the following: + +* Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, ... +* Editor: +* Testers and advisors: Enrico Glerean + +We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html + + +See also +======== + +* `High Performance Data Analytics in Python + ` is a logical follow-up to + this lesson that goes more in-depth to tools of high-performance + and large-scale Python. diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/installation.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/installation.rst.txt new file mode 100644 index 00000000..2a14305a --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/installation.rst.txt @@ -0,0 +1,232 @@ +Software installation +===================== + +This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or some other way access to it. For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line for some lessons). + +**If you need installation help, show this page to someone around you +and they can probably do all you need** + + +Generic list of tools required +------------------------------ + +Note: The actual installation instructions are below. This is a +generic description which will help those who already understand all +of the tools. + +* **Python 3** (Anaconda is recommended, it will include everything) + + * With some extra packages installed. They are all included in + Aanconda, and are listed in the ``environment.yml`` file you can + find under miniconda below. +* Text editor (several lessons, can also be done through Jupyterlab) +* Command-line shell (several lessons, can also be done through Jupyterlab) +* git (not needed, this lesson is usually done as a demo) + +.. admonition:: Generic instructions with miniconda and an environment file (advanced) + :class: dropdown + + This is the advanced, minimal method of installing the Python + packages. For most people, we recommend Anaconda (below). You + will actually learn about miniconda during the workshop. This + doesn't provide the graphical Anaconda navigator, so you'll need to + activate the miniconda environment using the command line. + + You can read how to install miniconda from the `CodeRefinery + installation instructions + `__. + + Then `this environment file + `__ + contains all packages needed, and can be installed with: + + .. code:: console + + $ conda env create -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml + + Each time you start a new shell, you need to activate miniconda (if + you don't do run ``conda init``), and then you need to activate the + proper environment with ``conda activate python-for-scicomp``. + + We might have missed some packages, though, which can be later + installed with ``conda install``. + + + +Python +------ + +We expect you to have a working Python installation with some common +libraries. We recommend that you install the `Anaconda python +distribution `__. The +`Anaconda Navigator `__ +provides a convenient way to access the software. + +.. admonition:: Other options + :class: toggle + + We recommend Anaconda, Anaconda Navigator, and JupyterLab in these + instructions because it is simple and can be used by everyone. As + you advance in your career, we + recommend that you explore other options as well, but + that can come later. + + Any other Python distribution which you can install libraries into + would work, but because there are so many different ways to do this, + we don't support them. You would need the extra libraries mentioned + in the Miniconda instructions above. + + +JupyterLab +~~~~~~~~~~ + +We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). If you install the full +Anaconda distribution, this will be available and can be started +either through Anaconda Navigator or command line. + + + +Verification of Python and JupyterLab +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. admonition:: Watch the video + + See this `verification in video form + `__ - if you can do this, you are + ready to go for day one. Your exact steps may be a bit different. + +**You should be able to start JupyterLab.** You can do this from the +`Anaconda Navigator `__ (recommended if you have it): + +.. figure:: img/installation/anaconda-navigator-jupyterlab.png + :class: with-border + + Starting JupyterLab from the Anaconda Navigator. + +... or you can start JupyterLab from the command line: + +.. code-block:: console + + $ jupyter-lab + (... Jupyter starts in a web browser) + + + +**Verify that you can start a Jupyter notebook.** We will learn how to +do this in day 1, but you can try running ``print("Hello, world!")`` +if you want. + +.. figure:: img/installation/jupyterlab-notebook.png + :class: with-border + + Starting a Jupyter Notebook from JupyterLab. + + +Text editor +----------- + +For one portion of the course, you will need a text editor. **If you +don't know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.** + +.. admonition:: Other editors + :class: toggle + + Because we need to be simple in our teaching, we only teach the + most basic editors. We encourage you to try out more advanced ones + yourself. + + For other editors, see the `CodeRefinery instructions + `__. You don't + exactly need a terminal editor - the graphical ones, such as VSCode or + whatever you use now, will work as well. + + + +Command line +------------ + +**You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed.** If you want to +test in advance: + +* You can start it from JupyterLab (recommended): + + .. figure:: img/installation/jupyterlab-terminal.png + :class: with-border + :scale: 75% + + From the JupyterLab launcher, select "Terminal". + +.. admonition:: Other ways to access the command line + :class: toggle + + * From the Anaconda Navigator: + + .. figure:: img/installation/anaconda-prompt.png + :class: with-border + + From the Anaconda Navigator, you can select "environments" on the + left, then click on one, then the arrow, then "Open terminal". + + * From your operating system's terminal applications, if you activate + Anaconda. + + + +Verification of the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify command line usage, type the following commands (without the +``$``), and you should see the corresponding output that lists the +Python version: + +.. code-block:: console + + $ python -V + Python 3.8.3 + + ## Or python3... + $ python3 -V + Python 3.8.3 + +Any version of Python 3 through a recent Anaconda should work for the +course. + + + +Zoom +---- + +If this is an online workshop, it might use Zoom. You can see +`CodeRefinery instructions for it +`__. + + + +Need help? +---------- + +If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up! + + + +See also +-------- + +* `Research Software Hour on conda + `__ +* `Conda manual `__ (technical) +* `Anaconda individual edition home + `__ +* `Anaconda getting started + `__ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/jupyter.ipynb.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/jupyter.ipynb.txt new file mode 100644 index 00000000..70526301 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/jupyter.ipynb.txt @@ -0,0 +1,409 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter\n", + "\n", + "\n", + "```{questions}\n", + "\n", + " - What is the purpose of a \"Computational narrative\"?\n", + " - What role does Jupyter play in development?\n", + " - When is Jupyter not a good tool?\n", + "```\n", + "\n", + "```{objectives}\n", + "\n", + " This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.\n", + "\n", + " - Be able to use Jupyter to run examples for the rest of the course.\n", + " - Be able to run Jupyter in a directory do your own work.\n", + " - You won't be a Jupyter expert after this, but should be able to do the rest of the course.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is Jupyter?\n", + "\n", + "Jupyter is a web-based interactive computing system. It is most well known for having the *notebook file format* and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a *computational narrative*.\n", + "\n", + "Jupyter is good for data exploration and interactive work.\n", + "\n", + "**We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.**\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting started with Jupyter\n", + "\n", + "* Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run `jupyter-lab`. You can also start in from Anaconda Navigator.\n", + "\n", + "For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here, we see a tour of the JupyterLab interface:\n", + "\n", + "![Main UI tour](img/jupyter/main-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 1\n", + "```{challenge} Exercises: Jupyter-1\n", + "\n", + " 1. Start Jupyter in the directory you want to use for this course.\n", + " - If you are starting from the navigator, change to the directory you want to use.\n", + " - If you are starting from the command line, you should navigate to the directory you want to use first.\n", + "\n", + " 2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.\n", + "\n", + " 4. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.\n", + "\n", + " 5. (optional, advanced) Look at the notebook file in a text\n", + " editor. How does it work?\n", + "\n", + "If everything works for you, this will end very quickly. You can begin reading the next sections independently.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Running code in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A notebook is divided into **cells**. Each cell has some **input**, and when it is executed an **output** appears right below it.\n", + "\n", + "There are different types of cells: primarily **code** cells and **markdown** cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/). For example the previous sentence is:\n", + "\n", + "```none\n", + "Markdown is a lightweight way of giving *style* to `text` - you \n", + "can check out [this reference](https://commonmark.org/help/).\n", + "```\n", + "\n", + "![notebook UI](img/jupyter/notebook-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When using keyboard shortcuts, you can switch between edit mode and command mode with `Enter` and `Esc`. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:\n", + "* `Ctrl-Enter`: Run cell\n", + "* `Shift-Enter`: Run cell and select cell below\n", + "* `Alt-Enter`: Run cell and insert new cell below\n", + "* `a` / `b`: insert new cell above/below\n", + "* `m` / `y`: markdown cell / code cell\n", + "* `x`: cut cell\n", + "* `c`: copy cell\n", + "* `v`: paste cell\n", + "* `d, d`: delete cell" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, let's look at some code samples:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0\n", + "1\n", + "2\n" + ] + } + ], + "source": [ + "for i in range(3):\n", + " print(i)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "10\n" + ] + } + ], + "source": [ + "print(sum(range(5)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By convention, if the last thing in a cell is an object, that object gets printed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "45" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sum(range(5))\n", + "sum(range(10))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to raw cells, there are **magics**, which exist outside of Python. They are a property of the runtime itself (in Python's case, they come from **IPython**. For example, the following cell magic [%%bash](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-bash) turns the cell into a shell script (may not work on all operating systems):" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1\n", + "2\n", + "3\n" + ] + } + ], + "source": [ + "%%bash\n", + "for x in $(seq 3) ; do\n", + " echo $x\n", + "done" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "* A **cell magic** starts with `%%`, goes on the first line of a cell, and applies to the whole cell\n", + "* A **line magic** starts with `%`, goes on any line, and applies to that line." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "```{challenge} Exercises: Jupyter-2\n", + "\n", + " 1. Run some trivial code, such as ``print(1)``.\n", + "\n", + " 2. Run some slightly less trivial code, like print out the first\n", + " ten [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number).\n", + "\n", + " 3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the [reference](https://commonmark.org/help/) to add a heading, bullet list, and some (bold, italic, or inline code)\n", + "\n", + " 4. Use the [%%timeit](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit) magic function to time your Fibonacci\n", + " function.\n", + "\n", + " 5. Again using ``%%timeit``, figure out the fastest way to sum the\n", + " numbers 0 to 1000000.\n", + " \n", + " 6. Once you are done, close your notebooks and other tabs you don't need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.\n", + "```\n", + "\n", + "`````{solution} Solutions: Jupyter-2\n", + "\n", + "1. --\n", + "\n", + "2. Simple fibonacci code\n", + "\n", + " ```python\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " print(a)\n", + " a, b = b, a+b\n", + " ```\n", + "\n", + "3. Markdown description\n", + "\n", + " ```md\n", + " # Fibonacci\n", + " * Start with two variables `a` and `b`\n", + " * Repeat 10 times\n", + " * Print old `a`, then increment both\n", + " * Makes use of the Python *tuple assignment*: `a, b = new_a, new_b`\n", + " ```\n", + "\n", + "4. In this case, the print() statements get out of hand, so we comment that out. In general, writing output usually takes a lot of time reletive to the computation, so we don't want to time that (unless output is the main point of the code, then we do have to time it!\n", + "\n", + " ```ipython\n", + " %%timeit\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " #print(a)\n", + " a, b = b, a+b\n", + " ```\n", + " ```none\n", + " 395 ns ± 10.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n", + " ```\n", + "\n", + "5. --\n", + "\n", + "6. --\n", + "\n", + "`````" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why Jupyter?\n", + "\n", + "- Being able to **edit, check, re-edit** quickly is great for **prototyping and testing new ideas**\n", + " - Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.\n", + "- You can make a **complete story** - in one place. No more having code, figures, and description in different places.\n", + " - Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.\n", + "- Notebook as an interactive publication itself - for example the discovery of gravitational waves data is [released as a notebook](https://www.gw-openscience.org/tutorials/).\n", + "- Jupyter Notebooks display on Github - low-barrier way to share your analysis.\n", + "- Teaching - great for getting difficult software distribution out of the way." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why not Jupyter?\n", + "\n", + "Jupyter is great for many things, but there are some problems if not used well:\n", + "\n", + "- They **don't promote modularity**, and once you get started in a\n", + " notebook it can be hard to migrate to modules.\n", + "- They are **difficult to test**. There are things to run notebooks as\n", + " unit tests like [nbval](https://nbval.readthedocs.io/), but it's not\n", + " perfect.\n", + "- Notebooks can be **version controlled**\n", + " ([nbdime](https://nbdime.readthedocs.io/) helps with that), but\n", + " there are **still limitations**.\n", + "- You can **change code after you run it** and run code out of order.\n", + " This can make debugging hard and results irreproducible if you\n", + " aren't careful.\n", + "- Notebooks **aren't named by default** and tend to **acquire a bunch of\n", + " unrelated stuff**. Be careful with organization!\n", + "- Once lots of code is in notebooks, it can be **hard to change to\n", + " proper programs that can be scripted**.\n", + "\n", + "You can read more about these downsides .\n", + "\n", + "**But these downsides aren't specific to Jupyter!** They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "```{challenge} Exercises: Jupyter-3\n", + "\n", + " (optional) Discuss the following in groups:\n", + "\n", + " 1. Have any of you used Jupyter in a way that became impossible to\n", + " maintain: too many files, code all spread out, not able to find\n", + " your code and run it in the right order. How did you solve that?\n", + "\n", + " 2. On the other hand, what are your successes with Jupyter?\n", + " \n", + " 3. How can you prevent these problems by better development strategies?\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## See also\n", + "\n", + "- The [CodeRefinery Jupyter lesson](https://coderefinery.github.io/jupyter/) has much more, and the source of some of the content above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{keypoints}\n", + "\n", + " - Jupyter is powerful and can be used for interactive work\n", + " - ... but not the end solution when you need to scale up.\n", + "```" + ] + } + ], + "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.10.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/libraries.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/libraries.rst.txt new file mode 100644 index 00000000..724ef81d --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/libraries.rst.txt @@ -0,0 +1,353 @@ +Library ecosystem +================= + +.. questions:: + + - What happens when you need some method Beyond what we discuss in this course, what is available? + - How do you decide what to build on for your work? + +.. objectives:: + + - Know of some other available packages, but don't necessarily know + how to use them. + - Be able to evaluate what you should reuse and what you should + develop yourself. + +You can't do everything yourself. In fact, once we heard a quote such +as this: + + When you are a student, you are expected to do everything + yourself, and that is how you are evaluated. When you become a + researcher, you *have* to be able to reuse what others have done. + We don't have much practice in doing this. + -- A student + +In this lesson, we'll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types: + +- Well-maintained libraries that are used by many others. +- A wide variety of public code that might work but isn't necessarily + well-maintained (for example, code from articles). + +We'll start with the first then go to the second. + + + +Glossary +-------- + +Library + A collection of code used by a program. + +Package + A library that has been made easily installable and reusable. + Often published on public repositories such as the `Python Package + Index `__ + +Dependency + A requirement of another program, not included in that program. + + + +The Python/SciPy ecosystem +-------------------------- + +This section is nothing more than a tour of what exists in Python. +You aren't expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work. + +The "core" packages `could be considered +`__. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy): + +* Python +* Numpy - arrays, everything builds on this +* Scipy - scientific functions (not necessarily a lot builds on this) +* matplotlib - plotting, many other plotting tools build on this +* pandas - data structures +* IPython / Jupyter: interactive work + + + +Core numerics libraries +~~~~~~~~~~~~~~~~~~~~~~~ + +* `numpy `__ - arrays and array math. +* `scipy `__ - software + for math, science, and engineering. + + + +Plotting +~~~~~~~~ + +* `matplotlib `__ - base plotting package, + somewhat low level but almost everything builds on it. +* `seaborn `__ - higher level plotting + interface; statistical graphics. +* `mayavi `__ - 3D plotting +* `PIL `__ - image manipulation. The + original PIL is no longer maintained, the new "Pillow" is a drop-in + replacement. + + + +Data analysis and other important core packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `pandas `__ - columnar + data analysis +* `statsmodels `__ - just what it says +* `SymPy `__ - symbolic math +* `networkx `__ - graph and network analysis +* `h5py `__ and `PyTables `__ - interfaces to + the `HDF5 `__ on-disk file format +* `dateutil `__ and `pytz + `__ - date arithmetic and handling, + timezone database and conversion + + + +Interactive computing and human interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Interactive computing + + * `IPython `__ - nicer interactive interpreter + * `Jupyter `__ (notebook, lab, hub, ...) - + web-based interface to IPython and other languages + +* Testing + + * `pytest `__ - automated testing interface + +* Documentation + + * `Sphinx `__ - documentation generator + (also used for this lesson...) + +* Development environments + + * `Spyder `__ - interactive Python + development environment. + +* `Binder `__ - load any git repository in + Jupyter automatically, good for reproducible research + + + +Speeding up code and parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `PyMPI `__ - Message + Passing Interface (MPI) in Python for parallelizing jobs. +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `numba `__ - just in time compiling of + functions for speed-up +* `PyPy `__ - Python written in Python so that + it can internally optimize more. +* `Dask `__ - distributed array data structure for + distributed computation +* `Joblib `__ - easy embarrassingly + parallel computing +* `IPyParallel `__ - easy + parallel task engine +* `numexpr `__ - Fast evaluation of + array expressions by automatically compiling the arithmetic. + + + +Machine learning +~~~~~~~~~~~~~~~~ + +If you need some machine learning, you probably already know what you +need and this list is short and irrelevant. + +- `tensorflow `__ +- `pytorch `__ +- `nltk `__ - natural language processing +- `scikit-learn `__ - simple tools for + predictive data analysis + + + +Connecting Python to other languages +------------------------------------ + +As we discussed with Scipy, very many of the above packages aren't +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things: + +* **Extending Python** by writing your own modules in C. + + * It's actually common to first have (or write) an analysis package + in C or C++, then make the Python interface. Then it can be + supported by other languages, too. + + * Or one starts an analysis package in Python, and slowly moves bits + of it to C over time as there is need. + +* **Embedding Python**, where you have another primary application + that uses Python under the hood as an internal scripting language. + +These features aren't exactly unique to Python, but Python does +support them very well. Read more: `Extending and embedding Python +`__. + + + +Tools for interfacing with other languages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These days, one rarely directly extends the Python interpreter, but uses + +* `cffi `__ and `ctypes + `__ - interface to C + and compatible libraries +* `cython `__ - easily make C extensions for + Python, also interface to C libraries +* `f2py `__ - interface to Fortran + code +* `swig `__ - connect to a variety of programming languages. +* ``Boost.python`` - Another Python/C++ interface +* TODO: Julia modules for Python? + + + +Evaluating Python packages for reuse +------------------------------------ + +Above, we talked about well-maintained mainstream packages. **Do you +trust random code you find online (for example included in a paper)?** + +Especially consider scientific results, which *have* to be correct. +Still, you also *can't* build everything yourself, so you have to +carefully evaluate the situation. + +Below are some things to consider: + +* Are there releases? Have they been going on for a while? + +* Are releases installable without copy-paste? + +* Are dependencies handled well? + +* Does the code randomly change, so that it no longer works with your + code. Is this relevant? + +* Is there good documentation, that not just tells how to use it but + how it works? + +* Is there automated testing? What's your evaluation of the risk of + undetectable scientific errors? + +* Is there a community, or is it one person? Is it backed by some + organization? Does it have a permanent home? + +* Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) + where a community *could* form? + +* Do others post issues and make contributions? Are these issues + dealt with in a timely manner? Can you search past bug reports? + +* Is the software citeable? + + + +Is your work reuseable? +----------------------- + +Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a `CodeRefinery workshop `__ will make +sure you have the tools to produce high-quality, reusable code. + + + +What's next? +------------ + +* The `CodeRefinery workshop `__ mentioned + above will prepare you for others to reuse your code and for you to + contribute to other code. +* The upcoming :doc:`dependencies` lesson will teach you how to + record and manage dependencies so that anyone can seamlessly reuse + your code. + + + +Exercises +--------- + +.. exercise:: Libraries 1.1: Libraries in your work + + What libraries do you use in your work? What have you made, which + you could have reused from some other source. What have you used + from some other source that you wished you had re-created? + + Discuss in your groups or HackMD. + +.. solution:: Libraries 1.1 + + ... is there anything to say here? + + +.. exercise:: Libraries 1.2: Evaluating packages + + Below are some links to some packages, both public and made by the + authors of this lesson. Evaluate them, considering "would I use + this in my project?" + + a) https://github.com/networkx/networkx/ + b) some code on webpage in a paper's footnote + c) https://github.com/rkdarst/pcd + d) https://github.com/dftlibs/numgrid + e) https://github.com/rkdarst/dynbench + f) https://vpython.org/ + +.. solution:: Libraries 1.2 + + a) networkx: This seems to be a relatively large, active project + using best practices. Probably usable. + b) I would probably use it if I had to, but would prefer not to. + c) This (written by one of the authors of this lesson) has no + documenting, no community, no best practices, and is very old. + Probably not a good idea to try to use it + d) This project uses best practices, but doesn't seem to have a big + community. It's probably fine to use, but who knows if it will + be maintained 10 years from now. It does have automated tests + via Github Actions (``.github/workflows`` and the green checks), + so the authors have put some work into making it correct. + e) This (also written by one of the authors) looks like it was made + for a paper of some sort. It has some minimal documentation, + but still is missing many best practices and is clearly not + maintained anymore (look at the ancient pull request). Probably + not a good idea to use unless you have to. + f) This project has a pretty website, and some information. But + seems to not be using best practices of an open repository, and + custom locations which could disappear at any time. + + You notice that several of the older projects here were written by + one of the authors of this lesson. It goes to show that everyone + starts somewhere and improves over time - don't feel bad if your + work isn't perfect, as long as you keep trying to get better! + + + +See also +-------- + +* `Topical Software in the SciPy ecosystem + `__ - relatively + detailed (but not comprehensive) list of projects + + +.. keypoints:: + + - Almost everything you need can already be found, except your + incremental work. + - When do you build on that other work, and when do you create + things yourself? diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/numpy-advanced.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/numpy-advanced.rst.txt new file mode 100644 index 00000000..aba1ec3b --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/numpy-advanced.rst.txt @@ -0,0 +1,407 @@ +Advanced NumPy +============== + +.. questions:: + + - How can NumPy be so fast? + - Why are some things fast and some things slow? + - How can I control whether NumPy makes a copy or operates in-place? + +.. objectives:: + + - Understand why NumPy has so many specialized functions for specific operations + - Understand the underlying machinery of the Numpy :class:`~numpy.ndarray` object + - Understand when and why NumPy makes a copy of the data rather than a view + + This is intended as a follow-up to the :doc:`basic NumPy lesson `. The intended + audience for this advanced lesson is those who have used NumPy before and + now want to learn how to get the most out of this amazing package. + + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +`Guide to NumPy `_ by +Travis E. Oliphant, its initial creator. + + + +NumPy can be really fast +------------------------ + +Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python's build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast. + +.. highlight:: c + +How fast can NumPy be? Let's race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:: + + #include + #include + #define N_ELEMENTS 100000000 + int main(int argc, char** argv) { + double* a = (double*) malloc(sizeof(double) * N_ELEMENTS); + int i; + for(i=0; i` before continuing with this + advanced lesson. If you are taking a live course - don't + worry, watch and learn and explore some during the exercises! + +.. solution:: Solutions: Numpy-Advanced-1 + + The script can be implemented like this:: + + import numpy as np + print(np.random.rand(100_000_000).sum()) + + +.. highlight:: python + +The libraries behind the curtain: MKL and BLAS +---------------------------------------------- + +NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel's `Math Kernel Library (MKL) `_, +which are in turn derived from a Fortran library called +`Basic Linear Algebra Subprograms (BLAS) `_. +BLAS for Fortran was `published in 1979 `_ +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +`specialized CPU instructions for manipulating arrays `_. +In other words, they are *fast*. + +One of the functions inside the BLAS library is a +`function `_ +to compute the "norm" of a vector, which is the same as computing its length, using the +`Pythagorean theorem `_: +:math:`\sqrt(a[0]^2 + a[1]^2 + \ldots)`. + +Let's race the BLAS function versus a naive "manual" version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:: + + import numpy as np + rng = np.random.default_rng(seed=0) + a = rng.random(100_000_000) + +We now implement the Pythagorean theorem using basic NumPy functionality and +use ``%%timeit`` to record how long it takes to execute:: + + %%timeit + l = np.sqrt(np.sum(a ** 2)) + print(l) + +And here is the version using the specialized BLAS function :func:`~numpy.linalg.norm`:: + + %%timeit + l = np.linalg.norm(a) + print(l) + + +NumPy tries to avoid copying data +---------------------------------- + +Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy's +:class:`numpy.ndarray` datastructure works behind the scenes. + + +An example: matrix transpose +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let's see how long NumPy's +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +:func:`~numpy.random.rand` matrix:: + + import numpy as np + a = np.random.rand(10_000, 20_000) + print(f'Matrix `a` takes up {a.nbytes / 10**6} MB') + +Let's time the :meth:`~numpy.ndarray.transpose` method:: + + %%timeit + b = a.transpose() + +It takes mere nanoseconds to transpose 1600 MB of data! How? + + +The ndarray exposed +~~~~~~~~~~~~~~~~~~~ +The first thing you need to know about :class:`numpy.ndarray` is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector. + +.. image:: img/numpy-advanced/01_memory_layout.svg + +NumPy is faking the second dimension behind the scenes! When we request the +element at say, ``[2, 3]``, NumPy converts this to the correct index in the +long 1D array ``[11]``. + + * Converting ``[2, 3]`` → ``[11]`` is called "raveling" + * The reverse, converting ``[11]`` → ``[2, 3]`` is called "unraveling" + +The implications of this are many, so take let's take some time to understand +it properly by writing our own ``ravel()`` function. + +Exercise 2 +---------- + +.. challenge:: Exercises: Numpy-Advanced-2 + + Write a function called ``ravel()`` that takes the row and column of an + element in a 2D matrix and produces the appropriate index in an 1D array, + where all the rows are concatenated. See the image above to remind yourself + how each row of the 2D matrix ends up in the 1D array. + + The function takes these inputs: + + - ``row`` The row of the requested element in the matrix as integer index. + - ``col`` The column of the requested element in the matrix as integer index. + - ``n_rows`` The total number of rows of the matrix. + - ``n_cols`` The total number of columns of the matrix. + + Here are some examples of input and desired output: + + - ``ravel(2, 3, n_rows=4, n_cols=4)`` → ``11`` + - ``ravel(2, 3, n_rows=4, n_cols=8)`` → ``19`` + - ``ravel(0, 0, n_rows=1, n_cols=1)`` → ``0`` + - ``ravel(3, 3, n_rows=4, n_cols=4)`` → ``15`` + - ``ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000)`` → ``69_318_923`` + +.. solution:: Solutions: Numpy-Advanced-2 + + The function can be implemented like this:: + + def ravel(row, col, n_rows, n_cols): + return row * n_cols + col + +Strides +------- + +As seen in the exercise, to get to the next row, we have to skip over +``n_cols`` indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of "strides":: + + np.zeros((4, 8)).strides # (64, 8) + np.zeros((4, 5, 6, 7, 8)).strides # (13440, 2688, 448, 64, 8) + +The :attr:`~numpy.ndarray.strides` attribute contains for each dimension, the number of *bytes* (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes. + +So now we know the mystery behind the speed of :meth:`~numpy.ndarray.transpose`. NumPy can avoid +copying any data by just modifying the :attr:`~numpy.ndarray.strides` of the array:: + + import numpy as np + + a = np.random.rand(10_000, 20_000) + b = a.transpose() + + print(a.strides) # (160000, 8) + print(b.strides) # (8, 160000) + +Another example: reshaping +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modifying the shape of an array through :func:`numpy.reshape` is also +accomplished without any copying of data by modifying the :attr:`~numpy.ndarray.strides`:: + + a = np.random.rand(20_000, 10_000) + print(f'{a.strides=}') # (80000, 8) + b = a.reshape(40_000, 5_000) + print(f'{b.strides=}') # (40000, 8) + c = a.reshape(20_000, 5_000, 2) + print(f'{c.strides=}') # (80000, 16, 8) + + +Exercises 3 +----------- + +.. challenge:: Exercises: Numpy-Advanced-3 + + A little known feature of NumPy is the ``numpy.stride_tricks`` module + that allows you to modify the :attr:`~numpy.ndarray.strides` attribute directly. Playing + around with this is very educational. + + 1. Create your own ``transpose()`` function that will transpose a 2D matrix + by reversing its :attr:`~numpy.ndarray.shape` and :attr:`~numpy.ndarray.strides` attributes using + :func:`numpy.lib.stride_tricks.as_strided`. + + 2. Create a (5 ✕ 100 000 000 000) array containing on the first row all + 1's, the second row all 2's, and so on. Start with an 1D array + ``a = np.array([1., 2., 3., 4., 5.])`` + and modify its ``shape`` and ``strides`` attributes using + :func:`numpy.lib.stride_tricks.as_strided` to obtain the desired 2D + matrix:: + + array([[1., 1., 1., ..., 1., 1., 1.], + [2., 2., 2., ..., 2., 2., 2.], + [3., 3., 3., ..., 3., 3., 3.], + [4., 4., 4., ..., 4., 4., 4.], + [5., 5., 5., ..., 5., 5., 5.]]) + + +.. solution:: Solutions: Numpy-Advanced-3 + + 1. The ``transpose()`` function can be implemented like this:: + + from numpy.lib.stride_tricks import as_strided + def transpose(a): + return as_strided(a, shape=a.shape[::-1], strides=a.strides[::-1]) + + # Testing the function on a small matrix + a = np.array([[1, 2, 3], + [4, 5, 6]]) + print('Before transpose:') + print(a) + print('After transpose:') + print(transpose(a)) + + 2. By setting one of the ``.strides`` to `0`, we can repeat a value + infinitely many times without using any additional memory:: + + from numpy.lib.stride_tricks import as_strided + a = np.array([1., 2., 3., 4., 5.]) + as_strided(a, shape=(5, 100_000_000_000), strides=(8, 0)) + + +A fast thing + a fast thing = a fast thing? +------------------------------------------- + +If :func:`numpy.transpose` is fast, and :func:`numpy.reshape` is fast, then +doing them both must be fast too, right?:: + + # Create a large array + a = np.random.rand(10_000, 20_000) + +Measuring the time it takes to first transpose and then reshape:: + + %%timeit -n 1 -r 1 + a.T.reshape(40_000, 5_000) + +In this case, the data actually had to be copied and it's super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the :attr:`~numpy.ndarray.strides`:: + + a = np.array([[1, 2, 3], [4, 5, 6]]) + + print('Original array:') + print(a) + + print('\nTransposed:') + print(a.T) + + print('\nTransposed and then reshaped:') + print(a.T.reshape(2, 3)) + + +Copy versus view +---------------- + +Whenever NumPy constructs a new array by modifying the :attr:`~numpy.ndarray.strides` instead of +copying data, we way it created a "view". This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +:class:`numpy.ndarray` object will have a reference to the original array in +its :attr:`~numpy.ndarray.base` attribute:: + + a = np.zeros((5, 5)) + print(a.base) # None + b = a[:2, :2] + print(b.base.shape) # (5, 5) + +.. warning:: + When you create a large array and select only a portion of it, the large + array will stay in memory if a view was created! + +The new array ``b`` object has a pointer to the same memory buffer as the array +it has been derived from:: + + print(a.__array_interface__['data']) + print(b.__array_interface__['data']) + +Views are created by virtue of modifying the value of the :attr:`~numpy.ndarray.shape` attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:: + + b = a[1:3, 1:3] # This view does not start at the beginning + offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0] + print('Offset:', offset, 'bytes') # Offset: 48 bytes + +.. image:: img/numpy-advanced/02_views.svg + +Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:: + + b[0, 0] = 1. + print(a) # Original matrix was modified + +Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:: + + c = a[[0, 2]] # Select rows 0 and 2 + print(c.base) # None. So not a view. + + +See also +-------- + +* `Guide to Numpy `__ +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + * `Advanced NumPy: Master stride tricks with 25 illustrated exercises `__ + + + +.. keypoints:: + + - The best way to make your code more efficient is to learn more about the + NumPy API and use specialized functions whenever possible. + - NumPy will avoid copying data whenever it can. Whether it can depends on + what kind of layout the data is currently in. diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/numpy.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/numpy.rst.txt new file mode 100644 index 00000000..06f76be3 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/numpy.rst.txt @@ -0,0 +1,518 @@ +.. _numpy: + +NumPy +===== + +.. questions:: + + - Why use NumPy instead of pure python? + - How to use basic NumPy? + - What is vectorization? + +.. objectives:: + + - Understand the Numpy array object + - Be able to use basic NumPy functionality + - Understand enough of NumPy to seach for answers to the rest of your questions ;) + + We expect most people to be able to do all the basic exercises + here. It is probably quite easy for many people; we have advanced + exercises at the end in that case. + + + +So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible. + +.. highlight:: python + +What is an array? +----------------- + +For example, consider ``[1, 2.5, 'asdf', False, [1.5, True]]`` - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately. + +NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it. + +An array is a 'grid' of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has: + +* :ref:`dtype ` - data type. Arrays always contain one type +* :term:`shape` - shape of the data, for example ``3×2`` or ``3×2×500`` or even + ``500`` (one dimensional) or ``[]`` (zero dimensional). +* :attr:`data ` - raw data storage in memory. This can be passed to C or + Fortran code for efficient calculations. + + +To test the performance of pure Python vs NumPy we can write in our jupyter notebook: + +Create one list and one 'empty' list, to store the result in :: + + a = list(range(10000)) + b = [ 0 ] * 10000 + +In a new cell starting with ``%%timeit``, loop through the list ``a`` and fill the second list ``b`` with ``a`` squared :: + + %%timeit + for i in range(len(a)): + b[i] = a[i]**2 + +That looks and feels quite fast. But let's take a look at how NumPy performs for the same task. + +So for the NumPy example, create one array and one 'empty' array to store the result in :: + + import numpy as np + a = np.arange(10000) + b = np.zeros(10000) + +In a new cell starting with ``%%timeit``, fill ``b`` with ``a`` squared :: + + %%timeit + b = a ** 2 + +We see that compared to working with numpy arrays, working with traditional python lists is actually slow. + + +Creating arrays +--------------- + +There are different ways of creating arrays (:func:`numpy.array`, :attr:`numpy.ndarray.shape`, :attr:`numpy.ndarray.size`):: + + a = np.array([1,2,3]) # 1-dimensional array (rank 1) + b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2) + + b.shape # the shape (rows,columns) + b.size # number of elements + +In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (:func:`numpy.zeros`, :func:`numpy.ones`, :func:`numpy.full`, :func:`numpy.eye`, :func:`numpy.arange`, :func:`numpy.linspace`):: + + np.zeros((2, 3)) # 2x3 array with all elements 0 + np.ones((1,2)) # 1x2 array with all elements 1 + np.full((2,2),7) # 2x2 array with all elements 7 + np.eye(2) # 2x2 identity matrix + + np.arange(10) # Evenly spaced values in an interval + np.linspace(0,9,10) # same as above, see exercise + + c = np.ones((3,3)) + d = np.ones((3, 2), 'bool') # 3x2 boolean array + +Arrays can also be stored and read from a (.npy) file (:func:`numpy.save`, :func:`numpy.load`):: + + np.save('x.npy', a) # save the array a to a .npy file + x = np.load('x.npy') # load an array from a .npy file and store it in variable x + +In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (:attr:`numpy.ndarray.dtype`, :meth:`numpy.ndarray.astype`):: + + d.dtype # datatype of the array + d.astype('int') # change datatype from boolean to integer + +In the last example, ``.astype('int')``, it will make a **copy** of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed. + + + +Exercises 1 +----------- + +.. challenge:: Exercises: Numpy-1 + + 1. **Datatypes** Try out :func:`np.arange(10) ` and :func:`np.linspace(0,9,10) `, what is the difference? Can you adjust one to do the same as the other? + + 2. **Datatypes** Create a 3x2 array of random float numbers (check :func:`numpy.random.random`) between 0 and 1. Now change the arrays datatype to int (:meth:`array.astype `). How does the array look like? + + 3. **Reshape** Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check :meth:`array.reshape `) in any way possible. What is not possible? + + 4. **NumPyI/O** Save above array to .npy file (:func:`numpy.save`) and read it in again. + +.. solution:: Solutions: Numpy-1 + + 1. **Datatypes** + + - ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**, + - while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**. + + Both ``np.linspace`` and ``np.arange`` take dtype as an argument and can be adjusted to match each other in that way. + + 2. **Datatypes** eg ``a = np.random.random((3,2))``. ``a.astype('int')`` results in an all zero array, not as maybe expected the rounded int (all numbers [0, 1) are cast to 0). + + 3. **Reshape** eg ``b = np.random.randint(0,10,(3,2))``. + + ``b.reshape((6,1))`` and ``b.reshape((2,3))`` possible. + + It is not possible to reshape to shapes using more or less elements than ``b.size = 6``, so for example ``b.reshape((12,1))`` gives an error. + + 4. **NumPyI/O** ``np.save('x.npy', b)`` and ``x = np.load('x.npy')`` + + + +Array maths and vectorization +----------------------------- + +Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do. + +By default, basic arithmetic (``+``, ``-``, ``*``, ``/``) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is "vectorized" +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop. + +Note that unlike Matlab, where ``*`` means matrix multiplication, NumPy uses +``*`` to perform element-by-element multiplication and uses the ``@`` symbol to +perform matrix multiplication:: + + a = np.array([[1,2],[3,4]]) + b = np.array([[5,6],[7,8]]) + + # Addition + c = a + b + d = np.add(a,b) + + # Matrix multiplication + e = a @ b + f = np.dot(a, b) + +Other common mathematical operations include: ``-`` (:data:`numpy.subtract`), ``*`` (:data:`numpy.multiply`), ``/`` (:data:`numpy.divide`), ``.T`` (:func:`numpy.transpose`), :data:`numpy.sqrt`, :func:`numpy.sum`, :func:`numpy.mean`, ... + + + +Exercises 2 +----------- + +.. challenge:: Exercises: Numpy-2 + + - **Matrix multiplication** What is the difference between :data:`numpy.multiply` and :func:`numpy.dot` ? Try it. + - **Axis** What is the difference between :func:`np.sum(axis=1) ` vs + :func:`np.sum(axis=0) ` on a two-dimensional array? What if you leave out the axis parameter? + + +.. solution:: Solutions: Numpy-2 + + - **Matrix multiplication** ``np.multiply`` does elementwise multiplication on two arrays, while ``np.dot`` enables matrix multiplication. + - **Axis** ``axis=1`` does the operation (here: ``np.sum``) over each row, while axis=0 does it over each column. If axis is left out, the sum of the full array is given. + + + +Indexing and Slicing +-------------------- + +.. seealso:: + + :ref:`Numpy basic indexing docs ` + +NumPy has many ways to extract values out of arrays: + +- You can select a single element +- You can select rows or columns +- You can select ranges where a condition is true. + +Clever and efficient use of these operations is a key to NumPy's +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C. + +:: + + a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15 + a[0] # first row + a[:,0] # first column + a[1:3,1:3] # middle 2x2 array + + a[(0, 1), (1, 1)] # second element of first and second row as array + +Boolean indexing on above created array:: + + idx = (a > 0) # creates boolean matrix of same size as a + a[idx] # array with matching values of above criterion + + a[a > 0] # same as above in one line + + + +Exercises 3 +----------- + +.. challenge:: Exercise: Numpy-3 + + :: + + a = np.eye(4) + b = a[:,0] + b[0] = 5 + + - **View vs copy** Try out above code. How does ``a`` look like before ``b`` has changed and after? How could it be avoided? + +.. solution:: Solution: Numpy-3 + + - **View vs copy** The change in ``b`` has also changed the array ``a``! + This is because ``b`` is merely a view of a part of array ``a``. Both + variables point to the same memory. Hence, if one is changed, the other + one also changes. If you need to keep the original array as is, use + ``np.copy(a)``. + + +Types of operations +------------------- + +There are different types of standard operations in NumPy: + +**ufuncs**, ":ref:`universal functions `": These are element-by-element +functions with standardized arguments: + +- One, two, or three input arguments +- For example, ``a + b`` is similar to :data:`np.add(a, b) ` but the ufunc + has more control. +- ``out=`` output argument, store output in this array (rather than + make a new array) - saves copying data! +- See the `full reference + `__ + +- They also do **broadcasting** (:ref:`ref `). Can you add a 1-dimensional array of shape `(3)` + to an 2-dimensional array of shape `(3, 2)`? With broadcasting you + can! + + :: + + a = np.array([[1, 2, 3], + [4, 5, 6]]) + b = np.array([10, 10, 10]) + a + b # array([[11, 12, 13], + # [14, 15, 16]]) + + Broadcasting is smart and consistent about what it does, which I'm + not clever enough to explain quickly here: `the manual page on + broadcasting + `__. + The basic idea is that it expands dimensions of the smaller array so + that they are compatible in shape. + +**Array methods** do something to one array: + +- Some of these are the same as ufuncs:: + + x = np.arange(12) + x.shape = (3, 4) + x # array([[ 0, 1, 2, 3], + # [ 4, 5, 6, 7], + # [ 8, 9, 10, 11]]) + x.max() # 11 + x.max(axis=0) # array([ 8, 9, 10, 11]) + x.max(axis=1) # array([ 3, 7, 11]) + +**Other functions**: there are countless other functions covering +linear algebra, scientific functions, etc. + + + +Exercises 4 +----------- + +.. challenge:: Exercises: Numpy-4 + + - **In-place addition**: Create an array, add it to itself using a + ufunc. + + - **In-place addition** (advanced): Create an array of + ``dtype='float'``, and an array of ``dtype='int'``. Try to use the + int array is the output argument of the first two arrays. + + - **Output arguments and timing** Repeat the initial ``b = a ** + 2`` example using the output arguments and time it. Can you make + it even faster using the output argument? + +.. solution:: Solution: Numpy-4 + + - **in-place addition**:: + + x = np.array([1, 2, 3]) + id(x) # get the memory-ID of x + np.add(x, x, x) # Third argument is output array + np.add(x, x, x) + print(x) + id(x) # get the memory-ID of x + # - notice it is the same + + You note that ``np.add()`` has a third argument that is the + output array (same as ``out=``), *and* the function returns that + same array. + + + - **Output arguments and timing** In this case, on my computer, it was + actually slower (this is due to it being such a small array!):: + + a = np.arange(10000) + b = np.zeros(10000) + + :: + + %%timeit + numpy.square(a, out=b) + + This is a good example of why you always need to time things + before deciding what is best. + + +Linear algebra and other advanced math +-------------------------------------- + +In general, you use :class:`arrays ` (n-dimensions), not :class:`matrixes ` +(specialized 2-dimensional) in NumPy. + +Internally, NumPy doesn't invent its own math routines: it relies on +`BLAS +`__ +and `LAPACK `__ to do this kind +of math - the same as many other languages. + +- `Linear algebra in numpy + `__ + +- `Many, many other array functions + `__ + +- `Scipy `__ has even + more functions + +- Many other libraries use NumPy arrays as the standard data + structure: they take data in this format, and return it similarly. + Thus, all the other packages you may want to use are compatible + +- If you need to write your own fast code in C, NumPy arrays can be + used to pass data. This is known as `extending Python + `__. + + + + +Additional exercises +-------------------- + +.. challenge:: Numpy-5 + + If you have extra time, try these out. These are advanced and + optional, and will not be done in most courses. + + 1. Reverse a vector. Given a vector, reverse it such that the last + element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]`` + + 2. Create a 2D array with zeros on the borders and 1 inside. + + 3. Create a random array with elements [0, 1), then add 10 to all + elements in the range [0.2, 0.7). + + 4. What is :func:`np.round(0.5) `? What is ``np.round(1.5)``? Why? + + 5. In addition to ``np.round``, explore :data:`numpy.ceil`, :data:`numpy.floor`, + :data:`numpy.trunc`. In particular, take note of how they behave with + negative numbers. + + 6. Recall the identity :math:`\sin^2(x) + \cos^2(x) = 1`. Create a + random 4x4 array with values in the range [0, 10). Now test the + equality with :data:`numpy.equal`. What result do you get with + :func:`numpy.allclose` instead of ``np.equal``? + + 7. Create a 1D array with 10 random elements. Sort it. + + 8. What's the difference between :meth:`np_array.sort() ` and + :func:`np.sort(np_array) `? + + 9. For the random array in question 8, instead of sorting it, perform + an indirect sort. That is, return the list of indices which would + index the array in sorted order. + + 10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next + combine them into a single 8x4 array with the content of the zeros + array on top and the ones on the bottom. Finally, do the same, + but create a 4x8 array with the zeros on the left and the ones on + the right. + + 11. NumPy functionality Create two 2D arrays and do matrix multiplication + first manually (for loop), then using the np.dot function. Use %%timeit + to compare execution times. What is happening? + + +.. solution:: Solution Numpy-5 + + 1. One solution is:: + + a = np.array([1, 2, 3]) + a[::-1] + + 2. One solution is:: + + b = np.ones((10,10)) + b[:,[0, -1]]=0 + b[[0, -1],:]=0 + + 3. A possible solution is:: + + x = np.random.rand(100) + y = x + 10*(x >= 0.2)*(x < 0.7) + + 4. For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. + + 5. Let's test those functions with few negative and positive values:: + + a = np.array([-3.3, -2.5, -1.5, -0.75, -0.5, 0.5, 0.75, 1.5, 2.5, 3]) + np.round(a) + np.ceil(a) + np.floor(a) + np.trun(a) + + 6. One solution is:: + + x = 10*np.random.rand(4,4) + oo = np.ones((4,4)) + s2c2 = np.square(np.sin(x))+np.square(np.cos(x)) + np.equal(oo,s2c2) + np.allclose(oo,s2c2) + + 7. Sorting the array itself, without copying it:: + + x = np.random.rand(10) + x.sort() + + 8. NumPy.sort() returns a sorted copy of an array. + + 9. ``np.argsort(x)`` + + 10. One solution is:: + + z = np.zeros((4,4)) + o = np.ones((4,4)) + np.concatenate((z,o)) + np.concatenate((z,o),axis=1) + + 11. Using numpy without numpy functionality (np.dot) in this case, is still slow. + + + +See also +-------- + +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + +* `2020 Nature paper on NumPy's role and basic concepts `__ + + + +.. keypoints:: + + - NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally. + - Be aware of some NumPy specific peculiarities diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/packaging.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/packaging.rst.txt new file mode 100644 index 00000000..405dc6d6 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/packaging.rst.txt @@ -0,0 +1,321 @@ +Packaging +========= + +.. questions:: + + - How to organize Python projects larger than one script? + - What is a good file and folder structure for Python projects? + - How can you make your Python functions most usable by your collaborators? + - How to prepare your code to make a Python package? + - How to publish your Python package? + +.. objectives:: + + - Learn to identify the components of a Python package + - Learn to create a Python package + - Learn to publish a Python package + + +Organizing Python projects +-------------------------- + +Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file. + +In the :ref:`scripts` episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further. + +**Recommendations**: + +- Collect related functions into modules (files). +- Collect related modules into packages (we will show how). +- Add a ``LICENSE`` file to your code + (see `Software Licensing and Open source explained with cakes `__). +- Write a ``README.md`` file describing what the code does and how to use it. +- It is also recommended to `document your package `__. +- When the project grows, you might need `automated testing `__. + +To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: ``scipy``. + +These are the 3 files: + +.. literalinclude:: packaging-example-project/calculator/adding.py + :caption: adding.py + +.. literalinclude:: packaging-example-project/calculator/subtracting.py + :caption: subtracting.py + +.. literalinclude:: packaging-example-project/calculator/integrating.py + :caption: integrating.py + +We will add a fourth file: + +.. literalinclude:: packaging-example-project/calculator/__init__.py + :caption: __init__.py + +This ``__init__.py`` file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using *relative imports* +(with the dot). + +This is how we will arrange the files in the project folder/repository: + +.. code-block:: none + :emphasize-lines: 3-6 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + └── README.md + +Now we are ready to test the package. For this we need to be in the "root" +folder, what we have called the *project-folder*. We also need to have +``scipy`` available in our environment: + +.. literalinclude:: packaging-example-project/test.py + +The package is not yet pip-installable, though. We will make this possible in +the next section. + + +Testing a local pip install +--------------------------- + +To make our example package pip-installable we need to add one more file: + +.. code-block:: none + :emphasize-lines: 9 + + project-folder + ├── calculator + │ ├── adding.py + │ ├── __init__.py + │ ├── integrating.py + │ └── subtracting.py + ├── LICENSE + ├── README.md + └── setup.py + +This is how ``setup.py`` looks: + +.. literalinclude:: packaging-example-project/setup.py + :caption: setup.py + :emphasize-lines: 18-20 + +Note how our package requires ``scipy`` and we decided to not pin the version +here (see :ref:`version_pinning`). + +Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see :ref:`pypi`) + + + +Exercises 1 +----------- + +.. challenge:: Packaging-1 + + To test a local pip install: + + - Create a new folder outside of our example project + - Create a new virtual environment (:ref:`dependency_management`) + - Install the example package from the project folder + into the new environment: ``$ pip install /path/to/project-folder/`` + - Test the local installation: + + .. literalinclude:: packaging-example-project/test.py + + +Sharing packages via PyPI +------------------------- + +Once we are able to pip-install the example package locally, we are ready for +upload. + +We exercise by uploading to `test-PyPI `__, not the +real `PyPI `__, so that if we mess things up, nothing bad +happens. + +We need two more things: + +- We will do this using `Twine `__ so you need + to pip install that, too. +- You need an account on `test-PyPI `__. + +.. highlight:: console + +Let's try it out. First we create the distribution package:: + + $ python setup.py sdist + +We need twine:: + + $ pip install twine + +And use twine to upload the distribution files to test-PyPI:: + + $ twine upload -r testpypi dist/* + + Uploading distributions to https://test.pypi.org/legacy/ + Enter your username: + Enter your password: + +Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt "myname"):: + + $ pip install -i https://test.pypi.org/simple/ calculator-myname + + +Tools that simplify sharing via PyPI +------------------------------------ + +The solution that we have used to create the example package (using +``setuptools`` and ``twine``) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using ``pyproject.toml`` as more general alternative to +``setup.py``. + +There are at least two tools which try to make the packaging and PyPI interaction easier: + +- `Poetry `__ +- `Flit `__ + + +Building a conda package and share it +------------------------------------- + +.. demo:: + + Most people will watch and observe this, due to speed which we will + move. + +.. callout:: Prerequisites + + To create a conda package, `conda-build` package is required. You may install it with **Anaconda Navigator** or from the command line:: + + $ conda install conda-build + + +The simplest way for creating a conda package for your python script is to +first publish it in `PyPI `__ following the steps explained +above. + + +Building a python package with conda skeleton pypi +*************************************************** + +Once build, the conda package can be installed locally. For this example, we +will use `runtest `__. `runtest +`__ is a numerically tolerant end-to-end test +library for research software. + +1. Create pypi skeleton:: + + $ conda skeleton pypi runtest + + The command above will create a new folder called `runtest` containing a file `meta.yaml`, the conda recipe for `runtest`. + +2. Edit `meta.yaml` and update requirements: + + .. code-block:: yaml + + requirements: + host: + - pip + - python + - flit + run: + - python + - flit + + In the requirements above, we specified what is required for the `host `__ and for `running `__ the package. + + .. callout:: Remark + + For pure python recipes, this is all you need for building a python package with conda. + If your package needs to be built (for instance compilation), you would need additional files e.g. `build.sh` (to build on Linux/Mac-OSX) and `bld.bat` (to build on Windows systems). You can also add test scripts for testing your package. See `documentation `__ + + +3. Build your package with conda + + Your package is now ready to be build with conda:: + + $ conda-build runtest + + + .. callout:: Conda package location + + Look at the messages produced while building. The location of the local conda package is given (search for `anaconda upload`):: + + ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2 + + The prefix `~/anaconda3/` may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder `win-64` differs too (for instance `linux-64` on Linux machines). + + The conda package we have created is specific to your platform (here `win-64`). It can be converted to other platforms using `conda convert `__. + +4. Check within new environment + + It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments. + + :: + + $ conda create -n local-runtest --use-local runtest + + We can then check `runtest` has been successfully installed in `local-runtest` conda environment. Open a new Terminal with `local-runtest` environment (either from the command line:: + + $ conda activate local-runtest + + or via **Anaconda Navigator** (Open Terminal), import runtest and + check its version: + + .. code-block:: python + + import runtest + print(runtest.__version__) + + +.. callout:: Building a conda package from scratch + + It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the `conda-build documentation `__ for more information. + +To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a `conda channel `__ (see below). + + + +Publishing a python package +*************************** + +- Upload your package to *Anaconda.org*: see instructions `here + `__. + Please note that you will have to create an account on Anaconda. + +- Upload your package to `conda-forge `__: + conda-forge is a conda channel: it contains community-led collection of + recipes, build infrastructure and distributions for the conda package + manager. Anyone can public conda packages to conda-forge if certain + `guidelines `__ are respected. + +- Upload your package to `bioconda `_: bioconda is + a very popular channel for the conda package manager specializing in + bioinformatics software. As for conda-forge, you need to follow their + `guidelines `__ when + building conda recipes. + +You can also `create your own conda channel +`__ +for publishing your packages. + + +.. keypoints:: + + - Organize your code for publishing + - Pypi + - conda diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/pandas.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/pandas.rst.txt new file mode 100644 index 00000000..e5a2d626 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/pandas.rst.txt @@ -0,0 +1,583 @@ +Pandas +====== + +.. questions:: + + - How do I learn a new Python package? + - How can I use pandas dataframes in my research? + +.. objectives:: + + - Learn simple and some more advanced usage of pandas dataframes + - Get a feeling for when pandas is useful and know where to find more information + - Understand enough of pandas to be able to read its documentation. + +.. default-domain:: py + + +Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including: + +- a `Getting started guide `__ + (including tutorials and a 10 minute flash intro) +- a `"10 minutes to pandas" `__ + tutorial +- thorough `Documentation `__ containing a user guide, + API reference and contribution guide +- a `cheatsheet `__ +- a `cookbook `__. + +Let's get a flavor of what we can do with pandas. We will be working with an +example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:: + + import pandas as pd + +We can download the data from `this GitHub repository `__ +by visiting the page and saving it to disk, or by directly reading into +a :class:`~pandas.DataFrame`:: + + url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv" + titanic = pd.read_csv(url, index_col='Name') + +We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:: + + # print the first 5 lines of the dataframe + titanic.head() + + # print summary statistics for each column + titanic.describe() + +Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38\% of passengers survived, etc. + +Let's say we're interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn't survive, and plot corresponding histograms of +the age distribution (:meth:`pandas.DataFrame.groupby`, :meth:`pandas.DataFrame.hist`):: + + print(titanic.groupby("Survived")["Age"].mean()) + +:: + + titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10), + layout=(2,1), zorder=2, sharex=True, rwidth=0.9); + + +Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let's get back to basics. + +.. callout:: Getting help + + Series and DataFrames have a lot functionality, but + how can we find out what methods are available and how they work? One way is to visit + the `API reference `__ + and reading through the list. + Another way is to use the autocompletion feature in Jupyter and type e.g. + ``titanic["Age"].`` in a notebook and then hit ``TAB`` twice - this should open + up a list menu of available methods and attributes. + + Jupyter also offers quick access to help pages (docstrings) which can be + more efficient than searching the internet. Two ways exist: + + - Write a function name followed by question mark and execute the cell, e.g. + write ``titanic.hist?`` and hit ``SHIFT + ENTER``. + - Write the function name and hit ``SHIFT + TAB``. + + +What's in a dataframe? +---------------------- + +As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +:class:`pandas.DataFrame` +is composed of rows and columns: + +.. image:: img/pandas/01_table_dataframe.svg + +Each column of a dataframe is a :class:`pandas.Series` object +- a dataframe is thus a collection of series:: + + # print some information about the columns + titanic.info() + +Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type ``int64`` or of type ``object``. + +Let's inspect one column of the Titanic passanger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):: + + titanic["Age"] + titanic.Age # same as above + type(titanic["Age"]) + +The columns have names. Here's how to get them (:attr:`~pandas.DataFrame.columns`):: + + titanic.columns + +However, the rows also have names! This is what Pandas calls the :obj:`~pandas.DataFrame.index`:: + + titanic.index + +We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and values. We can +refer to columns and rows either by number or by their name +(:attr:`~pandas.DataFrame.loc`, :attr:`~pandas.DataFrame.iloc`, +:attr:`~pandas.DataFrame.at`, :attr:`~pandas.DataFrame.iat`):: + + titanic.loc['Lam, Mr. Ali',"Age"] # select single value by row and column + titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"] # slice the dataframe by row and column *names* + titanic.iloc[0:2,3:6] # same slice as above by row and column *numbers* + + titanic.at['Lam, Mr. Ali',"Age"] = 42 # set single value by row and column *name* (fast) + titanic.at['Lam, Mr. Ali',"Age"] # select single value by row and column *name* (fast) + titanic.iat[0,5] # select same value by row and column *number* (fast) + + titanic["is_passenger"] = True # set a whole column + +Dataframes also support boolean indexing, just like we saw for ``numpy`` +arrays:: + + titanic[titanic["Age"] > 70] + # ".str" creates a string object from a column + titanic[titanic.index.str.contains("Margaret")] + +What if your dataset has missing data? Pandas uses the value :py:data:`numpy.nan` +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:: + + titanic.isna() # returns boolean mask of NaN values + titanic.dropna() # drop missing values + titanic.dropna(how="any") # or how="all" + titanic.dropna(subset=["Cabin"]) # only drop NaNs from one column + titanic.fillna(0) # replace NaNs with zero + titanic.fillna(method='ffill') # forward-fill NaNs + + + +Exercises 1 +----------- + +.. challenge:: Exploring dataframes + + - Have a look at the available methods and attributes using the + `API reference `__ + or the autocomplete feature in Jupyter. + - Try out a few methods using the Titanic dataset and have a look at + the docstrings (help pages) of methods that pique your interest + - Compute the mean age of the first 10 passengers by slicing and the :py:meth:`pandas.DataFrame.mean` method + - (Advanced) Using boolean indexing, compute the survival rate + (mean of "Survived" values) among passengers over and under the average age. + + .. solution:: + + - Mean age of the first 10 passengers:: + + titanic.iloc[:10,:]["Age"].mean() + + or:: + + titanic.loc[:"Nasser, Mrs. Nicholas (Adele Achem)","Age"].mean() + + or:: + + titanic.iloc[:10,4].mean() + + - Survival rate among passengers over and under average age:: + + titanic[titanic["Age"] > titanic["Age"].mean()]["Survived"].mean() + + and:: + + titanic[titanic["Age"] < titanic["Age"].mean()]["Survived"].mean() + + +Tidy data +--------- + +The above analysis was rather straightforward thanks to the fact +that the dataset is *tidy*. + +.. image:: img/pandas/tidy_data.png + +In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data. + +What would untidy data look like? Here's an example from +some run time statistics from a 1500 m running event:: + + runners = pd.DataFrame([ + {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240}, + {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300}, + {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360}, + ]) + +What makes this data untidy is that the column names `400, 800, 1200, 1500` +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row. + +To make untidy data tidy, a common operation is to "melt" it, +which is to convert it from wide form to a long form:: + + runners = pd.melt(runners, id_vars="Runner", + value_vars=[400, 800, 1200, 1500], + var_name="distance", + value_name="time" + ) + +In this form it's easier to **filter**, **group**, **join** +and **aggregate** the data, and it's also easier to model relationships +between variables. + +The opposite of melting is to *pivot* data, which can be useful to +view data in different ways as we'll see below. + +For a detailed exposition of data tidying, have a look at +`this article `__. + + + +Working with dataframes +----------------------- + +We saw above how we can read in data into a dataframe using the :func:`~pandas.read_csv` function. +Pandas also understands multiple other formats, for example using :obj:`~pandas.read_excel`, +:obj:`~pandas.read_hdf`, :obj:`~pandas.read_json`, etc. (and corresponding methods to write to file: +:obj:`~pandas.DataFrame.to_csv`, :obj:`~pandas.DataFrame.to_excel`, :obj:`~pandas.DataFrame.to_hdf`, :obj:`~pandas.DataFrame.to_json`, etc.) + +But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +:class:`~pandas.DataFrame` docs:: + + dates = pd.date_range('20130101', periods=6) + df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD')) + +or a dictionary (see same docs):: + + df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'], + 'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'], + 'C': np.array([3] * 8, dtype='int32'), + 'D': np.random.randn(8), + 'E': np.random.randn(8)}) + +There are many ways to operate on dataframes. Let's look at a +few examples in order to get a feeling of what's possible +and what the use cases can be. + +We can easily split and :func:`concatenate ` dataframes:: + + sub1, sub2, sub3 = df[:2], df[2:4], df[4:] + pd.concat([sub1, sub2, sub3]) + +When pulling data from multiple dataframes, a powerful :obj:`pandas.DataFrame.merge` method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:: + + age = pd.DataFrame([ + {"Runner": "Runner 4", "Age": 18}, + {"Runner": "Runner 2", "Age": 21}, + {"Runner": "Runner 1", "Age": 23}, + {"Runner": "Runner 3", "Age": 19}, + ]) + +We now want to use this table to annotate the original ``runners`` table from +before with their age. Note that the ``runners`` and ``age`` dataframes have a +different ordering to it, and ``age`` has an entry for ``Dave`` which is not +present in the ``runners`` table. We can let Pandas deal with all of it using +the :obj:`~pandas.DataFrame.merge` method:: + + # Add the age for each runner + runners.merge(age, on="Runner") + +In fact, much of what can be done in SQL +`is also possible with pandas `__. + +:obj:`~pandas.DataFrame.groupby` is a powerful method which splits a dataframe and aggregates data +in groups. To see what's possible, let's return to the Titanic dataset. Let's +test the old saying "Women and children first". We start by creating a new +column ``Child`` to indicate whether a passenger was a child or not, based on +the existing ``Age`` column. For this example, let's assume that you are a +child when you are younger than 12 years:: + + titanic["Child"] = titanic["Age"] < 12 + +Now we can test the saying by grouping the data on ``Sex`` and then creating further sub-groups based on ``Child``:: + + titanic.groupby(["Sex", "Child"])["Survived"].mean() + +Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +:obj:`~pandas.DataFrame.std`, :obj:`~pandas.DataFrame.min`, +:obj:`~pandas.DataFrame.max`, :obj:`~pandas.DataFrame.cumsum`, +:obj:`~pandas.DataFrame.median`, :obj:`~pandas.DataFrame.skew`, +:obj:`~pandas.DataFrame.var` etc. + + + +Exercises 2 +----------- + +.. challenge:: Analyze the Titanic passenger list dataset + + In the Titanic passenger list dataset, + investigate the family size of the passengers (i.e. the "SibSp" column). + + - What different family sizes exist in the passenger list? Hint: try the :meth:`~pandas.Series.unique` method + - What are the names of the people in the largest family group? + - (Advanced) Create histograms showing the distribution of family sizes for + passengers split by the fare, i.e. one group of high-fare passengers (where + the fare is above average) and one for low-fare passengers + (Hint: instead of an existing column name, you can give a lambda function + as a parameter to :meth:`~pandas.DataFrame.hist` to compute a value on the fly. For example + ``lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich"``). + + .. solution:: + + - Existing family sizes:: + + titanic["SibSp"].unique() + + - We get 8 from above. There is no ``Name`` column, since we + made ``Name`` the index when we loaded the dataframe with + ``read_csv``, so we use :attr:`pandas.DataFrame.index` to get + the names. So, names of members of largest family(ies):: + + titanic[titanic["SibSp"] == 8].index + + - Histogram of family size based on fare class:: + + titanic.hist("SibSp", + lambda x: "Poor" if titanic["Fare"].loc[x] < titanic["Fare"].mean() else "Rich", + rwidth=0.9) + + + + +Time series superpowers +----------------------- + +An introduction of pandas wouldn't be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv . + +Unfortunately this API does not allow "non-browser requests", so +:obj:`pandas.read_csv` will not work. We can either open the above link in +a browser and download the file, or use the JupyterLab interface by clicking +"File" and "Open from URL", and then save the CSV file to disk. + +We can then load and explore the data:: + + # File → Open from URL → enter https://api.nobelprize.org/v1/laureate.csv + # This opens it in JupyterLab but also saves it as laureate.csv + nobel = pd.read_csv("laureate.csv") + nobel.head() + +This dataset has three columns for time, "born"/"died" and "year". +These are represented as strings and integers, respectively, and +need to be converted to datetime format. :func:`pandas.to_datetime` +makes this easy:: + + # the errors='coerce' argument is needed because the dataset is a bit messy + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + +Pandas knows a lot about dates (using :attr:`~pandas.Series.dt`):: + + print(nobel["born"].dt.day) + print(nobel["born"].dt.year) + print(nobel["born"].dt.weekday) + +We can add a column containing the (approximate) lifespan in years rounded +to one decimal:: + + nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1) + +and then plot a :meth:`histogram ` of lifespans:: + + nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9) + +Finally, let's see one more example of an informative plot (:meth:`~pandas.DataFrame.boxplot`) +produced by a single line of code:: + + nobel.boxplot(column="lifespan", by="category") + + + +Exercises 3 +----------- + +.. challenge:: Analyze the Nobel prize dataset + + - What country has received the largest number of Nobel prizes, and how many? + How many countries are represented in the dataset? Hint: use the :obj:`~pandas.Series.describe` method + on the ``bornCountryCode`` column. + - Create a histogram of the age when the laureates received their Nobel prizes. + Hint: follow the above steps we performed for the lifespan. + - List all the Nobel laureates from your country. + + Now more advanced steps: + + - Now define an array of 4 countries of your choice and extract + only laureates from these countries:: + + countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4]) + subset = nobel.loc[nobel['bornCountry'].isin(countries)] + + - Use :meth:`~pandas.DataFrame.groupby` to compute how many nobel prizes each country received in + each category. The :meth:`~pandas.core.groupby.GroupBy.size` method tells us how many rows, hence nobel + prizes, are in each group:: + + nobel.groupby(['bornCountry', 'category']).size() + + - (Optional) Create a pivot table to view a spreadsheet like structure, and view it + + - First add a column “number” to the nobel dataframe containing 1’s + (to enable the counting below). We need to make a copy of + ``subset``, because right now it is only a view:: + + subset = subset.copy() + subset.loc[:, 'number'] = 1 + + - Then create the :meth:`~pandas.DataFrame.pivot_table`:: + + table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum) + + - (Optional) Install the **seaborn** visualization library if you don't + already have it, and create a heatmap of your table:: + + import seaborn as sns + sns.heatmap(table,linewidths=.5); + + - Play around with other nice looking plots:: + + sns.violinplot(y="year", x="bornCountry", inner="stick", data=subset); + + :: + + sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5); + + :: + + subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))] + sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm"); + + :: + + sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count"); + + + .. solution:: + + We use the :meth:`describe` method: + + :: + + nobel.bornCountryCode.describe() + # count 956 + # unique 81 + # top US + # freq 287 + + We see that the US has received the largest number of Nobel prizes, + and 81 countries are represented. + + To calculate the age at which laureates receive their prize, we need + to ensure that the "year" and "born" columns are in datetime format:: + + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + + Then we add a column with the age at which Nobel prize was received + and plot a histogram:: + + nobel["age_nobel"] = round((nobel["year"] - nobel["born"]).dt.days / 365, 1) + nobel.hist(column="age_nobel", bins=25, figsize=(8,10), rwidth=0.9) + + We can print names of all laureates from a given country, e.g.:: + + nobel[nobel["country"] == "Sweden"].loc[:, "firstname":"surname"] + +Beyond the basics +----------------- + +Larger DataFrame operations might be faster using :func:`~pandas.eval` with string expressions, `see +`__:: + + import pandas as pd + nrows, ncols = 100000, 100 + rng = np.random.RandomState(42) + df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols)) + for i in range(4)) + +Adding dataframes the pythonic way yields:: + + %timeit df1 + df2 + df3 + df4 + # 80ms + +And by using :func:`~pandas.eval`:: + + %timeit pd.eval('df1 + df2 + df3 + df4') + # 40ms + + +We can assign function return lists as dataframe columns:: + + def fibo(n): + """Compute Fibonacci numbers. Here we skip the overhead from the + recursive function calls by using a list. """ + if n < 0: + raise NotImplementedError('Not defined for negative values') + elif n < 2: + return n + memo = [0]*(n+1) + memo[0] = 0 + memo[1] = 1 + for i in range(2, n+1): + memo[i] = memo[i-1] + memo[i-2] + return memo + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = fibo(99) + + +There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its `API +`__. And when there is not, you can always +apply your own functions to the data using :obj:`~pandas.DataFrame.apply`:: + + + from functools import lru_cache + + @lru_cache + def fib(x): + """Compute Fibonacci numbers. The @lru_cache remembers values we + computed before, which speeds up this function a lot.""" + if x < 0: + raise NotImplementedError('Not defined for negative values') + elif x < 2: + return x + else: + return fib(x - 2) + fib(x - 1) + + df = pd.DataFrame({'Generation': np.arange(100)}) + df['Number of Rabbits'] = df['Generation'].apply(fib) + + +Note that the numpy precisision for integers caps at int64 while python ints are unbounded -- +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df['Number of Rabbits'][99] given by both functions above +is in fact . + + +.. keypoints:: + + - pandas dataframes are a good data structure for tabular data + - Dataframes allow both simple and advanced analysis in very compact form diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/parallel-pi-multiprocessing.ipynb.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/parallel-pi-multiprocessing.ipynb.txt new file mode 100644 index 00000000..970dbada --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/parallel-pi-multiprocessing.ipynb.txt @@ -0,0 +1,303 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Python multithreading solution\n", + "Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import random" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "def sample(n):\n", + " \"\"\"Make n trials of points in the square. Return (n, number_in_circle)\n", + " \n", + " This is our basic function. By design, it returns everything it\\\n", + " needs to compute the final answer: both n (even though it is an input\n", + " argument) and n_inside_circle. To compute our final answer, all we\n", + " have to do is sum up the n:s and the n_inside_circle:s and do our\n", + " computation\"\"\"\n", + " n_inside_circle = 0\n", + " for i in range(n):\n", + " x = random.random()\n", + " y = random.random()\n", + " if x**2 + y**2 < 1.0:\n", + " n_inside_circle += 1\n", + " return n, n_inside_circle" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it just for timing\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Do the actual calculation (the previous result doesn't get saved)\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is the \"calculate answer\" phase." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.144548" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "pi = 4.0 * (n_inside_circle / n)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in parallel with multiprocessing\n", + "This divides the calculation into 10 tasks and runs `sample` on each of them. Then it re-combines the results." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import multiprocessing.pool\n", + "pool = multiprocessing.pool.Pool()\n", + "# The default pool makes one process per CPU" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it once to time it\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "pool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.140768" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in \"parallel\" with threads\n", + "To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool = multiprocessing.pool.ThreadPool()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%timeit -o\n", + "# Do it once to time it\n", + "threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.142388" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Future ideas\n", + "\n", + "You could make a separate `calculate` function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.\n", + "\n", + "Notice the similarity to [split-apply-combine](https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html) or [map-reduce](https://en.wikipedia.org/wiki/MapReduce) which is a specialization of split-apply-combine." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/parallel.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/parallel.rst.txt new file mode 100644 index 00000000..dc00fb22 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/parallel.rst.txt @@ -0,0 +1,517 @@ +Parallel programming +==================== + +.. questions:: + + - When you need more than one processor, what do you do? + - How can we use more than one processor/core in Python? + +.. objectives:: + + - Understand the major strategies of parallelizing code + - Understand mechanics of the ``multiprocessing`` package + - Know when to use more advanced packages or approaches + + + +Modes of parallelism +-------------------- + +You realize you do have more computation to do than you can on one processor? +What do you do? + +1. Profile your code, identify the *actual* slow spots. + +2. Can you improve your code in those areas? Use an existing library? + +3. Are there are any low-effort optimizations that you can make? + +4. Consider using `numba `__ or + `cython `__ to accelerate key functions. + +5. Think about parallelizing. + + +Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers). + +**Parallel computing** is when many different tasks are carried out +simultaneously. There are three main models: + +* **Embarrassingly parallel:** the code does not need to + synchronize/communicate with other instances, and you can run + multiple instances of the code separately, and combine the results + later. If you can do this, great! (array jobs, task queues, + workflow management tools) + +* **Multithreading:** Parallel threads need to communicate and do so via + the same memory (variables, state, etc). (OpenMP, ``threading``) + +* **Multiprocessing, message passing:** Different processes manage + their own memory segments. They share data by communicating (passing + messages) as needed. (``multiprocessing``, MPI). + +.. warning:: + + Parallel programming is not magic, but many things can go wrong and + you can get unexpected results or difficult to debug problems. + Parallel programming is a fascinating world to get involved in, but + make sure you invest enough time to do it well. + + See the video by Raymond Hettinger ("See Also" at bottom + of page) for an entertaining take on this. + + + +Multithreading and the GIL +-------------------------- + +The designers of the Python language made the choice +that **only one thread in a process can run actual Python code** +by using the so-called **global interpreter lock (GIL)**. +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. *But it's not all bad!:* + +* External libraries (NumPy, SciPy, Pandas, etc), written in C or other + languages, can release the lock and run multi-threaded. + +* Most input/output releases the GIL, and input/output is slow. The + ``threading`` library can be used to multithread I/O. + +* Python libraries like ``multiprocessing`` and ``mpi4py`` run *multiple + Python processes* and this circumvents the GIL. + + +Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix: + +.. code-block:: python + + import numpy as np + import time + + A = np.random.random((4000,4000)) + A = A * A.T + time_start = time.time() + np.linalg.inv(A) + time_end = time.time() + print("time spent for inverting A is", round(time_end - time_start,2), 's') + +If we run this in a Jupyter notebook or through a Python script, **it +will automatically use multithreading** through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either ``export OMP_NUM_THREADS=1`` or ``export MKL_NUM_THREADS=1``, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime. + + +.. seealso:: + + * `More on the global interpreter lock + `__ + * `Threading python module + `__. This is + very low level and you shouldn't use it unless you really know what + you are doing. + * We recommend you find a UNIX threading tutorial first before embarking + on using the :py:mod:`threading` module. + + + +multiprocessing +--------------- + +As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +:py:mod:`multiprocessing` module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock. + +To show an example, +the `split-apply-combine `__ +or `map-reduce `__ paradigm is +quite useful for many scientific workflows. Consider you have this:: + + def square(x): + return x*x + +You can apply the function to every element in a list using the +:py:func:`map` function: + +.. code-block:: pycon + + >>> list(map(square, [1, 2, 3, 4, 5, 6])) + [1, 4, 9, 16, 25, 36] + +The :py:class:`multiprocessing.pool.Pool` class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list: + +.. code-block:: pycon + + >>> from multiprocessing import Pool + >>> with Pool() as pool: + ... pool.map(square, [1, 2, 3, 4, 5, 6]) + [1, 4, 9, 16, 25, 36] + +.. warning:: + + Running the above example **interactively** in a Jupyter notebook + or through an Python/IPython terminal may or may not work on your + computer! This is a feature and not a bug, as covered in the + `documentation `__. + + Fortunately, there is a fork of multiprocesssing called + `multiprocess `__ which does + work in interactive environments. All we have to do is install it + by ``pip install multiprocess`` and change the import statement: + ``from multiprocess import Pool``. + + +Exercises, multiprocessing +-------------------------- + +.. challenge:: Parallel-1, multiprocessing + + Here, you find some code which calculates pi by a stochastic + algorithm. You don't really need to worry how the algorithm works, + but it computes random points in a 1x1 square, and computes the + number that fall into a circle. Copy it into a Jupyter notebook + and use the ``%%timeit`` cell magic on the computation part (the + one highlighted line after timeit below): + + .. code-block:: python + :emphasize-lines: 20 + + import random + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x**2 + y**2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + %%timeit + n, n_inside_circle = sample(10**6) + + pi = 4.0 * (n_inside_circle / n) + pi + + Using the :py:class:`multiprocessing.pool.Pool` code from the lesson, run + the ``sample`` function 10 times, each with ``10**5`` samples + only. Combine the results and time the calculation. What is the + difference in time taken? + + NOTE: If you're working in an interactive environment and this + doesn't work with the ``multiprocessing`` module, install and use + the ``multiprocess`` module instead! + + (optional, advanced) Do the same but with + :py:class:`multiprocessing.pool.ThreadPool` instead. This works identically + to ``Pool``, but uses threads instead of different processes. + Compare the time taken. + + .. solution:: + + See the finished notebook here: + + .. toctree:: + + parallel-pi-multiprocessing + + You notice the version with ``ThreadPool`` is no faster, and + probably takes even longer. This is because this is a + pure-Python function which can not run simultaneously in + multiple threads. + +.. challenge:: (advanced) Parallel-2 Running on a cluster + + How does the pool know how many CPUs to take? What happens if you + run on a computer cluster and request only part of the CPUs on a + node? + + .. solution:: + + Pool by default uses one process for each CPU on the node - it + doesn't know about your cluster's scheduling system. It's + possible that you have permission to use 2 CPUs but it is trying + to use 12. This is generally a bad situation, and will just + slow you down (and make other users on the same node upset)! + + You either need to be able to specify the number of CPUs to use + (and pass it the right number), or make it aware of the cluster + system. For example, on a Slurm cluster you would check the + environment variable ``SLURM_CPUS_PER_TASK``. + + Whatever you do, document what your code is doing under the + hood, so that other users know what is going on (we've learned + this from experience...). + + +MPI +--- + +The message passing interface (MPI) approach to parallelization +is that: + +- Tasks (cores) have a rank and are numbered 0, 1, 2, 3, ... +- Each task (core) manages its own memory +- Tasks communicate and share data by sending messages +- Many higher-level functions exist to distribute information to other tasks + and gather information from other tasks +- All tasks typically run the entire code and we have to be careful to avoid + that all tasks do the same thing + +Introductory MPI lessons where Python is included: + +- https://rantahar.github.io/introduction-to-mpi/ +- https://pdc-support.github.io/introduction-to-mpi/ + +These blog posts are good for gentle MPI/mpi4py introduction: + +- https://www.kth.se/blogs/pdc/2019/08/parallel-programming-in-python-mpi4py-part-1/ +- https://www.kth.se/blogs/pdc/2019/11/parallel-programming-in-python-mpi4py-part-2/ + +Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together. + +Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work: + +.. code-block:: python + :emphasize-lines: 3,23-25,29,39,42 + + import random + import time + from mpi4py import MPI + + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x ** 2 + y ** 2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + + comm = MPI.COMM_WORLD + size = comm.Get_size() + rank = comm.Get_rank() + + n = 10 ** 7 + + if size > 1: + n_task = int(n / size) + else: + n_task = n + + t0 = time.perf_counter() + _, n_inside_circle = sample(n_task) + t = time.perf_counter() - t0 + + print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}") + n_inside_circle = comm.gather(n_inside_circle, root=0) + print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}") + + if rank == 0: + pi_estimate = 4.0 * sum(n_inside_circle) / n + print( + f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds" + ) + + + +Exercises, MPI +-------------- + +.. challenge:: Parallel-2, MPI + + We can do this as **exercise or as demo**. Note that this example requires ``mpi4py`` and a + MPI installation such as for instance `OpenMPI `__. + + - Try to run this example on one core: ``$ python example.py``. + - Then compare the output with a run on multiple cores (in this case 2): ``$ mpiexec -n 2 python example.py``. + - Can you guess what the ``comm.gather`` function does by looking at the print-outs right before and after. + - Why do we have the if-statement ``if rank == 0`` at the end? + - Why did we use ``_, n_inside_circle = sample(n_task)`` and not ``n, n_inside_circle = sample(n_task)``? + + + .. solution:: + + We first run the example normally, and get: + + .. code-block:: console + + $ python example.py + before gather: rank 0, n_inside_circle: 7854305 + after gather: rank 0, n_inside_circle: [7854305] + + number of darts: 10000000, estimate: 3.141722, time spent: 2.5 seconds + + Next we take advantage of the MPI parallelisation and run on 2 cores: + + .. code-block:: console + + $ mpirun -n 2 python mpi_test.py + before gather: rank 0, n_inside_circle: 3926634 + before gather: rank 1, n_inside_circle: 3925910 + after gather: rank 1, n_inside_circle: None + after gather: rank 0, n_inside_circle: [3926634, 3925910] + + number of darts: 10000000, estimate: 3.1410176, time spent: 1.3 seconds + + Note that two MPI processes are now printing output. Also, the parallel + version runs twice as fast! + + The ``comm.gather`` function collects (gathers) values of a + given variable from all MPI ranks onto one `root` rank, which is + conventionally rank 0. + + A conditional ``if rank == 0`` is typically used to print output + (or write data to file, etc) from only one rank. + + An underscore ``_`` is often used as a variable name in cases + where the data is unimportant and will not be reused. + +Coupling to other languages +--------------------------- + +As mentioned further up in "Multithreading and the GIL", Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP "directly". + +However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don't +need parallelism, but need to make an optimized algorithm for a small part of the code. + +Two strategies are common: + +- Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization: + + - C: use the `cffi `__ package (C foreign function interface). :py:mod:`ctypes` is a similar but slightly more primitive module that is in the standard library. + - C++: use `pybind11 `__ + - Fortran: create a C interface using ``iso_c_binding`` and then couple the C layer to Python + using `cffi `__ + - Rust: use `PyO3 `__ + +- Let compiled languages do the shared-memory parallelization part (as in above + point) and let Python do the MPI work and distribute tasks across nodes using + an ``mpi4py`` layer. + +Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course. + +Before you take this route, **profile the application** first to be sure where +the bottleneck is. + +Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason. + + + +Dask and task queues +-------------------- + +There are other strategies that go completely beyond the manual +parallelization methods above. We won't go into much detail. + +Dask +~~~~ + +`Dask `__ is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs. + +Dask is very popular for data analysis and is used by a number of high-level Python libraries: + +- Dask arrays scale NumPy (see also `xarray `__ +- Dask dataframes scale Pandas workflows +- Dask-ML scales Scikit-Learn + +Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block. + +.. discussion:: Example from dask.org + + .. code-block:: + + # Arrays implement the Numpy API + import dask.array as da + x = da.random.random(size=(10000, 10000), + chunks=(1000, 1000)) + x + x.T - x.mean(axis=0) + # It runs using multiple threads on your machine. + # It could also be distributed to multiple machines + + + +Exercises, Dask +--------------- + +.. challenge:: Dask-Examples (optional) + + `Dask examples `__ illustrate the usage of dask and can be run interactively through `mybinder `__. Start an `interactive session on mybinder `__ and test/run a few dask examples. + +.. warning: dask on HPC + + On HPC, it is important to use `dask-mpi `__ that deploys dask using MPI4Py. The setup can be a bit tricky and we recommend the usage of `dask-jobqueue and dask-drmaa `__: these packages need to be installed on the target platform (not through conda) to fully benefit from the native underlying MPI libraries. + +Task queues +~~~~~~~~~~~ + +A **task queue** has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for *embarrassingly parallel* jobs. + +There are different descriptions of `task queues in Python +`__. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant. + + + +See also +-------- + +* `Thinking about Concurrency, Raymond Hettinger + `__. Good introduction to simple and + safe concurrent code. +* `Introduction to Numba and Cython `__. +* `More detailed exposition of parallel computing in Python `__. +* `Introduction to Dask for scalable analytics `__. + +.. keypoints:: + + - Pure Python is not very good for highly parallel code. + - Luckily it interfaces to many things which *are* good, and give + you the full control you need. + - Combining vectorized functions (NumPy, Scipy, pandas, etc.) with + the parallel strategies listed here will get you very far. + - Another popular framework similar to `multiprocessing` is + `joblib `__. diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/python.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/python.rst.txt new file mode 100644 index 00000000..20a0cf9a --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/python.rst.txt @@ -0,0 +1,186 @@ +Introduction to Python +====================== + +.. questions:: + + - What are the basic blocks of Python language? + - How are functions and classes defined in Python? + +.. objectives:: + + - Get a *very* short introduction to Python types and syntax + - Be able to follow the rest of the examples in the course, even if you don't understand everything perfectly. + + We expect everyone to be able to know the following basic material + to follow the course (though it is not *everything* you need to + know about Python). + +If you are not familiar with Python, here is a *very* short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise. + +.. seealso:: + + This page contains an overview of the basics of Python. You can + also refer to `This Python overview from a different lesson + `__ + which is slightly more engaging. + + + +Scalars +------- + +Scalar types, that is, single elements of various types: + +:: + + i = 42 # integer + i = 2**77 # Integers have arbitrary precision + g = 3.14 # floating point number + c = 2 - 3j # Complex number + b = True # boolean + s = "Hello!" # String (Unicode) + q = b'Hello' # bytes (8-bit values) + +Read more: :class:`int`, :class:`float`, :class:`complex`, +:class:`bool`, :class:`str`, :class:`bytes`. + + +Collections +----------- + +Collections are data structures capable of storing multiple values. + +:: + + l = [1, 2, 3] # list + l[1] # lists are indexed by int + l[1] = True # list elements can be any type + d = {"Janne": 123, "Richard": 456} # dictionary + d["Janne"] + s = set(("apple", "cherry", "banana", "apple")) # Set of unique values + s + +Read more: :class:`list`, :class:`tuple`, :class:`dict`, :class:`set`. + + +Control structures +------------------ + +Python has the usual control structures, that is conditional +statements and loops. For example, the :ref:`if` statement: + +:: + + x = 2 + if x == 3: + print('x is 3') + elif x == 2: + print('x is 2') + else: + print('x is something else') + +:ref:`While ` loops loop until some condition is met: + +:: + + x = 0 + while x < 42: + print('x is ', x) + x += 0.2 + +:ref:`For ` loops loop over some collection of values: + +:: + + xs = [1, 2, 3, 4] + for x in xs: + print(x) + + +Often you want to loop over a sequence of integers, in that case the +:func:`range` function is useful: + +:: + + for x in range(9): + print(x) + +Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the :func:`enumerate` +function: + +:: + + xs = [1, 'hello', 'world'] + for ii, x in enumerate(xs): + print(ii, x) + + +Functions and classes +--------------------- + +Python functions are defined by the :ref:`def` keyword. They take a +number of arguments, and return a number of return values. + +:: + + def hello(name): + """Say hello to the person given by the argument""" + print('Hello', name) + return 'Hello ' + name + + hello("Anne") + +Classes are defined by the :ref:`class` keyword: + +:: + + class Hello: + def __init__(self, name): + self._name = name + def say(self): + print('Hello', self._name) + + h = Hello("Richard") + h.say() + + +Python type system +------------------ + +Python is strongly and dynamically typed. + +Strong here means, roughly, that it's not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior). + +:: + + x = 42 + type(x) + x + "hello" + +Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type: + +:: + + x = 42 + x = "hello" + + +*Jargon*: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation. + + +??? (lesson here) + + + +.. keypoints:: + + - Python offers a nice set of basic types as many other programming languages + - Python is strongly typed and dynamically typed diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/quick-reference.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/quick-reference.rst.txt new file mode 100644 index 00000000..077859af --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/quick-reference.rst.txt @@ -0,0 +1,26 @@ +Quick reference +=============== + +* `Pandas cheatsheet + `__ (pandas.pydata.org) + +* `Pandas cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy cheatsheet + `__ + (via `Datacamp + `__) + +* `JupyterLab cheatsheet + `__ + +* `Matplotlib cheatsheet + `__ + (via `Datacamp + `__) + +* `Numpy, Pandas, Matplotlib, Scikit-learn all together + `__ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/scipy.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/scipy.rst.txt new file mode 100644 index 00000000..df4ee8a4 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/scipy.rst.txt @@ -0,0 +1,183 @@ +SciPy +===== + +.. questions:: + + - When you need more advanced mathematical functions, where do you + look? + +.. objectives:: + + - Understand that SciPy exists and what kinds of things it has. + - Understand the importance of using external libraries and how to + use them. + - Understand the purpose of wrapping existing C/Fortran code. + - Non-objective: know details of everything (or anything) in SciPy. + +.. seealso:: + + * Main article: `SciPy documentation `__ + + + +SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms. + + + +What's in SciPy? +---------------- + +Briefly, it contains functionality for + +- Special functions (Bessel, Gamma, etc.) +- Numerical integration +- Optimization +- Interpolation +- Fast Fourier Transform (FFT) +- Signal processing +- Linear algebra (more complete than in NumPy) +- Sparse matrices +- Statistics +- More I/O routine, e.g. Matrix Market format for sparse matrices, + MATLAB files (.mat), etc. + +Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages. + +Most functions are documented ridiculously well from a scientific +standpoint: you aren't just using some unknown function, but have a +full scientific description and citation to the method and +implementation. + + + +Exercises: use SciPy +-------------------- + +These exercises do not exist because *you* might need *these* +functions someday. They are because *you* will need to *read +documentation and understand documentation of an an external library* +eventually. + +1: Numerical integration +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Define a function of one variable and using + `scipy.integrate.quad `__ + calculate the integral of your function in the + interval ``[0.0, 4.0]``. Then vary the interval and also modify the function and check + whether scipy can integrate it. + + +.. solution:: + + .. code-block:: python + + from scipy import integrate + + def myfunction(x): + # you need to define result + return result + + integral = integrate.quad(myfunction, 0.0, 4.0) + print(integral) + + `quad + `__ + uses the Fortran library QUADPACK, which one can assume is pretty + good. You can also see a whole lot of scientific information about + the function on the docs page - including the scientific names of + the methods used. + + + +2: Sparse matrices +~~~~~~~~~~~~~~~~~~ + +.. challenge:: + + Do the following exercise **or** read the documentation and + understand the relevant functions of SciPy: + + Use the SciPy sparse matrix functionality to create a random sparse + matrix with a probability of non-zero elements of 0.05 and size 10000 + x 10000. The use the SciPy sparse linear algebra support to calculate + the matrix-vector product of the sparse matrix you just created and a + random vector. Use the %timeit macro to measure how long it + takes. Does the optional ``format`` argument when you create the + sparse matrix make a difference? + + Then, compare to how long it takes if you'd instead first convert the + sparse matrix to a normal NumPy dense array, and use the NumPy ``dot`` + method to calculate the matrix-vector product. + + Can you figure out a quick rule of thumb when it's worth using a + sparse matrix representation vs. a dense representation? + +.. solution:: + + The basic code to do the test is: + + .. code-block:: + + import numpy + import scipy.sparse + + vector = numpy.random.random(10000) + matrix = scipy.sparse.rand(10000, 10000, density=.05, format='csc') + + # We time this line + matrix.dot(vector) + + From the top of the `spare matrix module documentation + `__, we can + see there are a variety of different available sparse matrix types: + ``bsr``, ``coo``, ``csr``, ``csc``, etc. These each represent a + different way of storing the matrices. + + It seems that ``csr`` and ``csc`` are fairly fast. ``lil`` and + ``dok`` are slow but it says that these are good for creating + matrices with random insertions. + + For example, ``csr`` takes 7ms, ``lil`` 42ms, ``dok`` 1600ms, and + converting to a non-sparse array ``matrix.toarray()`` and + multiplying takes 64ms on one particular computer. + + This code allows us to time the performance at different + densities. It seems that with the ``csr`` format, sparse is better + below densities of around .4 to .5: + + ..code-block:: + + for density in [.01, .05, .1, .2, .3, .4, .5]: + matrix = scipy.sparse.rand(10000, 10000, density=density, format='csr') + time_sparse = timeit.timeit('matrix.dot(vector)', number=10, globals=globals()) + matrix2 = matrix.toarray() + time_full = timeit.timeit('matrix2.dot(vector)', number=10, globals=globals()) + print(f"{density} {time_sparse:.3f} {time_full:.3f}") + + + +See also +-------- + +* `SciPy general introduction `__ +* `SciPy documentation + `__ + + + +.. keypoints:: + + - When you need advance math or scientific functions, let's just + admit it: you do a web search first. + - But when you see something in SciPy come up, you know your + solutions are in good hands. diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/scripts.rst.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/scripts.rst.txt new file mode 100644 index 00000000..010d8be0 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/scripts.rst.txt @@ -0,0 +1,304 @@ +.. _scripts: + +Scripts +======= + +.. questions:: + + - Why are command line programs useful, compared to Jupyter + notebooks and similar? + - How to create a Python script? + - How to generalize a Python script? + +.. objectives:: + + - Learn how to streamline your Python notebooks by creating repeatable Python scripts + - Learn how to import other Python files + - Learn to parse command line arguments in Python + +Why scripts? +------------- + +So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work. + +But after several weeks of hard work with Python, you may end up: + +- either with 10 different notebooks (so that you can run them concurrently) +- or with a very long notebook which is becoming hardly readable! + +Let's imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks? + +In this episode, we will learn how to automate your work using Python scripts so that + +* you do not need to manually configure your notebooks to be able to run with different parameters +* can easily run you work via other tools, such as on computing clusters. + + +From Jupyter notebooks to Python scripts +----------------------------------------- + +Save as Python script +--------------------- + +Jupyter notebooks can be parameterized for instance using `papermill `_. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See `CodeRefinery's lesson on Modular code development `__. + +Within JupyterLab, you can export any Jupyter notebook to a Python script: + +.. figure:: https://jupyterlab.readthedocs.io/en/stable/_images/exporting_menu.png + + Select File (top menu bar) → Export Notebook as → **Export notebook to Executable Script**. + + +.. highlight:: console + +Actually, you could also export your notebook in many other formats. +Check the `JupyterLab documentation `_ for more information. +If you are working by the command line (File → New → Terminal), you can also convert files in the terminal by running:: + + $ jupyter nbconvert --to script your_notebook_name.ipynb + + +Exercises 1 +----------- + +.. challenge:: Scripts-1 + + .. highlight:: console + + + 1. Download the :download:`weather_observations.ipynb <../resources/code/scripts/weather_observations.ipynb>` and the weather_data file and upload them to your jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from `rp5.kz `_ and was slightly adjusted for this lecture. + + **Note:** If you haven't downloaded the file directly to your jupyterlab folder, it will be located in your **Downloads** folder or the folder you selected. In jupyterlab click on the 'upload file' button, navigate to the folder containing the file and select it to load it into your jupyterlab folder. + + 2. Open a terminal in jupyter (File -> New -> Terminal). + + 3. Convert the jupyter script to a python script by calling:: + + $ jupyter nbconvert --to script weather_observations.ipynb + + 4. Run the script (note: you may have ``python3`` rather than ``python``):: + + $ python weather_observations.py + +Command line arguments with ``sys.argv`` +---------------------------------------- + +We now have a python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +What we need is to allow arguments to be put in from the command line in order to have the same code +plot information for different time ranges without odifying the code itself. This can be achieved by +using pythons :py:mod:`sys` package, which provides access to arguments given to the python interpreter at +startup in the :py:data:`sys.argv` list. The first (i.e. ``sys.argv[0]`` entry of this array is the called script, +and any further argument (separated by space) is appended to this list. Lets see how it works: + +We modify the **weather_observations.py** script such that we allow start +and end times as well as the output file to be passed in as arguments to the function: + +.. code-block:: python + :emphasize-lines: 1,5-6,8,16 + + import sys + import pandas as pd + + # set start and end time + start_date = pd.to_datetime(sys.argv[1],dayfirst=True) + end_date = pd.to_datetime(sys.argv[2],dayfirst=True) + + output_file_name = sys.argv[3] + + ... + + # select the data + weather = weather[weather['Local time'].between(start_date,end_date)] + ... + + fig.savefig(output_file_name) + +We can try it out: + +.. code-block:: console + + $ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png + + +.. discussion:: + + - Does it work? + + - Why is this better than modifying the script every time I want it to + plot data for a different period? + + - What problems do you expect when using this approach (using :data:`sys.argv`)? + +This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time: + +- `argparse `__: + built-in to Python, this is the one that we will show below. +- `doctopt `__: you write the help text and this generates a parser for you. +- `click `__: another nice + library for command line interfaces - very easy to use. + + +Parsing command line arguments with :mod:`argparse` +--------------------------------------------------- + +:py:mod:`Argparse ` not only gives you descriptive command line arguments, it also automatically +generates a ``--help`` option for you. To use ``argparse`` you first set up a parser +by calling :class:`parser = argparse.ArgumentParser() ` and then you add arguments using +:py:meth:`parser.add_argument(args) `. There are two different types of arguments: + +- Positional arguments +- Optional arguments + +**Positional arguments** are detected by their order, while **optional arguments** need to be +given with their respective flags ( like ``--name`` or ``-n``). +The following example would parse a positional argument ``Name`` of type ``string`` +and an optional argument ``date`` of type ``string`` which defaults to ``01/01/2000``. + +.. code-block:: python + :emphasize-lines: 3, 5-8, 10 + + import argparse + + parser = argparse.ArgumentParser() + # One positional and one optional argument + parser.add_argument('name', type=str, metavar="N", + help="The name of the subject") + parser.add_argument('-d', '--date', type=string, default="01/01/2000", + help="Birth date of the subject") + + args = parser.parse_args() + + print(args.name + " was born on " + args.date) + +If this code was in ``birthday.py`` and we would call ``python birthday.py --help`` it +would show the following message: + +.. code-block:: console + + usage: birthday.py [-h] [-d DATE] N + + positional arguments: + N The name of the subject + + optional arguments: + -h, --help show this help message and exit + -d DATE, --date DATE Birth date of the subject + + +Exercises 2 +----------- + +.. challenge:: Scripts-2 + + 1. Take the python script we have written in the preceding exercise and use + :py:mod:`argparse` to specify the input and output files and allow the start and end dates to be set. + The start and end dates should be optional parameters with the defaults as they are in the current script. + + 2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from Mai 2020 to October 2020). + Also use data for cairo (``https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv``) + + +.. solution:: + + .. literalinclude:: ../resources/code/scripts/weather_observations_argparse.py + :language: python + :emphasize-lines: 2,4-8,10,13,16-17,37 + + + + +.. discussion:: + + **What was the point of doing this?** + + Now you can do this: + + .. code-block:: console + + $ python weather_observations.py --help + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png + $ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png + $ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png + $ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output temperature_cairo.png + + - We can now process different input files without changing the script. + - We can select multiple time ranges without modifying the script. + - This way we can also loop over file patterns (using shell loops or similar) or use + the script in a workflow management system and process many files in parallel. + - By changing from :data:`sys.argv` to :mod:`argparse` we made the script more robust against + user input errors and also got a help text (accessible via ``--help``). + + +Load larger option lists using config files +------------------------------------------- + +In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line: + +.. code-block:: console + + + $ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021 + + +This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple ``Parameter = Value`` +format, and parse it yourself, or you can use e.g. the ``JSON`` or ``YAML`` formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won't go into the details of the formats, and will only give +a short example using YAML here. + +The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (`yaml `__) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the :mod:`json` package). + +The Python module :download:`optionsparser.py <../resources/code/scripts/optionsparser.py>` provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values. + +In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation ...), set the labels and titles explicitly etc. + +In the YAML format, names and values are separated by ``:``. Our above example would therefore translate to the following YAML file: + +.. literalinclude:: ../resources/code/scripts/weather_options.yml + :language: yaml + +Exercises 3 (optional) +---------------------- + +.. challenge:: Scripts-3 + + 1. Download the :download:`optionsparser.py ` + function and load it into your working folder in Jupyterlab. + Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line + (using e.g. argparse or sys.argv) still needs to be read from the command line. + + + 2. Run your script with different config files. + + +.. solution:: + + The modified **weather_observations.py** script: + + .. literalinclude:: ../resources/code/scripts/weather_observations_config.py + :language: python + :emphasize-lines: 5,9-12,15-27,30,33,36-37,58 + + +.. admonition:: Further reading + + - Linking Jupyterlab notebooks to python scripts (making linking ``.py``- and ``.ipynb``-files easier) using `jupytext `_ + - The `wikipedia page about YAML `_ contains a lot of additional information on the YAML syntax. + - `The Coderefinery Lesson about reproducible research `_ can give additional information about good coding practices and workflow automation. + + - `CodeRefinery's lesson on Modular code development `__ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_sources/web-apis.ipynb.txt b/branch/rkdarst--remove-catfacts-jsonl/_sources/web-apis.ipynb.txt new file mode 100644 index 00000000..14a37e96 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_sources/web-apis.ipynb.txt @@ -0,0 +1,1048 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c87bb04a-3f53-45ac-bbc9-fe182c844219", + "metadata": { + "tags": [] + }, + "source": [ + "# Web APIs with Python\n", + "\n", + ":::{questions}\n", + "- Have you ever needed to get some data from somewhere else on the web?\n", + ":::\n", + "\n", + ":::{objectives}\n", + "- Understand a web server and API and why might you need to talk to one.\n", + "- Basics of the [requests](https://requests.readthedocs.io/en/latest/) Python library\n", + "- Some lightweight recommendations on saving data when you get to more serious data download.\n", + ":::\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "2398bb45-e061-4e7a-8931-82906a3892ff", + "metadata": { + "tags": [] + }, + "source": [ + "## Requests\n", + "\n", + "Requests is a Python library that makes **requests** to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.\n", + "\n", + "First, let's take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: " + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "c69a16ac-a5b3-4ff0-a949-720b5bbd37cd", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + " \n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Embed the requests homepage\n", + "from IPython.display import IFrame\n", + "requests_documentation_url = \"https://requests.readthedocs.io/en/latest/\"\n", + "IFrame(requests_documentation_url, '100%', '30%')" + ] + }, + { + "cell_type": "markdown", + "id": "6d6b334b-309e-429b-aad5-0ab76f071c15", + "metadata": {}, + "source": [ + "## Retrieve data from API\n", + "\n", + "An **API (Application Programming Interface)** is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the **request-response** cycle.\n", + "\n", + "We can find a list of some free APIs (available without authentication) at . These APIs can be used for developing and testing our code." + ] + }, + { + "cell_type": "markdown", + "id": "0a21faac-a7d8-448d-a8db-6fb23b9bd64c", + "metadata": { + "tags": [] + }, + "source": [ + "Let's make a request to the Cat Fact API. If we go to , it gives us the definitions:\n", + "* GET `/fact` is the **API endpoint**.\n", + "* **GET** is the type of request we make and\n", + "* `/fact` is the **path**.\n", + "\n", + "You can even test this in your web browser: \n", + "\n", + "Using the Requests library, we do this with {meth}`~requests.get`." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "fa134bb7-1250-46bd-bd80-e3e0d0820523", + "metadata": {}, + "outputs": [], + "source": [ + "# Import\n", + "import requests\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "64a7f3be-420b-4e1c-a76d-67d9e6b29f4f", + "metadata": { + "tags": [] + }, + "source": [ + "The {class}`requests.Response` object tells us what the server said. We can access the response content using {attr}`~requests.Response.content`." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "b3e1ddb3-76a1-4e53-a32b-4005d92626c6", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "b'{\"fact\":\"Cats come back to full alertness from the sleep state faster than any other creature.\",\"length\":85}'" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "response_content = response.content\n", + "\n", + "# Display\n", + "display(response_content)" + ] + }, + { + "cell_type": "markdown", + "id": "3886ff1c-0619-4fc5-828a-269257db6e63", + "metadata": { + "tags": [] + }, + "source": [ + "The response content is in the [JSON format](https://en.wikipedia.org/wiki/JSON) and Requests gives us the {meth}`~requests.Response.json` method that decodes it and returns the corresponding data as Python objects. This is equivalent to {func}`json.load`." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "7651cd8c-9581-4d04-b3bf-c57997a5684a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'fact': 'Cats come back to full alertness from the sleep state faster than any other creature.',\n", + " 'length': 85}" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json)" + ] + }, + { + "cell_type": "markdown", + "id": "10ca2577-94a4-4689-a01a-2681fe4c5d20", + "metadata": { + "tags": [] + }, + "source": [ + "(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)" + ] + }, + { + "cell_type": "markdown", + "id": "80e02c0b-9b59-44ea-ab26-092b6cdb510b", + "metadata": { + "tags": [] + }, + "source": [ + "## API which requires parameters\n", + "\n", + "Let's then examine another API which accepts [parameters](https://requests.readthedocs.io/en/latest/user/quickstart/#passing-parameters-in-urls) to specify the information request. In particular, we will request a list of Finnish universities from using the `/search` end point and a parameter _country_ with value _Finland_, like this:\n", + "`http://universities.hipolabs.com/search?country=Finland` ." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "b98cba34-0f3a-43fb-befe-0e1c48fdb1c3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "[{'country': 'Finland',\n", + " 'domains': ['abo.fi'],\n", + " 'web_pages': ['http://www.abo.fi/'],\n", + " 'alpha_two_code': 'FI',\n", + " 'name': 'Abo Akademi University',\n", + " 'state-province': None},\n", + " {'country': 'Finland',\n", + " 'domains': ['cou.fi'],\n", + " 'web_pages': ['http://www.cou.fi/'],\n", + " 'alpha_two_code': 'FI',\n", + " 'name': 'Central Ostrobothnia University of Applied Sciences',\n", + " 'state-province': None}]" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search?country=Finland'\n", + "\n", + "# Make a request\n", + "response = requests.get(url)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])" + ] + }, + { + "cell_type": "markdown", + "id": "18ee30d2-e072-41b2-b4d4-8203cb5e86ce", + "metadata": { + "tags": [] + }, + "source": [ + "URLs containing parameters can always be constructed manually using the _&_ character and then listing the parameter (_key_, _value_) pairs as above.\n", + "\n", + "However, _Requests_ allows us to provide the parameters as a dictionary of strings, using the _params_ keyword argument to {meth}`~requests.get`. This is easier to read and less error-prone." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "1c1ddced-d423-42cd-89ac-3a0c6d751d9d", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "[{'country': 'Finland',\n", + " 'domains': ['abo.fi'],\n", + " 'web_pages': ['http://www.abo.fi/'],\n", + " 'alpha_two_code': 'FI',\n", + " 'name': 'Abo Akademi University',\n", + " 'state-province': None},\n", + " {'country': 'Finland',\n", + " 'domains': ['cou.fi'],\n", + " 'web_pages': ['http://www.cou.fi/'],\n", + " 'alpha_two_code': 'FI',\n", + " 'name': 'Central Ostrobothnia University of Applied Sciences',\n", + " 'state-province': None}]" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# URL\n", + "url = 'http://universities.hipolabs.com/search'\n", + "\n", + "# Make the parameter dictionary\n", + "parameters = {'country' : 'Finland'}\n", + "\n", + "# Get response\n", + "response = requests.get(url, params=parameters)\n", + "\n", + "# Decode JSON\n", + "response_json = response.json()\n", + "\n", + "# Display\n", + "display(response_json[:2])\n" + ] + }, + { + "cell_type": "markdown", + "id": "35c751c9-009c-46f7-af8a-40c4132dcfbd", + "metadata": {}, + "source": [ + "## Exercises 1" + ] + }, + { + "cell_type": "markdown", + "id": "033d8d63-43db-4a3e-a9cd-e142134a0b9b", + "metadata": {}, + "source": [ + "::::{exercise} Exercise WebAPIs-1: Request different activity suggestions from the Bored API\n", + "\n", + "Go to the [documentation page of the Bored API](https://www.boredapi.com/documentation). The Bored API is an open API which can be used to randomly generate activity suggestions.\n", + "\n", + "Let's examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response\n", + "\n", + "```json\n", + "{\n", + " \"activity\": \"Learn Express.js\",\n", + " \"accessibility\": 0.25,\n", + " \"type\": \"education\",\n", + " \"participants\": 1,\n", + " \"price\": 0.1,\n", + " \"link\": \"https://expressjs.com/\",\n", + " \"key\": \"3943506\"\n", + "} \n", + "```\n", + "\n", + "Let's replicate the query and see if we can get another random suggestion.\n", + "::::" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "1744a2a7-5c9a-48d4-96b4-9d523b2e43bc", + "metadata": {}, + "outputs": [], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Send the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "77fdd8cd-2c85-474e-bceb-2a737c92521b", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'activity': 'Make your own LEGO creation',\n", + " 'type': 'recreational',\n", + " 'participants': 1,\n", + " 'price': 0,\n", + " 'link': '',\n", + " 'key': '1129748',\n", + " 'accessibility': 0.1}" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "69ae7da6-6c9c-4f2a-94ea-fc75f437eb80", + "metadata": {}, + "source": [ + "Next, let's try to narrow down the suggestions by adding some parameters\n", + "- type\n", + "- participants\n", + "\n", + "All possible parameter values are presented at the bottom of the bored documentation page. [Relevant parts in the _Requests_ documentation](https://requests.readthedocs.io/en/latest/user/quickstart/#parameters)" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "933feded-0d73-4038-b909-6f713cb3782a", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'education',\n", + " 'participants' : 1,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "f9dbeea0-31d3-43b0-8d18-94b608e82a77", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Response'" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "{'activity': 'Memorize the fifty states and their capitals',\n", + " 'type': 'education',\n", + " 'participants': 1,\n", + " 'price': 0,\n", + " 'link': '',\n", + " 'key': '4179309',\n", + " 'accessibility': 0}" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Show the JSON content of the response\n", + "display(\"Response\")\n", + "display(response.json())" + ] + }, + { + "cell_type": "markdown", + "id": "301eb0af-2db2-474b-87e4-8d8815a3a04b", + "metadata": {}, + "source": [ + "Let's narrow the request further with more parameters\n", + "- price range\n", + "- accessibility range\n", + "\n", + "(All possible parameter values are again presented at the bottom of the document page.)" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "d04823d4-154e-48ec-9576-f537bd20c271", + "metadata": {}, + "outputs": [], + "source": [ + "# Define some parameters\n", + "params = {\n", + " 'type' : 'social',\n", + " 'participants' : 2,\n", + " 'minprice' : 0,\n", + " 'maxprice' : 1000,\n", + "}\n", + "\n", + "# Send the request using get() with parameters\n", + "response = requests.get(url, params)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "87978afc-6d0d-46c0-ad0f-e5b851d302e1", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'activity': \"Text a friend you haven't talked to in a long time\",\n", + " 'type': 'social',\n", + " 'participants': 2,\n", + " 'price': 0.05,\n", + " 'link': '',\n", + " 'key': '6081071',\n", + " 'accessibility': 0.2}" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "''" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Show the JSON content of the response\n", + "display(response.json())\n", + "display(\"\")" + ] + }, + { + "cell_type": "markdown", + "id": "0a019d02-cd86-4fdc-874e-b99557955cd1", + "metadata": {}, + "source": [ + "## Exercises 2\n", + "\n", + ":::{exercise} Exercise WebAPIs-2: Examine request and response headers\n", + "\n", + "Request [headers](https://requests.readthedocs.io/en/latest/user/quickstart/#response-headers) are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).\n", + "\n", + "Let's first make a request.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "eb583c27-2ce3-420e-a116-b717f8fa0e3e", + "metadata": {}, + "outputs": [], + "source": [ + "# Import modules\n", + "import requests\n", + "\n", + "# URL of the activity API end point\n", + "url = \"http://www.boredapi.com/api/activity/\"\n", + "\n", + "# Make the request using the get() function\n", + "response = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "271d5abd-6648-4976-899e-25e93d5d8f73", + "metadata": {}, + "source": [ + "We can access the headers of the original request" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "91f78d05-60e7-48ad-8f13-bc4d445e75bc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Request headers'" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive'}" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "display(\"Request headers\")\n", + "display(dict(response.request.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "d6149ec8-c57f-4fab-aaa5-6a61fc7d0291", + "metadata": {}, + "source": [ + "We can also access the headers of the response " + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "d4ff753a-d3dd-41c9-b533-386d0b30d4c3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Response headers'" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "{'Server': 'Cowboy',\n", + " 'Connection': 'keep-alive',\n", + " 'X-Powered-By': 'Express',\n", + " 'Access-Control-Allow-Origin': '*',\n", + " 'Access-Control-Allow-Headers': 'Origin, X-Requested-With, Content-Type, Accept',\n", + " 'Content-Type': 'application/json; charset=utf-8',\n", + " 'Content-Length': '129',\n", + " 'Etag': 'W/\"81-CRSvdYzNLdBSTRSB4vD92JfbcpE\"',\n", + " 'Date': 'Mon, 21 Nov 2022 19:30:53 GMT',\n", + " 'Via': '1.1 vegur'}" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "display(\"Response headers\")\n", + "display(dict(response.headers))" + ] + }, + { + "cell_type": "markdown", + "id": "7132bc48-90a0-49ea-a215-a87006aecf1d", + "metadata": {}, + "source": [ + "In many cases, the default headers\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive'}\n", + "```\n", + "\n", + "added automatically by _Requests_ are sufficient. However, similarly to parameters, we can pass [custom headers](https://requests.readthedocs.io/en/latest/user/quickstart/#custom-headers) to the _get_ function as an argument. \n", + "\n", + "This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.\n", + "\n", + "```json\n", + "{'User-Agent': 'python-requests/2.28.1',\n", + " 'Accept-Encoding': 'gzip, deflate, br',\n", + " 'Accept': '*/*',\n", + " 'Connection': 'keep-alive',\n", + " 'example-user-id' : 'example-password'}\n", + "```\n", + "\n", + "For examples of APIs using this type of authentication, see\n", + "\n", + "- [Imgur API](https://api.imgur.com/oauth2)\n", + "\n", + "For more on authentication, see also [_Requests_ documentation](https://requests.readthedocs.io/en/latest/user/authentication/). \n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "3d50de82-4f2c-4bc4-8f23-3cb4bdb62127", + "metadata": {}, + "source": [ + "## Exercises 3\n", + "\n", + ":::{exercise} Exercise WebAPIs-3: Scrape links from a webpage (Advanced)\n", + "\n", + "Let's use _Requests_ to get the HTML source code of www.example.com, examine it, and use the [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) library to extract links from it.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "cc3373a9-e54f-4049-b715-481ec9893189", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "b'\\n\\n\\n Example Domain\\n\\n \\n \\n \\n \\n\\n\\n\\n
\\n

Example Domain

\\n

This domain is for use in illustrative examples in documents. You may use this\\n domain in literature without prior coordination or asking for permission.

\\n

More information...

\\n
\\n\\n\\n'" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Import module\n", + "import requests\n", + "\n", + "# Define webpage to scrape\n", + "url = \"http://www.example.com/\"\n", + "\n", + "# Make a request for the URL\n", + "response = requests.get(url)\n", + "\n", + "# Examine the response\n", + "display(response.content)" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "d59e52c4-95cf-427d-b3d4-8d0a6dc02aa5", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "\n", + "\n", + " Example Domain\n", + "\n", + " \n", + " \n", + " \n", + " \n", + "\n", + "\n", + "\n", + "
\n", + "

Example Domain

\n", + "

This domain is for use in illustrative examples in documents. You may use this\n", + " domain in literature without prior coordination or asking for permission.

\n", + "

More information...

\n", + "
\n", + "\n", + "\n", + "\n" + ] + } + ], + "source": [ + "# Looks like HTML :) Let's access it using the text attribute\n", + "html = response.text\n", + "\n", + "print(html)" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "327695ae-b376-4d5b-9293-6e89ff272790", + "metadata": {}, + "outputs": [ + { + "ename": "NameError", + "evalue": "name 'html' is not defined", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mNameError\u001b[0m Traceback (most recent call last)", + "Cell \u001b[0;32mIn [1], line 5\u001b[0m\n\u001b[1;32m 2\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m \u001b[38;5;21;01mbs4\u001b[39;00m \u001b[38;5;28;01mimport\u001b[39;00m BeautifulSoup\n\u001b[1;32m 4\u001b[0m \u001b[38;5;66;03m# Create soup\u001b[39;00m\n\u001b[0;32m----> 5\u001b[0m soup \u001b[38;5;241m=\u001b[39m BeautifulSoup(\u001b[43mhtml\u001b[49m, \u001b[38;5;124m'\u001b[39m\u001b[38;5;124mhtml.parser\u001b[39m\u001b[38;5;124m'\u001b[39m)\n", + "\u001b[0;31mNameError\u001b[0m: name 'html' is not defined" + ] + } + ], + "source": [ + "# Import beautiful soup module\n", + "from bs4 import BeautifulSoup\n", + "\n", + "# Create soup\n", + "soup = BeautifulSoup(html, 'html.parser')" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "0e21c6de-a845-4823-b777-bf2cd44fbfd2", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Found title: Example Domain\n" + ] + } + ], + "source": [ + "# Extract page title from the HTML\n", + "print(f\"Found title: {soup.title.text}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "a7fa0e7b-b171-4e65-b987-84a101da58df", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Found link: https://www.iana.org/domains/example\n" + ] + } + ], + "source": [ + "# Extract links (hrefs) from the HTML\n", + "for link in soup.find_all('a'):\n", + " print(f\"Found link: {link.get('href')}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "6581edcb-c170-4cc7-a442-d8d8c724ca50", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Found text: \n", + "\n", + "\n", + "Example Domain\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "Example Domain\n", + "This domain is for use in illustrative examples in documents. You may use this\n", + " domain in literature without prior coordination or asking for permission.\n", + "More information...\n", + "\n", + "\n", + "\n", + "\n" + ] + } + ], + "source": [ + "# Extract all text from the HTML\n", + "print(f\"Found text: {soup.get_text()}\") " + ] + }, + { + "cell_type": "markdown", + "id": "7cdff2d8-0c98-45b3-a825-ed1492d10302", + "metadata": {}, + "source": [ + "## After exercises: Saving retrieved data to disk\n", + "\n", + "Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudal study.\n", + "\n", + "To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don't, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).\n", + "\n", + "For example, let's retrieve three cat facts and save them to a JSONLINES file using the [jsonlines library](https://jsonlines.readthedocs.io/en/latest/)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "80a8dcd1-ba04-45de-840e-aa014c19a75c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Make request 0\n" + ] + }, + { + "ename": "NameError", + "evalue": "name 'requests' is not defined", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mNameError\u001b[0m Traceback (most recent call last)", + "Cell \u001b[0;32mIn [5], line 15\u001b[0m\n\u001b[1;32m 12\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mMake request \u001b[39m\u001b[38;5;132;01m{\u001b[39;00mi\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m 14\u001b[0m \u001b[38;5;66;03m# Make a request\u001b[39;00m\n\u001b[0;32m---> 15\u001b[0m response \u001b[38;5;241m=\u001b[39m \u001b[43mrequests\u001b[49m\u001b[38;5;241m.\u001b[39mget(url)\n\u001b[1;32m 17\u001b[0m \u001b[38;5;66;03m# Decode to JSON\u001b[39;00m\n\u001b[1;32m 18\u001b[0m response_json \u001b[38;5;241m=\u001b[39m response\u001b[38;5;241m.\u001b[39mjson()\n", + "\u001b[0;31mNameError\u001b[0m: name 'requests' is not defined" + ] + } + ], + "source": [ + "# Import\n", + "import requests\n", + "import jsonlines\n", + "import time\n", + "\n", + "# URL\n", + "url = 'https://catfact.ninja/fact'\n", + "\n", + "# Make three requests in loop and make a list of response JSON objects\n", + "for i in range(3):\n", + "\n", + " # Logging\n", + " print(f\"Make request {i}\")\n", + "\n", + " # Make a request\n", + " response = requests.get(url)\n", + " \n", + " # Decode to JSON\n", + " response_json = response.json()\n", + " \n", + " # Open a jsonlines writer in 'append' mode \n", + " with jsonlines.open('catfacts.jsonl', mode='a') as writer:\n", + "\n", + " # Write\n", + " writer.write(response_json)\n", + " \n", + " # Sleep for one second between requests\n", + " time.sleep(1)\n" + ] + }, + { + "cell_type": "markdown", + "id": "efb4a0ff-6a70-471a-af61-39c0350d4166", + "metadata": {}, + "source": [ + "We can then read the objects from the disk using the same library." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "2d424c23-bdf3-47f7-a643-4312a07c955a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'fact': 'In the 1930s, two Russian biologists discovered that color change in Siamese kittens depend on their body temperature. Siamese cats carry albino genes that work only when the body temperature is above 98° F. If these kittens are left in a very warm room, their points won’t darken and they will stay a creamy white.',\n", + " 'length': 315}" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "{'fact': \"The Maine Coon cat is America's only natural breed of domestic feline. It is 4 to 5 times larger than the Singapura, the smallest breed of cat.\",\n", + " 'length': 143}" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "{'fact': \"Cats must have fat in their diet because they can't produce it on their own.\",\n", + " 'length': 76}" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Open a jsonlines reader\n", + "with jsonlines.open('catfacts.jsonl', mode='r') as reader:\n", + " \n", + " # Read and display\n", + " for obj in reader:\n", + " display(obj)" + ] + }, + { + "cell_type": "markdown", + "id": "2f6b8117-b1ef-43cb-9458-0fe4ac49b67a", + "metadata": {}, + "source": [ + "## Wrap-up\n", + "\n", + "\n", + ":::{keypoints}\n", + "- Requests is a common tool\n", + "- Web APIs may often require some trial and error, but actually getting data is usually not that difficult\n", + "- Storing all the data and processing it well can be a much larger issue.\n", + ":::\n", + "\n" + ] + } + ], + "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.8.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/_sphinx_javascript_frameworks_compat.js b/branch/rkdarst--remove-catfacts-jsonl/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..8549469d --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,134 @@ +/* + * _sphinx_javascript_frameworks_compat.js + * ~~~~~~~~~~ + * + * Compatability shim for jQuery and underscores.js. + * + * WILL BE REMOVED IN Sphinx 6.0 + * xref RemovedInSphinx60Warning + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/basic.css b/branch/rkdarst--remove-catfacts-jsonl/_static/basic.css new file mode 100644 index 00000000..eeb0519a --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/basic.css @@ -0,0 +1,899 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} +dl.footnote > dt, +dl.citation > dt { + float: left; + margin-right: 0.5em; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} +dl.field-list > dt:after { + content: ":"; +} + + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/check-solid.svg b/branch/rkdarst--remove-catfacts-jsonl/_static/check-solid.svg new file mode 100644 index 00000000..92fad4b5 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/clipboard.min.js b/branch/rkdarst--remove-catfacts-jsonl/_static/clipboard.min.js new file mode 100644 index 00000000..54b3c463 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton.css b/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton.css new file mode 100644 index 00000000..f1916ec7 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton.js b/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton.js new file mode 100644 index 00000000..02c5c82d --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton.js @@ -0,0 +1,248 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copié dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = ``; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = 'div.highlight pre'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} + + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '.linenos, .gp'; + + let text = filterText(target, exclude); + return formatCopyText(text, '', false, true, true, true, '', '') +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton_funcs.js b/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton_funcs.js new file mode 100644 index 00000000..dbe1aaad --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/badge_only.css b/branch/rkdarst--remove-catfacts-jsonl/_static/css/badge_only.css new file mode 100644 index 00000000..c718cee4 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}} \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Bold.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Bold.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Regular.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Regular.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.eot b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.svg b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.ttf b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold-italic.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold-italic.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold-italic.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-bold.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal-italic.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal-italic.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal-italic.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal.woff b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal.woff differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal.woff2 b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/css/fonts/lato-normal.woff2 differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/css/theme.css b/branch/rkdarst--remove-catfacts-jsonl/_static/css/theme.css new file mode 100644 index 00000000..09a1af86 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search>a:hover{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.version{margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dt:after,html.writer-html5 .rst-content dl.field-list>dt:after,html.writer-html5 .rst-content dl.footnote>dt:after{content:":"}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets,html.writer-html5 .rst-content dl.footnote>dt>span.brackets{margin-right:.5rem}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{font-style:italic}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p,html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content dl.citation,.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content dl.citation code,.rst-content dl.citation tt,.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel{border:1px solid #7fbbe3;background:#e7f2fa;font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/doctools.js b/branch/rkdarst--remove-catfacts-jsonl/_static/doctools.js new file mode 100644 index 00000000..527b876c --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/documentation_options.js b/branch/rkdarst--remove-catfacts-jsonl/_static/documentation_options.js new file mode 100644 index 00000000..c066c69a --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/documentation_options.js @@ -0,0 +1,14 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'dirhtml', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/file.png b/branch/rkdarst--remove-catfacts-jsonl/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/_static/file.png differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/_static/jquery-3.6.0.js b/branch/rkdarst--remove-catfacts-jsonl/_static/jquery-3.6.0.js new file mode 100644 index 00000000..fc6c299b --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/_static/jquery-3.6.0.js @@ -0,0 +1,10881 @@ +/*! + * jQuery JavaScript Library v3.6.0 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright OpenJS Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + * + * Date: 2021-03-02T17:08Z + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var flat = arr.flat ? function( array ) { + return arr.flat.call( array ); +} : function( array ) { + return arr.concat.apply( [], array ); +}; + + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + +var isFunction = function isFunction( obj ) { + + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML elements + // (i.e., `typeof document.createElement( "object" ) === "function"`). + // We don't want to classify *any* DOM node as a function. + // Support: QtWeb <=3.8.5, WebKit <=534.34, wkhtmltopdf tool <=0.12.5 + // Plus for old WebKit, typeof returns "function" for HTML collections + // (e.g., `typeof document.getElementsByTagName("div") === "function"`). (gh-4756) + return typeof obj === "function" && typeof obj.nodeType !== "number" && + typeof obj.item !== "function"; + }; + + +var isWindow = function isWindow( obj ) { + return obj != null && obj === obj.window; + }; + + +var document = window.document; + + + + var preservedScriptAttributes = { + type: true, + src: true, + nonce: true, + noModule: true + }; + + function DOMEval( code, node, doc ) { + doc = doc || document; + + var i, val, + script = doc.createElement( "script" ); + + script.text = code; + if ( node ) { + for ( i in preservedScriptAttributes ) { + + // Support: Firefox 64+, Edge 18+ + // Some browsers don't support the "nonce" property on scripts. + // On the other hand, just using `getAttribute` is not enough as + // the `nonce` attribute is reset to an empty string whenever it + // becomes browsing-context connected. + // See https://github.com/whatwg/html/issues/2369 + // See https://html.spec.whatwg.org/#nonce-attributes + // The `node.getAttribute` check was added for the sake of + // `jQuery.globalEval` so that it can fake a nonce-containing node + // via an object. + val = node[ i ] || node.getAttribute && node.getAttribute( i ); + if ( val ) { + script.setAttribute( i, val ); + } + } + } + doc.head.appendChild( script ).parentNode.removeChild( script ); + } + + +function toType( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; +} +/* global Symbol */ +// Defining this global in .eslintrc.json would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.6.0", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + + // Return all the elements in a clean array + if ( num == null ) { + return slice.call( this ); + } + + // Return just the one element from the set + return num < 0 ? this[ num + this.length ] : this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + even: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return ( i + 1 ) % 2; + } ) ); + }, + + odd: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return i % 2; + } ) ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + copy = options[ name ]; + + // Prevent Object.prototype pollution + // Prevent never-ending loop + if ( name === "__proto__" || target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = Array.isArray( copy ) ) ) ) { + src = target[ name ]; + + // Ensure proper type for the source value + if ( copyIsArray && !Array.isArray( src ) ) { + clone = []; + } else if ( !copyIsArray && !jQuery.isPlainObject( src ) ) { + clone = {}; + } else { + clone = src; + } + copyIsArray = false; + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + // Evaluates a script in a provided context; falls back to the global one + // if not specified. + globalEval: function( code, options, doc ) { + DOMEval( code, { nonce: options && options.nonce }, doc ); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return flat( ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), + function( _i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); + } ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = toType( obj ); + + if ( isFunction( obj ) || isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.6 + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://js.foundation/ + * + * Date: 2021-02-16 + */ +( function( window ) { +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + nonnativeSelectorCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ( {} ).hasOwnProperty, + arr = [], + pop = arr.pop, + pushNative = arr.push, + push = arr.push, + slice = arr.slice, + + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[ i ] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|" + + "ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // https://www.w3.org/TR/css-syntax-3/#ident-token-diagram + identifier = "(?:\\\\[\\da-fA-F]{1,6}" + whitespace + + "?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + + // "Attribute values must be CSS identifiers [capture 5] + // or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + + whitespace + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + + "*" ), + rdescend = new RegExp( whitespace + "|>" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + + whitespace + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + + whitespace + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + whitespace + + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rhtml = /HTML$/i, + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\[\\da-fA-F]{1,6}" + whitespace + "?|\\\\([^\\r\\n\\f])", "g" ), + funescape = function( escape, nonHex ) { + var high = "0x" + escape.slice( 1 ) - 0x10000; + + return nonHex ? + + // Strip the backslash prefix from a non-hex escape sequence + nonHex : + + // Replace a hexadecimal escape sequence with the encoded Unicode code point + // Support: IE <=11+ + // For values outside the Basic Multilingual Plane (BMP), manually construct a + // surrogate pair + high < 0 ? + String.fromCharCode( high + 0x10000 ) : + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + inDisabledFieldset = addCombinator( + function( elem ) { + return elem.disabled === true && elem.nodeName.toLowerCase() === "fieldset"; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + ( arr = slice.call( preferredDoc.childNodes ) ), + preferredDoc.childNodes + ); + + // Support: Android<4.0 + // Detect silently failing push.apply + // eslint-disable-next-line no-unused-expressions + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + pushNative.apply( target, slice.call( els ) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + + // Can't trust NodeList.length + while ( ( target[ j++ ] = els[ i++ ] ) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + setDocument( context ); + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && ( match = rquickExpr.exec( selector ) ) ) { + + // ID selector + if ( ( m = match[ 1 ] ) ) { + + // Document context + if ( nodeType === 9 ) { + if ( ( elem = context.getElementById( m ) ) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && ( elem = newContext.getElementById( m ) ) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[ 2 ] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( ( m = match[ 3 ] ) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !nonnativeSelectorCache[ selector + " " ] && + ( !rbuggyQSA || !rbuggyQSA.test( selector ) ) && + + // Support: IE 8 only + // Exclude object elements + ( nodeType !== 1 || context.nodeName.toLowerCase() !== "object" ) ) { + + newSelector = selector; + newContext = context; + + // qSA considers elements outside a scoping root when evaluating child or + // descendant combinators, which is not what we want. + // In such cases, we work around the behavior by prefixing every selector in the + // list with an ID selector referencing the scope context. + // The technique has to be used as well when a leading combinator is used + // as such selectors are not recognized by querySelectorAll. + // Thanks to Andrew Dupont for this technique. + if ( nodeType === 1 && + ( rdescend.test( selector ) || rcombinators.test( selector ) ) ) { + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + + // We can use :scope instead of the ID hack if the browser + // supports it & if we're not changing the context. + if ( newContext !== context || !support.scope ) { + + // Capture the context ID, setting it first if necessary + if ( ( nid = context.getAttribute( "id" ) ) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", ( nid = expando ) ); + } + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[ i ] = ( nid ? "#" + nid : ":scope" ) + " " + + toSelector( groups[ i ] ); + } + newSelector = groups.join( "," ); + } + + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + nonnativeSelectorCache( selector, true ); + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return ( cache[ key + " " ] = value ); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement( "fieldset" ); + + try { + return !!fn( el ); + } catch ( e ) { + return false; + } finally { + + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split( "|" ), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[ i ] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( ( cur = cur.nextSibling ) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return ( name === "input" || name === "button" ) && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + + // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Only certain elements can match :enabled or :disabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled + if ( "form" in elem ) { + + // Check for inherited disabledness on relevant non-disabled elements: + // * listed form-associated elements in a disabled fieldset + // https://html.spec.whatwg.org/multipage/forms.html#category-listed + // https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled + // * option elements in a disabled optgroup + // https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled + // All such elements have a "form" property. + if ( elem.parentNode && elem.disabled === false ) { + + // Option elements defer to a parent optgroup if present + if ( "label" in elem ) { + if ( "label" in elem.parentNode ) { + return elem.parentNode.disabled === disabled; + } else { + return elem.disabled === disabled; + } + } + + // Support: IE 6 - 11 + // Use the isDisabled shortcut property to check for disabled fieldset ancestors + return elem.isDisabled === disabled || + + // Where there is no isDisabled, check manually + /* jshint -W018 */ + elem.isDisabled !== !disabled && + inDisabledFieldset( elem ) === disabled; + } + + return elem.disabled === disabled; + + // Try to winnow out elements that can't be disabled before trusting the disabled property. + // Some victims get caught in our net (label, legend, menu, track), but it shouldn't + // even exist on them, let alone have a boolean value. + } else if ( "label" in elem ) { + return elem.disabled === disabled; + } + + // Remaining elements are neither :enabled nor :disabled + return false; + }; +} + +/** + * Returns a function to use in pseudos for positionals + * @param {Function} fn + */ +function createPositionalPseudo( fn ) { + return markFunction( function( argument ) { + argument = +argument; + return markFunction( function( seed, matches ) { + var j, + matchIndexes = fn( [], seed.length, argument ), + i = matchIndexes.length; + + // Match elements found at the specified indexes + while ( i-- ) { + if ( seed[ ( j = matchIndexes[ i ] ) ] ) { + seed[ j ] = !( matches[ j ] = seed[ j ] ); + } + } + } ); + } ); +} + +/** + * Checks a node for validity as a Sizzle context + * @param {Element|Object=} context + * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + */ +function testContext( context ) { + return context && typeof context.getElementsByTagName !== "undefined" && context; +} + +// Expose support vars for convenience +support = Sizzle.support = {}; + +/** + * Detects XML nodes + * @param {Element|Object} elem An element or a document + * @returns {Boolean} True iff elem is a non-HTML XML node + */ +isXML = Sizzle.isXML = function( elem ) { + var namespace = elem && elem.namespaceURI, + docElem = elem && ( elem.ownerDocument || elem ).documentElement; + + // Support: IE <=8 + // Assume HTML when documentElement doesn't yet exist, such as inside loading iframes + // https://bugs.jquery.com/ticket/4833 + return !rhtml.test( namespace || docElem && docElem.nodeName || "HTML" ); +}; + +/** + * Sets document-related variables once based on the current document + * @param {Element|Object} [doc] An element or document object to use to set the document + * @returns {Object} Returns the current document + */ +setDocument = Sizzle.setDocument = function( node ) { + var hasCompare, subWindow, + doc = node ? node.ownerDocument || node : preferredDoc; + + // Return early if doc is invalid or already selected + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( doc == document || doc.nodeType !== 9 || !doc.documentElement ) { + return document; + } + + // Update global variables + document = doc; + docElem = document.documentElement; + documentIsHTML = !isXML( document ); + + // Support: IE 9 - 11+, Edge 12 - 18+ + // Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936) + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( preferredDoc != document && + ( subWindow = document.defaultView ) && subWindow.top !== subWindow ) { + + // Support: IE 11, Edge + if ( subWindow.addEventListener ) { + subWindow.addEventListener( "unload", unloadHandler, false ); + + // Support: IE 9 - 10 only + } else if ( subWindow.attachEvent ) { + subWindow.attachEvent( "onunload", unloadHandler ); + } + } + + // Support: IE 8 - 11+, Edge 12 - 18+, Chrome <=16 - 25 only, Firefox <=3.6 - 31 only, + // Safari 4 - 5 only, Opera <=11.6 - 12.x only + // IE/Edge & older browsers don't support the :scope pseudo-class. + // Support: Safari 6.0 only + // Safari 6.0 supports :scope but it's an alias of :root there. + support.scope = assert( function( el ) { + docElem.appendChild( el ).appendChild( document.createElement( "div" ) ); + return typeof el.querySelectorAll !== "undefined" && + !el.querySelectorAll( ":scope fieldset div" ).length; + } ); + + /* Attributes + ---------------------------------------------------------------------- */ + + // Support: IE<8 + // Verify that getAttribute really returns attributes and not properties + // (excepting IE8 booleans) + support.attributes = assert( function( el ) { + el.className = "i"; + return !el.getAttribute( "className" ); + } ); + + /* getElement(s)By* + ---------------------------------------------------------------------- */ + + // Check if getElementsByTagName("*") returns only elements + support.getElementsByTagName = assert( function( el ) { + el.appendChild( document.createComment( "" ) ); + return !el.getElementsByTagName( "*" ).length; + } ); + + // Support: IE<9 + support.getElementsByClassName = rnative.test( document.getElementsByClassName ); + + // Support: IE<10 + // Check if getElementById returns elements by name + // The broken getElementById methods don't pick up programmatically-set names, + // so use a roundabout getElementsByName test + support.getById = assert( function( el ) { + docElem.appendChild( el ).id = expando; + return !document.getElementsByName || !document.getElementsByName( expando ).length; + } ); + + // ID filter and find + if ( support.getById ) { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + return elem.getAttribute( "id" ) === attrId; + }; + }; + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var elem = context.getElementById( id ); + return elem ? [ elem ] : []; + } + }; + } else { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + var node = typeof elem.getAttributeNode !== "undefined" && + elem.getAttributeNode( "id" ); + return node && node.value === attrId; + }; + }; + + // Support: IE 6 - 7 only + // getElementById is not reliable as a find shortcut + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var node, i, elems, + elem = context.getElementById( id ); + + if ( elem ) { + + // Verify the id attribute + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + + // Fall back on getElementsByName + elems = context.getElementsByName( id ); + i = 0; + while ( ( elem = elems[ i++ ] ) ) { + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + } + } + + return []; + } + }; + } + + // Tag + Expr.find[ "TAG" ] = support.getElementsByTagName ? + function( tag, context ) { + if ( typeof context.getElementsByTagName !== "undefined" ) { + return context.getElementsByTagName( tag ); + + // DocumentFragment nodes don't have gEBTN + } else if ( support.qsa ) { + return context.querySelectorAll( tag ); + } + } : + + function( tag, context ) { + var elem, + tmp = [], + i = 0, + + // By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too + results = context.getElementsByTagName( tag ); + + // Filter out possible comments + if ( tag === "*" ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem.nodeType === 1 ) { + tmp.push( elem ); + } + } + + return tmp; + } + return results; + }; + + // Class + Expr.find[ "CLASS" ] = support.getElementsByClassName && function( className, context ) { + if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) { + return context.getElementsByClassName( className ); + } + }; + + /* QSA/matchesSelector + ---------------------------------------------------------------------- */ + + // QSA and matchesSelector support + + // matchesSelector(:active) reports false when true (IE9/Opera 11.5) + rbuggyMatches = []; + + // qSa(:focus) reports false when true (Chrome 21) + // We allow this because of a bug in IE8/9 that throws an error + // whenever `document.activeElement` is accessed on an iframe + // So, we allow :focus to pass through QSA all the time to avoid the IE error + // See https://bugs.jquery.com/ticket/13378 + rbuggyQSA = []; + + if ( ( support.qsa = rnative.test( document.querySelectorAll ) ) ) { + + // Build QSA regex + // Regex strategy adopted from Diego Perini + assert( function( el ) { + + var input; + + // Select is set to empty string on purpose + // This is to test IE's treatment of not explicitly + // setting a boolean content attribute, + // since its presence should be enough + // https://bugs.jquery.com/ticket/12359 + docElem.appendChild( el ).innerHTML = "" + + ""; + + // Support: IE8, Opera 11-12.16 + // Nothing should be selected when empty strings follow ^= or $= or *= + // The test attribute must be unknown in Opera but "safe" for WinRT + // https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section + if ( el.querySelectorAll( "[msallowcapture^='']" ).length ) { + rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); + } + + // Support: IE8 + // Boolean attributes and "value" are not treated correctly + if ( !el.querySelectorAll( "[selected]" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); + } + + // Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+ + if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) { + rbuggyQSA.push( "~=" ); + } + + // Support: IE 11+, Edge 15 - 18+ + // IE 11/Edge don't find elements on a `[name='']` query in some cases. + // Adding a temporary attribute to the document before the selection works + // around the issue. + // Interestingly, IE 10 & older don't seem to have the issue. + input = document.createElement( "input" ); + input.setAttribute( "name", "" ); + el.appendChild( input ); + if ( !el.querySelectorAll( "[name='']" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*name" + whitespace + "*=" + + whitespace + "*(?:''|\"\")" ); + } + + // Webkit/Opera - :checked should return selected option elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + // IE8 throws error here and will not see later tests + if ( !el.querySelectorAll( ":checked" ).length ) { + rbuggyQSA.push( ":checked" ); + } + + // Support: Safari 8+, iOS 8+ + // https://bugs.webkit.org/show_bug.cgi?id=136851 + // In-page `selector#id sibling-combinator selector` fails + if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) { + rbuggyQSA.push( ".#.+[+~]" ); + } + + // Support: Firefox <=3.6 - 5 only + // Old Firefox doesn't throw on a badly-escaped identifier. + el.querySelectorAll( "\\\f" ); + rbuggyQSA.push( "[\\r\\n\\f]" ); + } ); + + assert( function( el ) { + el.innerHTML = "" + + ""; + + // Support: Windows 8 Native Apps + // The type and name attributes are restricted during .innerHTML assignment + var input = document.createElement( "input" ); + input.setAttribute( "type", "hidden" ); + el.appendChild( input ).setAttribute( "name", "D" ); + + // Support: IE8 + // Enforce case-sensitivity of name attribute + if ( el.querySelectorAll( "[name=d]" ).length ) { + rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); + } + + // FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled) + // IE8 throws error here and will not see later tests + if ( el.querySelectorAll( ":enabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: IE9-11+ + // IE's :disabled selector does not pick up the children of disabled fieldsets + docElem.appendChild( el ).disabled = true; + if ( el.querySelectorAll( ":disabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: Opera 10 - 11 only + // Opera 10-11 does not throw on post-comma invalid pseudos + el.querySelectorAll( "*,:x" ); + rbuggyQSA.push( ",.*:" ); + } ); + } + + if ( ( support.matchesSelector = rnative.test( ( matches = docElem.matches || + docElem.webkitMatchesSelector || + docElem.mozMatchesSelector || + docElem.oMatchesSelector || + docElem.msMatchesSelector ) ) ) ) { + + assert( function( el ) { + + // Check to see if it's possible to do matchesSelector + // on a disconnected node (IE 9) + support.disconnectedMatch = matches.call( el, "*" ); + + // This should fail with an exception + // Gecko does not error, returns false instead + matches.call( el, "[s!='']:x" ); + rbuggyMatches.push( "!=", pseudos ); + } ); + } + + rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join( "|" ) ); + rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join( "|" ) ); + + /* Contains + ---------------------------------------------------------------------- */ + hasCompare = rnative.test( docElem.compareDocumentPosition ); + + // Element contains another + // Purposefully self-exclusive + // As in, an element does not contain itself + contains = hasCompare || rnative.test( docElem.contains ) ? + function( a, b ) { + var adown = a.nodeType === 9 ? a.documentElement : a, + bup = b && b.parentNode; + return a === bup || !!( bup && bup.nodeType === 1 && ( + adown.contains ? + adown.contains( bup ) : + a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 + ) ); + } : + function( a, b ) { + if ( b ) { + while ( ( b = b.parentNode ) ) { + if ( b === a ) { + return true; + } + } + } + return false; + }; + + /* Sorting + ---------------------------------------------------------------------- */ + + // Document order sorting + sortOrder = hasCompare ? + function( a, b ) { + + // Flag for duplicate removal + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + // Sort on method existence if only one input has compareDocumentPosition + var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; + if ( compare ) { + return compare; + } + + // Calculate position if both inputs belong to the same document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + compare = ( a.ownerDocument || a ) == ( b.ownerDocument || b ) ? + a.compareDocumentPosition( b ) : + + // Otherwise we know they are disconnected + 1; + + // Disconnected nodes + if ( compare & 1 || + ( !support.sortDetached && b.compareDocumentPosition( a ) === compare ) ) { + + // Choose the first element that is related to our preferred document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( a == document || a.ownerDocument == preferredDoc && + contains( preferredDoc, a ) ) { + return -1; + } + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( b == document || b.ownerDocument == preferredDoc && + contains( preferredDoc, b ) ) { + return 1; + } + + // Maintain original order + return sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + } + + return compare & 4 ? -1 : 1; + } : + function( a, b ) { + + // Exit early if the nodes are identical + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + var cur, + i = 0, + aup = a.parentNode, + bup = b.parentNode, + ap = [ a ], + bp = [ b ]; + + // Parentless nodes are either documents or disconnected + if ( !aup || !bup ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + return a == document ? -1 : + b == document ? 1 : + /* eslint-enable eqeqeq */ + aup ? -1 : + bup ? 1 : + sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + + // If the nodes are siblings, we can do a quick check + } else if ( aup === bup ) { + return siblingCheck( a, b ); + } + + // Otherwise we need full lists of their ancestors for comparison + cur = a; + while ( ( cur = cur.parentNode ) ) { + ap.unshift( cur ); + } + cur = b; + while ( ( cur = cur.parentNode ) ) { + bp.unshift( cur ); + } + + // Walk down the tree looking for a discrepancy + while ( ap[ i ] === bp[ i ] ) { + i++; + } + + return i ? + + // Do a sibling check if the nodes have a common ancestor + siblingCheck( ap[ i ], bp[ i ] ) : + + // Otherwise nodes in our document sort first + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + ap[ i ] == preferredDoc ? -1 : + bp[ i ] == preferredDoc ? 1 : + /* eslint-enable eqeqeq */ + 0; + }; + + return document; +}; + +Sizzle.matches = function( expr, elements ) { + return Sizzle( expr, null, null, elements ); +}; + +Sizzle.matchesSelector = function( elem, expr ) { + setDocument( elem ); + + if ( support.matchesSelector && documentIsHTML && + !nonnativeSelectorCache[ expr + " " ] && + ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && + ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { + + try { + var ret = matches.call( elem, expr ); + + // IE 9's matchesSelector returns false on disconnected nodes + if ( ret || support.disconnectedMatch || + + // As well, disconnected nodes are said to be in a document + // fragment in IE 9 + elem.document && elem.document.nodeType !== 11 ) { + return ret; + } + } catch ( e ) { + nonnativeSelectorCache( expr, true ); + } + } + + return Sizzle( expr, document, null, [ elem ] ).length > 0; +}; + +Sizzle.contains = function( context, elem ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( context.ownerDocument || context ) != document ) { + setDocument( context ); + } + return contains( context, elem ); +}; + +Sizzle.attr = function( elem, name ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( elem.ownerDocument || elem ) != document ) { + setDocument( elem ); + } + + var fn = Expr.attrHandle[ name.toLowerCase() ], + + // Don't get fooled by Object.prototype properties (jQuery #13807) + val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? + fn( elem, name, !documentIsHTML ) : + undefined; + + return val !== undefined ? + val : + support.attributes || !documentIsHTML ? + elem.getAttribute( name ) : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; +}; + +Sizzle.escape = function( sel ) { + return ( sel + "" ).replace( rcssescape, fcssescape ); +}; + +Sizzle.error = function( msg ) { + throw new Error( "Syntax error, unrecognized expression: " + msg ); +}; + +/** + * Document sorting and removing duplicates + * @param {ArrayLike} results + */ +Sizzle.uniqueSort = function( results ) { + var elem, + duplicates = [], + j = 0, + i = 0; + + // Unless we *know* we can detect duplicates, assume their presence + hasDuplicate = !support.detectDuplicates; + sortInput = !support.sortStable && results.slice( 0 ); + results.sort( sortOrder ); + + if ( hasDuplicate ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem === results[ i ] ) { + j = duplicates.push( i ); + } + } + while ( j-- ) { + results.splice( duplicates[ j ], 1 ); + } + } + + // Clear input after sorting to release objects + // See https://github.com/jquery/sizzle/pull/225 + sortInput = null; + + return results; +}; + +/** + * Utility function for retrieving the text value of an array of DOM nodes + * @param {Array|Element} elem + */ +getText = Sizzle.getText = function( elem ) { + var node, + ret = "", + i = 0, + nodeType = elem.nodeType; + + if ( !nodeType ) { + + // If no nodeType, this is expected to be an array + while ( ( node = elem[ i++ ] ) ) { + + // Do not traverse comment nodes + ret += getText( node ); + } + } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { + + // Use textContent for elements + // innerText usage removed for consistency of new lines (jQuery #11153) + if ( typeof elem.textContent === "string" ) { + return elem.textContent; + } else { + + // Traverse its children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + ret += getText( elem ); + } + } + } else if ( nodeType === 3 || nodeType === 4 ) { + return elem.nodeValue; + } + + // Do not include comment or processing instruction nodes + + return ret; +}; + +Expr = Sizzle.selectors = { + + // Can be adjusted by the user + cacheLength: 50, + + createPseudo: markFunction, + + match: matchExpr, + + attrHandle: {}, + + find: {}, + + relative: { + ">": { dir: "parentNode", first: true }, + " ": { dir: "parentNode" }, + "+": { dir: "previousSibling", first: true }, + "~": { dir: "previousSibling" } + }, + + preFilter: { + "ATTR": function( match ) { + match[ 1 ] = match[ 1 ].replace( runescape, funescape ); + + // Move the given value to match[3] whether quoted or unquoted + match[ 3 ] = ( match[ 3 ] || match[ 4 ] || + match[ 5 ] || "" ).replace( runescape, funescape ); + + if ( match[ 2 ] === "~=" ) { + match[ 3 ] = " " + match[ 3 ] + " "; + } + + return match.slice( 0, 4 ); + }, + + "CHILD": function( match ) { + + /* matches from matchExpr["CHILD"] + 1 type (only|nth|...) + 2 what (child|of-type) + 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) + 4 xn-component of xn+y argument ([+-]?\d*n|) + 5 sign of xn-component + 6 x of xn-component + 7 sign of y-component + 8 y of y-component + */ + match[ 1 ] = match[ 1 ].toLowerCase(); + + if ( match[ 1 ].slice( 0, 3 ) === "nth" ) { + + // nth-* requires argument + if ( !match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + // numeric x and y parameters for Expr.filter.CHILD + // remember that false/true cast respectively to 0/1 + match[ 4 ] = +( match[ 4 ] ? + match[ 5 ] + ( match[ 6 ] || 1 ) : + 2 * ( match[ 3 ] === "even" || match[ 3 ] === "odd" ) ); + match[ 5 ] = +( ( match[ 7 ] + match[ 8 ] ) || match[ 3 ] === "odd" ); + + // other types prohibit arguments + } else if ( match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + return match; + }, + + "PSEUDO": function( match ) { + var excess, + unquoted = !match[ 6 ] && match[ 2 ]; + + if ( matchExpr[ "CHILD" ].test( match[ 0 ] ) ) { + return null; + } + + // Accept quoted arguments as-is + if ( match[ 3 ] ) { + match[ 2 ] = match[ 4 ] || match[ 5 ] || ""; + + // Strip excess characters from unquoted arguments + } else if ( unquoted && rpseudo.test( unquoted ) && + + // Get excess from tokenize (recursively) + ( excess = tokenize( unquoted, true ) ) && + + // advance to the next closing parenthesis + ( excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length ) ) { + + // excess is a negative index + match[ 0 ] = match[ 0 ].slice( 0, excess ); + match[ 2 ] = unquoted.slice( 0, excess ); + } + + // Return only captures needed by the pseudo filter method (type and argument) + return match.slice( 0, 3 ); + } + }, + + filter: { + + "TAG": function( nodeNameSelector ) { + var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); + return nodeNameSelector === "*" ? + function() { + return true; + } : + function( elem ) { + return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; + }; + }, + + "CLASS": function( className ) { + var pattern = classCache[ className + " " ]; + + return pattern || + ( pattern = new RegExp( "(^|" + whitespace + + ")" + className + "(" + whitespace + "|$)" ) ) && classCache( + className, function( elem ) { + return pattern.test( + typeof elem.className === "string" && elem.className || + typeof elem.getAttribute !== "undefined" && + elem.getAttribute( "class" ) || + "" + ); + } ); + }, + + "ATTR": function( name, operator, check ) { + return function( elem ) { + var result = Sizzle.attr( elem, name ); + + if ( result == null ) { + return operator === "!="; + } + if ( !operator ) { + return true; + } + + result += ""; + + /* eslint-disable max-len */ + + return operator === "=" ? result === check : + operator === "!=" ? result !== check : + operator === "^=" ? check && result.indexOf( check ) === 0 : + operator === "*=" ? check && result.indexOf( check ) > -1 : + operator === "$=" ? check && result.slice( -check.length ) === check : + operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 : + operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : + false; + /* eslint-enable max-len */ + + }; + }, + + "CHILD": function( type, what, _argument, first, last ) { + var simple = type.slice( 0, 3 ) !== "nth", + forward = type.slice( -4 ) !== "last", + ofType = what === "of-type"; + + return first === 1 && last === 0 ? + + // Shortcut for :nth-*(n) + function( elem ) { + return !!elem.parentNode; + } : + + function( elem, _context, xml ) { + var cache, uniqueCache, outerCache, node, nodeIndex, start, + dir = simple !== forward ? "nextSibling" : "previousSibling", + parent = elem.parentNode, + name = ofType && elem.nodeName.toLowerCase(), + useCache = !xml && !ofType, + diff = false; + + if ( parent ) { + + // :(first|last|only)-(child|of-type) + if ( simple ) { + while ( dir ) { + node = elem; + while ( ( node = node[ dir ] ) ) { + if ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) { + + return false; + } + } + + // Reverse direction for :only-* (if we haven't yet done so) + start = dir = type === "only" && !start && "nextSibling"; + } + return true; + } + + start = [ forward ? parent.firstChild : parent.lastChild ]; + + // non-xml :nth-child(...) stores cache data on `parent` + if ( forward && useCache ) { + + // Seek `elem` from a previously-cached index + + // ...in a gzip-friendly way + node = parent; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex && cache[ 2 ]; + node = nodeIndex && parent.childNodes[ nodeIndex ]; + + while ( ( node = ++nodeIndex && node && node[ dir ] || + + // Fallback to seeking `elem` from the start + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + // When found, cache indexes on `parent` and break + if ( node.nodeType === 1 && ++diff && node === elem ) { + uniqueCache[ type ] = [ dirruns, nodeIndex, diff ]; + break; + } + } + + } else { + + // Use previously-cached element index if available + if ( useCache ) { + + // ...in a gzip-friendly way + node = elem; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex; + } + + // xml :nth-child(...) + // or :nth-last-child(...) or :nth(-last)?-of-type(...) + if ( diff === false ) { + + // Use the same loop as above to seek `elem` from the start + while ( ( node = ++nodeIndex && node && node[ dir ] || + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + if ( ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) && + ++diff ) { + + // Cache the index of each encountered element + if ( useCache ) { + outerCache = node[ expando ] || + ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + uniqueCache[ type ] = [ dirruns, diff ]; + } + + if ( node === elem ) { + break; + } + } + } + } + } + + // Incorporate the offset, then check against cycle size + diff -= last; + return diff === first || ( diff % first === 0 && diff / first >= 0 ); + } + }; + }, + + "PSEUDO": function( pseudo, argument ) { + + // pseudo-class names are case-insensitive + // http://www.w3.org/TR/selectors/#pseudo-classes + // Prioritize by case sensitivity in case custom pseudos are added with uppercase letters + // Remember that setFilters inherits from pseudos + var args, + fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || + Sizzle.error( "unsupported pseudo: " + pseudo ); + + // The user may use createPseudo to indicate that + // arguments are needed to create the filter function + // just as Sizzle does + if ( fn[ expando ] ) { + return fn( argument ); + } + + // But maintain support for old signatures + if ( fn.length > 1 ) { + args = [ pseudo, pseudo, "", argument ]; + return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? + markFunction( function( seed, matches ) { + var idx, + matched = fn( seed, argument ), + i = matched.length; + while ( i-- ) { + idx = indexOf( seed, matched[ i ] ); + seed[ idx ] = !( matches[ idx ] = matched[ i ] ); + } + } ) : + function( elem ) { + return fn( elem, 0, args ); + }; + } + + return fn; + } + }, + + pseudos: { + + // Potentially complex pseudos + "not": markFunction( function( selector ) { + + // Trim the selector passed to compile + // to avoid treating leading and trailing + // spaces as combinators + var input = [], + results = [], + matcher = compile( selector.replace( rtrim, "$1" ) ); + + return matcher[ expando ] ? + markFunction( function( seed, matches, _context, xml ) { + var elem, + unmatched = matcher( seed, null, xml, [] ), + i = seed.length; + + // Match elements unmatched by `matcher` + while ( i-- ) { + if ( ( elem = unmatched[ i ] ) ) { + seed[ i ] = !( matches[ i ] = elem ); + } + } + } ) : + function( elem, _context, xml ) { + input[ 0 ] = elem; + matcher( input, null, xml, results ); + + // Don't keep the element (issue #299) + input[ 0 ] = null; + return !results.pop(); + }; + } ), + + "has": markFunction( function( selector ) { + return function( elem ) { + return Sizzle( selector, elem ).length > 0; + }; + } ), + + "contains": markFunction( function( text ) { + text = text.replace( runescape, funescape ); + return function( elem ) { + return ( elem.textContent || getText( elem ) ).indexOf( text ) > -1; + }; + } ), + + // "Whether an element is represented by a :lang() selector + // is based solely on the element's language value + // being equal to the identifier C, + // or beginning with the identifier C immediately followed by "-". + // The matching of C against the element's language value is performed case-insensitively. + // The identifier C does not have to be a valid language name." + // http://www.w3.org/TR/selectors/#lang-pseudo + "lang": markFunction( function( lang ) { + + // lang value must be a valid identifier + if ( !ridentifier.test( lang || "" ) ) { + Sizzle.error( "unsupported lang: " + lang ); + } + lang = lang.replace( runescape, funescape ).toLowerCase(); + return function( elem ) { + var elemLang; + do { + if ( ( elemLang = documentIsHTML ? + elem.lang : + elem.getAttribute( "xml:lang" ) || elem.getAttribute( "lang" ) ) ) { + + elemLang = elemLang.toLowerCase(); + return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; + } + } while ( ( elem = elem.parentNode ) && elem.nodeType === 1 ); + return false; + }; + } ), + + // Miscellaneous + "target": function( elem ) { + var hash = window.location && window.location.hash; + return hash && hash.slice( 1 ) === elem.id; + }, + + "root": function( elem ) { + return elem === docElem; + }, + + "focus": function( elem ) { + return elem === document.activeElement && + ( !document.hasFocus || document.hasFocus() ) && + !!( elem.type || elem.href || ~elem.tabIndex ); + }, + + // Boolean properties + "enabled": createDisabledPseudo( false ), + "disabled": createDisabledPseudo( true ), + + "checked": function( elem ) { + + // In CSS3, :checked should return both checked and selected elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + var nodeName = elem.nodeName.toLowerCase(); + return ( nodeName === "input" && !!elem.checked ) || + ( nodeName === "option" && !!elem.selected ); + }, + + "selected": function( elem ) { + + // Accessing this property makes selected-by-default + // options in Safari work properly + if ( elem.parentNode ) { + // eslint-disable-next-line no-unused-expressions + elem.parentNode.selectedIndex; + } + + return elem.selected === true; + }, + + // Contents + "empty": function( elem ) { + + // http://www.w3.org/TR/selectors/#empty-pseudo + // :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5), + // but not by others (comment: 8; processing instruction: 7; etc.) + // nodeType < 6 works because attributes (2) do not appear as children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + if ( elem.nodeType < 6 ) { + return false; + } + } + return true; + }, + + "parent": function( elem ) { + return !Expr.pseudos[ "empty" ]( elem ); + }, + + // Element/input types + "header": function( elem ) { + return rheader.test( elem.nodeName ); + }, + + "input": function( elem ) { + return rinputs.test( elem.nodeName ); + }, + + "button": function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === "button" || name === "button"; + }, + + "text": function( elem ) { + var attr; + return elem.nodeName.toLowerCase() === "input" && + elem.type === "text" && + + // Support: IE<8 + // New HTML5 attribute values (e.g., "search") appear with elem.type === "text" + ( ( attr = elem.getAttribute( "type" ) ) == null || + attr.toLowerCase() === "text" ); + }, + + // Position-in-collection + "first": createPositionalPseudo( function() { + return [ 0 ]; + } ), + + "last": createPositionalPseudo( function( _matchIndexes, length ) { + return [ length - 1 ]; + } ), + + "eq": createPositionalPseudo( function( _matchIndexes, length, argument ) { + return [ argument < 0 ? argument + length : argument ]; + } ), + + "even": createPositionalPseudo( function( matchIndexes, length ) { + var i = 0; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "odd": createPositionalPseudo( function( matchIndexes, length ) { + var i = 1; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "lt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? + argument + length : + argument > length ? + length : + argument; + for ( ; --i >= 0; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "gt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? argument + length : argument; + for ( ; ++i < length; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ) + } +}; + +Expr.pseudos[ "nth" ] = Expr.pseudos[ "eq" ]; + +// Add button/input type pseudos +for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { + Expr.pseudos[ i ] = createInputPseudo( i ); +} +for ( i in { submit: true, reset: true } ) { + Expr.pseudos[ i ] = createButtonPseudo( i ); +} + +// Easy API for creating new setFilters +function setFilters() {} +setFilters.prototype = Expr.filters = Expr.pseudos; +Expr.setFilters = new setFilters(); + +tokenize = Sizzle.tokenize = function( selector, parseOnly ) { + var matched, match, tokens, type, + soFar, groups, preFilters, + cached = tokenCache[ selector + " " ]; + + if ( cached ) { + return parseOnly ? 0 : cached.slice( 0 ); + } + + soFar = selector; + groups = []; + preFilters = Expr.preFilter; + + while ( soFar ) { + + // Comma and first run + if ( !matched || ( match = rcomma.exec( soFar ) ) ) { + if ( match ) { + + // Don't consume trailing commas as valid + soFar = soFar.slice( match[ 0 ].length ) || soFar; + } + groups.push( ( tokens = [] ) ); + } + + matched = false; + + // Combinators + if ( ( match = rcombinators.exec( soFar ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + + // Cast descendant combinators to space + type: match[ 0 ].replace( rtrim, " " ) + } ); + soFar = soFar.slice( matched.length ); + } + + // Filters + for ( type in Expr.filter ) { + if ( ( match = matchExpr[ type ].exec( soFar ) ) && ( !preFilters[ type ] || + ( match = preFilters[ type ]( match ) ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + type: type, + matches: match + } ); + soFar = soFar.slice( matched.length ); + } + } + + if ( !matched ) { + break; + } + } + + // Return the length of the invalid excess + // if we're just parsing + // Otherwise, throw an error or return tokens + return parseOnly ? + soFar.length : + soFar ? + Sizzle.error( selector ) : + + // Cache the tokens + tokenCache( selector, groups ).slice( 0 ); +}; + +function toSelector( tokens ) { + var i = 0, + len = tokens.length, + selector = ""; + for ( ; i < len; i++ ) { + selector += tokens[ i ].value; + } + return selector; +} + +function addCombinator( matcher, combinator, base ) { + var dir = combinator.dir, + skip = combinator.next, + key = skip || dir, + checkNonElements = base && key === "parentNode", + doneName = done++; + + return combinator.first ? + + // Check against closest ancestor/preceding element + function( elem, context, xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + return matcher( elem, context, xml ); + } + } + return false; + } : + + // Check against all ancestor/preceding elements + function( elem, context, xml ) { + var oldCache, uniqueCache, outerCache, + newCache = [ dirruns, doneName ]; + + // We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching + if ( xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + if ( matcher( elem, context, xml ) ) { + return true; + } + } + } + } else { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + outerCache = elem[ expando ] || ( elem[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ elem.uniqueID ] || + ( outerCache[ elem.uniqueID ] = {} ); + + if ( skip && skip === elem.nodeName.toLowerCase() ) { + elem = elem[ dir ] || elem; + } else if ( ( oldCache = uniqueCache[ key ] ) && + oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { + + // Assign to newCache so results back-propagate to previous elements + return ( newCache[ 2 ] = oldCache[ 2 ] ); + } else { + + // Reuse newcache so results back-propagate to previous elements + uniqueCache[ key ] = newCache; + + // A match means we're done; a fail means we have to keep checking + if ( ( newCache[ 2 ] = matcher( elem, context, xml ) ) ) { + return true; + } + } + } + } + } + return false; + }; +} + +function elementMatcher( matchers ) { + return matchers.length > 1 ? + function( elem, context, xml ) { + var i = matchers.length; + while ( i-- ) { + if ( !matchers[ i ]( elem, context, xml ) ) { + return false; + } + } + return true; + } : + matchers[ 0 ]; +} + +function multipleContexts( selector, contexts, results ) { + var i = 0, + len = contexts.length; + for ( ; i < len; i++ ) { + Sizzle( selector, contexts[ i ], results ); + } + return results; +} + +function condense( unmatched, map, filter, context, xml ) { + var elem, + newUnmatched = [], + i = 0, + len = unmatched.length, + mapped = map != null; + + for ( ; i < len; i++ ) { + if ( ( elem = unmatched[ i ] ) ) { + if ( !filter || filter( elem, context, xml ) ) { + newUnmatched.push( elem ); + if ( mapped ) { + map.push( i ); + } + } + } + } + + return newUnmatched; +} + +function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { + if ( postFilter && !postFilter[ expando ] ) { + postFilter = setMatcher( postFilter ); + } + if ( postFinder && !postFinder[ expando ] ) { + postFinder = setMatcher( postFinder, postSelector ); + } + return markFunction( function( seed, results, context, xml ) { + var temp, i, elem, + preMap = [], + postMap = [], + preexisting = results.length, + + // Get initial elements from seed or context + elems = seed || multipleContexts( + selector || "*", + context.nodeType ? [ context ] : context, + [] + ), + + // Prefilter to get matcher input, preserving a map for seed-results synchronization + matcherIn = preFilter && ( seed || !selector ) ? + condense( elems, preMap, preFilter, context, xml ) : + elems, + + matcherOut = matcher ? + + // If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results, + postFinder || ( seed ? preFilter : preexisting || postFilter ) ? + + // ...intermediate processing is necessary + [] : + + // ...otherwise use results directly + results : + matcherIn; + + // Find primary matches + if ( matcher ) { + matcher( matcherIn, matcherOut, context, xml ); + } + + // Apply postFilter + if ( postFilter ) { + temp = condense( matcherOut, postMap ); + postFilter( temp, [], context, xml ); + + // Un-match failing elements by moving them back to matcherIn + i = temp.length; + while ( i-- ) { + if ( ( elem = temp[ i ] ) ) { + matcherOut[ postMap[ i ] ] = !( matcherIn[ postMap[ i ] ] = elem ); + } + } + } + + if ( seed ) { + if ( postFinder || preFilter ) { + if ( postFinder ) { + + // Get the final matcherOut by condensing this intermediate into postFinder contexts + temp = []; + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) ) { + + // Restore matcherIn since elem is not yet a final match + temp.push( ( matcherIn[ i ] = elem ) ); + } + } + postFinder( null, ( matcherOut = [] ), temp, xml ); + } + + // Move matched elements from seed to results to keep them synchronized + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) && + ( temp = postFinder ? indexOf( seed, elem ) : preMap[ i ] ) > -1 ) { + + seed[ temp ] = !( results[ temp ] = elem ); + } + } + } + + // Add elements to results, through postFinder if defined + } else { + matcherOut = condense( + matcherOut === results ? + matcherOut.splice( preexisting, matcherOut.length ) : + matcherOut + ); + if ( postFinder ) { + postFinder( null, results, matcherOut, xml ); + } else { + push.apply( results, matcherOut ); + } + } + } ); +} + +function matcherFromTokens( tokens ) { + var checkContext, matcher, j, + len = tokens.length, + leadingRelative = Expr.relative[ tokens[ 0 ].type ], + implicitRelative = leadingRelative || Expr.relative[ " " ], + i = leadingRelative ? 1 : 0, + + // The foundational matcher ensures that elements are reachable from top-level context(s) + matchContext = addCombinator( function( elem ) { + return elem === checkContext; + }, implicitRelative, true ), + matchAnyContext = addCombinator( function( elem ) { + return indexOf( checkContext, elem ) > -1; + }, implicitRelative, true ), + matchers = [ function( elem, context, xml ) { + var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( + ( checkContext = context ).nodeType ? + matchContext( elem, context, xml ) : + matchAnyContext( elem, context, xml ) ); + + // Avoid hanging onto element (issue #299) + checkContext = null; + return ret; + } ]; + + for ( ; i < len; i++ ) { + if ( ( matcher = Expr.relative[ tokens[ i ].type ] ) ) { + matchers = [ addCombinator( elementMatcher( matchers ), matcher ) ]; + } else { + matcher = Expr.filter[ tokens[ i ].type ].apply( null, tokens[ i ].matches ); + + // Return special upon seeing a positional matcher + if ( matcher[ expando ] ) { + + // Find the next relative operator (if any) for proper handling + j = ++i; + for ( ; j < len; j++ ) { + if ( Expr.relative[ tokens[ j ].type ] ) { + break; + } + } + return setMatcher( + i > 1 && elementMatcher( matchers ), + i > 1 && toSelector( + + // If the preceding token was a descendant combinator, insert an implicit any-element `*` + tokens + .slice( 0, i - 1 ) + .concat( { value: tokens[ i - 2 ].type === " " ? "*" : "" } ) + ).replace( rtrim, "$1" ), + matcher, + i < j && matcherFromTokens( tokens.slice( i, j ) ), + j < len && matcherFromTokens( ( tokens = tokens.slice( j ) ) ), + j < len && toSelector( tokens ) + ); + } + matchers.push( matcher ); + } + } + + return elementMatcher( matchers ); +} + +function matcherFromGroupMatchers( elementMatchers, setMatchers ) { + var bySet = setMatchers.length > 0, + byElement = elementMatchers.length > 0, + superMatcher = function( seed, context, xml, results, outermost ) { + var elem, j, matcher, + matchedCount = 0, + i = "0", + unmatched = seed && [], + setMatched = [], + contextBackup = outermostContext, + + // We must always have either seed elements or outermost context + elems = seed || byElement && Expr.find[ "TAG" ]( "*", outermost ), + + // Use integer dirruns iff this is the outermost matcher + dirrunsUnique = ( dirruns += contextBackup == null ? 1 : Math.random() || 0.1 ), + len = elems.length; + + if ( outermost ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + outermostContext = context == document || context || outermost; + } + + // Add elements passing elementMatchers directly to results + // Support: IE<9, Safari + // Tolerate NodeList properties (IE: "length"; Safari: ) matching elements by id + for ( ; i !== len && ( elem = elems[ i ] ) != null; i++ ) { + if ( byElement && elem ) { + j = 0; + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( !context && elem.ownerDocument != document ) { + setDocument( elem ); + xml = !documentIsHTML; + } + while ( ( matcher = elementMatchers[ j++ ] ) ) { + if ( matcher( elem, context || document, xml ) ) { + results.push( elem ); + break; + } + } + if ( outermost ) { + dirruns = dirrunsUnique; + } + } + + // Track unmatched elements for set filters + if ( bySet ) { + + // They will have gone through all possible matchers + if ( ( elem = !matcher && elem ) ) { + matchedCount--; + } + + // Lengthen the array for every element, matched or not + if ( seed ) { + unmatched.push( elem ); + } + } + } + + // `i` is now the count of elements visited above, and adding it to `matchedCount` + // makes the latter nonnegative. + matchedCount += i; + + // Apply set filters to unmatched elements + // NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount` + // equals `i`), unless we didn't visit _any_ elements in the above loop because we have + // no element matchers and no seed. + // Incrementing an initially-string "0" `i` allows `i` to remain a string only in that + // case, which will result in a "00" `matchedCount` that differs from `i` but is also + // numerically zero. + if ( bySet && i !== matchedCount ) { + j = 0; + while ( ( matcher = setMatchers[ j++ ] ) ) { + matcher( unmatched, setMatched, context, xml ); + } + + if ( seed ) { + + // Reintegrate element matches to eliminate the need for sorting + if ( matchedCount > 0 ) { + while ( i-- ) { + if ( !( unmatched[ i ] || setMatched[ i ] ) ) { + setMatched[ i ] = pop.call( results ); + } + } + } + + // Discard index placeholder values to get only actual matches + setMatched = condense( setMatched ); + } + + // Add matches to results + push.apply( results, setMatched ); + + // Seedless set matches succeeding multiple successful matchers stipulate sorting + if ( outermost && !seed && setMatched.length > 0 && + ( matchedCount + setMatchers.length ) > 1 ) { + + Sizzle.uniqueSort( results ); + } + } + + // Override manipulation of globals by nested matchers + if ( outermost ) { + dirruns = dirrunsUnique; + outermostContext = contextBackup; + } + + return unmatched; + }; + + return bySet ? + markFunction( superMatcher ) : + superMatcher; +} + +compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { + var i, + setMatchers = [], + elementMatchers = [], + cached = compilerCache[ selector + " " ]; + + if ( !cached ) { + + // Generate a function of recursive functions that can be used to check each element + if ( !match ) { + match = tokenize( selector ); + } + i = match.length; + while ( i-- ) { + cached = matcherFromTokens( match[ i ] ); + if ( cached[ expando ] ) { + setMatchers.push( cached ); + } else { + elementMatchers.push( cached ); + } + } + + // Cache the compiled function + cached = compilerCache( + selector, + matcherFromGroupMatchers( elementMatchers, setMatchers ) + ); + + // Save selector and tokenization + cached.selector = selector; + } + return cached; +}; + +/** + * A low-level selection function that works with Sizzle's compiled + * selector functions + * @param {String|Function} selector A selector or a pre-compiled + * selector function built with Sizzle.compile + * @param {Element} context + * @param {Array} [results] + * @param {Array} [seed] A set of elements to match against + */ +select = Sizzle.select = function( selector, context, results, seed ) { + var i, tokens, token, type, find, + compiled = typeof selector === "function" && selector, + match = !seed && tokenize( ( selector = compiled.selector || selector ) ); + + results = results || []; + + // Try to minimize operations if there is only one selector in the list and no seed + // (the latter of which guarantees us context) + if ( match.length === 1 ) { + + // Reduce context if the leading compound selector is an ID + tokens = match[ 0 ] = match[ 0 ].slice( 0 ); + if ( tokens.length > 2 && ( token = tokens[ 0 ] ).type === "ID" && + context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[ 1 ].type ] ) { + + context = ( Expr.find[ "ID" ]( token.matches[ 0 ] + .replace( runescape, funescape ), context ) || [] )[ 0 ]; + if ( !context ) { + return results; + + // Precompiled matchers will still verify ancestry, so step up a level + } else if ( compiled ) { + context = context.parentNode; + } + + selector = selector.slice( tokens.shift().value.length ); + } + + // Fetch a seed set for right-to-left matching + i = matchExpr[ "needsContext" ].test( selector ) ? 0 : tokens.length; + while ( i-- ) { + token = tokens[ i ]; + + // Abort if we hit a combinator + if ( Expr.relative[ ( type = token.type ) ] ) { + break; + } + if ( ( find = Expr.find[ type ] ) ) { + + // Search, expanding context for leading sibling combinators + if ( ( seed = find( + token.matches[ 0 ].replace( runescape, funescape ), + rsibling.test( tokens[ 0 ].type ) && testContext( context.parentNode ) || + context + ) ) ) { + + // If seed is empty or no tokens remain, we can return early + tokens.splice( i, 1 ); + selector = seed.length && toSelector( tokens ); + if ( !selector ) { + push.apply( results, seed ); + return results; + } + + break; + } + } + } + } + + // Compile and execute a filtering function if one is not provided + // Provide `match` to avoid retokenization if we modified the selector above + ( compiled || compile( selector, match ) )( + seed, + context, + !documentIsHTML, + results, + !context || rsibling.test( selector ) && testContext( context.parentNode ) || context + ); + return results; +}; + +// One-time assignments + +// Sort stability +support.sortStable = expando.split( "" ).sort( sortOrder ).join( "" ) === expando; + +// Support: Chrome 14-35+ +// Always assume duplicates if they aren't passed to the comparison function +support.detectDuplicates = !!hasDuplicate; + +// Initialize against the default document +setDocument(); + +// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27) +// Detached nodes confoundingly follow *each other* +support.sortDetached = assert( function( el ) { + + // Should return 1, but returns 4 (following) + return el.compareDocumentPosition( document.createElement( "fieldset" ) ) & 1; +} ); + +// Support: IE<8 +// Prevent attribute/property "interpolation" +// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx +if ( !assert( function( el ) { + el.innerHTML = ""; + return el.firstChild.getAttribute( "href" ) === "#"; +} ) ) { + addHandle( "type|href|height|width", function( elem, name, isXML ) { + if ( !isXML ) { + return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); + } + } ); +} + +// Support: IE<9 +// Use defaultValue in place of getAttribute("value") +if ( !support.attributes || !assert( function( el ) { + el.innerHTML = ""; + el.firstChild.setAttribute( "value", "" ); + return el.firstChild.getAttribute( "value" ) === ""; +} ) ) { + addHandle( "value", function( elem, _name, isXML ) { + if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { + return elem.defaultValue; + } + } ); +} + +// Support: IE<9 +// Use getAttributeNode to fetch booleans when getAttribute lies +if ( !assert( function( el ) { + return el.getAttribute( "disabled" ) == null; +} ) ) { + addHandle( booleans, function( elem, name, isXML ) { + var val; + if ( !isXML ) { + return elem[ name ] === true ? name.toLowerCase() : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; + } + } ); +} + +return Sizzle; + +} )( window ); + + + +jQuery.find = Sizzle; +jQuery.expr = Sizzle.selectors; + +// Deprecated +jQuery.expr[ ":" ] = jQuery.expr.pseudos; +jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort; +jQuery.text = Sizzle.getText; +jQuery.isXMLDoc = Sizzle.isXML; +jQuery.contains = Sizzle.contains; +jQuery.escapeSelector = Sizzle.escape; + + + + +var dir = function( elem, dir, until ) { + var matched = [], + truncate = until !== undefined; + + while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) { + if ( elem.nodeType === 1 ) { + if ( truncate && jQuery( elem ).is( until ) ) { + break; + } + matched.push( elem ); + } + } + return matched; +}; + + +var siblings = function( n, elem ) { + var matched = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType === 1 && n !== elem ) { + matched.push( n ); + } + } + + return matched; +}; + + +var rneedsContext = jQuery.expr.match.needsContext; + + + +function nodeName( elem, name ) { + + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + +} +var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i ); + + + +// Implement the identical functionality for filter and not +function winnow( elements, qualifier, not ) { + if ( isFunction( qualifier ) ) { + return jQuery.grep( elements, function( elem, i ) { + return !!qualifier.call( elem, i, elem ) !== not; + } ); + } + + // Single element + if ( qualifier.nodeType ) { + return jQuery.grep( elements, function( elem ) { + return ( elem === qualifier ) !== not; + } ); + } + + // Arraylike of elements (jQuery, arguments, Array) + if ( typeof qualifier !== "string" ) { + return jQuery.grep( elements, function( elem ) { + return ( indexOf.call( qualifier, elem ) > -1 ) !== not; + } ); + } + + // Filtered directly for both simple and complex selectors + return jQuery.filter( qualifier, elements, not ); +} + +jQuery.filter = function( expr, elems, not ) { + var elem = elems[ 0 ]; + + if ( not ) { + expr = ":not(" + expr + ")"; + } + + if ( elems.length === 1 && elem.nodeType === 1 ) { + return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : []; + } + + return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) { + return elem.nodeType === 1; + } ) ); +}; + +jQuery.fn.extend( { + find: function( selector ) { + var i, ret, + len = this.length, + self = this; + + if ( typeof selector !== "string" ) { + return this.pushStack( jQuery( selector ).filter( function() { + for ( i = 0; i < len; i++ ) { + if ( jQuery.contains( self[ i ], this ) ) { + return true; + } + } + } ) ); + } + + ret = this.pushStack( [] ); + + for ( i = 0; i < len; i++ ) { + jQuery.find( selector, self[ i ], ret ); + } + + return len > 1 ? jQuery.uniqueSort( ret ) : ret; + }, + filter: function( selector ) { + return this.pushStack( winnow( this, selector || [], false ) ); + }, + not: function( selector ) { + return this.pushStack( winnow( this, selector || [], true ) ); + }, + is: function( selector ) { + return !!winnow( + this, + + // If this is a positional/relative selector, check membership in the returned set + // so $("p:first").is("p:last") won't return true for a doc with two "p". + typeof selector === "string" && rneedsContext.test( selector ) ? + jQuery( selector ) : + selector || [], + false + ).length; + } +} ); + + +// Initialize a jQuery object + + +// A central reference to the root jQuery(document) +var rootjQuery, + + // A simple way to check for HTML strings + // Prioritize #id over to avoid XSS via location.hash (#9521) + // Strict HTML recognition (#11290: must start with <) + // Shortcut simple #id case for speed + rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/, + + init = jQuery.fn.init = function( selector, context, root ) { + var match, elem; + + // HANDLE: $(""), $(null), $(undefined), $(false) + if ( !selector ) { + return this; + } + + // Method init() accepts an alternate rootjQuery + // so migrate can support jQuery.sub (gh-2101) + root = root || rootjQuery; + + // Handle HTML strings + if ( typeof selector === "string" ) { + if ( selector[ 0 ] === "<" && + selector[ selector.length - 1 ] === ">" && + selector.length >= 3 ) { + + // Assume that strings that start and end with <> are HTML and skip the regex check + match = [ null, selector, null ]; + + } else { + match = rquickExpr.exec( selector ); + } + + // Match html or make sure no context is specified for #id + if ( match && ( match[ 1 ] || !context ) ) { + + // HANDLE: $(html) -> $(array) + if ( match[ 1 ] ) { + context = context instanceof jQuery ? context[ 0 ] : context; + + // Option to run scripts is true for back-compat + // Intentionally let the error be thrown if parseHTML is not present + jQuery.merge( this, jQuery.parseHTML( + match[ 1 ], + context && context.nodeType ? context.ownerDocument || context : document, + true + ) ); + + // HANDLE: $(html, props) + if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) { + for ( match in context ) { + + // Properties of context are called as methods if possible + if ( isFunction( this[ match ] ) ) { + this[ match ]( context[ match ] ); + + // ...and otherwise set as attributes + } else { + this.attr( match, context[ match ] ); + } + } + } + + return this; + + // HANDLE: $(#id) + } else { + elem = document.getElementById( match[ 2 ] ); + + if ( elem ) { + + // Inject the element directly into the jQuery object + this[ 0 ] = elem; + this.length = 1; + } + return this; + } + + // HANDLE: $(expr, $(...)) + } else if ( !context || context.jquery ) { + return ( context || root ).find( selector ); + + // HANDLE: $(expr, context) + // (which is just equivalent to: $(context).find(expr) + } else { + return this.constructor( context ).find( selector ); + } + + // HANDLE: $(DOMElement) + } else if ( selector.nodeType ) { + this[ 0 ] = selector; + this.length = 1; + return this; + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( isFunction( selector ) ) { + return root.ready !== undefined ? + root.ready( selector ) : + + // Execute immediately if ready is not present + selector( jQuery ); + } + + return jQuery.makeArray( selector, this ); + }; + +// Give the init function the jQuery prototype for later instantiation +init.prototype = jQuery.fn; + +// Initialize central reference +rootjQuery = jQuery( document ); + + +var rparentsprev = /^(?:parents|prev(?:Until|All))/, + + // Methods guaranteed to produce a unique set when starting from a unique set + guaranteedUnique = { + children: true, + contents: true, + next: true, + prev: true + }; + +jQuery.fn.extend( { + has: function( target ) { + var targets = jQuery( target, this ), + l = targets.length; + + return this.filter( function() { + var i = 0; + for ( ; i < l; i++ ) { + if ( jQuery.contains( this, targets[ i ] ) ) { + return true; + } + } + } ); + }, + + closest: function( selectors, context ) { + var cur, + i = 0, + l = this.length, + matched = [], + targets = typeof selectors !== "string" && jQuery( selectors ); + + // Positional selectors never match, since there's no _selection_ context + if ( !rneedsContext.test( selectors ) ) { + for ( ; i < l; i++ ) { + for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) { + + // Always skip document fragments + if ( cur.nodeType < 11 && ( targets ? + targets.index( cur ) > -1 : + + // Don't pass non-elements to Sizzle + cur.nodeType === 1 && + jQuery.find.matchesSelector( cur, selectors ) ) ) { + + matched.push( cur ); + break; + } + } + } + } + + return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched ); + }, + + // Determine the position of an element within the set + index: function( elem ) { + + // No argument, return index in parent + if ( !elem ) { + return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; + } + + // Index in selector + if ( typeof elem === "string" ) { + return indexOf.call( jQuery( elem ), this[ 0 ] ); + } + + // Locate the position of the desired element + return indexOf.call( this, + + // If it receives a jQuery object, the first element is used + elem.jquery ? elem[ 0 ] : elem + ); + }, + + add: function( selector, context ) { + return this.pushStack( + jQuery.uniqueSort( + jQuery.merge( this.get(), jQuery( selector, context ) ) + ) + ); + }, + + addBack: function( selector ) { + return this.add( selector == null ? + this.prevObject : this.prevObject.filter( selector ) + ); + } +} ); + +function sibling( cur, dir ) { + while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {} + return cur; +} + +jQuery.each( { + parent: function( elem ) { + var parent = elem.parentNode; + return parent && parent.nodeType !== 11 ? parent : null; + }, + parents: function( elem ) { + return dir( elem, "parentNode" ); + }, + parentsUntil: function( elem, _i, until ) { + return dir( elem, "parentNode", until ); + }, + next: function( elem ) { + return sibling( elem, "nextSibling" ); + }, + prev: function( elem ) { + return sibling( elem, "previousSibling" ); + }, + nextAll: function( elem ) { + return dir( elem, "nextSibling" ); + }, + prevAll: function( elem ) { + return dir( elem, "previousSibling" ); + }, + nextUntil: function( elem, _i, until ) { + return dir( elem, "nextSibling", until ); + }, + prevUntil: function( elem, _i, until ) { + return dir( elem, "previousSibling", until ); + }, + siblings: function( elem ) { + return siblings( ( elem.parentNode || {} ).firstChild, elem ); + }, + children: function( elem ) { + return siblings( elem.firstChild ); + }, + contents: function( elem ) { + if ( elem.contentDocument != null && + + // Support: IE 11+ + // elements with no `data` attribute has an object + // `contentDocument` with a `null` prototype. + getProto( elem.contentDocument ) ) { + + return elem.contentDocument; + } + + // Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only + // Treat the template element as a regular one in browsers that + // don't support it. + if ( nodeName( elem, "template" ) ) { + elem = elem.content || elem; + } + + return jQuery.merge( [], elem.childNodes ); + } +}, function( name, fn ) { + jQuery.fn[ name ] = function( until, selector ) { + var matched = jQuery.map( this, fn, until ); + + if ( name.slice( -5 ) !== "Until" ) { + selector = until; + } + + if ( selector && typeof selector === "string" ) { + matched = jQuery.filter( selector, matched ); + } + + if ( this.length > 1 ) { + + // Remove duplicates + if ( !guaranteedUnique[ name ] ) { + jQuery.uniqueSort( matched ); + } + + // Reverse order for parents* and prev-derivatives + if ( rparentsprev.test( name ) ) { + matched.reverse(); + } + } + + return this.pushStack( matched ); + }; +} ); +var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g ); + + + +// Convert String-formatted options into Object-formatted ones +function createOptions( options ) { + var object = {}; + jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) { + object[ flag ] = true; + } ); + return object; +} + +/* + * Create a callback list using the following parameters: + * + * options: an optional list of space-separated options that will change how + * the callback list behaves or a more traditional option object + * + * By default a callback list will act like an event callback list and can be + * "fired" multiple times. + * + * Possible options: + * + * once: will ensure the callback list can only be fired once (like a Deferred) + * + * memory: will keep track of previous values and will call any callback added + * after the list has been fired right away with the latest "memorized" + * values (like a Deferred) + * + * unique: will ensure a callback can only be added once (no duplicate in the list) + * + * stopOnFalse: interrupt callings when a callback returns false + * + */ +jQuery.Callbacks = function( options ) { + + // Convert options from String-formatted to Object-formatted if needed + // (we check in cache first) + options = typeof options === "string" ? + createOptions( options ) : + jQuery.extend( {}, options ); + + var // Flag to know if list is currently firing + firing, + + // Last fire value for non-forgettable lists + memory, + + // Flag to know if list was already fired + fired, + + // Flag to prevent firing + locked, + + // Actual callback list + list = [], + + // Queue of execution data for repeatable lists + queue = [], + + // Index of currently firing callback (modified by add/remove as needed) + firingIndex = -1, + + // Fire callbacks + fire = function() { + + // Enforce single-firing + locked = locked || options.once; + + // Execute callbacks for all pending executions, + // respecting firingIndex overrides and runtime changes + fired = firing = true; + for ( ; queue.length; firingIndex = -1 ) { + memory = queue.shift(); + while ( ++firingIndex < list.length ) { + + // Run callback and check for early termination + if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false && + options.stopOnFalse ) { + + // Jump to end and forget the data so .add doesn't re-fire + firingIndex = list.length; + memory = false; + } + } + } + + // Forget the data if we're done with it + if ( !options.memory ) { + memory = false; + } + + firing = false; + + // Clean up if we're done firing for good + if ( locked ) { + + // Keep an empty list if we have data for future add calls + if ( memory ) { + list = []; + + // Otherwise, this object is spent + } else { + list = ""; + } + } + }, + + // Actual Callbacks object + self = { + + // Add a callback or a collection of callbacks to the list + add: function() { + if ( list ) { + + // If we have memory from a past run, we should fire after adding + if ( memory && !firing ) { + firingIndex = list.length - 1; + queue.push( memory ); + } + + ( function add( args ) { + jQuery.each( args, function( _, arg ) { + if ( isFunction( arg ) ) { + if ( !options.unique || !self.has( arg ) ) { + list.push( arg ); + } + } else if ( arg && arg.length && toType( arg ) !== "string" ) { + + // Inspect recursively + add( arg ); + } + } ); + } )( arguments ); + + if ( memory && !firing ) { + fire(); + } + } + return this; + }, + + // Remove a callback from the list + remove: function() { + jQuery.each( arguments, function( _, arg ) { + var index; + while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) { + list.splice( index, 1 ); + + // Handle firing indexes + if ( index <= firingIndex ) { + firingIndex--; + } + } + } ); + return this; + }, + + // Check if a given callback is in the list. + // If no argument is given, return whether or not list has callbacks attached. + has: function( fn ) { + return fn ? + jQuery.inArray( fn, list ) > -1 : + list.length > 0; + }, + + // Remove all callbacks from the list + empty: function() { + if ( list ) { + list = []; + } + return this; + }, + + // Disable .fire and .add + // Abort any current/pending executions + // Clear all callbacks and values + disable: function() { + locked = queue = []; + list = memory = ""; + return this; + }, + disabled: function() { + return !list; + }, + + // Disable .fire + // Also disable .add unless we have memory (since it would have no effect) + // Abort any pending executions + lock: function() { + locked = queue = []; + if ( !memory && !firing ) { + list = memory = ""; + } + return this; + }, + locked: function() { + return !!locked; + }, + + // Call all callbacks with the given context and arguments + fireWith: function( context, args ) { + if ( !locked ) { + args = args || []; + args = [ context, args.slice ? args.slice() : args ]; + queue.push( args ); + if ( !firing ) { + fire(); + } + } + return this; + }, + + // Call all the callbacks with the given arguments + fire: function() { + self.fireWith( this, arguments ); + return this; + }, + + // To know if the callbacks have already been called at least once + fired: function() { + return !!fired; + } + }; + + return self; +}; + + +function Identity( v ) { + return v; +} +function Thrower( ex ) { + throw ex; +} + +function adoptValue( value, resolve, reject, noValue ) { + var method; + + try { + + // Check for promise aspect first to privilege synchronous behavior + if ( value && isFunction( ( method = value.promise ) ) ) { + method.call( value ).done( resolve ).fail( reject ); + + // Other thenables + } else if ( value && isFunction( ( method = value.then ) ) ) { + method.call( value, resolve, reject ); + + // Other non-thenables + } else { + + // Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer: + // * false: [ value ].slice( 0 ) => resolve( value ) + // * true: [ value ].slice( 1 ) => resolve() + resolve.apply( undefined, [ value ].slice( noValue ) ); + } + + // For Promises/A+, convert exceptions into rejections + // Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in + // Deferred#then to conditionally suppress rejection. + } catch ( value ) { + + // Support: Android 4.0 only + // Strict mode functions invoked without .call/.apply get global-object context + reject.apply( undefined, [ value ] ); + } +} + +jQuery.extend( { + + Deferred: function( func ) { + var tuples = [ + + // action, add listener, callbacks, + // ... .then handlers, argument index, [final state] + [ "notify", "progress", jQuery.Callbacks( "memory" ), + jQuery.Callbacks( "memory" ), 2 ], + [ "resolve", "done", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 0, "resolved" ], + [ "reject", "fail", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 1, "rejected" ] + ], + state = "pending", + promise = { + state: function() { + return state; + }, + always: function() { + deferred.done( arguments ).fail( arguments ); + return this; + }, + "catch": function( fn ) { + return promise.then( null, fn ); + }, + + // Keep pipe for back-compat + pipe: function( /* fnDone, fnFail, fnProgress */ ) { + var fns = arguments; + + return jQuery.Deferred( function( newDefer ) { + jQuery.each( tuples, function( _i, tuple ) { + + // Map tuples (progress, done, fail) to arguments (done, fail, progress) + var fn = isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ]; + + // deferred.progress(function() { bind to newDefer or newDefer.notify }) + // deferred.done(function() { bind to newDefer or newDefer.resolve }) + // deferred.fail(function() { bind to newDefer or newDefer.reject }) + deferred[ tuple[ 1 ] ]( function() { + var returned = fn && fn.apply( this, arguments ); + if ( returned && isFunction( returned.promise ) ) { + returned.promise() + .progress( newDefer.notify ) + .done( newDefer.resolve ) + .fail( newDefer.reject ); + } else { + newDefer[ tuple[ 0 ] + "With" ]( + this, + fn ? [ returned ] : arguments + ); + } + } ); + } ); + fns = null; + } ).promise(); + }, + then: function( onFulfilled, onRejected, onProgress ) { + var maxDepth = 0; + function resolve( depth, deferred, handler, special ) { + return function() { + var that = this, + args = arguments, + mightThrow = function() { + var returned, then; + + // Support: Promises/A+ section 2.3.3.3.3 + // https://promisesaplus.com/#point-59 + // Ignore double-resolution attempts + if ( depth < maxDepth ) { + return; + } + + returned = handler.apply( that, args ); + + // Support: Promises/A+ section 2.3.1 + // https://promisesaplus.com/#point-48 + if ( returned === deferred.promise() ) { + throw new TypeError( "Thenable self-resolution" ); + } + + // Support: Promises/A+ sections 2.3.3.1, 3.5 + // https://promisesaplus.com/#point-54 + // https://promisesaplus.com/#point-75 + // Retrieve `then` only once + then = returned && + + // Support: Promises/A+ section 2.3.4 + // https://promisesaplus.com/#point-64 + // Only check objects and functions for thenability + ( typeof returned === "object" || + typeof returned === "function" ) && + returned.then; + + // Handle a returned thenable + if ( isFunction( then ) ) { + + // Special processors (notify) just wait for resolution + if ( special ) { + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ) + ); + + // Normal processors (resolve) also hook into progress + } else { + + // ...and disregard older resolution values + maxDepth++; + + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ), + resolve( maxDepth, deferred, Identity, + deferred.notifyWith ) + ); + } + + // Handle all other returned values + } else { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Identity ) { + that = undefined; + args = [ returned ]; + } + + // Process the value(s) + // Default process is resolve + ( special || deferred.resolveWith )( that, args ); + } + }, + + // Only normal processors (resolve) catch and reject exceptions + process = special ? + mightThrow : + function() { + try { + mightThrow(); + } catch ( e ) { + + if ( jQuery.Deferred.exceptionHook ) { + jQuery.Deferred.exceptionHook( e, + process.stackTrace ); + } + + // Support: Promises/A+ section 2.3.3.3.4.1 + // https://promisesaplus.com/#point-61 + // Ignore post-resolution exceptions + if ( depth + 1 >= maxDepth ) { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Thrower ) { + that = undefined; + args = [ e ]; + } + + deferred.rejectWith( that, args ); + } + } + }; + + // Support: Promises/A+ section 2.3.3.3.1 + // https://promisesaplus.com/#point-57 + // Re-resolve promises immediately to dodge false rejection from + // subsequent errors + if ( depth ) { + process(); + } else { + + // Call an optional hook to record the stack, in case of exception + // since it's otherwise lost when execution goes async + if ( jQuery.Deferred.getStackHook ) { + process.stackTrace = jQuery.Deferred.getStackHook(); + } + window.setTimeout( process ); + } + }; + } + + return jQuery.Deferred( function( newDefer ) { + + // progress_handlers.add( ... ) + tuples[ 0 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onProgress ) ? + onProgress : + Identity, + newDefer.notifyWith + ) + ); + + // fulfilled_handlers.add( ... ) + tuples[ 1 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onFulfilled ) ? + onFulfilled : + Identity + ) + ); + + // rejected_handlers.add( ... ) + tuples[ 2 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onRejected ) ? + onRejected : + Thrower + ) + ); + } ).promise(); + }, + + // Get a promise for this deferred + // If obj is provided, the promise aspect is added to the object + promise: function( obj ) { + return obj != null ? jQuery.extend( obj, promise ) : promise; + } + }, + deferred = {}; + + // Add list-specific methods + jQuery.each( tuples, function( i, tuple ) { + var list = tuple[ 2 ], + stateString = tuple[ 5 ]; + + // promise.progress = list.add + // promise.done = list.add + // promise.fail = list.add + promise[ tuple[ 1 ] ] = list.add; + + // Handle state + if ( stateString ) { + list.add( + function() { + + // state = "resolved" (i.e., fulfilled) + // state = "rejected" + state = stateString; + }, + + // rejected_callbacks.disable + // fulfilled_callbacks.disable + tuples[ 3 - i ][ 2 ].disable, + + // rejected_handlers.disable + // fulfilled_handlers.disable + tuples[ 3 - i ][ 3 ].disable, + + // progress_callbacks.lock + tuples[ 0 ][ 2 ].lock, + + // progress_handlers.lock + tuples[ 0 ][ 3 ].lock + ); + } + + // progress_handlers.fire + // fulfilled_handlers.fire + // rejected_handlers.fire + list.add( tuple[ 3 ].fire ); + + // deferred.notify = function() { deferred.notifyWith(...) } + // deferred.resolve = function() { deferred.resolveWith(...) } + // deferred.reject = function() { deferred.rejectWith(...) } + deferred[ tuple[ 0 ] ] = function() { + deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments ); + return this; + }; + + // deferred.notifyWith = list.fireWith + // deferred.resolveWith = list.fireWith + // deferred.rejectWith = list.fireWith + deferred[ tuple[ 0 ] + "With" ] = list.fireWith; + } ); + + // Make the deferred a promise + promise.promise( deferred ); + + // Call given func if any + if ( func ) { + func.call( deferred, deferred ); + } + + // All done! + return deferred; + }, + + // Deferred helper + when: function( singleValue ) { + var + + // count of uncompleted subordinates + remaining = arguments.length, + + // count of unprocessed arguments + i = remaining, + + // subordinate fulfillment data + resolveContexts = Array( i ), + resolveValues = slice.call( arguments ), + + // the primary Deferred + primary = jQuery.Deferred(), + + // subordinate callback factory + updateFunc = function( i ) { + return function( value ) { + resolveContexts[ i ] = this; + resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value; + if ( !( --remaining ) ) { + primary.resolveWith( resolveContexts, resolveValues ); + } + }; + }; + + // Single- and empty arguments are adopted like Promise.resolve + if ( remaining <= 1 ) { + adoptValue( singleValue, primary.done( updateFunc( i ) ).resolve, primary.reject, + !remaining ); + + // Use .then() to unwrap secondary thenables (cf. gh-3000) + if ( primary.state() === "pending" || + isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) { + + return primary.then(); + } + } + + // Multiple arguments are aggregated like Promise.all array elements + while ( i-- ) { + adoptValue( resolveValues[ i ], updateFunc( i ), primary.reject ); + } + + return primary.promise(); + } +} ); + + +// These usually indicate a programmer mistake during development, +// warn about them ASAP rather than swallowing them by default. +var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/; + +jQuery.Deferred.exceptionHook = function( error, stack ) { + + // Support: IE 8 - 9 only + // Console exists when dev tools are open, which can happen at any time + if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) { + window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack ); + } +}; + + + + +jQuery.readyException = function( error ) { + window.setTimeout( function() { + throw error; + } ); +}; + + + + +// The deferred used on DOM ready +var readyList = jQuery.Deferred(); + +jQuery.fn.ready = function( fn ) { + + readyList + .then( fn ) + + // Wrap jQuery.readyException in a function so that the lookup + // happens at the time of error handling instead of callback + // registration. + .catch( function( error ) { + jQuery.readyException( error ); + } ); + + return this; +}; + +jQuery.extend( { + + // Is the DOM ready to be used? Set to true once it occurs. + isReady: false, + + // A counter to track how many items to wait for before + // the ready event fires. See #6781 + readyWait: 1, + + // Handle when the DOM is ready + ready: function( wait ) { + + // Abort if there are pending holds or we're already ready + if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) { + return; + } + + // Remember that the DOM is ready + jQuery.isReady = true; + + // If a normal DOM Ready event fired, decrement, and wait if need be + if ( wait !== true && --jQuery.readyWait > 0 ) { + return; + } + + // If there are functions bound, to execute + readyList.resolveWith( document, [ jQuery ] ); + } +} ); + +jQuery.ready.then = readyList.then; + +// The ready event handler and self cleanup method +function completed() { + document.removeEventListener( "DOMContentLoaded", completed ); + window.removeEventListener( "load", completed ); + jQuery.ready(); +} + +// Catch cases where $(document).ready() is called +// after the browser event has already occurred. +// Support: IE <=9 - 10 only +// Older IE sometimes signals "interactive" too soon +if ( document.readyState === "complete" || + ( document.readyState !== "loading" && !document.documentElement.doScroll ) ) { + + // Handle it asynchronously to allow scripts the opportunity to delay ready + window.setTimeout( jQuery.ready ); + +} else { + + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", completed ); + + // A fallback to window.onload, that will always work + window.addEventListener( "load", completed ); +} + + + + +// Multifunctional method to get and set values of a collection +// The value/s can optionally be executed if it's a function +var access = function( elems, fn, key, value, chainable, emptyGet, raw ) { + var i = 0, + len = elems.length, + bulk = key == null; + + // Sets many values + if ( toType( key ) === "object" ) { + chainable = true; + for ( i in key ) { + access( elems, fn, i, key[ i ], true, emptyGet, raw ); + } + + // Sets one value + } else if ( value !== undefined ) { + chainable = true; + + if ( !isFunction( value ) ) { + raw = true; + } + + if ( bulk ) { + + // Bulk operations run against the entire set + if ( raw ) { + fn.call( elems, value ); + fn = null; + + // ...except when executing function values + } else { + bulk = fn; + fn = function( elem, _key, value ) { + return bulk.call( jQuery( elem ), value ); + }; + } + } + + if ( fn ) { + for ( ; i < len; i++ ) { + fn( + elems[ i ], key, raw ? + value : + value.call( elems[ i ], i, fn( elems[ i ], key ) ) + ); + } + } + } + + if ( chainable ) { + return elems; + } + + // Gets + if ( bulk ) { + return fn.call( elems ); + } + + return len ? fn( elems[ 0 ], key ) : emptyGet; +}; + + +// Matches dashed string for camelizing +var rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g; + +// Used by camelCase as callback to replace() +function fcamelCase( _all, letter ) { + return letter.toUpperCase(); +} + +// Convert dashed to camelCase; used by the css and data modules +// Support: IE <=9 - 11, Edge 12 - 15 +// Microsoft forgot to hump their vendor prefix (#9572) +function camelCase( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); +} +var acceptData = function( owner ) { + + // Accepts only: + // - Node + // - Node.ELEMENT_NODE + // - Node.DOCUMENT_NODE + // - Object + // - Any + return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType ); +}; + + + + +function Data() { + this.expando = jQuery.expando + Data.uid++; +} + +Data.uid = 1; + +Data.prototype = { + + cache: function( owner ) { + + // Check if the owner object already has a cache + var value = owner[ this.expando ]; + + // If not, create one + if ( !value ) { + value = {}; + + // We can accept data for non-element nodes in modern browsers, + // but we should not, see #8335. + // Always return an empty object. + if ( acceptData( owner ) ) { + + // If it is a node unlikely to be stringify-ed or looped over + // use plain assignment + if ( owner.nodeType ) { + owner[ this.expando ] = value; + + // Otherwise secure it in a non-enumerable property + // configurable must be true to allow the property to be + // deleted when data is removed + } else { + Object.defineProperty( owner, this.expando, { + value: value, + configurable: true + } ); + } + } + } + + return value; + }, + set: function( owner, data, value ) { + var prop, + cache = this.cache( owner ); + + // Handle: [ owner, key, value ] args + // Always use camelCase key (gh-2257) + if ( typeof data === "string" ) { + cache[ camelCase( data ) ] = value; + + // Handle: [ owner, { properties } ] args + } else { + + // Copy the properties one-by-one to the cache object + for ( prop in data ) { + cache[ camelCase( prop ) ] = data[ prop ]; + } + } + return cache; + }, + get: function( owner, key ) { + return key === undefined ? + this.cache( owner ) : + + // Always use camelCase key (gh-2257) + owner[ this.expando ] && owner[ this.expando ][ camelCase( key ) ]; + }, + access: function( owner, key, value ) { + + // In cases where either: + // + // 1. No key was specified + // 2. A string key was specified, but no value provided + // + // Take the "read" path and allow the get method to determine + // which value to return, respectively either: + // + // 1. The entire cache object + // 2. The data stored at the key + // + if ( key === undefined || + ( ( key && typeof key === "string" ) && value === undefined ) ) { + + return this.get( owner, key ); + } + + // When the key is not a string, or both a key and value + // are specified, set or extend (existing objects) with either: + // + // 1. An object of properties + // 2. A key and value + // + this.set( owner, key, value ); + + // Since the "set" path can have two possible entry points + // return the expected data based on which path was taken[*] + return value !== undefined ? value : key; + }, + remove: function( owner, key ) { + var i, + cache = owner[ this.expando ]; + + if ( cache === undefined ) { + return; + } + + if ( key !== undefined ) { + + // Support array or space separated string of keys + if ( Array.isArray( key ) ) { + + // If key is an array of keys... + // We always set camelCase keys, so remove that. + key = key.map( camelCase ); + } else { + key = camelCase( key ); + + // If a key with the spaces exists, use it. + // Otherwise, create an array by matching non-whitespace + key = key in cache ? + [ key ] : + ( key.match( rnothtmlwhite ) || [] ); + } + + i = key.length; + + while ( i-- ) { + delete cache[ key[ i ] ]; + } + } + + // Remove the expando if there's no more data + if ( key === undefined || jQuery.isEmptyObject( cache ) ) { + + // Support: Chrome <=35 - 45 + // Webkit & Blink performance suffers when deleting properties + // from DOM nodes, so set to undefined instead + // https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted) + if ( owner.nodeType ) { + owner[ this.expando ] = undefined; + } else { + delete owner[ this.expando ]; + } + } + }, + hasData: function( owner ) { + var cache = owner[ this.expando ]; + return cache !== undefined && !jQuery.isEmptyObject( cache ); + } +}; +var dataPriv = new Data(); + +var dataUser = new Data(); + + + +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + +var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, + rmultiDash = /[A-Z]/g; + +function getData( data ) { + if ( data === "true" ) { + return true; + } + + if ( data === "false" ) { + return false; + } + + if ( data === "null" ) { + return null; + } + + // Only convert to a number if it doesn't change the string + if ( data === +data + "" ) { + return +data; + } + + if ( rbrace.test( data ) ) { + return JSON.parse( data ); + } + + return data; +} + +function dataAttr( elem, key, data ) { + var name; + + // If nothing was found internally, try to fetch any + // data from the HTML5 data-* attribute + if ( data === undefined && elem.nodeType === 1 ) { + name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase(); + data = elem.getAttribute( name ); + + if ( typeof data === "string" ) { + try { + data = getData( data ); + } catch ( e ) {} + + // Make sure we set the data so it isn't changed later + dataUser.set( elem, key, data ); + } else { + data = undefined; + } + } + return data; +} + +jQuery.extend( { + hasData: function( elem ) { + return dataUser.hasData( elem ) || dataPriv.hasData( elem ); + }, + + data: function( elem, name, data ) { + return dataUser.access( elem, name, data ); + }, + + removeData: function( elem, name ) { + dataUser.remove( elem, name ); + }, + + // TODO: Now that all calls to _data and _removeData have been replaced + // with direct calls to dataPriv methods, these can be deprecated. + _data: function( elem, name, data ) { + return dataPriv.access( elem, name, data ); + }, + + _removeData: function( elem, name ) { + dataPriv.remove( elem, name ); + } +} ); + +jQuery.fn.extend( { + data: function( key, value ) { + var i, name, data, + elem = this[ 0 ], + attrs = elem && elem.attributes; + + // Gets all values + if ( key === undefined ) { + if ( this.length ) { + data = dataUser.get( elem ); + + if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) { + i = attrs.length; + while ( i-- ) { + + // Support: IE 11 only + // The attrs elements can be null (#14894) + if ( attrs[ i ] ) { + name = attrs[ i ].name; + if ( name.indexOf( "data-" ) === 0 ) { + name = camelCase( name.slice( 5 ) ); + dataAttr( elem, name, data[ name ] ); + } + } + } + dataPriv.set( elem, "hasDataAttrs", true ); + } + } + + return data; + } + + // Sets multiple values + if ( typeof key === "object" ) { + return this.each( function() { + dataUser.set( this, key ); + } ); + } + + return access( this, function( value ) { + var data; + + // The calling jQuery object (element matches) is not empty + // (and therefore has an element appears at this[ 0 ]) and the + // `value` parameter was not undefined. An empty jQuery object + // will result in `undefined` for elem = this[ 0 ] which will + // throw an exception if an attempt to read a data cache is made. + if ( elem && value === undefined ) { + + // Attempt to get data from the cache + // The key will always be camelCased in Data + data = dataUser.get( elem, key ); + if ( data !== undefined ) { + return data; + } + + // Attempt to "discover" the data in + // HTML5 custom data-* attrs + data = dataAttr( elem, key ); + if ( data !== undefined ) { + return data; + } + + // We tried really hard, but the data doesn't exist. + return; + } + + // Set the data... + this.each( function() { + + // We always store the camelCased key + dataUser.set( this, key, value ); + } ); + }, null, value, arguments.length > 1, null, true ); + }, + + removeData: function( key ) { + return this.each( function() { + dataUser.remove( this, key ); + } ); + } +} ); + + +jQuery.extend( { + queue: function( elem, type, data ) { + var queue; + + if ( elem ) { + type = ( type || "fx" ) + "queue"; + queue = dataPriv.get( elem, type ); + + // Speed up dequeue by getting out quickly if this is just a lookup + if ( data ) { + if ( !queue || Array.isArray( data ) ) { + queue = dataPriv.access( elem, type, jQuery.makeArray( data ) ); + } else { + queue.push( data ); + } + } + return queue || []; + } + }, + + dequeue: function( elem, type ) { + type = type || "fx"; + + var queue = jQuery.queue( elem, type ), + startLength = queue.length, + fn = queue.shift(), + hooks = jQuery._queueHooks( elem, type ), + next = function() { + jQuery.dequeue( elem, type ); + }; + + // If the fx queue is dequeued, always remove the progress sentinel + if ( fn === "inprogress" ) { + fn = queue.shift(); + startLength--; + } + + if ( fn ) { + + // Add a progress sentinel to prevent the fx queue from being + // automatically dequeued + if ( type === "fx" ) { + queue.unshift( "inprogress" ); + } + + // Clear up the last queue stop function + delete hooks.stop; + fn.call( elem, next, hooks ); + } + + if ( !startLength && hooks ) { + hooks.empty.fire(); + } + }, + + // Not public - generate a queueHooks object, or return the current one + _queueHooks: function( elem, type ) { + var key = type + "queueHooks"; + return dataPriv.get( elem, key ) || dataPriv.access( elem, key, { + empty: jQuery.Callbacks( "once memory" ).add( function() { + dataPriv.remove( elem, [ type + "queue", key ] ); + } ) + } ); + } +} ); + +jQuery.fn.extend( { + queue: function( type, data ) { + var setter = 2; + + if ( typeof type !== "string" ) { + data = type; + type = "fx"; + setter--; + } + + if ( arguments.length < setter ) { + return jQuery.queue( this[ 0 ], type ); + } + + return data === undefined ? + this : + this.each( function() { + var queue = jQuery.queue( this, type, data ); + + // Ensure a hooks for this queue + jQuery._queueHooks( this, type ); + + if ( type === "fx" && queue[ 0 ] !== "inprogress" ) { + jQuery.dequeue( this, type ); + } + } ); + }, + dequeue: function( type ) { + return this.each( function() { + jQuery.dequeue( this, type ); + } ); + }, + clearQueue: function( type ) { + return this.queue( type || "fx", [] ); + }, + + // Get a promise resolved when queues of a certain type + // are emptied (fx is the type by default) + promise: function( type, obj ) { + var tmp, + count = 1, + defer = jQuery.Deferred(), + elements = this, + i = this.length, + resolve = function() { + if ( !( --count ) ) { + defer.resolveWith( elements, [ elements ] ); + } + }; + + if ( typeof type !== "string" ) { + obj = type; + type = undefined; + } + type = type || "fx"; + + while ( i-- ) { + tmp = dataPriv.get( elements[ i ], type + "queueHooks" ); + if ( tmp && tmp.empty ) { + count++; + tmp.empty.add( resolve ); + } + } + resolve(); + return defer.promise( obj ); + } +} ); +var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source; + +var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" ); + + +var cssExpand = [ "Top", "Right", "Bottom", "Left" ]; + +var documentElement = document.documentElement; + + + + var isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ); + }, + composed = { composed: true }; + + // Support: IE 9 - 11+, Edge 12 - 18+, iOS 10.0 - 10.2 only + // Check attachment across shadow DOM boundaries when possible (gh-3504) + // Support: iOS 10.0-10.2 only + // Early iOS 10 versions support `attachShadow` but not `getRootNode`, + // leading to errors. We need to check for `getRootNode`. + if ( documentElement.getRootNode ) { + isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ) || + elem.getRootNode( composed ) === elem.ownerDocument; + }; + } +var isHiddenWithinTree = function( elem, el ) { + + // isHiddenWithinTree might be called from jQuery#filter function; + // in that case, element will be second argument + elem = el || elem; + + // Inline style trumps all + return elem.style.display === "none" || + elem.style.display === "" && + + // Otherwise, check computed style + // Support: Firefox <=43 - 45 + // Disconnected elements can have computed display: none, so first confirm that elem is + // in the document. + isAttached( elem ) && + + jQuery.css( elem, "display" ) === "none"; + }; + + + +function adjustCSS( elem, prop, valueParts, tween ) { + var adjusted, scale, + maxIterations = 20, + currentValue = tween ? + function() { + return tween.cur(); + } : + function() { + return jQuery.css( elem, prop, "" ); + }, + initial = currentValue(), + unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ), + + // Starting value computation is required for potential unit mismatches + initialInUnit = elem.nodeType && + ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) && + rcssNum.exec( jQuery.css( elem, prop ) ); + + if ( initialInUnit && initialInUnit[ 3 ] !== unit ) { + + // Support: Firefox <=54 + // Halve the iteration target value to prevent interference from CSS upper bounds (gh-2144) + initial = initial / 2; + + // Trust units reported by jQuery.css + unit = unit || initialInUnit[ 3 ]; + + // Iteratively approximate from a nonzero starting point + initialInUnit = +initial || 1; + + while ( maxIterations-- ) { + + // Evaluate and update our best guess (doubling guesses that zero out). + // Finish if the scale equals or crosses 1 (making the old*new product non-positive). + jQuery.style( elem, prop, initialInUnit + unit ); + if ( ( 1 - scale ) * ( 1 - ( scale = currentValue() / initial || 0.5 ) ) <= 0 ) { + maxIterations = 0; + } + initialInUnit = initialInUnit / scale; + + } + + initialInUnit = initialInUnit * 2; + jQuery.style( elem, prop, initialInUnit + unit ); + + // Make sure we update the tween properties later on + valueParts = valueParts || []; + } + + if ( valueParts ) { + initialInUnit = +initialInUnit || +initial || 0; + + // Apply relative offset (+=/-=) if specified + adjusted = valueParts[ 1 ] ? + initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] : + +valueParts[ 2 ]; + if ( tween ) { + tween.unit = unit; + tween.start = initialInUnit; + tween.end = adjusted; + } + } + return adjusted; +} + + +var defaultDisplayMap = {}; + +function getDefaultDisplay( elem ) { + var temp, + doc = elem.ownerDocument, + nodeName = elem.nodeName, + display = defaultDisplayMap[ nodeName ]; + + if ( display ) { + return display; + } + + temp = doc.body.appendChild( doc.createElement( nodeName ) ); + display = jQuery.css( temp, "display" ); + + temp.parentNode.removeChild( temp ); + + if ( display === "none" ) { + display = "block"; + } + defaultDisplayMap[ nodeName ] = display; + + return display; +} + +function showHide( elements, show ) { + var display, elem, + values = [], + index = 0, + length = elements.length; + + // Determine new display value for elements that need to change + for ( ; index < length; index++ ) { + elem = elements[ index ]; + if ( !elem.style ) { + continue; + } + + display = elem.style.display; + if ( show ) { + + // Since we force visibility upon cascade-hidden elements, an immediate (and slow) + // check is required in this first loop unless we have a nonempty display value (either + // inline or about-to-be-restored) + if ( display === "none" ) { + values[ index ] = dataPriv.get( elem, "display" ) || null; + if ( !values[ index ] ) { + elem.style.display = ""; + } + } + if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) { + values[ index ] = getDefaultDisplay( elem ); + } + } else { + if ( display !== "none" ) { + values[ index ] = "none"; + + // Remember what we're overwriting + dataPriv.set( elem, "display", display ); + } + } + } + + // Set the display of the elements in a second loop to avoid constant reflow + for ( index = 0; index < length; index++ ) { + if ( values[ index ] != null ) { + elements[ index ].style.display = values[ index ]; + } + } + + return elements; +} + +jQuery.fn.extend( { + show: function() { + return showHide( this, true ); + }, + hide: function() { + return showHide( this ); + }, + toggle: function( state ) { + if ( typeof state === "boolean" ) { + return state ? this.show() : this.hide(); + } + + return this.each( function() { + if ( isHiddenWithinTree( this ) ) { + jQuery( this ).show(); + } else { + jQuery( this ).hide(); + } + } ); + } +} ); +var rcheckableType = ( /^(?:checkbox|radio)$/i ); + +var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]*)/i ); + +var rscriptType = ( /^$|^module$|\/(?:java|ecma)script/i ); + + + +( function() { + var fragment = document.createDocumentFragment(), + div = fragment.appendChild( document.createElement( "div" ) ), + input = document.createElement( "input" ); + + // Support: Android 4.0 - 4.3 only + // Check state lost if the name is set (#11217) + // Support: Windows Web Apps (WWA) + // `name` and `type` must use .setAttribute for WWA (#14901) + input.setAttribute( "type", "radio" ); + input.setAttribute( "checked", "checked" ); + input.setAttribute( "name", "t" ); + + div.appendChild( input ); + + // Support: Android <=4.1 only + // Older WebKit doesn't clone checked state correctly in fragments + support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + + // Support: IE <=11 only + // Make sure textarea (and checkbox) defaultValue is properly cloned + div.innerHTML = ""; + support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; + + // Support: IE <=9 only + // IE <=9 replaces "; + support.option = !!div.lastChild; +} )(); + + +// We have to close these tags to support XHTML (#13200) +var wrapMap = { + + // XHTML parsers do not magically insert elements in the + // same way that tag soup parsers do. So we cannot shorten + // this by omitting or other required elements. + thead: [ 1, "", "
" ], + col: [ 2, "", "
" ], + tr: [ 2, "", "
" ], + td: [ 3, "", "
" ], + + _default: [ 0, "", "" ] +}; + +wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; +wrapMap.th = wrapMap.td; + +// Support: IE <=9 only +if ( !support.option ) { + wrapMap.optgroup = wrapMap.option = [ 1, "" ]; +} + + +function getAll( context, tag ) { + + // Support: IE <=9 - 11 only + // Use typeof to avoid zero-argument method invocation on host objects (#15151) + var ret; + + if ( typeof context.getElementsByTagName !== "undefined" ) { + ret = context.getElementsByTagName( tag || "*" ); + + } else if ( typeof context.querySelectorAll !== "undefined" ) { + ret = context.querySelectorAll( tag || "*" ); + + } else { + ret = []; + } + + if ( tag === undefined || tag && nodeName( context, tag ) ) { + return jQuery.merge( [ context ], ret ); + } + + return ret; +} + + +// Mark scripts as having already been evaluated +function setGlobalEval( elems, refElements ) { + var i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + dataPriv.set( + elems[ i ], + "globalEval", + !refElements || dataPriv.get( refElements[ i ], "globalEval" ) + ); + } +} + + +var rhtml = /<|&#?\w+;/; + +function buildFragment( elems, context, scripts, selection, ignored ) { + var elem, tmp, tag, wrap, attached, j, + fragment = context.createDocumentFragment(), + nodes = [], + i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + elem = elems[ i ]; + + if ( elem || elem === 0 ) { + + // Add nodes directly + if ( toType( elem ) === "object" ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); + + // Convert non-html into a text node + } else if ( !rhtml.test( elem ) ) { + nodes.push( context.createTextNode( elem ) ); + + // Convert html into DOM nodes + } else { + tmp = tmp || fragment.appendChild( context.createElement( "div" ) ); + + // Deserialize a standard representation + tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase(); + wrap = wrapMap[ tag ] || wrapMap._default; + tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ]; + + // Descend through wrappers to the right content + j = wrap[ 0 ]; + while ( j-- ) { + tmp = tmp.lastChild; + } + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, tmp.childNodes ); + + // Remember the top-level container + tmp = fragment.firstChild; + + // Ensure the created nodes are orphaned (#12392) + tmp.textContent = ""; + } + } + } + + // Remove wrapper from fragment + fragment.textContent = ""; + + i = 0; + while ( ( elem = nodes[ i++ ] ) ) { + + // Skip elements already in the context collection (trac-4087) + if ( selection && jQuery.inArray( elem, selection ) > -1 ) { + if ( ignored ) { + ignored.push( elem ); + } + continue; + } + + attached = isAttached( elem ); + + // Append to fragment + tmp = getAll( fragment.appendChild( elem ), "script" ); + + // Preserve script evaluation history + if ( attached ) { + setGlobalEval( tmp ); + } + + // Capture executables + if ( scripts ) { + j = 0; + while ( ( elem = tmp[ j++ ] ) ) { + if ( rscriptType.test( elem.type || "" ) ) { + scripts.push( elem ); + } + } + } + } + + return fragment; +} + + +var rtypenamespace = /^([^.]*)(?:\.(.+)|)/; + +function returnTrue() { + return true; +} + +function returnFalse() { + return false; +} + +// Support: IE <=9 - 11+ +// focus() and blur() are asynchronous, except when they are no-op. +// So expect focus to be synchronous when the element is already active, +// and blur to be synchronous when the element is not already active. +// (focus and blur are always synchronous in other supported browsers, +// this just defines when we can count on it). +function expectSync( elem, type ) { + return ( elem === safeActiveElement() ) === ( type === "focus" ); +} + +// Support: IE <=9 only +// Accessing document.activeElement can throw unexpectedly +// https://bugs.jquery.com/ticket/13393 +function safeActiveElement() { + try { + return document.activeElement; + } catch ( err ) { } +} + +function on( elem, types, selector, data, fn, one ) { + var origFn, type; + + // Types can be a map of types/handlers + if ( typeof types === "object" ) { + + // ( types-Object, selector, data ) + if ( typeof selector !== "string" ) { + + // ( types-Object, data ) + data = data || selector; + selector = undefined; + } + for ( type in types ) { + on( elem, type, selector, data, types[ type ], one ); + } + return elem; + } + + if ( data == null && fn == null ) { + + // ( types, fn ) + fn = selector; + data = selector = undefined; + } else if ( fn == null ) { + if ( typeof selector === "string" ) { + + // ( types, selector, fn ) + fn = data; + data = undefined; + } else { + + // ( types, data, fn ) + fn = data; + data = selector; + selector = undefined; + } + } + if ( fn === false ) { + fn = returnFalse; + } else if ( !fn ) { + return elem; + } + + if ( one === 1 ) { + origFn = fn; + fn = function( event ) { + + // Can use an empty set, since event contains the info + jQuery().off( event ); + return origFn.apply( this, arguments ); + }; + + // Use same guid so caller can remove using origFn + fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ ); + } + return elem.each( function() { + jQuery.event.add( this, types, fn, data, selector ); + } ); +} + +/* + * Helper functions for managing events -- not part of the public interface. + * Props to Dean Edwards' addEvent library for many of the ideas. + */ +jQuery.event = { + + global: {}, + + add: function( elem, types, handler, data, selector ) { + + var handleObjIn, eventHandle, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.get( elem ); + + // Only attach events to objects that accept data + if ( !acceptData( elem ) ) { + return; + } + + // Caller can pass in an object of custom data in lieu of the handler + if ( handler.handler ) { + handleObjIn = handler; + handler = handleObjIn.handler; + selector = handleObjIn.selector; + } + + // Ensure that invalid selectors throw exceptions at attach time + // Evaluate against documentElement in case elem is a non-element node (e.g., document) + if ( selector ) { + jQuery.find.matchesSelector( documentElement, selector ); + } + + // Make sure that the handler has a unique ID, used to find/remove it later + if ( !handler.guid ) { + handler.guid = jQuery.guid++; + } + + // Init the element's event structure and main handler, if this is the first + if ( !( events = elemData.events ) ) { + events = elemData.events = Object.create( null ); + } + if ( !( eventHandle = elemData.handle ) ) { + eventHandle = elemData.handle = function( e ) { + + // Discard the second event of a jQuery.event.trigger() and + // when an event is called after a page has unloaded + return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ? + jQuery.event.dispatch.apply( elem, arguments ) : undefined; + }; + } + + // Handle multiple events separated by a space + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // There *must* be a type, no attaching namespace-only handlers + if ( !type ) { + continue; + } + + // If event changes its type, use the special event handlers for the changed type + special = jQuery.event.special[ type ] || {}; + + // If selector defined, determine special event api type, otherwise given type + type = ( selector ? special.delegateType : special.bindType ) || type; + + // Update special based on newly reset type + special = jQuery.event.special[ type ] || {}; + + // handleObj is passed to all event handlers + handleObj = jQuery.extend( { + type: type, + origType: origType, + data: data, + handler: handler, + guid: handler.guid, + selector: selector, + needsContext: selector && jQuery.expr.match.needsContext.test( selector ), + namespace: namespaces.join( "." ) + }, handleObjIn ); + + // Init the event handler queue if we're the first + if ( !( handlers = events[ type ] ) ) { + handlers = events[ type ] = []; + handlers.delegateCount = 0; + + // Only use addEventListener if the special events handler returns false + if ( !special.setup || + special.setup.call( elem, data, namespaces, eventHandle ) === false ) { + + if ( elem.addEventListener ) { + elem.addEventListener( type, eventHandle ); + } + } + } + + if ( special.add ) { + special.add.call( elem, handleObj ); + + if ( !handleObj.handler.guid ) { + handleObj.handler.guid = handler.guid; + } + } + + // Add to the element's handler list, delegates in front + if ( selector ) { + handlers.splice( handlers.delegateCount++, 0, handleObj ); + } else { + handlers.push( handleObj ); + } + + // Keep track of which events have ever been used, for event optimization + jQuery.event.global[ type ] = true; + } + + }, + + // Detach an event or set of events from an element + remove: function( elem, types, handler, selector, mappedTypes ) { + + var j, origCount, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.hasData( elem ) && dataPriv.get( elem ); + + if ( !elemData || !( events = elemData.events ) ) { + return; + } + + // Once for each type.namespace in types; type may be omitted + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // Unbind all events (on this namespace, if provided) for the element + if ( !type ) { + for ( type in events ) { + jQuery.event.remove( elem, type + types[ t ], handler, selector, true ); + } + continue; + } + + special = jQuery.event.special[ type ] || {}; + type = ( selector ? special.delegateType : special.bindType ) || type; + handlers = events[ type ] || []; + tmp = tmp[ 2 ] && + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ); + + // Remove matching events + origCount = j = handlers.length; + while ( j-- ) { + handleObj = handlers[ j ]; + + if ( ( mappedTypes || origType === handleObj.origType ) && + ( !handler || handler.guid === handleObj.guid ) && + ( !tmp || tmp.test( handleObj.namespace ) ) && + ( !selector || selector === handleObj.selector || + selector === "**" && handleObj.selector ) ) { + handlers.splice( j, 1 ); + + if ( handleObj.selector ) { + handlers.delegateCount--; + } + if ( special.remove ) { + special.remove.call( elem, handleObj ); + } + } + } + + // Remove generic event handler if we removed something and no more handlers exist + // (avoids potential for endless recursion during removal of special event handlers) + if ( origCount && !handlers.length ) { + if ( !special.teardown || + special.teardown.call( elem, namespaces, elemData.handle ) === false ) { + + jQuery.removeEvent( elem, type, elemData.handle ); + } + + delete events[ type ]; + } + } + + // Remove data and the expando if it's no longer used + if ( jQuery.isEmptyObject( events ) ) { + dataPriv.remove( elem, "handle events" ); + } + }, + + dispatch: function( nativeEvent ) { + + var i, j, ret, matched, handleObj, handlerQueue, + args = new Array( arguments.length ), + + // Make a writable jQuery.Event from the native event object + event = jQuery.event.fix( nativeEvent ), + + handlers = ( + dataPriv.get( this, "events" ) || Object.create( null ) + )[ event.type ] || [], + special = jQuery.event.special[ event.type ] || {}; + + // Use the fix-ed jQuery.Event rather than the (read-only) native event + args[ 0 ] = event; + + for ( i = 1; i < arguments.length; i++ ) { + args[ i ] = arguments[ i ]; + } + + event.delegateTarget = this; + + // Call the preDispatch hook for the mapped type, and let it bail if desired + if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) { + return; + } + + // Determine handlers + handlerQueue = jQuery.event.handlers.call( this, event, handlers ); + + // Run delegates first; they may want to stop propagation beneath us + i = 0; + while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) { + event.currentTarget = matched.elem; + + j = 0; + while ( ( handleObj = matched.handlers[ j++ ] ) && + !event.isImmediatePropagationStopped() ) { + + // If the event is namespaced, then each handler is only invoked if it is + // specially universal or its namespaces are a superset of the event's. + if ( !event.rnamespace || handleObj.namespace === false || + event.rnamespace.test( handleObj.namespace ) ) { + + event.handleObj = handleObj; + event.data = handleObj.data; + + ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle || + handleObj.handler ).apply( matched.elem, args ); + + if ( ret !== undefined ) { + if ( ( event.result = ret ) === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + } + } + } + + // Call the postDispatch hook for the mapped type + if ( special.postDispatch ) { + special.postDispatch.call( this, event ); + } + + return event.result; + }, + + handlers: function( event, handlers ) { + var i, handleObj, sel, matchedHandlers, matchedSelectors, + handlerQueue = [], + delegateCount = handlers.delegateCount, + cur = event.target; + + // Find delegate handlers + if ( delegateCount && + + // Support: IE <=9 + // Black-hole SVG instance trees (trac-13180) + cur.nodeType && + + // Support: Firefox <=42 + // Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861) + // https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click + // Support: IE 11 only + // ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343) + !( event.type === "click" && event.button >= 1 ) ) { + + for ( ; cur !== this; cur = cur.parentNode || this ) { + + // Don't check non-elements (#13208) + // Don't process clicks on disabled elements (#6911, #8165, #11382, #11764) + if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) { + matchedHandlers = []; + matchedSelectors = {}; + for ( i = 0; i < delegateCount; i++ ) { + handleObj = handlers[ i ]; + + // Don't conflict with Object.prototype properties (#13203) + sel = handleObj.selector + " "; + + if ( matchedSelectors[ sel ] === undefined ) { + matchedSelectors[ sel ] = handleObj.needsContext ? + jQuery( sel, this ).index( cur ) > -1 : + jQuery.find( sel, this, null, [ cur ] ).length; + } + if ( matchedSelectors[ sel ] ) { + matchedHandlers.push( handleObj ); + } + } + if ( matchedHandlers.length ) { + handlerQueue.push( { elem: cur, handlers: matchedHandlers } ); + } + } + } + } + + // Add the remaining (directly-bound) handlers + cur = this; + if ( delegateCount < handlers.length ) { + handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } ); + } + + return handlerQueue; + }, + + addProp: function( name, hook ) { + Object.defineProperty( jQuery.Event.prototype, name, { + enumerable: true, + configurable: true, + + get: isFunction( hook ) ? + function() { + if ( this.originalEvent ) { + return hook( this.originalEvent ); + } + } : + function() { + if ( this.originalEvent ) { + return this.originalEvent[ name ]; + } + }, + + set: function( value ) { + Object.defineProperty( this, name, { + enumerable: true, + configurable: true, + writable: true, + value: value + } ); + } + } ); + }, + + fix: function( originalEvent ) { + return originalEvent[ jQuery.expando ] ? + originalEvent : + new jQuery.Event( originalEvent ); + }, + + special: { + load: { + + // Prevent triggered image.load events from bubbling to window.load + noBubble: true + }, + click: { + + // Utilize native event to ensure correct state for checkable inputs + setup: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Claim the first handler + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + // dataPriv.set( el, "click", ... ) + leverageNative( el, "click", returnTrue ); + } + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Force setup before triggering a click + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + leverageNative( el, "click" ); + } + + // Return non-false to allow normal event-path propagation + return true; + }, + + // For cross-browser consistency, suppress native .click() on links + // Also prevent it if we're currently inside a leveraged native-event stack + _default: function( event ) { + var target = event.target; + return rcheckableType.test( target.type ) && + target.click && nodeName( target, "input" ) && + dataPriv.get( target, "click" ) || + nodeName( target, "a" ); + } + }, + + beforeunload: { + postDispatch: function( event ) { + + // Support: Firefox 20+ + // Firefox doesn't alert if the returnValue field is not set. + if ( event.result !== undefined && event.originalEvent ) { + event.originalEvent.returnValue = event.result; + } + } + } + } +}; + +// Ensure the presence of an event listener that handles manually-triggered +// synthetic events by interrupting progress until reinvoked in response to +// *native* events that it fires directly, ensuring that state changes have +// already occurred before other listeners are invoked. +function leverageNative( el, type, expectSync ) { + + // Missing expectSync indicates a trigger call, which must force setup through jQuery.event.add + if ( !expectSync ) { + if ( dataPriv.get( el, type ) === undefined ) { + jQuery.event.add( el, type, returnTrue ); + } + return; + } + + // Register the controller as a special universal handler for all event namespaces + dataPriv.set( el, type, false ); + jQuery.event.add( el, type, { + namespace: false, + handler: function( event ) { + var notAsync, result, + saved = dataPriv.get( this, type ); + + if ( ( event.isTrigger & 1 ) && this[ type ] ) { + + // Interrupt processing of the outer synthetic .trigger()ed event + // Saved data should be false in such cases, but might be a leftover capture object + // from an async native handler (gh-4350) + if ( !saved.length ) { + + // Store arguments for use when handling the inner native event + // There will always be at least one argument (an event object), so this array + // will not be confused with a leftover capture object. + saved = slice.call( arguments ); + dataPriv.set( this, type, saved ); + + // Trigger the native event and capture its result + // Support: IE <=9 - 11+ + // focus() and blur() are asynchronous + notAsync = expectSync( this, type ); + this[ type ](); + result = dataPriv.get( this, type ); + if ( saved !== result || notAsync ) { + dataPriv.set( this, type, false ); + } else { + result = {}; + } + if ( saved !== result ) { + + // Cancel the outer synthetic event + event.stopImmediatePropagation(); + event.preventDefault(); + + // Support: Chrome 86+ + // In Chrome, if an element having a focusout handler is blurred by + // clicking outside of it, it invokes the handler synchronously. If + // that handler calls `.remove()` on the element, the data is cleared, + // leaving `result` undefined. We need to guard against this. + return result && result.value; + } + + // If this is an inner synthetic event for an event with a bubbling surrogate + // (focus or blur), assume that the surrogate already propagated from triggering the + // native event and prevent that from happening again here. + // This technically gets the ordering wrong w.r.t. to `.trigger()` (in which the + // bubbling surrogate propagates *after* the non-bubbling base), but that seems + // less bad than duplication. + } else if ( ( jQuery.event.special[ type ] || {} ).delegateType ) { + event.stopPropagation(); + } + + // If this is a native event triggered above, everything is now in order + // Fire an inner synthetic event with the original arguments + } else if ( saved.length ) { + + // ...and capture the result + dataPriv.set( this, type, { + value: jQuery.event.trigger( + + // Support: IE <=9 - 11+ + // Extend with the prototype to reset the above stopImmediatePropagation() + jQuery.extend( saved[ 0 ], jQuery.Event.prototype ), + saved.slice( 1 ), + this + ) + } ); + + // Abort handling of the native event + event.stopImmediatePropagation(); + } + } + } ); +} + +jQuery.removeEvent = function( elem, type, handle ) { + + // This "if" is needed for plain objects + if ( elem.removeEventListener ) { + elem.removeEventListener( type, handle ); + } +}; + +jQuery.Event = function( src, props ) { + + // Allow instantiation without the 'new' keyword + if ( !( this instanceof jQuery.Event ) ) { + return new jQuery.Event( src, props ); + } + + // Event object + if ( src && src.type ) { + this.originalEvent = src; + this.type = src.type; + + // Events bubbling up the document may have been marked as prevented + // by a handler lower down the tree; reflect the correct value. + this.isDefaultPrevented = src.defaultPrevented || + src.defaultPrevented === undefined && + + // Support: Android <=2.3 only + src.returnValue === false ? + returnTrue : + returnFalse; + + // Create target properties + // Support: Safari <=6 - 7 only + // Target should not be a text node (#504, #13143) + this.target = ( src.target && src.target.nodeType === 3 ) ? + src.target.parentNode : + src.target; + + this.currentTarget = src.currentTarget; + this.relatedTarget = src.relatedTarget; + + // Event type + } else { + this.type = src; + } + + // Put explicitly provided properties onto the event object + if ( props ) { + jQuery.extend( this, props ); + } + + // Create a timestamp if incoming event doesn't have one + this.timeStamp = src && src.timeStamp || Date.now(); + + // Mark it as fixed + this[ jQuery.expando ] = true; +}; + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + constructor: jQuery.Event, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse, + isSimulated: false, + + preventDefault: function() { + var e = this.originalEvent; + + this.isDefaultPrevented = returnTrue; + + if ( e && !this.isSimulated ) { + e.preventDefault(); + } + }, + stopPropagation: function() { + var e = this.originalEvent; + + this.isPropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopPropagation(); + } + }, + stopImmediatePropagation: function() { + var e = this.originalEvent; + + this.isImmediatePropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopImmediatePropagation(); + } + + this.stopPropagation(); + } +}; + +// Includes all common event props including KeyEvent and MouseEvent specific props +jQuery.each( { + altKey: true, + bubbles: true, + cancelable: true, + changedTouches: true, + ctrlKey: true, + detail: true, + eventPhase: true, + metaKey: true, + pageX: true, + pageY: true, + shiftKey: true, + view: true, + "char": true, + code: true, + charCode: true, + key: true, + keyCode: true, + button: true, + buttons: true, + clientX: true, + clientY: true, + offsetX: true, + offsetY: true, + pointerId: true, + pointerType: true, + screenX: true, + screenY: true, + targetTouches: true, + toElement: true, + touches: true, + which: true +}, jQuery.event.addProp ); + +jQuery.each( { focus: "focusin", blur: "focusout" }, function( type, delegateType ) { + jQuery.event.special[ type ] = { + + // Utilize native event if possible so blur/focus sequence is correct + setup: function() { + + // Claim the first handler + // dataPriv.set( this, "focus", ... ) + // dataPriv.set( this, "blur", ... ) + leverageNative( this, type, expectSync ); + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function() { + + // Force setup before trigger + leverageNative( this, type ); + + // Return non-false to allow normal event-path propagation + return true; + }, + + // Suppress native focus or blur as it's already being fired + // in leverageNative. + _default: function() { + return true; + }, + + delegateType: delegateType + }; +} ); + +// Create mouseenter/leave events using mouseover/out and event-time checks +// so that event delegation works in jQuery. +// Do the same for pointerenter/pointerleave and pointerover/pointerout +// +// Support: Safari 7 only +// Safari sends mouseenter too often; see: +// https://bugs.chromium.org/p/chromium/issues/detail?id=470258 +// for the description of the bug (it existed in older Chrome versions as well). +jQuery.each( { + mouseenter: "mouseover", + mouseleave: "mouseout", + pointerenter: "pointerover", + pointerleave: "pointerout" +}, function( orig, fix ) { + jQuery.event.special[ orig ] = { + delegateType: fix, + bindType: fix, + + handle: function( event ) { + var ret, + target = this, + related = event.relatedTarget, + handleObj = event.handleObj; + + // For mouseenter/leave call the handler if related is outside the target. + // NB: No relatedTarget if the mouse left/entered the browser window + if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) { + event.type = handleObj.origType; + ret = handleObj.handler.apply( this, arguments ); + event.type = fix; + } + return ret; + } + }; +} ); + +jQuery.fn.extend( { + + on: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn ); + }, + one: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn, 1 ); + }, + off: function( types, selector, fn ) { + var handleObj, type; + if ( types && types.preventDefault && types.handleObj ) { + + // ( event ) dispatched jQuery.Event + handleObj = types.handleObj; + jQuery( types.delegateTarget ).off( + handleObj.namespace ? + handleObj.origType + "." + handleObj.namespace : + handleObj.origType, + handleObj.selector, + handleObj.handler + ); + return this; + } + if ( typeof types === "object" ) { + + // ( types-object [, selector] ) + for ( type in types ) { + this.off( type, selector, types[ type ] ); + } + return this; + } + if ( selector === false || typeof selector === "function" ) { + + // ( types [, fn] ) + fn = selector; + selector = undefined; + } + if ( fn === false ) { + fn = returnFalse; + } + return this.each( function() { + jQuery.event.remove( this, types, fn, selector ); + } ); + } +} ); + + +var + + // Support: IE <=10 - 11, Edge 12 - 13 only + // In IE/Edge using regex groups here causes severe slowdowns. + // See https://connect.microsoft.com/IE/feedback/details/1736512/ + rnoInnerhtml = /\s*$/g; + +// Prefer a tbody over its parent table for containing new rows +function manipulationTarget( elem, content ) { + if ( nodeName( elem, "table" ) && + nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) { + + return jQuery( elem ).children( "tbody" )[ 0 ] || elem; + } + + return elem; +} + +// Replace/restore the type attribute of script elements for safe DOM manipulation +function disableScript( elem ) { + elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type; + return elem; +} +function restoreScript( elem ) { + if ( ( elem.type || "" ).slice( 0, 5 ) === "true/" ) { + elem.type = elem.type.slice( 5 ); + } else { + elem.removeAttribute( "type" ); + } + + return elem; +} + +function cloneCopyEvent( src, dest ) { + var i, l, type, pdataOld, udataOld, udataCur, events; + + if ( dest.nodeType !== 1 ) { + return; + } + + // 1. Copy private data: events, handlers, etc. + if ( dataPriv.hasData( src ) ) { + pdataOld = dataPriv.get( src ); + events = pdataOld.events; + + if ( events ) { + dataPriv.remove( dest, "handle events" ); + + for ( type in events ) { + for ( i = 0, l = events[ type ].length; i < l; i++ ) { + jQuery.event.add( dest, type, events[ type ][ i ] ); + } + } + } + } + + // 2. Copy user data + if ( dataUser.hasData( src ) ) { + udataOld = dataUser.access( src ); + udataCur = jQuery.extend( {}, udataOld ); + + dataUser.set( dest, udataCur ); + } +} + +// Fix IE bugs, see support tests +function fixInput( src, dest ) { + var nodeName = dest.nodeName.toLowerCase(); + + // Fails to persist the checked state of a cloned checkbox or radio button. + if ( nodeName === "input" && rcheckableType.test( src.type ) ) { + dest.checked = src.checked; + + // Fails to return the selected option to the default selected state when cloning options + } else if ( nodeName === "input" || nodeName === "textarea" ) { + dest.defaultValue = src.defaultValue; + } +} + +function domManip( collection, args, callback, ignored ) { + + // Flatten any nested arrays + args = flat( args ); + + var fragment, first, scripts, hasScripts, node, doc, + i = 0, + l = collection.length, + iNoClone = l - 1, + value = args[ 0 ], + valueIsFunction = isFunction( value ); + + // We can't cloneNode fragments that contain checked, in WebKit + if ( valueIsFunction || + ( l > 1 && typeof value === "string" && + !support.checkClone && rchecked.test( value ) ) ) { + return collection.each( function( index ) { + var self = collection.eq( index ); + if ( valueIsFunction ) { + args[ 0 ] = value.call( this, index, self.html() ); + } + domManip( self, args, callback, ignored ); + } ); + } + + if ( l ) { + fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored ); + first = fragment.firstChild; + + if ( fragment.childNodes.length === 1 ) { + fragment = first; + } + + // Require either new content or an interest in ignored elements to invoke the callback + if ( first || ignored ) { + scripts = jQuery.map( getAll( fragment, "script" ), disableScript ); + hasScripts = scripts.length; + + // Use the original fragment for the last item + // instead of the first because it can end up + // being emptied incorrectly in certain situations (#8070). + for ( ; i < l; i++ ) { + node = fragment; + + if ( i !== iNoClone ) { + node = jQuery.clone( node, true, true ); + + // Keep references to cloned scripts for later restoration + if ( hasScripts ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( scripts, getAll( node, "script" ) ); + } + } + + callback.call( collection[ i ], node, i ); + } + + if ( hasScripts ) { + doc = scripts[ scripts.length - 1 ].ownerDocument; + + // Reenable scripts + jQuery.map( scripts, restoreScript ); + + // Evaluate executable scripts on first document insertion + for ( i = 0; i < hasScripts; i++ ) { + node = scripts[ i ]; + if ( rscriptType.test( node.type || "" ) && + !dataPriv.access( node, "globalEval" ) && + jQuery.contains( doc, node ) ) { + + if ( node.src && ( node.type || "" ).toLowerCase() !== "module" ) { + + // Optional AJAX dependency, but won't run scripts if not present + if ( jQuery._evalUrl && !node.noModule ) { + jQuery._evalUrl( node.src, { + nonce: node.nonce || node.getAttribute( "nonce" ) + }, doc ); + } + } else { + DOMEval( node.textContent.replace( rcleanScript, "" ), node, doc ); + } + } + } + } + } + } + + return collection; +} + +function remove( elem, selector, keepData ) { + var node, + nodes = selector ? jQuery.filter( selector, elem ) : elem, + i = 0; + + for ( ; ( node = nodes[ i ] ) != null; i++ ) { + if ( !keepData && node.nodeType === 1 ) { + jQuery.cleanData( getAll( node ) ); + } + + if ( node.parentNode ) { + if ( keepData && isAttached( node ) ) { + setGlobalEval( getAll( node, "script" ) ); + } + node.parentNode.removeChild( node ); + } + } + + return elem; +} + +jQuery.extend( { + htmlPrefilter: function( html ) { + return html; + }, + + clone: function( elem, dataAndEvents, deepDataAndEvents ) { + var i, l, srcElements, destElements, + clone = elem.cloneNode( true ), + inPage = isAttached( elem ); + + // Fix IE cloning issues + if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && + !jQuery.isXMLDoc( elem ) ) { + + // We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2 + destElements = getAll( clone ); + srcElements = getAll( elem ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + fixInput( srcElements[ i ], destElements[ i ] ); + } + } + + // Copy the events from the original to the clone + if ( dataAndEvents ) { + if ( deepDataAndEvents ) { + srcElements = srcElements || getAll( elem ); + destElements = destElements || getAll( clone ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + cloneCopyEvent( srcElements[ i ], destElements[ i ] ); + } + } else { + cloneCopyEvent( elem, clone ); + } + } + + // Preserve script evaluation history + destElements = getAll( clone, "script" ); + if ( destElements.length > 0 ) { + setGlobalEval( destElements, !inPage && getAll( elem, "script" ) ); + } + + // Return the cloned set + return clone; + }, + + cleanData: function( elems ) { + var data, elem, type, + special = jQuery.event.special, + i = 0; + + for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) { + if ( acceptData( elem ) ) { + if ( ( data = elem[ dataPriv.expando ] ) ) { + if ( data.events ) { + for ( type in data.events ) { + if ( special[ type ] ) { + jQuery.event.remove( elem, type ); + + // This is a shortcut to avoid jQuery.event.remove's overhead + } else { + jQuery.removeEvent( elem, type, data.handle ); + } + } + } + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataPriv.expando ] = undefined; + } + if ( elem[ dataUser.expando ] ) { + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataUser.expando ] = undefined; + } + } + } + } +} ); + +jQuery.fn.extend( { + detach: function( selector ) { + return remove( this, selector, true ); + }, + + remove: function( selector ) { + return remove( this, selector ); + }, + + text: function( value ) { + return access( this, function( value ) { + return value === undefined ? + jQuery.text( this ) : + this.empty().each( function() { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + this.textContent = value; + } + } ); + }, null, value, arguments.length ); + }, + + append: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.appendChild( elem ); + } + } ); + }, + + prepend: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.insertBefore( elem, target.firstChild ); + } + } ); + }, + + before: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this ); + } + } ); + }, + + after: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this.nextSibling ); + } + } ); + }, + + empty: function() { + var elem, + i = 0; + + for ( ; ( elem = this[ i ] ) != null; i++ ) { + if ( elem.nodeType === 1 ) { + + // Prevent memory leaks + jQuery.cleanData( getAll( elem, false ) ); + + // Remove any remaining nodes + elem.textContent = ""; + } + } + + return this; + }, + + clone: function( dataAndEvents, deepDataAndEvents ) { + dataAndEvents = dataAndEvents == null ? false : dataAndEvents; + deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents; + + return this.map( function() { + return jQuery.clone( this, dataAndEvents, deepDataAndEvents ); + } ); + }, + + html: function( value ) { + return access( this, function( value ) { + var elem = this[ 0 ] || {}, + i = 0, + l = this.length; + + if ( value === undefined && elem.nodeType === 1 ) { + return elem.innerHTML; + } + + // See if we can take a shortcut and just use innerHTML + if ( typeof value === "string" && !rnoInnerhtml.test( value ) && + !wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) { + + value = jQuery.htmlPrefilter( value ); + + try { + for ( ; i < l; i++ ) { + elem = this[ i ] || {}; + + // Remove element nodes and prevent memory leaks + if ( elem.nodeType === 1 ) { + jQuery.cleanData( getAll( elem, false ) ); + elem.innerHTML = value; + } + } + + elem = 0; + + // If using innerHTML throws an exception, use the fallback method + } catch ( e ) {} + } + + if ( elem ) { + this.empty().append( value ); + } + }, null, value, arguments.length ); + }, + + replaceWith: function() { + var ignored = []; + + // Make the changes, replacing each non-ignored context element with the new content + return domManip( this, arguments, function( elem ) { + var parent = this.parentNode; + + if ( jQuery.inArray( this, ignored ) < 0 ) { + jQuery.cleanData( getAll( this ) ); + if ( parent ) { + parent.replaceChild( elem, this ); + } + } + + // Force callback invocation + }, ignored ); + } +} ); + +jQuery.each( { + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function( name, original ) { + jQuery.fn[ name ] = function( selector ) { + var elems, + ret = [], + insert = jQuery( selector ), + last = insert.length - 1, + i = 0; + + for ( ; i <= last; i++ ) { + elems = i === last ? this : this.clone( true ); + jQuery( insert[ i ] )[ original ]( elems ); + + // Support: Android <=4.0 only, PhantomJS 1 only + // .get() because push.apply(_, arraylike) throws on ancient WebKit + push.apply( ret, elems.get() ); + } + + return this.pushStack( ret ); + }; +} ); +var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" ); + +var getStyles = function( elem ) { + + // Support: IE <=11 only, Firefox <=30 (#15098, #14150) + // IE throws on elements created in popups + // FF meanwhile throws on frame elements through "defaultView.getComputedStyle" + var view = elem.ownerDocument.defaultView; + + if ( !view || !view.opener ) { + view = window; + } + + return view.getComputedStyle( elem ); + }; + +var swap = function( elem, options, callback ) { + var ret, name, + old = {}; + + // Remember the old values, and insert the new ones + for ( name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + ret = callback.call( elem ); + + // Revert the old values + for ( name in options ) { + elem.style[ name ] = old[ name ]; + } + + return ret; +}; + + +var rboxStyle = new RegExp( cssExpand.join( "|" ), "i" ); + + + +( function() { + + // Executing both pixelPosition & boxSizingReliable tests require only one layout + // so they're executed at the same time to save the second computation. + function computeStyleTests() { + + // This is a singleton, we need to execute it only once + if ( !div ) { + return; + } + + container.style.cssText = "position:absolute;left:-11111px;width:60px;" + + "margin-top:1px;padding:0;border:0"; + div.style.cssText = + "position:relative;display:block;box-sizing:border-box;overflow:scroll;" + + "margin:auto;border:1px;padding:1px;" + + "width:60%;top:1%"; + documentElement.appendChild( container ).appendChild( div ); + + var divStyle = window.getComputedStyle( div ); + pixelPositionVal = divStyle.top !== "1%"; + + // Support: Android 4.0 - 4.3 only, Firefox <=3 - 44 + reliableMarginLeftVal = roundPixelMeasures( divStyle.marginLeft ) === 12; + + // Support: Android 4.0 - 4.3 only, Safari <=9.1 - 10.1, iOS <=7.0 - 9.3 + // Some styles come back with percentage values, even though they shouldn't + div.style.right = "60%"; + pixelBoxStylesVal = roundPixelMeasures( divStyle.right ) === 36; + + // Support: IE 9 - 11 only + // Detect misreporting of content dimensions for box-sizing:border-box elements + boxSizingReliableVal = roundPixelMeasures( divStyle.width ) === 36; + + // Support: IE 9 only + // Detect overflow:scroll screwiness (gh-3699) + // Support: Chrome <=64 + // Don't get tricked when zoom affects offsetWidth (gh-4029) + div.style.position = "absolute"; + scrollboxSizeVal = roundPixelMeasures( div.offsetWidth / 3 ) === 12; + + documentElement.removeChild( container ); + + // Nullify the div so it wouldn't be stored in the memory and + // it will also be a sign that checks already performed + div = null; + } + + function roundPixelMeasures( measure ) { + return Math.round( parseFloat( measure ) ); + } + + var pixelPositionVal, boxSizingReliableVal, scrollboxSizeVal, pixelBoxStylesVal, + reliableTrDimensionsVal, reliableMarginLeftVal, + container = document.createElement( "div" ), + div = document.createElement( "div" ); + + // Finish early in limited (non-browser) environments + if ( !div.style ) { + return; + } + + // Support: IE <=9 - 11 only + // Style of cloned element affects source element cloned (#8908) + div.style.backgroundClip = "content-box"; + div.cloneNode( true ).style.backgroundClip = ""; + support.clearCloneStyle = div.style.backgroundClip === "content-box"; + + jQuery.extend( support, { + boxSizingReliable: function() { + computeStyleTests(); + return boxSizingReliableVal; + }, + pixelBoxStyles: function() { + computeStyleTests(); + return pixelBoxStylesVal; + }, + pixelPosition: function() { + computeStyleTests(); + return pixelPositionVal; + }, + reliableMarginLeft: function() { + computeStyleTests(); + return reliableMarginLeftVal; + }, + scrollboxSize: function() { + computeStyleTests(); + return scrollboxSizeVal; + }, + + // Support: IE 9 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Behavior in IE 9 is more subtle than in newer versions & it passes + // some versions of this test; make sure not to make it pass there! + // + // Support: Firefox 70+ + // Only Firefox includes border widths + // in computed dimensions. (gh-4529) + reliableTrDimensions: function() { + var table, tr, trChild, trStyle; + if ( reliableTrDimensionsVal == null ) { + table = document.createElement( "table" ); + tr = document.createElement( "tr" ); + trChild = document.createElement( "div" ); + + table.style.cssText = "position:absolute;left:-11111px;border-collapse:separate"; + tr.style.cssText = "border:1px solid"; + + // Support: Chrome 86+ + // Height set through cssText does not get applied. + // Computed height then comes back as 0. + tr.style.height = "1px"; + trChild.style.height = "9px"; + + // Support: Android 8 Chrome 86+ + // In our bodyBackground.html iframe, + // display for all div elements is set to "inline", + // which causes a problem only in Android 8 Chrome 86. + // Ensuring the div is display: block + // gets around this issue. + trChild.style.display = "block"; + + documentElement + .appendChild( table ) + .appendChild( tr ) + .appendChild( trChild ); + + trStyle = window.getComputedStyle( tr ); + reliableTrDimensionsVal = ( parseInt( trStyle.height, 10 ) + + parseInt( trStyle.borderTopWidth, 10 ) + + parseInt( trStyle.borderBottomWidth, 10 ) ) === tr.offsetHeight; + + documentElement.removeChild( table ); + } + return reliableTrDimensionsVal; + } + } ); +} )(); + + +function curCSS( elem, name, computed ) { + var width, minWidth, maxWidth, ret, + + // Support: Firefox 51+ + // Retrieving style before computed somehow + // fixes an issue with getting wrong values + // on detached elements + style = elem.style; + + computed = computed || getStyles( elem ); + + // getPropertyValue is needed for: + // .css('filter') (IE 9 only, #12537) + // .css('--customProperty) (#3144) + if ( computed ) { + ret = computed.getPropertyValue( name ) || computed[ name ]; + + if ( ret === "" && !isAttached( elem ) ) { + ret = jQuery.style( elem, name ); + } + + // A tribute to the "awesome hack by Dean Edwards" + // Android Browser returns percentage for some values, + // but width seems to be reliably pixels. + // This is against the CSSOM draft spec: + // https://drafts.csswg.org/cssom/#resolved-values + if ( !support.pixelBoxStyles() && rnumnonpx.test( ret ) && rboxStyle.test( name ) ) { + + // Remember the original values + width = style.width; + minWidth = style.minWidth; + maxWidth = style.maxWidth; + + // Put in the new values to get a computed value out + style.minWidth = style.maxWidth = style.width = ret; + ret = computed.width; + + // Revert the changed values + style.width = width; + style.minWidth = minWidth; + style.maxWidth = maxWidth; + } + } + + return ret !== undefined ? + + // Support: IE <=9 - 11 only + // IE returns zIndex value as an integer. + ret + "" : + ret; +} + + +function addGetHookIf( conditionFn, hookFn ) { + + // Define the hook, we'll check on the first run if it's really needed. + return { + get: function() { + if ( conditionFn() ) { + + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. + delete this.get; + return; + } + + // Hook needed; redefine it so that the support test is not executed again. + return ( this.get = hookFn ).apply( this, arguments ); + } + }; +} + + +var cssPrefixes = [ "Webkit", "Moz", "ms" ], + emptyStyle = document.createElement( "div" ).style, + vendorProps = {}; + +// Return a vendor-prefixed property or undefined +function vendorPropName( name ) { + + // Check for vendor prefixed names + var capName = name[ 0 ].toUpperCase() + name.slice( 1 ), + i = cssPrefixes.length; + + while ( i-- ) { + name = cssPrefixes[ i ] + capName; + if ( name in emptyStyle ) { + return name; + } + } +} + +// Return a potentially-mapped jQuery.cssProps or vendor prefixed property +function finalPropName( name ) { + var final = jQuery.cssProps[ name ] || vendorProps[ name ]; + + if ( final ) { + return final; + } + if ( name in emptyStyle ) { + return name; + } + return vendorProps[ name ] = vendorPropName( name ) || name; +} + + +var + + // Swappable if display is none or starts with table + // except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + rdisplayswap = /^(none|table(?!-c[ea]).+)/, + rcustomProp = /^--/, + cssShow = { position: "absolute", visibility: "hidden", display: "block" }, + cssNormalTransform = { + letterSpacing: "0", + fontWeight: "400" + }; + +function setPositiveNumber( _elem, value, subtract ) { + + // Any relative (+/-) values have already been + // normalized at this point + var matches = rcssNum.exec( value ); + return matches ? + + // Guard against undefined "subtract", e.g., when used as in cssHooks + Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) : + value; +} + +function boxModelAdjustment( elem, dimension, box, isBorderBox, styles, computedVal ) { + var i = dimension === "width" ? 1 : 0, + extra = 0, + delta = 0; + + // Adjustment may not be necessary + if ( box === ( isBorderBox ? "border" : "content" ) ) { + return 0; + } + + for ( ; i < 4; i += 2 ) { + + // Both box models exclude margin + if ( box === "margin" ) { + delta += jQuery.css( elem, box + cssExpand[ i ], true, styles ); + } + + // If we get here with a content-box, we're seeking "padding" or "border" or "margin" + if ( !isBorderBox ) { + + // Add padding + delta += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + + // For "border" or "margin", add border + if ( box !== "padding" ) { + delta += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + + // But still keep track of it otherwise + } else { + extra += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + + // If we get here with a border-box (content + padding + border), we're seeking "content" or + // "padding" or "margin" + } else { + + // For "content", subtract padding + if ( box === "content" ) { + delta -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + } + + // For "content" or "padding", subtract border + if ( box !== "margin" ) { + delta -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + } + } + + // Account for positive content-box scroll gutter when requested by providing computedVal + if ( !isBorderBox && computedVal >= 0 ) { + + // offsetWidth/offsetHeight is a rounded sum of content, padding, scroll gutter, and border + // Assuming integer scroll gutter, subtract the rest and round down + delta += Math.max( 0, Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + computedVal - + delta - + extra - + 0.5 + + // If offsetWidth/offsetHeight is unknown, then we can't determine content-box scroll gutter + // Use an explicit zero to avoid NaN (gh-3964) + ) ) || 0; + } + + return delta; +} + +function getWidthOrHeight( elem, dimension, extra ) { + + // Start with computed style + var styles = getStyles( elem ), + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-4322). + // Fake content-box until we know it's needed to know the true value. + boxSizingNeeded = !support.boxSizingReliable() || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + valueIsBorderBox = isBorderBox, + + val = curCSS( elem, dimension, styles ), + offsetProp = "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ); + + // Support: Firefox <=54 + // Return a confounding non-pixel value or feign ignorance, as appropriate. + if ( rnumnonpx.test( val ) ) { + if ( !extra ) { + return val; + } + val = "auto"; + } + + + // Support: IE 9 - 11 only + // Use offsetWidth/offsetHeight for when box sizing is unreliable. + // In those cases, the computed value can be trusted to be border-box. + if ( ( !support.boxSizingReliable() && isBorderBox || + + // Support: IE 10 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Interestingly, in some cases IE 9 doesn't suffer from this issue. + !support.reliableTrDimensions() && nodeName( elem, "tr" ) || + + // Fall back to offsetWidth/offsetHeight when value is "auto" + // This happens for inline elements with no explicit setting (gh-3571) + val === "auto" || + + // Support: Android <=4.1 - 4.3 only + // Also use offsetWidth/offsetHeight for misreported inline dimensions (gh-3602) + !parseFloat( val ) && jQuery.css( elem, "display", false, styles ) === "inline" ) && + + // Make sure the element is visible & connected + elem.getClientRects().length ) { + + isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; + + // Where available, offsetWidth/offsetHeight approximate border box dimensions. + // Where not available (e.g., SVG), assume unreliable box-sizing and interpret the + // retrieved value as a content box dimension. + valueIsBorderBox = offsetProp in elem; + if ( valueIsBorderBox ) { + val = elem[ offsetProp ]; + } + } + + // Normalize "" and auto + val = parseFloat( val ) || 0; + + // Adjust for the element's box model + return ( val + + boxModelAdjustment( + elem, + dimension, + extra || ( isBorderBox ? "border" : "content" ), + valueIsBorderBox, + styles, + + // Provide the current computed size to request scroll gutter calculation (gh-3589) + val + ) + ) + "px"; +} + +jQuery.extend( { + + // Add in style property hooks for overriding the default + // behavior of getting and setting a style property + cssHooks: { + opacity: { + get: function( elem, computed ) { + if ( computed ) { + + // We should always get a number back from opacity + var ret = curCSS( elem, "opacity" ); + return ret === "" ? "1" : ret; + } + } + } + }, + + // Don't automatically add "px" to these possibly-unitless properties + cssNumber: { + "animationIterationCount": true, + "columnCount": true, + "fillOpacity": true, + "flexGrow": true, + "flexShrink": true, + "fontWeight": true, + "gridArea": true, + "gridColumn": true, + "gridColumnEnd": true, + "gridColumnStart": true, + "gridRow": true, + "gridRowEnd": true, + "gridRowStart": true, + "lineHeight": true, + "opacity": true, + "order": true, + "orphans": true, + "widows": true, + "zIndex": true, + "zoom": true + }, + + // Add in properties whose names you wish to fix before + // setting or getting the value + cssProps: {}, + + // Get and set the style property on a DOM Node + style: function( elem, name, value, extra ) { + + // Don't set styles on text and comment nodes + if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { + return; + } + + // Make sure that we're working with the right name + var ret, type, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ), + style = elem.style; + + // Make sure that we're working with the right name. We don't + // want to query the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Gets hook for the prefixed version, then unprefixed version + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // Check if we're setting a value + if ( value !== undefined ) { + type = typeof value; + + // Convert "+=" or "-=" to relative numbers (#7345) + if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) { + value = adjustCSS( elem, name, ret ); + + // Fixes bug #9237 + type = "number"; + } + + // Make sure that null and NaN values aren't set (#7116) + if ( value == null || value !== value ) { + return; + } + + // If a number was passed in, add the unit (except for certain CSS properties) + // The isCustomProp check can be removed in jQuery 4.0 when we only auto-append + // "px" to a few hardcoded values. + if ( type === "number" && !isCustomProp ) { + value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" ); + } + + // background-* props affect original clone's values + if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { + style[ name ] = "inherit"; + } + + // If a hook was provided, use that value, otherwise just set the specified value + if ( !hooks || !( "set" in hooks ) || + ( value = hooks.set( elem, value, extra ) ) !== undefined ) { + + if ( isCustomProp ) { + style.setProperty( name, value ); + } else { + style[ name ] = value; + } + } + + } else { + + // If a hook was provided get the non-computed value from there + if ( hooks && "get" in hooks && + ( ret = hooks.get( elem, false, extra ) ) !== undefined ) { + + return ret; + } + + // Otherwise just get the value from the style object + return style[ name ]; + } + }, + + css: function( elem, name, extra, styles ) { + var val, num, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ); + + // Make sure that we're working with the right name. We don't + // want to modify the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Try prefixed name followed by the unprefixed name + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // If a hook was provided get the computed value from there + if ( hooks && "get" in hooks ) { + val = hooks.get( elem, true, extra ); + } + + // Otherwise, if a way to get the computed value exists, use that + if ( val === undefined ) { + val = curCSS( elem, name, styles ); + } + + // Convert "normal" to computed value + if ( val === "normal" && name in cssNormalTransform ) { + val = cssNormalTransform[ name ]; + } + + // Make numeric if forced or a qualifier was provided and val looks numeric + if ( extra === "" || extra ) { + num = parseFloat( val ); + return extra === true || isFinite( num ) ? num || 0 : val; + } + + return val; + } +} ); + +jQuery.each( [ "height", "width" ], function( _i, dimension ) { + jQuery.cssHooks[ dimension ] = { + get: function( elem, computed, extra ) { + if ( computed ) { + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit + return rdisplayswap.test( jQuery.css( elem, "display" ) ) && + + // Support: Safari 8+ + // Table columns in Safari have non-zero offsetWidth & zero + // getBoundingClientRect().width unless display is changed. + // Support: IE <=11 only + // Running getBoundingClientRect on a disconnected node + // in IE throws an error. + ( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ? + swap( elem, cssShow, function() { + return getWidthOrHeight( elem, dimension, extra ); + } ) : + getWidthOrHeight( elem, dimension, extra ); + } + }, + + set: function( elem, value, extra ) { + var matches, + styles = getStyles( elem ), + + // Only read styles.position if the test has a chance to fail + // to avoid forcing a reflow. + scrollboxSizeBuggy = !support.scrollboxSize() && + styles.position === "absolute", + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-3991) + boxSizingNeeded = scrollboxSizeBuggy || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + subtract = extra ? + boxModelAdjustment( + elem, + dimension, + extra, + isBorderBox, + styles + ) : + 0; + + // Account for unreliable border-box dimensions by comparing offset* to computed and + // faking a content-box to get border and padding (gh-3699) + if ( isBorderBox && scrollboxSizeBuggy ) { + subtract -= Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + parseFloat( styles[ dimension ] ) - + boxModelAdjustment( elem, dimension, "border", false, styles ) - + 0.5 + ); + } + + // Convert to pixels if value adjustment is needed + if ( subtract && ( matches = rcssNum.exec( value ) ) && + ( matches[ 3 ] || "px" ) !== "px" ) { + + elem.style[ dimension ] = value; + value = jQuery.css( elem, dimension ); + } + + return setPositiveNumber( elem, value, subtract ); + } + }; +} ); + +jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft, + function( elem, computed ) { + if ( computed ) { + return ( parseFloat( curCSS( elem, "marginLeft" ) ) || + elem.getBoundingClientRect().left - + swap( elem, { marginLeft: 0 }, function() { + return elem.getBoundingClientRect().left; + } ) + ) + "px"; + } + } +); + +// These hooks are used by animate to expand properties +jQuery.each( { + margin: "", + padding: "", + border: "Width" +}, function( prefix, suffix ) { + jQuery.cssHooks[ prefix + suffix ] = { + expand: function( value ) { + var i = 0, + expanded = {}, + + // Assumes a single number if not a string + parts = typeof value === "string" ? value.split( " " ) : [ value ]; + + for ( ; i < 4; i++ ) { + expanded[ prefix + cssExpand[ i ] + suffix ] = + parts[ i ] || parts[ i - 2 ] || parts[ 0 ]; + } + + return expanded; + } + }; + + if ( prefix !== "margin" ) { + jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber; + } +} ); + +jQuery.fn.extend( { + css: function( name, value ) { + return access( this, function( elem, name, value ) { + var styles, len, + map = {}, + i = 0; + + if ( Array.isArray( name ) ) { + styles = getStyles( elem ); + len = name.length; + + for ( ; i < len; i++ ) { + map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles ); + } + + return map; + } + + return value !== undefined ? + jQuery.style( elem, name, value ) : + jQuery.css( elem, name ); + }, name, value, arguments.length > 1 ); + } +} ); + + +function Tween( elem, options, prop, end, easing ) { + return new Tween.prototype.init( elem, options, prop, end, easing ); +} +jQuery.Tween = Tween; + +Tween.prototype = { + constructor: Tween, + init: function( elem, options, prop, end, easing, unit ) { + this.elem = elem; + this.prop = prop; + this.easing = easing || jQuery.easing._default; + this.options = options; + this.start = this.now = this.cur(); + this.end = end; + this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" ); + }, + cur: function() { + var hooks = Tween.propHooks[ this.prop ]; + + return hooks && hooks.get ? + hooks.get( this ) : + Tween.propHooks._default.get( this ); + }, + run: function( percent ) { + var eased, + hooks = Tween.propHooks[ this.prop ]; + + if ( this.options.duration ) { + this.pos = eased = jQuery.easing[ this.easing ]( + percent, this.options.duration * percent, 0, 1, this.options.duration + ); + } else { + this.pos = eased = percent; + } + this.now = ( this.end - this.start ) * eased + this.start; + + if ( this.options.step ) { + this.options.step.call( this.elem, this.now, this ); + } + + if ( hooks && hooks.set ) { + hooks.set( this ); + } else { + Tween.propHooks._default.set( this ); + } + return this; + } +}; + +Tween.prototype.init.prototype = Tween.prototype; + +Tween.propHooks = { + _default: { + get: function( tween ) { + var result; + + // Use a property on the element directly when it is not a DOM element, + // or when there is no matching style property that exists. + if ( tween.elem.nodeType !== 1 || + tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) { + return tween.elem[ tween.prop ]; + } + + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. + result = jQuery.css( tween.elem, tween.prop, "" ); + + // Empty strings, null, undefined and "auto" are converted to 0. + return !result || result === "auto" ? 0 : result; + }, + set: function( tween ) { + + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. + if ( jQuery.fx.step[ tween.prop ] ) { + jQuery.fx.step[ tween.prop ]( tween ); + } else if ( tween.elem.nodeType === 1 && ( + jQuery.cssHooks[ tween.prop ] || + tween.elem.style[ finalPropName( tween.prop ) ] != null ) ) { + jQuery.style( tween.elem, tween.prop, tween.now + tween.unit ); + } else { + tween.elem[ tween.prop ] = tween.now; + } + } + } +}; + +// Support: IE <=9 only +// Panic based approach to setting things on disconnected nodes +Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { + set: function( tween ) { + if ( tween.elem.nodeType && tween.elem.parentNode ) { + tween.elem[ tween.prop ] = tween.now; + } + } +}; + +jQuery.easing = { + linear: function( p ) { + return p; + }, + swing: function( p ) { + return 0.5 - Math.cos( p * Math.PI ) / 2; + }, + _default: "swing" +}; + +jQuery.fx = Tween.prototype.init; + +// Back compat <1.8 extension point +jQuery.fx.step = {}; + + + + +var + fxNow, inProgress, + rfxtypes = /^(?:toggle|show|hide)$/, + rrun = /queueHooks$/; + +function schedule() { + if ( inProgress ) { + if ( document.hidden === false && window.requestAnimationFrame ) { + window.requestAnimationFrame( schedule ); + } else { + window.setTimeout( schedule, jQuery.fx.interval ); + } + + jQuery.fx.tick(); + } +} + +// Animations created synchronously will run synchronously +function createFxNow() { + window.setTimeout( function() { + fxNow = undefined; + } ); + return ( fxNow = Date.now() ); +} + +// Generate parameters to create a standard animation +function genFx( type, includeWidth ) { + var which, + i = 0, + attrs = { height: type }; + + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right + includeWidth = includeWidth ? 1 : 0; + for ( ; i < 4; i += 2 - includeWidth ) { + which = cssExpand[ i ]; + attrs[ "margin" + which ] = attrs[ "padding" + which ] = type; + } + + if ( includeWidth ) { + attrs.opacity = attrs.width = type; + } + + return attrs; +} + +function createTween( value, prop, animation ) { + var tween, + collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ), + index = 0, + length = collection.length; + for ( ; index < length; index++ ) { + if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) { + + // We're done with this property + return tween; + } + } +} + +function defaultPrefilter( elem, props, opts ) { + var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display, + isBox = "width" in props || "height" in props, + anim = this, + orig = {}, + style = elem.style, + hidden = elem.nodeType && isHiddenWithinTree( elem ), + dataShow = dataPriv.get( elem, "fxshow" ); + + // Queue-skipping animations hijack the fx hooks + if ( !opts.queue ) { + hooks = jQuery._queueHooks( elem, "fx" ); + if ( hooks.unqueued == null ) { + hooks.unqueued = 0; + oldfire = hooks.empty.fire; + hooks.empty.fire = function() { + if ( !hooks.unqueued ) { + oldfire(); + } + }; + } + hooks.unqueued++; + + anim.always( function() { + + // Ensure the complete handler is called before this completes + anim.always( function() { + hooks.unqueued--; + if ( !jQuery.queue( elem, "fx" ).length ) { + hooks.empty.fire(); + } + } ); + } ); + } + + // Detect show/hide animations + for ( prop in props ) { + value = props[ prop ]; + if ( rfxtypes.test( value ) ) { + delete props[ prop ]; + toggle = toggle || value === "toggle"; + if ( value === ( hidden ? "hide" : "show" ) ) { + + // Pretend to be hidden if this is a "show" and + // there is still data from a stopped show/hide + if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) { + hidden = true; + + // Ignore all other no-op show/hide data + } else { + continue; + } + } + orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop ); + } + } + + // Bail out if this is a no-op like .hide().hide() + propTween = !jQuery.isEmptyObject( props ); + if ( !propTween && jQuery.isEmptyObject( orig ) ) { + return; + } + + // Restrict "overflow" and "display" styles during box animations + if ( isBox && elem.nodeType === 1 ) { + + // Support: IE <=9 - 11, Edge 12 - 15 + // Record all 3 overflow attributes because IE does not infer the shorthand + // from identically-valued overflowX and overflowY and Edge just mirrors + // the overflowX value there. + opts.overflow = [ style.overflow, style.overflowX, style.overflowY ]; + + // Identify a display type, preferring old show/hide data over the CSS cascade + restoreDisplay = dataShow && dataShow.display; + if ( restoreDisplay == null ) { + restoreDisplay = dataPriv.get( elem, "display" ); + } + display = jQuery.css( elem, "display" ); + if ( display === "none" ) { + if ( restoreDisplay ) { + display = restoreDisplay; + } else { + + // Get nonempty value(s) by temporarily forcing visibility + showHide( [ elem ], true ); + restoreDisplay = elem.style.display || restoreDisplay; + display = jQuery.css( elem, "display" ); + showHide( [ elem ] ); + } + } + + // Animate inline elements as inline-block + if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) { + if ( jQuery.css( elem, "float" ) === "none" ) { + + // Restore the original display value at the end of pure show/hide animations + if ( !propTween ) { + anim.done( function() { + style.display = restoreDisplay; + } ); + if ( restoreDisplay == null ) { + display = style.display; + restoreDisplay = display === "none" ? "" : display; + } + } + style.display = "inline-block"; + } + } + } + + if ( opts.overflow ) { + style.overflow = "hidden"; + anim.always( function() { + style.overflow = opts.overflow[ 0 ]; + style.overflowX = opts.overflow[ 1 ]; + style.overflowY = opts.overflow[ 2 ]; + } ); + } + + // Implement show/hide animations + propTween = false; + for ( prop in orig ) { + + // General show/hide setup for this element animation + if ( !propTween ) { + if ( dataShow ) { + if ( "hidden" in dataShow ) { + hidden = dataShow.hidden; + } + } else { + dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } ); + } + + // Store hidden/visible for toggle so `.stop().toggle()` "reverses" + if ( toggle ) { + dataShow.hidden = !hidden; + } + + // Show elements before animating them + if ( hidden ) { + showHide( [ elem ], true ); + } + + /* eslint-disable no-loop-func */ + + anim.done( function() { + + /* eslint-enable no-loop-func */ + + // The final step of a "hide" animation is actually hiding the element + if ( !hidden ) { + showHide( [ elem ] ); + } + dataPriv.remove( elem, "fxshow" ); + for ( prop in orig ) { + jQuery.style( elem, prop, orig[ prop ] ); + } + } ); + } + + // Per-property setup + propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim ); + if ( !( prop in dataShow ) ) { + dataShow[ prop ] = propTween.start; + if ( hidden ) { + propTween.end = propTween.start; + propTween.start = 0; + } + } + } +} + +function propFilter( props, specialEasing ) { + var index, name, easing, value, hooks; + + // camelCase, specialEasing and expand cssHook pass + for ( index in props ) { + name = camelCase( index ); + easing = specialEasing[ name ]; + value = props[ index ]; + if ( Array.isArray( value ) ) { + easing = value[ 1 ]; + value = props[ index ] = value[ 0 ]; + } + + if ( index !== name ) { + props[ name ] = value; + delete props[ index ]; + } + + hooks = jQuery.cssHooks[ name ]; + if ( hooks && "expand" in hooks ) { + value = hooks.expand( value ); + delete props[ name ]; + + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" + for ( index in value ) { + if ( !( index in props ) ) { + props[ index ] = value[ index ]; + specialEasing[ index ] = easing; + } + } + } else { + specialEasing[ name ] = easing; + } + } +} + +function Animation( elem, properties, options ) { + var result, + stopped, + index = 0, + length = Animation.prefilters.length, + deferred = jQuery.Deferred().always( function() { + + // Don't match elem in the :animated selector + delete tick.elem; + } ), + tick = function() { + if ( stopped ) { + return false; + } + var currentTime = fxNow || createFxNow(), + remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), + + // Support: Android 2.3 only + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) + temp = remaining / animation.duration || 0, + percent = 1 - temp, + index = 0, + length = animation.tweens.length; + + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( percent ); + } + + deferred.notifyWith( elem, [ animation, percent, remaining ] ); + + // If there's more to do, yield + if ( percent < 1 && length ) { + return remaining; + } + + // If this was an empty animation, synthesize a final progress notification + if ( !length ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + } + + // Resolve the animation and report its conclusion + deferred.resolveWith( elem, [ animation ] ); + return false; + }, + animation = deferred.promise( { + elem: elem, + props: jQuery.extend( {}, properties ), + opts: jQuery.extend( true, { + specialEasing: {}, + easing: jQuery.easing._default + }, options ), + originalProperties: properties, + originalOptions: options, + startTime: fxNow || createFxNow(), + duration: options.duration, + tweens: [], + createTween: function( prop, end ) { + var tween = jQuery.Tween( elem, animation.opts, prop, end, + animation.opts.specialEasing[ prop ] || animation.opts.easing ); + animation.tweens.push( tween ); + return tween; + }, + stop: function( gotoEnd ) { + var index = 0, + + // If we are going to the end, we want to run all the tweens + // otherwise we skip this part + length = gotoEnd ? animation.tweens.length : 0; + if ( stopped ) { + return this; + } + stopped = true; + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( 1 ); + } + + // Resolve when we played the last frame; otherwise, reject + if ( gotoEnd ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + deferred.resolveWith( elem, [ animation, gotoEnd ] ); + } else { + deferred.rejectWith( elem, [ animation, gotoEnd ] ); + } + return this; + } + } ), + props = animation.props; + + propFilter( props, animation.opts.specialEasing ); + + for ( ; index < length; index++ ) { + result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts ); + if ( result ) { + if ( isFunction( result.stop ) ) { + jQuery._queueHooks( animation.elem, animation.opts.queue ).stop = + result.stop.bind( result ); + } + return result; + } + } + + jQuery.map( props, createTween, animation ); + + if ( isFunction( animation.opts.start ) ) { + animation.opts.start.call( elem, animation ); + } + + // Attach callbacks from options + animation + .progress( animation.opts.progress ) + .done( animation.opts.done, animation.opts.complete ) + .fail( animation.opts.fail ) + .always( animation.opts.always ); + + jQuery.fx.timer( + jQuery.extend( tick, { + elem: elem, + anim: animation, + queue: animation.opts.queue + } ) + ); + + return animation; +} + +jQuery.Animation = jQuery.extend( Animation, { + + tweeners: { + "*": [ function( prop, value ) { + var tween = this.createTween( prop, value ); + adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween ); + return tween; + } ] + }, + + tweener: function( props, callback ) { + if ( isFunction( props ) ) { + callback = props; + props = [ "*" ]; + } else { + props = props.match( rnothtmlwhite ); + } + + var prop, + index = 0, + length = props.length; + + for ( ; index < length; index++ ) { + prop = props[ index ]; + Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || []; + Animation.tweeners[ prop ].unshift( callback ); + } + }, + + prefilters: [ defaultPrefilter ], + + prefilter: function( callback, prepend ) { + if ( prepend ) { + Animation.prefilters.unshift( callback ); + } else { + Animation.prefilters.push( callback ); + } + } +} ); + +jQuery.speed = function( speed, easing, fn ) { + var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : { + complete: fn || !fn && easing || + isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !isFunction( easing ) && easing + }; + + // Go to the end state if fx are off + if ( jQuery.fx.off ) { + opt.duration = 0; + + } else { + if ( typeof opt.duration !== "number" ) { + if ( opt.duration in jQuery.fx.speeds ) { + opt.duration = jQuery.fx.speeds[ opt.duration ]; + + } else { + opt.duration = jQuery.fx.speeds._default; + } + } + } + + // Normalize opt.queue - true/undefined/null -> "fx" + if ( opt.queue == null || opt.queue === true ) { + opt.queue = "fx"; + } + + // Queueing + opt.old = opt.complete; + + opt.complete = function() { + if ( isFunction( opt.old ) ) { + opt.old.call( this ); + } + + if ( opt.queue ) { + jQuery.dequeue( this, opt.queue ); + } + }; + + return opt; +}; + +jQuery.fn.extend( { + fadeTo: function( speed, to, easing, callback ) { + + // Show any hidden elements after setting opacity to 0 + return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show() + + // Animate to the value specified + .end().animate( { opacity: to }, speed, easing, callback ); + }, + animate: function( prop, speed, easing, callback ) { + var empty = jQuery.isEmptyObject( prop ), + optall = jQuery.speed( speed, easing, callback ), + doAnimation = function() { + + // Operate on a copy of prop so per-property easing won't be lost + var anim = Animation( this, jQuery.extend( {}, prop ), optall ); + + // Empty animations, or finishing resolves immediately + if ( empty || dataPriv.get( this, "finish" ) ) { + anim.stop( true ); + } + }; + + doAnimation.finish = doAnimation; + + return empty || optall.queue === false ? + this.each( doAnimation ) : + this.queue( optall.queue, doAnimation ); + }, + stop: function( type, clearQueue, gotoEnd ) { + var stopQueue = function( hooks ) { + var stop = hooks.stop; + delete hooks.stop; + stop( gotoEnd ); + }; + + if ( typeof type !== "string" ) { + gotoEnd = clearQueue; + clearQueue = type; + type = undefined; + } + if ( clearQueue ) { + this.queue( type || "fx", [] ); + } + + return this.each( function() { + var dequeue = true, + index = type != null && type + "queueHooks", + timers = jQuery.timers, + data = dataPriv.get( this ); + + if ( index ) { + if ( data[ index ] && data[ index ].stop ) { + stopQueue( data[ index ] ); + } + } else { + for ( index in data ) { + if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) { + stopQueue( data[ index ] ); + } + } + } + + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && + ( type == null || timers[ index ].queue === type ) ) { + + timers[ index ].anim.stop( gotoEnd ); + dequeue = false; + timers.splice( index, 1 ); + } + } + + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. + if ( dequeue || !gotoEnd ) { + jQuery.dequeue( this, type ); + } + } ); + }, + finish: function( type ) { + if ( type !== false ) { + type = type || "fx"; + } + return this.each( function() { + var index, + data = dataPriv.get( this ), + queue = data[ type + "queue" ], + hooks = data[ type + "queueHooks" ], + timers = jQuery.timers, + length = queue ? queue.length : 0; + + // Enable finishing flag on private data + data.finish = true; + + // Empty the queue first + jQuery.queue( this, type, [] ); + + if ( hooks && hooks.stop ) { + hooks.stop.call( this, true ); + } + + // Look for any active animations, and finish them + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && timers[ index ].queue === type ) { + timers[ index ].anim.stop( true ); + timers.splice( index, 1 ); + } + } + + // Look for any animations in the old queue and finish them + for ( index = 0; index < length; index++ ) { + if ( queue[ index ] && queue[ index ].finish ) { + queue[ index ].finish.call( this ); + } + } + + // Turn off finishing flag + delete data.finish; + } ); + } +} ); + +jQuery.each( [ "toggle", "show", "hide" ], function( _i, name ) { + var cssFn = jQuery.fn[ name ]; + jQuery.fn[ name ] = function( speed, easing, callback ) { + return speed == null || typeof speed === "boolean" ? + cssFn.apply( this, arguments ) : + this.animate( genFx( name, true ), speed, easing, callback ); + }; +} ); + +// Generate shortcuts for custom animations +jQuery.each( { + slideDown: genFx( "show" ), + slideUp: genFx( "hide" ), + slideToggle: genFx( "toggle" ), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" }, + fadeToggle: { opacity: "toggle" } +}, function( name, props ) { + jQuery.fn[ name ] = function( speed, easing, callback ) { + return this.animate( props, speed, easing, callback ); + }; +} ); + +jQuery.timers = []; +jQuery.fx.tick = function() { + var timer, + i = 0, + timers = jQuery.timers; + + fxNow = Date.now(); + + for ( ; i < timers.length; i++ ) { + timer = timers[ i ]; + + // Run the timer and safely remove it when done (allowing for external removal) + if ( !timer() && timers[ i ] === timer ) { + timers.splice( i--, 1 ); + } + } + + if ( !timers.length ) { + jQuery.fx.stop(); + } + fxNow = undefined; +}; + +jQuery.fx.timer = function( timer ) { + jQuery.timers.push( timer ); + jQuery.fx.start(); +}; + +jQuery.fx.interval = 13; +jQuery.fx.start = function() { + if ( inProgress ) { + return; + } + + inProgress = true; + schedule(); +}; + +jQuery.fx.stop = function() { + inProgress = null; +}; + +jQuery.fx.speeds = { + slow: 600, + fast: 200, + + // Default speed + _default: 400 +}; + + +// Based off of the plugin by Clint Helfers, with permission. +// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/ +jQuery.fn.delay = function( time, type ) { + time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time; + type = type || "fx"; + + return this.queue( type, function( next, hooks ) { + var timeout = window.setTimeout( next, time ); + hooks.stop = function() { + window.clearTimeout( timeout ); + }; + } ); +}; + + +( function() { + var input = document.createElement( "input" ), + select = document.createElement( "select" ), + opt = select.appendChild( document.createElement( "option" ) ); + + input.type = "checkbox"; + + // Support: Android <=4.3 only + // Default value for a checkbox should be "on" + support.checkOn = input.value !== ""; + + // Support: IE <=11 only + // Must access selectedIndex to make default options select + support.optSelected = opt.selected; + + // Support: IE <=11 only + // An input loses its value after becoming a radio + input = document.createElement( "input" ); + input.value = "t"; + input.type = "radio"; + support.radioValue = input.value === "t"; +} )(); + + +var boolHook, + attrHandle = jQuery.expr.attrHandle; + +jQuery.fn.extend( { + attr: function( name, value ) { + return access( this, jQuery.attr, name, value, arguments.length > 1 ); + }, + + removeAttr: function( name ) { + return this.each( function() { + jQuery.removeAttr( this, name ); + } ); + } +} ); + +jQuery.extend( { + attr: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set attributes on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + // Fallback to prop when attributes are not supported + if ( typeof elem.getAttribute === "undefined" ) { + return jQuery.prop( elem, name, value ); + } + + // Attribute hooks are determined by the lowercase version + // Grab necessary hook if one is defined + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + hooks = jQuery.attrHooks[ name.toLowerCase() ] || + ( jQuery.expr.match.bool.test( name ) ? boolHook : undefined ); + } + + if ( value !== undefined ) { + if ( value === null ) { + jQuery.removeAttr( elem, name ); + return; + } + + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + elem.setAttribute( name, value + "" ); + return value; + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + ret = jQuery.find.attr( elem, name ); + + // Non-existent attributes return null, we normalize to undefined + return ret == null ? undefined : ret; + }, + + attrHooks: { + type: { + set: function( elem, value ) { + if ( !support.radioValue && value === "radio" && + nodeName( elem, "input" ) ) { + var val = elem.value; + elem.setAttribute( "type", value ); + if ( val ) { + elem.value = val; + } + return value; + } + } + } + }, + + removeAttr: function( elem, value ) { + var name, + i = 0, + + // Attribute names can contain non-HTML whitespace characters + // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 + attrNames = value && value.match( rnothtmlwhite ); + + if ( attrNames && elem.nodeType === 1 ) { + while ( ( name = attrNames[ i++ ] ) ) { + elem.removeAttribute( name ); + } + } + } +} ); + +// Hooks for boolean attributes +boolHook = { + set: function( elem, value, name ) { + if ( value === false ) { + + // Remove boolean attributes when set to false + jQuery.removeAttr( elem, name ); + } else { + elem.setAttribute( name, name ); + } + return name; + } +}; + +jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( _i, name ) { + var getter = attrHandle[ name ] || jQuery.find.attr; + + attrHandle[ name ] = function( elem, name, isXML ) { + var ret, handle, + lowercaseName = name.toLowerCase(); + + if ( !isXML ) { + + // Avoid an infinite loop by temporarily removing this function from the getter + handle = attrHandle[ lowercaseName ]; + attrHandle[ lowercaseName ] = ret; + ret = getter( elem, name, isXML ) != null ? + lowercaseName : + null; + attrHandle[ lowercaseName ] = handle; + } + return ret; + }; +} ); + + + + +var rfocusable = /^(?:input|select|textarea|button)$/i, + rclickable = /^(?:a|area)$/i; + +jQuery.fn.extend( { + prop: function( name, value ) { + return access( this, jQuery.prop, name, value, arguments.length > 1 ); + }, + + removeProp: function( name ) { + return this.each( function() { + delete this[ jQuery.propFix[ name ] || name ]; + } ); + } +} ); + +jQuery.extend( { + prop: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set properties on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + + // Fix name and attach hooks + name = jQuery.propFix[ name ] || name; + hooks = jQuery.propHooks[ name ]; + } + + if ( value !== undefined ) { + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + return ( elem[ name ] = value ); + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + return elem[ name ]; + }, + + propHooks: { + tabIndex: { + get: function( elem ) { + + // Support: IE <=9 - 11 only + // elem.tabIndex doesn't always return the + // correct value when it hasn't been explicitly set + // https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + // Use proper attribute retrieval(#12072) + var tabindex = jQuery.find.attr( elem, "tabindex" ); + + if ( tabindex ) { + return parseInt( tabindex, 10 ); + } + + if ( + rfocusable.test( elem.nodeName ) || + rclickable.test( elem.nodeName ) && + elem.href + ) { + return 0; + } + + return -1; + } + } + }, + + propFix: { + "for": "htmlFor", + "class": "className" + } +} ); + +// Support: IE <=11 only +// Accessing the selectedIndex property +// forces the browser to respect setting selected +// on the option +// The getter ensures a default option is selected +// when in an optgroup +// eslint rule "no-unused-expressions" is disabled for this code +// since it considers such accessions noop +if ( !support.optSelected ) { + jQuery.propHooks.selected = { + get: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent && parent.parentNode ) { + parent.parentNode.selectedIndex; + } + return null; + }, + set: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent ) { + parent.selectedIndex; + + if ( parent.parentNode ) { + parent.parentNode.selectedIndex; + } + } + } + }; +} + +jQuery.each( [ + "tabIndex", + "readOnly", + "maxLength", + "cellSpacing", + "cellPadding", + "rowSpan", + "colSpan", + "useMap", + "frameBorder", + "contentEditable" +], function() { + jQuery.propFix[ this.toLowerCase() ] = this; +} ); + + + + + // Strip and collapse whitespace according to HTML spec + // https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace + function stripAndCollapse( value ) { + var tokens = value.match( rnothtmlwhite ) || []; + return tokens.join( " " ); + } + + +function getClass( elem ) { + return elem.getAttribute && elem.getAttribute( "class" ) || ""; +} + +function classesToArray( value ) { + if ( Array.isArray( value ) ) { + return value; + } + if ( typeof value === "string" ) { + return value.match( rnothtmlwhite ) || []; + } + return []; +} + +jQuery.fn.extend( { + addClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).addClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + if ( cur.indexOf( " " + clazz + " " ) < 0 ) { + cur += clazz + " "; + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + removeClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + if ( !arguments.length ) { + return this.attr( "class", "" ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + + // This expression is here for better compressibility (see addClass) + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + + // Remove *all* instances + while ( cur.indexOf( " " + clazz + " " ) > -1 ) { + cur = cur.replace( " " + clazz + " ", " " ); + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + toggleClass: function( value, stateVal ) { + var type = typeof value, + isValidValue = type === "string" || Array.isArray( value ); + + if ( typeof stateVal === "boolean" && isValidValue ) { + return stateVal ? this.addClass( value ) : this.removeClass( value ); + } + + if ( isFunction( value ) ) { + return this.each( function( i ) { + jQuery( this ).toggleClass( + value.call( this, i, getClass( this ), stateVal ), + stateVal + ); + } ); + } + + return this.each( function() { + var className, i, self, classNames; + + if ( isValidValue ) { + + // Toggle individual class names + i = 0; + self = jQuery( this ); + classNames = classesToArray( value ); + + while ( ( className = classNames[ i++ ] ) ) { + + // Check each className given, space separated list + if ( self.hasClass( className ) ) { + self.removeClass( className ); + } else { + self.addClass( className ); + } + } + + // Toggle whole class name + } else if ( value === undefined || type === "boolean" ) { + className = getClass( this ); + if ( className ) { + + // Store className if set + dataPriv.set( this, "__className__", className ); + } + + // If the element has a class name or if we're passed `false`, + // then remove the whole classname (if there was one, the above saved it). + // Otherwise bring back whatever was previously saved (if anything), + // falling back to the empty string if nothing was stored. + if ( this.setAttribute ) { + this.setAttribute( "class", + className || value === false ? + "" : + dataPriv.get( this, "__className__" ) || "" + ); + } + } + } ); + }, + + hasClass: function( selector ) { + var className, elem, + i = 0; + + className = " " + selector + " "; + while ( ( elem = this[ i++ ] ) ) { + if ( elem.nodeType === 1 && + ( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) { + return true; + } + } + + return false; + } +} ); + + + + +var rreturn = /\r/g; + +jQuery.fn.extend( { + val: function( value ) { + var hooks, ret, valueIsFunction, + elem = this[ 0 ]; + + if ( !arguments.length ) { + if ( elem ) { + hooks = jQuery.valHooks[ elem.type ] || + jQuery.valHooks[ elem.nodeName.toLowerCase() ]; + + if ( hooks && + "get" in hooks && + ( ret = hooks.get( elem, "value" ) ) !== undefined + ) { + return ret; + } + + ret = elem.value; + + // Handle most common string cases + if ( typeof ret === "string" ) { + return ret.replace( rreturn, "" ); + } + + // Handle cases where value is null/undef or number + return ret == null ? "" : ret; + } + + return; + } + + valueIsFunction = isFunction( value ); + + return this.each( function( i ) { + var val; + + if ( this.nodeType !== 1 ) { + return; + } + + if ( valueIsFunction ) { + val = value.call( this, i, jQuery( this ).val() ); + } else { + val = value; + } + + // Treat null/undefined as ""; convert numbers to string + if ( val == null ) { + val = ""; + + } else if ( typeof val === "number" ) { + val += ""; + + } else if ( Array.isArray( val ) ) { + val = jQuery.map( val, function( value ) { + return value == null ? "" : value + ""; + } ); + } + + hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ]; + + // If set returns undefined, fall back to normal setting + if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) { + this.value = val; + } + } ); + } +} ); + +jQuery.extend( { + valHooks: { + option: { + get: function( elem ) { + + var val = jQuery.find.attr( elem, "value" ); + return val != null ? + val : + + // Support: IE <=10 - 11 only + // option.text throws exceptions (#14686, #14858) + // Strip and collapse whitespace + // https://html.spec.whatwg.org/#strip-and-collapse-whitespace + stripAndCollapse( jQuery.text( elem ) ); + } + }, + select: { + get: function( elem ) { + var value, option, i, + options = elem.options, + index = elem.selectedIndex, + one = elem.type === "select-one", + values = one ? null : [], + max = one ? index + 1 : options.length; + + if ( index < 0 ) { + i = max; + + } else { + i = one ? index : 0; + } + + // Loop through all the selected options + for ( ; i < max; i++ ) { + option = options[ i ]; + + // Support: IE <=9 only + // IE8-9 doesn't update selected after form reset (#2551) + if ( ( option.selected || i === index ) && + + // Don't return options that are disabled or in a disabled optgroup + !option.disabled && + ( !option.parentNode.disabled || + !nodeName( option.parentNode, "optgroup" ) ) ) { + + // Get the specific value for the option + value = jQuery( option ).val(); + + // We don't need an array for one selects + if ( one ) { + return value; + } + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + }, + + set: function( elem, value ) { + var optionSet, option, + options = elem.options, + values = jQuery.makeArray( value ), + i = options.length; + + while ( i-- ) { + option = options[ i ]; + + /* eslint-disable no-cond-assign */ + + if ( option.selected = + jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1 + ) { + optionSet = true; + } + + /* eslint-enable no-cond-assign */ + } + + // Force browsers to behave consistently when non-matching value is set + if ( !optionSet ) { + elem.selectedIndex = -1; + } + return values; + } + } + } +} ); + +// Radios and checkboxes getter/setter +jQuery.each( [ "radio", "checkbox" ], function() { + jQuery.valHooks[ this ] = { + set: function( elem, value ) { + if ( Array.isArray( value ) ) { + return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 ); + } + } + }; + if ( !support.checkOn ) { + jQuery.valHooks[ this ].get = function( elem ) { + return elem.getAttribute( "value" ) === null ? "on" : elem.value; + }; + } +} ); + + + + +// Return jQuery for attributes-only inclusion + + +support.focusin = "onfocusin" in window; + + +var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/, + stopPropagationCallback = function( e ) { + e.stopPropagation(); + }; + +jQuery.extend( jQuery.event, { + + trigger: function( event, data, elem, onlyHandlers ) { + + var i, cur, tmp, bubbleType, ontype, handle, special, lastElement, + eventPath = [ elem || document ], + type = hasOwn.call( event, "type" ) ? event.type : event, + namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : []; + + cur = lastElement = tmp = elem = elem || document; + + // Don't do events on text and comment nodes + if ( elem.nodeType === 3 || elem.nodeType === 8 ) { + return; + } + + // focus/blur morphs to focusin/out; ensure we're not firing them right now + if ( rfocusMorph.test( type + jQuery.event.triggered ) ) { + return; + } + + if ( type.indexOf( "." ) > -1 ) { + + // Namespaced trigger; create a regexp to match event type in handle() + namespaces = type.split( "." ); + type = namespaces.shift(); + namespaces.sort(); + } + ontype = type.indexOf( ":" ) < 0 && "on" + type; + + // Caller can pass in a jQuery.Event object, Object, or just an event type string + event = event[ jQuery.expando ] ? + event : + new jQuery.Event( type, typeof event === "object" && event ); + + // Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true) + event.isTrigger = onlyHandlers ? 2 : 3; + event.namespace = namespaces.join( "." ); + event.rnamespace = event.namespace ? + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) : + null; + + // Clean up the event in case it is being reused + event.result = undefined; + if ( !event.target ) { + event.target = elem; + } + + // Clone any incoming data and prepend the event, creating the handler arg list + data = data == null ? + [ event ] : + jQuery.makeArray( data, [ event ] ); + + // Allow special events to draw outside the lines + special = jQuery.event.special[ type ] || {}; + if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) { + return; + } + + // Determine event propagation path in advance, per W3C events spec (#9951) + // Bubble up to document, then to window; watch for a global ownerDocument var (#9724) + if ( !onlyHandlers && !special.noBubble && !isWindow( elem ) ) { + + bubbleType = special.delegateType || type; + if ( !rfocusMorph.test( bubbleType + type ) ) { + cur = cur.parentNode; + } + for ( ; cur; cur = cur.parentNode ) { + eventPath.push( cur ); + tmp = cur; + } + + // Only add window if we got to document (e.g., not plain obj or detached DOM) + if ( tmp === ( elem.ownerDocument || document ) ) { + eventPath.push( tmp.defaultView || tmp.parentWindow || window ); + } + } + + // Fire handlers on the event path + i = 0; + while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) { + lastElement = cur; + event.type = i > 1 ? + bubbleType : + special.bindType || type; + + // jQuery handler + handle = ( dataPriv.get( cur, "events" ) || Object.create( null ) )[ event.type ] && + dataPriv.get( cur, "handle" ); + if ( handle ) { + handle.apply( cur, data ); + } + + // Native handler + handle = ontype && cur[ ontype ]; + if ( handle && handle.apply && acceptData( cur ) ) { + event.result = handle.apply( cur, data ); + if ( event.result === false ) { + event.preventDefault(); + } + } + } + event.type = type; + + // If nobody prevented the default action, do it now + if ( !onlyHandlers && !event.isDefaultPrevented() ) { + + if ( ( !special._default || + special._default.apply( eventPath.pop(), data ) === false ) && + acceptData( elem ) ) { + + // Call a native DOM method on the target with the same name as the event. + // Don't do default actions on window, that's where global variables be (#6170) + if ( ontype && isFunction( elem[ type ] ) && !isWindow( elem ) ) { + + // Don't re-trigger an onFOO event when we call its FOO() method + tmp = elem[ ontype ]; + + if ( tmp ) { + elem[ ontype ] = null; + } + + // Prevent re-triggering of the same event, since we already bubbled it above + jQuery.event.triggered = type; + + if ( event.isPropagationStopped() ) { + lastElement.addEventListener( type, stopPropagationCallback ); + } + + elem[ type ](); + + if ( event.isPropagationStopped() ) { + lastElement.removeEventListener( type, stopPropagationCallback ); + } + + jQuery.event.triggered = undefined; + + if ( tmp ) { + elem[ ontype ] = tmp; + } + } + } + } + + return event.result; + }, + + // Piggyback on a donor event to simulate a different one + // Used only for `focus(in | out)` events + simulate: function( type, elem, event ) { + var e = jQuery.extend( + new jQuery.Event(), + event, + { + type: type, + isSimulated: true + } + ); + + jQuery.event.trigger( e, null, elem ); + } + +} ); + +jQuery.fn.extend( { + + trigger: function( type, data ) { + return this.each( function() { + jQuery.event.trigger( type, data, this ); + } ); + }, + triggerHandler: function( type, data ) { + var elem = this[ 0 ]; + if ( elem ) { + return jQuery.event.trigger( type, data, elem, true ); + } + } +} ); + + +// Support: Firefox <=44 +// Firefox doesn't have focus(in | out) events +// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787 +// +// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1 +// focus(in | out) events fire after focus & blur events, +// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order +// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857 +if ( !support.focusin ) { + jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) { + + // Attach a single capturing handler on the document while someone wants focusin/focusout + var handler = function( event ) { + jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) ); + }; + + jQuery.event.special[ fix ] = { + setup: function() { + + // Handle: regular nodes (via `this.ownerDocument`), window + // (via `this.document`) & document (via `this`). + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ); + + if ( !attaches ) { + doc.addEventListener( orig, handler, true ); + } + dataPriv.access( doc, fix, ( attaches || 0 ) + 1 ); + }, + teardown: function() { + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ) - 1; + + if ( !attaches ) { + doc.removeEventListener( orig, handler, true ); + dataPriv.remove( doc, fix ); + + } else { + dataPriv.access( doc, fix, attaches ); + } + } + }; + } ); +} +var location = window.location; + +var nonce = { guid: Date.now() }; + +var rquery = ( /\?/ ); + + + +// Cross-browser xml parsing +jQuery.parseXML = function( data ) { + var xml, parserErrorElem; + if ( !data || typeof data !== "string" ) { + return null; + } + + // Support: IE 9 - 11 only + // IE throws on parseFromString with invalid input. + try { + xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" ); + } catch ( e ) {} + + parserErrorElem = xml && xml.getElementsByTagName( "parsererror" )[ 0 ]; + if ( !xml || parserErrorElem ) { + jQuery.error( "Invalid XML: " + ( + parserErrorElem ? + jQuery.map( parserErrorElem.childNodes, function( el ) { + return el.textContent; + } ).join( "\n" ) : + data + ) ); + } + return xml; +}; + + +var + rbracket = /\[\]$/, + rCRLF = /\r?\n/g, + rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i, + rsubmittable = /^(?:input|select|textarea|keygen)/i; + +function buildParams( prefix, obj, traditional, add ) { + var name; + + if ( Array.isArray( obj ) ) { + + // Serialize array item. + jQuery.each( obj, function( i, v ) { + if ( traditional || rbracket.test( prefix ) ) { + + // Treat each array item as a scalar. + add( prefix, v ); + + } else { + + // Item is non-scalar (array or object), encode its numeric index. + buildParams( + prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]", + v, + traditional, + add + ); + } + } ); + + } else if ( !traditional && toType( obj ) === "object" ) { + + // Serialize object item. + for ( name in obj ) { + buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add ); + } + + } else { + + // Serialize scalar item. + add( prefix, obj ); + } +} + +// Serialize an array of form elements or a set of +// key/values into a query string +jQuery.param = function( a, traditional ) { + var prefix, + s = [], + add = function( key, valueOrFunction ) { + + // If value is a function, invoke it and use its return value + var value = isFunction( valueOrFunction ) ? + valueOrFunction() : + valueOrFunction; + + s[ s.length ] = encodeURIComponent( key ) + "=" + + encodeURIComponent( value == null ? "" : value ); + }; + + if ( a == null ) { + return ""; + } + + // If an array was passed in, assume that it is an array of form elements. + if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) { + + // Serialize the form elements + jQuery.each( a, function() { + add( this.name, this.value ); + } ); + + } else { + + // If traditional, encode the "old" way (the way 1.3.2 or older + // did it), otherwise encode params recursively. + for ( prefix in a ) { + buildParams( prefix, a[ prefix ], traditional, add ); + } + } + + // Return the resulting serialization + return s.join( "&" ); +}; + +jQuery.fn.extend( { + serialize: function() { + return jQuery.param( this.serializeArray() ); + }, + serializeArray: function() { + return this.map( function() { + + // Can add propHook for "elements" to filter or add form elements + var elements = jQuery.prop( this, "elements" ); + return elements ? jQuery.makeArray( elements ) : this; + } ).filter( function() { + var type = this.type; + + // Use .is( ":disabled" ) so that fieldset[disabled] works + return this.name && !jQuery( this ).is( ":disabled" ) && + rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) && + ( this.checked || !rcheckableType.test( type ) ); + } ).map( function( _i, elem ) { + var val = jQuery( this ).val(); + + if ( val == null ) { + return null; + } + + if ( Array.isArray( val ) ) { + return jQuery.map( val, function( val ) { + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ); + } + + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ).get(); + } +} ); + + +var + r20 = /%20/g, + rhash = /#.*$/, + rantiCache = /([?&])_=[^&]*/, + rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg, + + // #7653, #8125, #8152: local protocol detection + rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/, + rnoContent = /^(?:GET|HEAD)$/, + rprotocol = /^\/\//, + + /* Prefilters + * 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example) + * 2) These are called: + * - BEFORE asking for a transport + * - AFTER param serialization (s.data is a string if s.processData is true) + * 3) key is the dataType + * 4) the catchall symbol "*" can be used + * 5) execution will start with transport dataType and THEN continue down to "*" if needed + */ + prefilters = {}, + + /* Transports bindings + * 1) key is the dataType + * 2) the catchall symbol "*" can be used + * 3) selection will start with transport dataType and THEN go to "*" if needed + */ + transports = {}, + + // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression + allTypes = "*/".concat( "*" ), + + // Anchor tag for parsing the document origin + originAnchor = document.createElement( "a" ); + +originAnchor.href = location.href; + +// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport +function addToPrefiltersOrTransports( structure ) { + + // dataTypeExpression is optional and defaults to "*" + return function( dataTypeExpression, func ) { + + if ( typeof dataTypeExpression !== "string" ) { + func = dataTypeExpression; + dataTypeExpression = "*"; + } + + var dataType, + i = 0, + dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || []; + + if ( isFunction( func ) ) { + + // For each dataType in the dataTypeExpression + while ( ( dataType = dataTypes[ i++ ] ) ) { + + // Prepend if requested + if ( dataType[ 0 ] === "+" ) { + dataType = dataType.slice( 1 ) || "*"; + ( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func ); + + // Otherwise append + } else { + ( structure[ dataType ] = structure[ dataType ] || [] ).push( func ); + } + } + } + }; +} + +// Base inspection function for prefilters and transports +function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) { + + var inspected = {}, + seekingTransport = ( structure === transports ); + + function inspect( dataType ) { + var selected; + inspected[ dataType ] = true; + jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) { + var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR ); + if ( typeof dataTypeOrTransport === "string" && + !seekingTransport && !inspected[ dataTypeOrTransport ] ) { + + options.dataTypes.unshift( dataTypeOrTransport ); + inspect( dataTypeOrTransport ); + return false; + } else if ( seekingTransport ) { + return !( selected = dataTypeOrTransport ); + } + } ); + return selected; + } + + return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" ); +} + +// A special extend for ajax options +// that takes "flat" options (not to be deep extended) +// Fixes #9887 +function ajaxExtend( target, src ) { + var key, deep, + flatOptions = jQuery.ajaxSettings.flatOptions || {}; + + for ( key in src ) { + if ( src[ key ] !== undefined ) { + ( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ]; + } + } + if ( deep ) { + jQuery.extend( true, target, deep ); + } + + return target; +} + +/* Handles responses to an ajax request: + * - finds the right dataType (mediates between content-type and expected dataType) + * - returns the corresponding response + */ +function ajaxHandleResponses( s, jqXHR, responses ) { + + var ct, type, finalDataType, firstDataType, + contents = s.contents, + dataTypes = s.dataTypes; + + // Remove auto dataType and get content-type in the process + while ( dataTypes[ 0 ] === "*" ) { + dataTypes.shift(); + if ( ct === undefined ) { + ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" ); + } + } + + // Check if we're dealing with a known content-type + if ( ct ) { + for ( type in contents ) { + if ( contents[ type ] && contents[ type ].test( ct ) ) { + dataTypes.unshift( type ); + break; + } + } + } + + // Check to see if we have a response for the expected dataType + if ( dataTypes[ 0 ] in responses ) { + finalDataType = dataTypes[ 0 ]; + } else { + + // Try convertible dataTypes + for ( type in responses ) { + if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) { + finalDataType = type; + break; + } + if ( !firstDataType ) { + firstDataType = type; + } + } + + // Or just use first one + finalDataType = finalDataType || firstDataType; + } + + // If we found a dataType + // We add the dataType to the list if needed + // and return the corresponding response + if ( finalDataType ) { + if ( finalDataType !== dataTypes[ 0 ] ) { + dataTypes.unshift( finalDataType ); + } + return responses[ finalDataType ]; + } +} + +/* Chain conversions given the request and the original response + * Also sets the responseXXX fields on the jqXHR instance + */ +function ajaxConvert( s, response, jqXHR, isSuccess ) { + var conv2, current, conv, tmp, prev, + converters = {}, + + // Work with a copy of dataTypes in case we need to modify it for conversion + dataTypes = s.dataTypes.slice(); + + // Create converters map with lowercased keys + if ( dataTypes[ 1 ] ) { + for ( conv in s.converters ) { + converters[ conv.toLowerCase() ] = s.converters[ conv ]; + } + } + + current = dataTypes.shift(); + + // Convert to each sequential dataType + while ( current ) { + + if ( s.responseFields[ current ] ) { + jqXHR[ s.responseFields[ current ] ] = response; + } + + // Apply the dataFilter if provided + if ( !prev && isSuccess && s.dataFilter ) { + response = s.dataFilter( response, s.dataType ); + } + + prev = current; + current = dataTypes.shift(); + + if ( current ) { + + // There's only work to do if current dataType is non-auto + if ( current === "*" ) { + + current = prev; + + // Convert response if prev dataType is non-auto and differs from current + } else if ( prev !== "*" && prev !== current ) { + + // Seek a direct converter + conv = converters[ prev + " " + current ] || converters[ "* " + current ]; + + // If none found, seek a pair + if ( !conv ) { + for ( conv2 in converters ) { + + // If conv2 outputs current + tmp = conv2.split( " " ); + if ( tmp[ 1 ] === current ) { + + // If prev can be converted to accepted input + conv = converters[ prev + " " + tmp[ 0 ] ] || + converters[ "* " + tmp[ 0 ] ]; + if ( conv ) { + + // Condense equivalence converters + if ( conv === true ) { + conv = converters[ conv2 ]; + + // Otherwise, insert the intermediate dataType + } else if ( converters[ conv2 ] !== true ) { + current = tmp[ 0 ]; + dataTypes.unshift( tmp[ 1 ] ); + } + break; + } + } + } + } + + // Apply converter (if not an equivalence) + if ( conv !== true ) { + + // Unless errors are allowed to bubble, catch and return them + if ( conv && s.throws ) { + response = conv( response ); + } else { + try { + response = conv( response ); + } catch ( e ) { + return { + state: "parsererror", + error: conv ? e : "No conversion from " + prev + " to " + current + }; + } + } + } + } + } + } + + return { state: "success", data: response }; +} + +jQuery.extend( { + + // Counter for holding the number of active queries + active: 0, + + // Last-Modified header cache for next request + lastModified: {}, + etag: {}, + + ajaxSettings: { + url: location.href, + type: "GET", + isLocal: rlocalProtocol.test( location.protocol ), + global: true, + processData: true, + async: true, + contentType: "application/x-www-form-urlencoded; charset=UTF-8", + + /* + timeout: 0, + data: null, + dataType: null, + username: null, + password: null, + cache: null, + throws: false, + traditional: false, + headers: {}, + */ + + accepts: { + "*": allTypes, + text: "text/plain", + html: "text/html", + xml: "application/xml, text/xml", + json: "application/json, text/javascript" + }, + + contents: { + xml: /\bxml\b/, + html: /\bhtml/, + json: /\bjson\b/ + }, + + responseFields: { + xml: "responseXML", + text: "responseText", + json: "responseJSON" + }, + + // Data converters + // Keys separate source (or catchall "*") and destination types with a single space + converters: { + + // Convert anything to text + "* text": String, + + // Text to html (true = no transformation) + "text html": true, + + // Evaluate text as a json expression + "text json": JSON.parse, + + // Parse text as xml + "text xml": jQuery.parseXML + }, + + // For options that shouldn't be deep extended: + // you can add your own custom options here if + // and when you create one that shouldn't be + // deep extended (see ajaxExtend) + flatOptions: { + url: true, + context: true + } + }, + + // Creates a full fledged settings object into target + // with both ajaxSettings and settings fields. + // If target is omitted, writes into ajaxSettings. + ajaxSetup: function( target, settings ) { + return settings ? + + // Building a settings object + ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) : + + // Extending ajaxSettings + ajaxExtend( jQuery.ajaxSettings, target ); + }, + + ajaxPrefilter: addToPrefiltersOrTransports( prefilters ), + ajaxTransport: addToPrefiltersOrTransports( transports ), + + // Main method + ajax: function( url, options ) { + + // If url is an object, simulate pre-1.5 signature + if ( typeof url === "object" ) { + options = url; + url = undefined; + } + + // Force options to be an object + options = options || {}; + + var transport, + + // URL without anti-cache param + cacheURL, + + // Response headers + responseHeadersString, + responseHeaders, + + // timeout handle + timeoutTimer, + + // Url cleanup var + urlAnchor, + + // Request state (becomes false upon send and true upon completion) + completed, + + // To know if global events are to be dispatched + fireGlobals, + + // Loop variable + i, + + // uncached part of the url + uncached, + + // Create the final options object + s = jQuery.ajaxSetup( {}, options ), + + // Callbacks context + callbackContext = s.context || s, + + // Context for global events is callbackContext if it is a DOM node or jQuery collection + globalEventContext = s.context && + ( callbackContext.nodeType || callbackContext.jquery ) ? + jQuery( callbackContext ) : + jQuery.event, + + // Deferreds + deferred = jQuery.Deferred(), + completeDeferred = jQuery.Callbacks( "once memory" ), + + // Status-dependent callbacks + statusCode = s.statusCode || {}, + + // Headers (they are sent all at once) + requestHeaders = {}, + requestHeadersNames = {}, + + // Default abort message + strAbort = "canceled", + + // Fake xhr + jqXHR = { + readyState: 0, + + // Builds headers hashtable if needed + getResponseHeader: function( key ) { + var match; + if ( completed ) { + if ( !responseHeaders ) { + responseHeaders = {}; + while ( ( match = rheaders.exec( responseHeadersString ) ) ) { + responseHeaders[ match[ 1 ].toLowerCase() + " " ] = + ( responseHeaders[ match[ 1 ].toLowerCase() + " " ] || [] ) + .concat( match[ 2 ] ); + } + } + match = responseHeaders[ key.toLowerCase() + " " ]; + } + return match == null ? null : match.join( ", " ); + }, + + // Raw string + getAllResponseHeaders: function() { + return completed ? responseHeadersString : null; + }, + + // Caches the header + setRequestHeader: function( name, value ) { + if ( completed == null ) { + name = requestHeadersNames[ name.toLowerCase() ] = + requestHeadersNames[ name.toLowerCase() ] || name; + requestHeaders[ name ] = value; + } + return this; + }, + + // Overrides response content-type header + overrideMimeType: function( type ) { + if ( completed == null ) { + s.mimeType = type; + } + return this; + }, + + // Status-dependent callbacks + statusCode: function( map ) { + var code; + if ( map ) { + if ( completed ) { + + // Execute the appropriate callbacks + jqXHR.always( map[ jqXHR.status ] ); + } else { + + // Lazy-add the new callbacks in a way that preserves old ones + for ( code in map ) { + statusCode[ code ] = [ statusCode[ code ], map[ code ] ]; + } + } + } + return this; + }, + + // Cancel the request + abort: function( statusText ) { + var finalText = statusText || strAbort; + if ( transport ) { + transport.abort( finalText ); + } + done( 0, finalText ); + return this; + } + }; + + // Attach deferreds + deferred.promise( jqXHR ); + + // Add protocol if not provided (prefilters might expect it) + // Handle falsy url in the settings object (#10093: consistency with old signature) + // We also use the url parameter if available + s.url = ( ( url || s.url || location.href ) + "" ) + .replace( rprotocol, location.protocol + "//" ); + + // Alias method option to type as per ticket #12004 + s.type = options.method || options.type || s.method || s.type; + + // Extract dataTypes list + s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ]; + + // A cross-domain request is in order when the origin doesn't match the current origin. + if ( s.crossDomain == null ) { + urlAnchor = document.createElement( "a" ); + + // Support: IE <=8 - 11, Edge 12 - 15 + // IE throws exception on accessing the href property if url is malformed, + // e.g. http://example.com:80x/ + try { + urlAnchor.href = s.url; + + // Support: IE <=8 - 11 only + // Anchor's host property isn't correctly set when s.url is relative + urlAnchor.href = urlAnchor.href; + s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !== + urlAnchor.protocol + "//" + urlAnchor.host; + } catch ( e ) { + + // If there is an error parsing the URL, assume it is crossDomain, + // it can be rejected by the transport if it is invalid + s.crossDomain = true; + } + } + + // Convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) { + s.data = jQuery.param( s.data, s.traditional ); + } + + // Apply prefilters + inspectPrefiltersOrTransports( prefilters, s, options, jqXHR ); + + // If request was aborted inside a prefilter, stop there + if ( completed ) { + return jqXHR; + } + + // We can fire global events as of now if asked to + // Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118) + fireGlobals = jQuery.event && s.global; + + // Watch for a new set of requests + if ( fireGlobals && jQuery.active++ === 0 ) { + jQuery.event.trigger( "ajaxStart" ); + } + + // Uppercase the type + s.type = s.type.toUpperCase(); + + // Determine if request has content + s.hasContent = !rnoContent.test( s.type ); + + // Save the URL in case we're toying with the If-Modified-Since + // and/or If-None-Match header later on + // Remove hash to simplify url manipulation + cacheURL = s.url.replace( rhash, "" ); + + // More options handling for requests with no content + if ( !s.hasContent ) { + + // Remember the hash so we can put it back + uncached = s.url.slice( cacheURL.length ); + + // If data is available and should be processed, append data to url + if ( s.data && ( s.processData || typeof s.data === "string" ) ) { + cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data; + + // #9682: remove data so that it's not used in an eventual retry + delete s.data; + } + + // Add or update anti-cache param if needed + if ( s.cache === false ) { + cacheURL = cacheURL.replace( rantiCache, "$1" ); + uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce.guid++ ) + + uncached; + } + + // Put hash and anti-cache on the URL that will be requested (gh-1732) + s.url = cacheURL + uncached; + + // Change '%20' to '+' if this is encoded form body content (gh-2658) + } else if ( s.data && s.processData && + ( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) { + s.data = s.data.replace( r20, "+" ); + } + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + if ( jQuery.lastModified[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] ); + } + if ( jQuery.etag[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] ); + } + } + + // Set the correct header, if data is being sent + if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) { + jqXHR.setRequestHeader( "Content-Type", s.contentType ); + } + + // Set the Accepts header for the server, depending on the dataType + jqXHR.setRequestHeader( + "Accept", + s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ? + s.accepts[ s.dataTypes[ 0 ] ] + + ( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) : + s.accepts[ "*" ] + ); + + // Check for headers option + for ( i in s.headers ) { + jqXHR.setRequestHeader( i, s.headers[ i ] ); + } + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && + ( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) { + + // Abort if not done already and return + return jqXHR.abort(); + } + + // Aborting is no longer a cancellation + strAbort = "abort"; + + // Install callbacks on deferreds + completeDeferred.add( s.complete ); + jqXHR.done( s.success ); + jqXHR.fail( s.error ); + + // Get transport + transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR ); + + // If no transport, we auto-abort + if ( !transport ) { + done( -1, "No Transport" ); + } else { + jqXHR.readyState = 1; + + // Send global event + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] ); + } + + // If request was aborted inside ajaxSend, stop there + if ( completed ) { + return jqXHR; + } + + // Timeout + if ( s.async && s.timeout > 0 ) { + timeoutTimer = window.setTimeout( function() { + jqXHR.abort( "timeout" ); + }, s.timeout ); + } + + try { + completed = false; + transport.send( requestHeaders, done ); + } catch ( e ) { + + // Rethrow post-completion exceptions + if ( completed ) { + throw e; + } + + // Propagate others as results + done( -1, e ); + } + } + + // Callback for when everything is done + function done( status, nativeStatusText, responses, headers ) { + var isSuccess, success, error, response, modified, + statusText = nativeStatusText; + + // Ignore repeat invocations + if ( completed ) { + return; + } + + completed = true; + + // Clear timeout if it exists + if ( timeoutTimer ) { + window.clearTimeout( timeoutTimer ); + } + + // Dereference transport for early garbage collection + // (no matter how long the jqXHR object will be used) + transport = undefined; + + // Cache response headers + responseHeadersString = headers || ""; + + // Set readyState + jqXHR.readyState = status > 0 ? 4 : 0; + + // Determine if successful + isSuccess = status >= 200 && status < 300 || status === 304; + + // Get response data + if ( responses ) { + response = ajaxHandleResponses( s, jqXHR, responses ); + } + + // Use a noop converter for missing script but not if jsonp + if ( !isSuccess && + jQuery.inArray( "script", s.dataTypes ) > -1 && + jQuery.inArray( "json", s.dataTypes ) < 0 ) { + s.converters[ "text script" ] = function() {}; + } + + // Convert no matter what (that way responseXXX fields are always set) + response = ajaxConvert( s, response, jqXHR, isSuccess ); + + // If successful, handle type chaining + if ( isSuccess ) { + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + modified = jqXHR.getResponseHeader( "Last-Modified" ); + if ( modified ) { + jQuery.lastModified[ cacheURL ] = modified; + } + modified = jqXHR.getResponseHeader( "etag" ); + if ( modified ) { + jQuery.etag[ cacheURL ] = modified; + } + } + + // if no content + if ( status === 204 || s.type === "HEAD" ) { + statusText = "nocontent"; + + // if not modified + } else if ( status === 304 ) { + statusText = "notmodified"; + + // If we have data, let's convert it + } else { + statusText = response.state; + success = response.data; + error = response.error; + isSuccess = !error; + } + } else { + + // Extract error from statusText and normalize for non-aborts + error = statusText; + if ( status || !statusText ) { + statusText = "error"; + if ( status < 0 ) { + status = 0; + } + } + } + + // Set data for the fake xhr object + jqXHR.status = status; + jqXHR.statusText = ( nativeStatusText || statusText ) + ""; + + // Success/Error + if ( isSuccess ) { + deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] ); + } else { + deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] ); + } + + // Status-dependent callbacks + jqXHR.statusCode( statusCode ); + statusCode = undefined; + + if ( fireGlobals ) { + globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError", + [ jqXHR, s, isSuccess ? success : error ] ); + } + + // Complete + completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] ); + + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] ); + + // Handle the global AJAX counter + if ( !( --jQuery.active ) ) { + jQuery.event.trigger( "ajaxStop" ); + } + } + } + + return jqXHR; + }, + + getJSON: function( url, data, callback ) { + return jQuery.get( url, data, callback, "json" ); + }, + + getScript: function( url, callback ) { + return jQuery.get( url, undefined, callback, "script" ); + } +} ); + +jQuery.each( [ "get", "post" ], function( _i, method ) { + jQuery[ method ] = function( url, data, callback, type ) { + + // Shift arguments if data argument was omitted + if ( isFunction( data ) ) { + type = type || callback; + callback = data; + data = undefined; + } + + // The url can be an options object (which then must have .url) + return jQuery.ajax( jQuery.extend( { + url: url, + type: method, + dataType: type, + data: data, + success: callback + }, jQuery.isPlainObject( url ) && url ) ); + }; +} ); + +jQuery.ajaxPrefilter( function( s ) { + var i; + for ( i in s.headers ) { + if ( i.toLowerCase() === "content-type" ) { + s.contentType = s.headers[ i ] || ""; + } + } +} ); + + +jQuery._evalUrl = function( url, options, doc ) { + return jQuery.ajax( { + url: url, + + // Make this explicit, since user can override this through ajaxSetup (#11264) + type: "GET", + dataType: "script", + cache: true, + async: false, + global: false, + + // Only evaluate the response if it is successful (gh-4126) + // dataFilter is not invoked for failure responses, so using it instead + // of the default converter is kludgy but it works. + converters: { + "text script": function() {} + }, + dataFilter: function( response ) { + jQuery.globalEval( response, options, doc ); + } + } ); +}; + + +jQuery.fn.extend( { + wrapAll: function( html ) { + var wrap; + + if ( this[ 0 ] ) { + if ( isFunction( html ) ) { + html = html.call( this[ 0 ] ); + } + + // The elements to wrap the target around + wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true ); + + if ( this[ 0 ].parentNode ) { + wrap.insertBefore( this[ 0 ] ); + } + + wrap.map( function() { + var elem = this; + + while ( elem.firstElementChild ) { + elem = elem.firstElementChild; + } + + return elem; + } ).append( this ); + } + + return this; + }, + + wrapInner: function( html ) { + if ( isFunction( html ) ) { + return this.each( function( i ) { + jQuery( this ).wrapInner( html.call( this, i ) ); + } ); + } + + return this.each( function() { + var self = jQuery( this ), + contents = self.contents(); + + if ( contents.length ) { + contents.wrapAll( html ); + + } else { + self.append( html ); + } + } ); + }, + + wrap: function( html ) { + var htmlIsFunction = isFunction( html ); + + return this.each( function( i ) { + jQuery( this ).wrapAll( htmlIsFunction ? html.call( this, i ) : html ); + } ); + }, + + unwrap: function( selector ) { + this.parent( selector ).not( "body" ).each( function() { + jQuery( this ).replaceWith( this.childNodes ); + } ); + return this; + } +} ); + + +jQuery.expr.pseudos.hidden = function( elem ) { + return !jQuery.expr.pseudos.visible( elem ); +}; +jQuery.expr.pseudos.visible = function( elem ) { + return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length ); +}; + + + + +jQuery.ajaxSettings.xhr = function() { + try { + return new window.XMLHttpRequest(); + } catch ( e ) {} +}; + +var xhrSuccessStatus = { + + // File protocol always yields status code 0, assume 200 + 0: 200, + + // Support: IE <=9 only + // #1450: sometimes IE returns 1223 when it should be 204 + 1223: 204 + }, + xhrSupported = jQuery.ajaxSettings.xhr(); + +support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported ); +support.ajax = xhrSupported = !!xhrSupported; + +jQuery.ajaxTransport( function( options ) { + var callback, errorCallback; + + // Cross domain only allowed if supported through XMLHttpRequest + if ( support.cors || xhrSupported && !options.crossDomain ) { + return { + send: function( headers, complete ) { + var i, + xhr = options.xhr(); + + xhr.open( + options.type, + options.url, + options.async, + options.username, + options.password + ); + + // Apply custom fields if provided + if ( options.xhrFields ) { + for ( i in options.xhrFields ) { + xhr[ i ] = options.xhrFields[ i ]; + } + } + + // Override mime type if needed + if ( options.mimeType && xhr.overrideMimeType ) { + xhr.overrideMimeType( options.mimeType ); + } + + // X-Requested-With header + // For cross-domain requests, seeing as conditions for a preflight are + // akin to a jigsaw puzzle, we simply never set it to be sure. + // (it can always be set on a per-request basis or even using ajaxSetup) + // For same-domain requests, won't change header if already provided. + if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) { + headers[ "X-Requested-With" ] = "XMLHttpRequest"; + } + + // Set headers + for ( i in headers ) { + xhr.setRequestHeader( i, headers[ i ] ); + } + + // Callback + callback = function( type ) { + return function() { + if ( callback ) { + callback = errorCallback = xhr.onload = + xhr.onerror = xhr.onabort = xhr.ontimeout = + xhr.onreadystatechange = null; + + if ( type === "abort" ) { + xhr.abort(); + } else if ( type === "error" ) { + + // Support: IE <=9 only + // On a manual native abort, IE9 throws + // errors on any property access that is not readyState + if ( typeof xhr.status !== "number" ) { + complete( 0, "error" ); + } else { + complete( + + // File: protocol always yields status 0; see #8605, #14207 + xhr.status, + xhr.statusText + ); + } + } else { + complete( + xhrSuccessStatus[ xhr.status ] || xhr.status, + xhr.statusText, + + // Support: IE <=9 only + // IE9 has no XHR2 but throws on binary (trac-11426) + // For XHR2 non-text, let the caller handle it (gh-2498) + ( xhr.responseType || "text" ) !== "text" || + typeof xhr.responseText !== "string" ? + { binary: xhr.response } : + { text: xhr.responseText }, + xhr.getAllResponseHeaders() + ); + } + } + }; + }; + + // Listen to events + xhr.onload = callback(); + errorCallback = xhr.onerror = xhr.ontimeout = callback( "error" ); + + // Support: IE 9 only + // Use onreadystatechange to replace onabort + // to handle uncaught aborts + if ( xhr.onabort !== undefined ) { + xhr.onabort = errorCallback; + } else { + xhr.onreadystatechange = function() { + + // Check readyState before timeout as it changes + if ( xhr.readyState === 4 ) { + + // Allow onerror to be called first, + // but that will not handle a native abort + // Also, save errorCallback to a variable + // as xhr.onerror cannot be accessed + window.setTimeout( function() { + if ( callback ) { + errorCallback(); + } + } ); + } + }; + } + + // Create the abort callback + callback = callback( "abort" ); + + try { + + // Do send the request (this may raise an exception) + xhr.send( options.hasContent && options.data || null ); + } catch ( e ) { + + // #14683: Only rethrow if this hasn't been notified as an error yet + if ( callback ) { + throw e; + } + } + }, + + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432) +jQuery.ajaxPrefilter( function( s ) { + if ( s.crossDomain ) { + s.contents.script = false; + } +} ); + +// Install script dataType +jQuery.ajaxSetup( { + accepts: { + script: "text/javascript, application/javascript, " + + "application/ecmascript, application/x-ecmascript" + }, + contents: { + script: /\b(?:java|ecma)script\b/ + }, + converters: { + "text script": function( text ) { + jQuery.globalEval( text ); + return text; + } + } +} ); + +// Handle cache's special case and crossDomain +jQuery.ajaxPrefilter( "script", function( s ) { + if ( s.cache === undefined ) { + s.cache = false; + } + if ( s.crossDomain ) { + s.type = "GET"; + } +} ); + +// Bind script tag hack transport +jQuery.ajaxTransport( "script", function( s ) { + + // This transport only deals with cross domain or forced-by-attrs requests + if ( s.crossDomain || s.scriptAttrs ) { + var script, callback; + return { + send: function( _, complete ) { + script = jQuery( " + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Binder

+
+

Questions

+
    +

  • Why sharing code alone may not be sufficient.

    • +

  • How to share a computational environment?

    • +

  • What is Binder?

    • +

  • How to binderize my Python repository?

    • +

  • How to publish my Python repository?

    • +
+
+
+

Objectives

+
    +

  • Learn about reproducible computational environments.

    • +

  • Learn to create and share custom computing environments with Binder.

    • +

  • Learn to get a DOI from Zenodo for a repository.

    • +
+
+
+

Why is it sometimes not enough to share your code?

+

Before we work in groups, +let’s take an example from geospatial +analysis where the first import in the code would be (please note that it is +not necessary to install any of the packages mentioned below):

+
from osgeo import ogr, osr, gdal
+
+
+

Depending on how you install this python package, it may be necessary to have +libgdal and its development headers already installed on your system; with +information on the version you have used, etc.

+
+

Exercise 1

+
+

Binder-1 (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+
+
+
+

Sharing a computing environment with Binder

+

Binder allows you to create +custom computing environments that can be shared and used by many remote users. +It uses repo2docker to +create a container image (docker image) of a +project using information contained in included configuration files.

+

Repo2docker is a standalone package that you can install locally on your laptop +but an online Binder service is freely available. +This is what we will be using in the tutorial.

+

The main objective of this exercise is to learn to fork a repository and add a +requirement file to share the computational environment with Binder.

+https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png +

Credit: Juliette Taka, Logilab and the OpenDreamKit project (2017)

+
+

Binder exercise/demo

+

In an earlier episode (Data visualization with Matplotlib) we have created this notebook:

+
import pandas as pd
+import matplotlib.pyplot as plt
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+data_2007 = data[data["year"] == 2007]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xscale("log")
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
+
+

We will now first share it via GitHub “statically”, +then using Binder.

+
+

Exercise/demo: Making your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+
+
+
+

How can I get a DOI from Zenodo?

+

Zenodo is a general purpose open-access +repository built and operated by CERN and OpenAIRE that allows researchers to archive and get a +Digital Object Identifier (DOI) to data that they +share.

+
+

Binder-3 (optional)

+

Everything you deposit on Zenodo is meant to be kept (long-term archive). +Therefore we recommend to practice with the Zenodo “sandbox” (practice/test area) +instead: https://sandbox.zenodo.org

+
    +

  1. Link GitHub with Zenodo:

    2. +
+
+
    +

  • Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing).

    • +

  • Log in to Zenodo with your GitHub account. Be aware that you may need to +authorize Zenodo application (Zenodo will redirect you back to GitHub for +Authorization).

    • +

  • Choose the repository webhooks options.

    • +

  • From the drop-down menu next to your email address at the top of the page, select GitHub.

    • +

  • You will be presented with a list of all your Github repositories.

    • +
+
+
    +

  1. Archiving a repo:

    2. +
+
+
    +

  • Select a repository you want to archive on Zenodo.

    • +

  • Toggle the “on” button next to the repository ou need to archive.

    • +

  • Click on the Repo that you want to reserve.

    • +

  • Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release.

    • +
+
+
    +

  1. Trigger Zenodo to Archive your repository

    2. +
+
+
    +

  • Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI.

    • +

  • If this is the first release of your code then you should give it a +version number of v1.0.0. Add description for your release then click the +Publish release button.

    • +

  • Zenodo takes an archive of your GitHub repository each time you create a new Release.

    • +
+
+
    +

  1. To ensure that everything is working:

    2. +
+
+
    +

  • Go to https://zenodo.org/account/settings/github/ (or the corresponding +sandbox at https://sandbox.zenodo.org/account/settings/github/), or the +Upload page (https://zenodo.org/deposit), you will find your repo is +listed.

    • +

  • Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo.

    • +

  • You can edit the archive on Zenodo and/or publish a new version of your software.

    • +

  • It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata +manually, you can also add a .zenodo.json or a CITATION.cff file to your repo and Zenodo will infer the metadata from this file.

    • +

  • Your code is now published on a Github public repository and archived on Zenodo.

    • +

  • Update the README file in your repository with the newly created zenodo badge.

    • +
+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/data-formats/index.html b/branch/rkdarst--remove-catfacts-jsonl/data-formats/index.html new file mode 100644 index 00000000..701c3e61 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/data-formats/index.html @@ -0,0 +1,1053 @@ + + + + + + + + + + + + + + + Data formats with Pandas and Numpy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Data formats with Pandas and Numpy

+
+

Questions

+
    +

  • How do you store your data right now?

    • +

  • Are you doing data cleaning / preprocessing every time you load the data?

    • +
+
+
+

Objectives

+
    +

  • Learn the distinguishing characteristics of different data formats.

    • +

  • Learn how you can read and write data in a variety of formats.

    • +
+
+
+

What is a data format?

+

Data format can mean two different things

+
    +

  1. data structure or how you’re storing the data in memory while you’re working on it;

    2. +

  2. file format or the way you’re storing the data in the disk.

    3. +
+

Let’s consider this randomly generated DataFrame with various columns:

+
import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
+dataset.info()
+
+
+

This DataFrame is structured in the tidy data format. +In tidy data format we have multiple columns of data that are collected in a Pandas DataFrame.

+../_images/tidy_data.png +

Let’s consider another example:

+
n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+np.info(data_array)
+
+
+

Here we have a different data structure: we have a two-dimentional array of numbers. +This is different to a Pandas DataFrame as data is stored as one contiguous block instead of individual columns. +This also means that the whole array must have one data type.

+
+https://github.com/elegant-scipy/elegant-scipy/raw/master/figures/NumPy_ndarrays_v2.png +
+

Source: Elegant Scipy

+
+
+

Now the question is: Can the data be saved to the disk without changing the data format?

+

For this we need a file format that can easily store our data structure.

+
+

Data type vs. data structure vs. file format

+
    +

  • Data type: Type of a single piece of data (integer, string, float, …).

    • +

  • Data structure: How the data is organized in memory (individual columns, 2D-array, nested dictionaries, …).

    • +

  • File format: How the data is organized when it is saved to the disk (columns of strings, block of binary data, …).

    • +
+

For example, a black and white image stored as a .png-file (file format) +might be stored in memory as an NxM array (data structure) of integers (data type).

+
+
+
+

What to look for in a file format?

+

When deciding which file format you should use for your program, you should remember the following:

+

There is no file format that is good for every use case.

+

Instead, there are various standard file formats for various use cases:

+
+https://imgs.xkcd.com/comics/standards.png +
+

Source: xkcd #927.

+
+
+

Usually, you’ll want to consider the following things when choosing a file format:

+
    +

  1. Is the file format good for my data structure (is it fast/space efficient/easy to use)?

    2. +

  2. Is everybody else / leading authorities in my field recommending a certain format?

    3. +

  3. Do I need a human-readable format or is it enought to work on it using code?

    4. +

  4. Do I want to archive / share the data or do I just want to store it while I’m working?

    5. +
+

Pandas supports many file formats for tidy data and Numpy supports some file formats for array data. +However, there are many other file formats that can be used through other libraries.

+

Table below describes some data formats:

+ +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
Name:
+
+
+
Human
+
readable:
+
+
+
Space
+
efficiency:
+
+
+
Arbitrary
+
data:
+
+
+
Tidy
+
data:
+
+
+
Array
+
data:
+
+
+
Long term
+
storage/sharing:
+
+

Pickle

❌

🟨

✅

🟨

🟨

❌

CSV

✅

❌

❌

✅

🟨

✅

Feather

❌

✅

❌

✅

❌

❌

Parquet

❌

✅

🟨

✅

🟨

✅

npy

❌

🟨

❌

❌

✅

❌

HDF5

❌

✅

❌

❌

✅

✅

NetCDF4

❌

✅

❌

❌

✅

✅

JSON

✅

❌

🟨

❌

❌

✅

Excel

❌

❌

❌

🟨

❌

✅

Graph formats

🟨

🟨

❌

❌

❌

🟨

+
+

Important

+
    +

  • ✅ : Good

    • +

  • 🟨 : Ok / depends on a case

    • +

  • ❌ : Bad

    • +
+
+
+
+

Storing arbitrary Python objects

+
+

Pickle

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: None (pickle-module is included with Python).

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: 🟨

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ❌! See warning below.

    • +

  • Best use cases: Saving Python objects for debugging.

    • +
+
+
+

Warning

+

Loading pickles that you have not created is +risky as they can contain arbitrary executable code.

+

Do not unpickle objects from sources that you do not trust!

+
+

Pickle is Python’s own serialization library. +It allows you to store Python objects into a binary file, but it is not a format you will want to use for long term storage or data sharing. +It is best suited for debugging your code by saving the Python variables for later inspection:

+
import pickle
+
+with open('data_array.pickle', 'wb') as f:
+    pickle.dump(data_array, f)
+
+with open('data_array.pickle', 'rb') as f:
+    data_array_pickle = pickle.load(f)
+
+
+
+
+
+

Exercise 1

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+ +
+
+

Storing tidy data

+
+

CSV (comma-separated values)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: numpy, pandas

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data. Small data. Data that needs to be human-readable.

    • +
+
+

CSV is by far the most popular file format, as it is human-readable and easily shareable. +However, it is not the best format to use when you’re working with big data.

+

Pandas has a very nice interface for writing and reading CSV files with to_csv- and read_csv-functions:

+
dataset.to_csv('dataset.csv', index=False)
+
+dataset_csv = pd.read_csv('dataset.csv')
+
+
+

Numpy has routines for saving and loading arrays as CSV files as well:

+
np.savetxt('data_array.csv', data_array)
+
+data_array_csv = np.loadtxt('data_array.csv')
+
+
+
+

Storing data in CSVs can reduce data precision

+
+

When working with floating point numbers you should be careful to save the data with enough decimal places so that you won’t lose precision.

+

For example, double-precision floating point numbers have ~16 decimal places of precision, but if you use normal Python to write these numbers, you can easily lose some of that precision. +Let’s consider the following example:

+
import numpy as np
+test_number = np.sqrt(2)
+# Write the number in a file
+test_file = open('sqrt2.csv', 'w')
+test_file.write('%f' % test_number)
+test_file.close()
+# Read the number from a file
+test_file = open('sqrt2.csv', 'r')
+test_number2 = np.float64(test_file.readline())
+test_file.close()
+# Calculate the distance between these numbers
+print(np.abs(test_number - test_number2))
+
+
+

CSV writing routines in Pandas and numpy try to avoid problems such as these by writing the floating point numbers with enough precision, but even they are not infallible. +We can check whether our written data matches the generated data:

+
dataset.compare(dataset_csv)
+
+np.all(data_array == data_array_csv)
+
+
+

In our case some rows of dataset_csv loaded from CSV do not match the original dataset as the last decimal can sometimes be rounded due to complex technical reasons.

+

Storage of these high-precision CSV files is usually very inefficient storage-wise.

+

Binary files, where floating point numbers are represented in their native binary format, do not suffer from such problems.

+
+
+
+
+

Feather

+
+

Requires additional packages

+
+

Using Feather requires pyarrow-package to be installed.

+

You can try installing pyarrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ✅

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Temporary storage of tidy data.

    • +
+
+

Feather is a file format for storing data frames quickly. +There are libraries for Python, R and Julia.

+

We can work with Feather files with to_feather- and read_feather-functions:

+
dataset.to_feather('dataset.feather')
+dataset_feather = pd.read_feather('dataset.feather')
+
+
+

Feather is not a good format for storing array data, so we won’t present an example of that here.

+
+
+

Parquet

+
+

Requires additional packages

+
+

Using Parquet requires pyarrow-package to be installed.

+

You can try installing PyArrow with

+
!pip install pyarrow
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, pyarrow

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ✅

    • +

  • Array data: 🟨

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in tidy data format. Archival of said data.

    • +
+
+

Parquet is a standardized open-source +columnar storage format that is commonly used for storing big data. +Parquet is usable from many different languages (C, Java, Python, MATLAB, Julia, etc.).

+

We can work with Parquet files with to_parquet- and read_parquet-functions:

+
dataset.to_parquet('dataset.parquet')
+dataset_parquet = pd.read_parquet('dataset.parquet')
+
+
+

Parquet can be used to store arbitrary data and arrays as well, but doing that is more complicated so we won’t do that here.

+
+
+
+

Exercise 2

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+ +
+
+

Storing array data

+
+

npy (numpy array format)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ✅

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ❌

    • +

  • Best use cases: Saving numpy arrays temporarily.

    • +
+
+

If you want to temporarily store numpy arrays, you can use the numpy.save()- and numpy.load()-functions:

+
np.save('data_array.npy', data_array)
+data_array_npy = np.load('data_array.npy')
+
+
+

There also exists numpy.savez()-function for storing multiple datasets in a single file:

+
np.savez('data_arrays.npz', data_array0=data_array, data_array1=data_array)
+data_arrays = np.load('data_arrays.npz')
+data_arrays['data_array0']
+
+
+

For big arrays it’s good idea to check other binary formats such as HDF5 or NetCDF4.

+

np.save- and np.savez-functions work with +sparse matrices, +but one can also use dedicated +scipy.sparse.save_npz- and +scipy.sparse.load_npz-functions. +Storing sparse matrices using these functions can give huge storage savings.

+
+
+

HDF5 (Hierarchical Data Format version 5)

+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: numpy, pandas, PyTables, h5py

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format.

    • +
+
+

HDF5 is a high performance storage format for storing large amounts of data in multiple datasets in a single file. +It is especially popular in fields where you need to store big multidimensional arrays such as physical sciences.

+

Pandas allows you to store tables as HDF5 with PyTables, which uses HDF5 to write the files. +You can create a HDF5 file with to_hdf- and read_parquet-functions:

+
dataset.to_hdf('dataset.h5', key='dataset', mode='w')
+dataset_hdf5 = pd.read_hdf('dataset.h5')
+
+
+

PyTables comes installed with the default Anaconda installation.

+

For writing data that is not a table, you can use the excellent h5py-package:

+
import h5py
+
+# Writing:
+
+# Open HDF5 file
+h5_file = h5py.File('data_array.h5', 'w')
+# Write dataset
+h5_file.create_dataset('data_array', data=data_array)
+# Close file and write data to disk. Important!
+h5_file.close()
+
+# Reading:
+
+# Open HDF5 file again
+h5_file = h5py.File('data_array.h5', 'r')
+# Read the full dataset
+data_array_h5 = h5_file['data_array'][()]
+# Close file
+h5_file.close()
+
+
+

h5py comes with Anaconda as well.

+
+
+

NetCDF4 (Network Common Data Form version 4)

+
+

Requires additional packages

+
+

Using NetCDF4 requires netCDF4- or h5netcdf-package to be installed. +h5netcdf is often mentioned as being faster to the official netCDF4-package, so we’ll be using it in the example.

+

A great NetCDF4 interface is provided by a xarray-package.

+

You can try installing these packages with

+
!pip install h5netcdf xarray
+
+
+

or you can take this as a demo.

+
+
+
+

Key features

+
    +

  • Type: Binary format

    • +

  • Packages needed: pandas, netCDF4/h5netcdf, xarray

    • +

  • Space efficiency: ✅

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ✅

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Working with big datasets in array data format. Especially useful if the dataset contains spatial or temporal dimensions. Archiving or sharing those datasets.

    • +
+
+

NetCDF4 is a data format that uses HDF5 as its file format, but it has standardized structure of datasets and metadata related to these datasets. +This makes it possible to be read from various different programs.

+

NetCDF4 is a common format for storing large data from big simulations in physical sciences.

+

Using interface provided by xarray:

+
# Write tidy data as NetCDF4
+dataset.to_xarray().to_netcdf('dataset.nc', engine='h5netcdf')
+# Read tidy data from NetCDF4
+import xarray as xr
+dataset_xarray = xr.open_dataset('dataset.nc', engine='h5netcdf')
+dataset_netcdf4 = dataset_xarray.to_pandas()
+dataset_xarray.close()
+
+
+

Working with array data is easy as well:

+
# Write array data as NetCDF4
+xr.DataArray(data_array).to_netcdf('data_array.nc', engine='h5netcdf')
+# Read array data from NetCDF4
+data_array_xarray = xr.open_dataarray('data_array.nc', engine='h5netcdf')
+data_array_netcdf4 = data_array_xarray.to_numpy()
+data_array_xarray.close()
+
+
+

The advantage of NetCDF4 compared to HDF5 is that one can easily add other metadata e.g. spatial dimensions (x, y, z) or timestamps (t) that tell where the grid-points are situated. +As the format is standardized, many programs can use this metadata for visualization and further analysis.

+
+
+
+

Exercise 3

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+ +
+
+

Other file formats

+
+

JSON (JavaScript Object Notation)

+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: None (json-module is included with Python).

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: 🟨

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Saving nested/relational data, storing web requests.

    • +
+
+

JSON is a popular human-readable data format. +It is especially common when dealing with web applications (REST-APIs etc.).

+

You rarely want to keep your data in this format, unless you’re working with +nested data with multiple layers or lots of interconnections.

+

Similarly to other popular files, Pandas can write and read json files with to_json()- and read_json()-functions:

+
dataset.to_json('dataset.json')
+dataset_json = pd.read_json('dataset.json')
+
+
+
+
+

Excel

+
+

Requires additional packages

+

Using Excel files with Pandas requires openpyxl-package to be installed.

+
+
+

Key features

+
    +

  • Type: Text format

    • +

  • Packages needed: openpyxl

    • +

  • Space efficiency: ❌

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: 🟨

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: ✅

    • +

  • Best use cases: Sharing data in many fields. Quick data analysis.

    • +
+
+

Excel is very popular in social sciences and economics. +However, it is not a good format for data science.

+

See Pandas’ documentation on working with Excel files.

+
+
+

Graph formats (adjency lists, gt, GraphML etc.)

+
+

Key features

+
    +

  • Type: Many different formats

    • +

  • Packages needed: Depends on a format.

    • +

  • Space efficiency: 🟨

    • +

  • Arbitrary data: ❌

    • +

  • Tidy data: ❌

    • +

  • Array data: ❌

    • +

  • Long term archival/sharing: 🟨

    • +

  • Best use cases: Saving graphs or data that can be represented as a graph.

    • +
+
+

There are plenty of data formats for storing graphs. +We won’t list them here as optimal data format depends heavily on the graph structure.

+

One can use functions in libraries such as +networkx, +graph-tool, +igraph +to read and write graphs.

+
+
+
+

Benefits of binary file formats

+

Binary files come with various benefits compared to text files.

+
    +

  1. They can represent floating point numbers with full precision.

    2. +

  2. Storing data in binary format can potentially save lots of space. +This is because you do not need to write numbers as characters. +Additionally some file formats support compression of the data.

    3. +

  3. Data loading from binary files is usually much faster than loading from text files. +This is because memory can be allocated for the data before data is loaded as the type of data in columns is known.

    4. +

  4. You can often store multiple datasets and metadata to the same file.

    5. +

  5. Many binary formats allow for partial loading of the data. +This makes it possible to work with datasets that are larger than your computer’s memory.

    6. +
+

Performance with tidy dataset:

+

For the tidy dataset we had, we can test the performance of the different file formats:

+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File format

File size [MB]

Write time [ms]

Read time [ms]

Data matches exactly

CSV

4.57

360

81.2

False

Feather

2.2

12.9

6.67

True

Parquet

1.82

35.1

8.96

True

HDF5

4.89

41.7

29.6

True

NetCDF4

6.9

92.9

74.2

True

+

The relatively poor performance of HDF5-based formats in this case is due to the data being mostly one dimensional columns full of character strings.

+

Performance with data array:

+

For the array-shaped data_array we had, we can test the performance of the different file formats:

+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File format

File size [MB]

Write time [ms]

Read time [ms]

Data matches exactly

CSV

23.8

690

294

True

npy

7.63

13.8

2.72

True

HDF5

7.63

27

3.97

True

NetCDF4

7.64

28.8

12.2

True

+

For this kind of a data, HDF5-based formats perform much better.

+
+
+

Things to remember

+
    +

  1. There is no file format that is good for every use case.

    2. +

  2. Usually, your research question determines which libraries you want to use to solve it. +Similarly, the data format you have determines file format you want to use.

    3. +

  3. However, if you’re using a previously existing framework or tools or you work in a specific field, you should prioritize using the formats that are used in said framework/tools/field.

    4. +

  4. When you’re starting your project, it’s a good idea to take your initial data, clean it, and store the results in a good binary format that works as a starting point for your future analysis. +If you’ve written the cleaning procedure as a script, you can always reproduce it.

    5. +

  5. Throughout your work, you should use code to turn important data to human-readable format (e.g. plots, averages, pandas.DataFrame.head()), not to keep your full data in a human-readable format.

    6. +

  6. Once you’ve finished, you should store the data in a format that can be easily shared to other people.

    7. +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pandas can read and write a variety of data formats.

    • +

  • There are many good, standard formats, and you don’t need to create your own.

    • +

  • There are plenty of other libraries dedicated to various formats.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/data-visualization/index.html b/branch/rkdarst--remove-catfacts-jsonl/data-visualization/index.html new file mode 100644 index 00000000..d5c0b66c --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/data-visualization/index.html @@ -0,0 +1,666 @@ + + + + + + + + + + + + + + + Data visualization with Matplotlib — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Data visualization with Matplotlib

+
+

Questions

+
    +

  • What happens if you can’t automatically produce plots?

    • +

  • When to use Matplotlib for data visualization?

    • +

  • When to prefer other libraries?

    • +
+
+
+

Objectives

+
    +

  • Be able to create simple plots with Matplotlib and tweak them

    • +

  • Know about object-oriented vs pyplot interfaces of Matplotlib

    • +

  • Be able to adapt gallery examples

    • +

  • Know how to look for help

    • +

  • Know that other tools exist

    • +
+
+
+

Repeatability/reproducibility

+

From Claus O. Wilke: “Fundamentals of Data Visualization”:

+
+

One thing I have learned over the years is that automation is your friend. I +think figures should be autogenerated as part of the data analysis pipeline +(which should also be automated), and they should come out of the pipeline +ready to be sent to the printer, no manual post-processing needed.

+
+
    +

  • No manual post-processing. This will bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • There is not the one perfect language and not the one perfect library for everything.

    • +

  • Within Python, many libraries exist:

    +
      +

    • Matplotlib: +probably the most standard and most widely used

      • +

    • Seaborn: +high-level interface to Matplotlib, statistical functions built in

      • +

    • Altair: +declarative visualization (R users will be more at home), statistics built in

      • +

    • Plotly: +interactive graphs

      • +

    • Bokeh: +also here good for interactivity

      • +

    • plotnine: +implementation of a grammar of graphics in Python, it is based on ggplot2

      • +

    • ggplot: +R users will be more at home

      • +

    • PyNGL: +used in the weather forecast community

      • +

    • K3D: +Jupyter notebook extension for 3D visualization

      • +

    • …

      • +
    +
    • +

  • Two main families of libraries: procedural (e.g. Matplotlib) and declarative +(using grammar of graphics).

    • +
+
+
+

Why are we starting with Matplotlib?

+
    +

  • Matplotlib is perhaps the most “standard” Python plotting library.

    • +

  • Many libraries build on top of Matplotlib.

    • +

  • MATLAB users will feel familiar.

    • +

  • Even if you choose to use another library (see above list), chances are high +that you need to adapt a Matplotlib plot of somebody else.

    • +

  • Libraries that are built on top of Matplotlib may need knowledge of Matplotlib +for custom adjustments.

    • +
+

However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code.

+

Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences. Later we will also try other libraries.

+
+
+

Getting started with Matplotlib

+

We can start in a Jupyter notebook since notebooks are typically a good fit +for data visualizations. But if you prefer to run this as a script, this is +also OK.

+

Let us create our first plot using +subplots(), +scatter, and some other methods on the +Axes object:

+
# this line tells Jupyter to display matplotlib figures in the notebook
+%matplotlib inline
+
+import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
+# uncomment the next line if you would like to save the figure to disk
+# fig.savefig("my-first-plot.png")
+
+
+
+Result of our first plot +
+

This is the result of our first plot.

+
+
+

When running a Matplotlib script on a remote server without a +“display” (e.g. compute cluster), you may need to add the +matplotlib.use call:

+
import matplotlib.pyplot as plt
+matplotlib.use("Agg")
+
+# ... rest of the script
+
+
+
+
+

Exercise: Matplotlib

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y*2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +
+
+ + +
+
+
+

Matplotlib has two different interfaces

+

When plotting with Matplotlib, it is useful to know and understand that +there are two approaches even though the reasons of this dual approach is +outside the scope of this lesson.

+
    +

  • The more modern option is an object-oriented interface (the +fig and ax objects +can be configured separately and passed around to functions):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_x, y=data_y, c="#E69F00")
+
+ax.set_xlabel("we should label the x axis")
+ax.set_ylabel("we should label the y axis")
+ax.set_title("some title")
+
    +
    +
    • +

  • The more traditional option mimics MATLAB plotting and uses the +pyplot interface (plt carries +the global settings):

    +
    import matplotlib.pyplot as plt
+
+# this is dataset 1 from
+# https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0]
+data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68]
+
+plt.scatter(x=data_x, y=data_y, c="#E69F00")
+
+plt.xlabel("we should label the x axis")
+plt.ylabel("we should label the y axis")
+plt.title("some title")
+
    +
    +
    • +
+

When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, we +recommend to learn and use the object oriented interface.

+
+

Why do we emphasize this?

+

One day you may want to write functions which wrap +around Matplotlib function calls and then you can send Figure and Axes +into these functions and there is less risk that adjusting figures changes +settings also for unrelated figures created in other functions.

+

When using the pyplot interface, settings are modified for the entire +matplotlib.pyplot package. The latter is acceptable for linear scripts but may yield +surprising results when introducing functions to enhance/abstract Matplotlib +calls.

+
+
+
+
+

Styling and customizing plots

+
    +

  • Do not customize “manually” using a graphical program (not easily repeatable/reproducible).

    • +

  • No manual post-processing. This will bite you when you need to regenerate 50 +figures one day before submission deadline or regenerate a set of figures +after the person who created them left the group.

    • +

  • Matplotlib and also all the other libraries allow to customize almost every aspect of a plot.

    • +

  • It is useful to study Matplotlib parts of a figure +so that we know what to search for to customize things.

    • +

  • Matplotlib cheatsheets: https://github.com/matplotlib/cheatsheets

    • +

  • You can also select among pre-defined themes/ +style +sheets +with use, for instance:

    +
    plt.style.use('ggplot')
+
    +
    +
    • +
+
+
+

Exercises: Styling and customization

+

Here are 3 exercises where we try to adapt existing scripts to either tweak +how the plot looks (exercises 1 and 2) or to modify the input data (example 3).

+

This is very close to real life: there are so many options and possibilities and it is +almost impossible to remember everything so this strategy is useful to practice:

+
    +

  • select an example that is close to what you have in mind

    • +

  • being able to adapt it to your needs

    • +

  • being able to search for help

    • +

  • being able to understand help request answers (not easy)

    • +
+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+
+data_2007 = data[data["year"] == 2007]
+
+data_2007
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+ +
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+ + + +
+
+

Discussion

+

After the exercises, the group can discuss their findings and it is important to +clarify questions at this point before moving on.

+
+
+
+

Keypoints

+
    +

  • Avoid manual post-processing, script everything.

    • +

  • Browse a number of example galleries to help you choose the library +that fits best your work/style.

    • +

  • Figures for presentation slides and figures for manuscripts have +different requirements.

    • +

  • Think about color-vision deficiencies when choosing colors. Use +existing solutions for this problem.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/dependencies/index.html b/branch/rkdarst--remove-catfacts-jsonl/dependencies/index.html new file mode 100644 index 00000000..6e956507 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/dependencies/index.html @@ -0,0 +1,639 @@ + + + + + + + + + + + + + + + Dependency management — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Dependency management

+
+

Questions

+
    +

  • Do you expect your code to work in one year? Five? What if it +uses numpy or tensorflow or random-github-package ?

    • +

  • How can my collaborators get the same results as me? What about +future me?

    • +

  • How can my collaborators easily install my codes with all the necessary dependencies?

    • +

  • How can I make it easy for my colleagues to reproduce my results?

    • +

  • How can I work on two (or more) projects with different and conflicting dependencies?

    • +
+
+
+

Objectives

+
    +

  • Learn how to record dependencies

    • +

  • Be able to communicate the dependencies as part of a report/thesis/publication

    • +

  • Learn how to use isolated environments for different projects

    • +

  • Simplify the use and reuse of scripts and projects

    • +
+
+
+

How do you track dependencies of your project?

+
    +

  • Dependency: Reliance on a external component. In this case, a +separately installed software package such as numpy.

    • +
+
+
+

Exercises 1

+
+

Dependencies-1 (15 min)

+

Please discuss in breakout rooms and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+
+
+

PyPI (The Python Package Index) and (Ana)conda

+
    +

  • PyPI (The Python Package Index) and Conda are popular packaging/dependency +management tools.

    • +

  • When you run pip install you typically install from PyPI but one can also pip install from a GitHub +repository and similar.

    • +

  • When you run conda install you typically install from Anaconda Cloud but there are many community-driven conda channels +and you can create your own.

    • +
+

Why are there two ecosystems?

+
+

PyPI

+
    +

  • Installation tool: pip

    • +

  • Summary: PyPI is traditionally used for Python-only packages or +for Python interfaces to external libraries. There are also packages +with bundled external libraries (such as numpy).

    • +

  • Amount of packages: Huge number. Old versions are supported for +a long time.

    • +

  • How libraries are handled: If your code depends on external +libraries or tools, these things need to be either included in the +pip-package or provided via some other installation system (like +operating system installer or manual installation).

    • +
  • +
    Pros:
      +

    • Easy to use

      • +

    • Package creation is easy

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Installing packages that need external libraries can be complicated

      • +
    +
    +
    +
    • +
+
+
+

Conda

+
    +

  • Installation tool: conda or mamba

    • +

  • Summary: Conda aims to be a more general package distribution tool +and it tries to provide not only the Python packages, but also libraries +and tools needed by the Python packages. Most scientific software written +in Python uses external libraries to speed up calculations and installing +these libraries can often become complicated without conda.

    • +

  • Amount of packages: Most popular packages are provided. Other packages +can be installed via pip.

    • +

  • How libraries are handled: Required libraries are installed as separate +conda packages.

    • +
  • +
    Pros:
      +

    • Quite easy to use

      • +

    • Easier to manage packages that need external libraries

      • +
    +
    +
    +
    • +
  • +
    Cons:
      +

    • Package creation is harder

      • +
    +
    +
    +
    • +
+
+ +

In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages.

+
+
+

Creating isolated environments

+

Isolated environments solve a couple of problems:

+
    +

  • You can install specific, also older, versions of packages into them.

    • +

  • You can create one environment for each project and you won’t encounter any +problems if the two projects require different versions of packages.

    • +

  • If you make some mistake and install something you did not want or need, you +can remove the environment and create a new one.

    • +

  • You can export a list of packages in an environment and share it with your +code. This makes replicating your results easier.

    • +
+
+
+

Exercises 2

+
+

Dependencies-2 (15 min)

+
+
+

Chloe just joined your team and will be working on her Master Thesis. She is +quite familiar with Python, still finishing some Python assignments (due in a +few weeks) and you give her a Python code for analyzing and plotting your +favorite data. The thing is that your Python code has been developed by +another Master Student (from last year) and requires a older version of +Numpy (1.18.1) and Matplotlib (3.1.3) (otherwise the code fails). The code +could probably work with a recent version of Python but has been validated with +Python 3.7 only. Having no idea what the code does, she decides that the best +approach is to create an isolated environment with the same dependencies +that were used previously. This will give her a baseline for future upgrade and +developments.

+

For this first exercise, we will be using conda for creating an isolated environment.

+
    +

  1. Create a conda environment:

    +
    $ conda create --name python37-env python=3.7 numpy=1.18.1 matplotlib=3.1.3
+
    +
    +
    2. +
+

Conda environments can also be managed (create, update, delete) from the +anaconda-navigator. Check out the corresponding documentation here.

+
    +

  1. Activate the environment:

    +
    $ conda activate python37-env
+
    +
    +
    +

    conda activate versus source activate

    +

    If you do not have a recent version of Anaconda or anaconda has not been +setup properly, you may encounter an error. With older version of anaconda, +you can try:

    +
    $ source activate python37-env
+
    +
    +
    +
    2. +

  2. Open a Python console and check that you have effectively the right version for each package:

    +
    import numpy
+import matplotlib
+
+print('Numpy version: ', numpy.__version__)
+print('Matplotlib version: ', matplotlib.__version__)
+
    +
    +

    Or use the one-liner if you have access to a terminal like bash

    +

    python -c “import numpy; print(numpy.__version__)” +python -c “import matplotlib;print(matplotlib.__version__)”

    +
    3. +

  3. Deactivate the environment:

    +
    $ conda deactivate
+
    +
    +
    4. +

  4. Check Numpy and Matplotlib versions in the default environment to make +sure they are different from python37-env.

    5. +
+

There is no need to specify the conda environment when using deactivate. It +deactivates the current environment.

+
+

Remark

+
    +

  • Sometimes the package version you would need does not seem to be +available. You may have to select another conda channel +for instance conda-forge. Channels can then +be indicated when installing a package:

    +
    $ conda install -c conda-forge matplotlib=3.1.3
+
    +
    +
    • +

  • We will see below that rather than specifying the list of dependencies as +argument of conda create, it is recommended to record dependencies in +a file.

    • +
+
+
+
+
+

Exercises 3

+
+

Dependencies-3 (15 min, optional)

+

This is the same exercise as before but we use virtualenv rather than conda.

+
    +

  1. Create a venv:

    +
    $ python3 -m venv scicomp
+
    +
    +

    Here scicomp is the name of the virtual environment. It creates a new +folder called scicomp.

    +
    2. +

  2. Activate it. To activate your newly created virtual environment locate the +script called activate and execute it.

    +
      +

    • Linux/Mac-OSX: look at bin folder in the scicomp folder:

      +
      $ source scicomp/bin/activate
+
      +
      +
      • +

    • Windows: most likely you can find it in the Scripts folder.

      • +
    +
    3. +

  3. Install Numpy 1.18.1 and Matplotlib 3.1.3 into the virtual environment:

    +
    $ pip install numpy==1.18.1
+$ pip install matplotlib==3.1.3
+
    +
    +
    4. +

  4. Deactivate it:

    +
    $ deactivate
+
    +
    +
    5. +
+
+
+
+

Problems that might happen with manual installation

+

Running the install commands manually can result in unexpected behaviour +such as:

+
    +

  • The installer might remove an already installed packages or update them.

    • +

  • The installer might not find a package that works with already installed packages.

    • +
+

The reason for this is that the installer does not know what commands +you ran in the past. It only knows the state of your environment and what +you’re currently telling it to install.

+

For example, check what version of scipy you’ll get if you run

+
$ pip install scipy
+
+
+

or

+
$ conda install scipy
+
+
+

Depending on your environment you can get scipy with versions from +1.6.2 with no numpy upgrade to 1.9.3 with automatic numpy upgrade.

+

These kinds of problems can be mitigated by recording dependencies in an +environment.yml or requirements.txt.

+
+
+

Recording dependencies

+

There are two standard ways to record dependencies for Python projects: +requirements.txt and environment.yml.

+

requirements.txt (used by virtual environment) is a simple +text file which looks like this:

+
numpy
+matplotlib
+pandas
+scipy
+
+
+

environments.yml (for conda) is a yaml-file which looks like this:

+
name: my-environment
+channels:
+  - defaults
+dependencies:
+  - numpy
+  - matplotlib
+  - pandas
+  - scipy
+
+
+

If you need to recreate the exact same environment later on, it can be very +useful to pin dependencies to certain versions. For example, there +is usually a delay between doing research and that research being published. +During this time the dependencies might update and reviewers or interested +researchers might not be able to replicate your results or run your code.

+

Here are the two files again, but this time with versions pinned:

+

requirements.txt with versions:

+
numpy==1.18.1
+matplotlib==3.1.3
+pandas==1.1.2
+scipy==1.6.2
+
+
+

environments.yml with versions:

+
name: my-environment
+channels:
+  - defaults
+dependencies:
+  - python=3.7
+  - numpy=1.18.1
+  - matplotlib=3.1.3
+  - pandas=1.1.2
+  - scipy=1.6.2
+
+
+ +
+

Putting too strict requirements can be counter-productive

+

Putting exact version numbers can be good for single-use applications, +like replicating a research paper, but it is usually bad for long-term +maintenance because the program won’t update at the same time as it’s +requirements do.

+

If you’re creating a library, adding strict dependencies can also create +a situation where the library cannot coexist with another library.

+
+
+
+

Dependencies 4

+
+

Dependencies-4 (15 min)

+
    +

  • Create the file environment.yml or requirements.txt

    • +
  • +
    Create an environment based on these dependencies:
      +

    • Conda: $ conda env create --file environment.yml

      • +

    • Virtual environment: First create and activate, then $ pip install -r requirements.txt

      • +
    +
    +
    +
    • +
  • +
    Freeze the environment:
      +

    • Conda: $ conda env export > environment.yml

      • +

    • Virtual environment: $ pip freeze > requirements.txt

      • +
    +
    +
    +
    • +

  • Have a look at the generated (“frozen”) file.

    • +
+
+
+

Hint: Updating packages from dependency files

+

Instead of installing packages with $ pip install somepackage, +you can add somepackage to requirements.txt and re-run +$ pip install -r requirements.txt.

+

With conda, you can add the package to environment.yml and +run $ conda env update --file environment.yml

+
+
+
+

How to communicate the dependencies as part of a report/thesis/publication

+

Each notebook or script or project which depends on libraries should come with +either a requirements.txt or a environment.yml, unless you are creating +and distributing this project as Python package (see next section).

+
    +

  • Attach a requirements.txt or a environment.yml to your thesis.

    • +

  • Even better: put requirements.txt or a environment.yml in your Git repository along your code.

    • +

  • Even better: also binderize your analysis pipeline (more about that in a later session).

    • +
+
+
+

Version pinning for package creators

+

We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in setup.py or pyproject.toml +(PyPI) or meta.yaml (conda).

+

These dependencies will then be used by either other libraries (who in turn +write their own setup.py or pyproject.toml or meta.yaml) or by +people directly (filling out requirements.txt or a environment.yml).

+

Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from setup.py):

+
# ...
+install_requires=[
+   'numpy==1.19.2',
+   'matplotlib==3.3.2'
+   'pandas==1.1.2'
+   'scipy==1.5.2'
+]
+# ...
+
+
+

or you can define a range or keep them undefined like here (example taken from +setup.py):

+
# ...
+install_requires=[
+   'numpy',
+   'matplotlib'
+   'pandas'
+   'scipy'
+]
+# ...
+
+
+

Should we pin the versions here or not?

+
    +

  • Pinning versions here would be good for reproducibility.

    • +

  • However pinning versions may make it difficult for this library to be used in a project alongside other +libraries with conflicting version dependencies.

    • +

  • Therefore as library creator make the version requirements as wide as possible.

    +
      +

    • Set minimum version when you know of a reason: >=2.1

      • +

    • Sometimes set maximum version to next major version (<4) (when +you currently use 3.x.y) when you expect issues with next +major version.

      • +
    +
    • +

  • As the “end consumer” of libraries, define your dependencies as narrowly as possible.

    • +
+
+
+

See also

+

Other tools for dependency management:

+
    +

  • Poetry: dependency management and packaging

    • +

  • Pipenv: dependency management, alternative to Poetry

    • +

  • pyenv: if you need different Python versions for different projects

    • +

  • micropipenv: lightweight tool to “rule them all”

    • +

  • mamba: a drop in replacement for +conda that does installations faster.

    • +

  • miniforge & mambaforge: Miniconda alternatives with +conda-forge as the default channel and optionally mamba as the default installer.

    • +
+

Other resources:

+ +
+

Keypoints

+
    +

  • Install dependencies by first recording them in requirements.txt or +environment.yml and install using these files, then you have a trace.

    • +

  • Use isolated environments and avoid installing packages system-wide.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/exercises/index.html b/branch/rkdarst--remove-catfacts-jsonl/exercises/index.html new file mode 100644 index 00000000..a72a62ef --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/exercises/index.html @@ -0,0 +1,1946 @@ + + + + + + + + + + + + + + + List of exercises — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

List of exercises

+
+

Full list

+

This is a list of all exercises and solutions in this lesson, mainly +as a reference for helpers and instructors. This list is +automatically generated from all of the other pages in the lesson. +Any single teaching event will probably cover only a subset of these, +depending on their interests.

+
+

Jupyter

+

In jupyter.ipynb:

+
+

Exercises: Jupyter-1

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are starting from the navigator, change to the directory you want to use.

      • +

    • If you are starting from the command line, you should navigate to the directory you want to use first.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+

In jupyter.ipynb:

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+

In jupyter.ipynb:

+ +

In jupyter.ipynb:

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

NumPy

+

In numpy.rst:

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-2

+ +
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+

In numpy.rst:

+ +

In numpy.rst:

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+

In numpy.rst:

+ +
+
+

Advanced NumPy

+

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lession before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+

In numpy-advanced.rst:

+ +

In numpy-advanced.rst:

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+

In numpy-advanced.rst:

+ +
+
+

Pandas

+

In pandas.rst:

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+

In pandas.rst:

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+

In pandas.rst:

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries:

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y="year", x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Data visualization with Matplotlib

+

In data-visualization.md:

+
+

Exercise Matplotlib-1: extend the previous example (15 min)

+
    +

  • Extend the previous plot by also plotting this set of values but this time +using a different color (#56B4E9):

    +
    # this is dataset 2
+data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74]
+
    +
    +
    • +

  • Then add another color (#009E73) which plots the second dataset, scaled +by 2.0.

    +
    # here we multiply all elements of data2_y by 2.0
+data2_y_scaled = [y*2.0 for y in data2_y]
+
    +
    +
    • +

  • Try to add a legend to the plot with matplotlib.axes.Axes.legend() and searching the web for clues on +how to add labels to each dataset.

    • +

  • At the end it should look like this one:

    +
    +Result of the exercise +
    +
    • +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+
+

Exercise Customization-1: log scale in Matplotlib (15 min)

+

In this exercise we will learn how to use log scales.

+
    +

  • To demonstrate this we first fetch some data to plot:

    +
    import pandas as pd
+
+url = "https://raw.githubusercontent.com/plotly/datasets/master/gapminder_with_codes.csv"
+data = pd.read_csv(url)
+
+data_2007 = data[data["year"] == 2007]
+
+data_2007
+
    +
    +
    • +

  • Try the above snippet in a notebook and it will give you an overview over the data.

    • +

  • Then we can plot the data, first using a linear scale:

    +
    import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+ax.scatter(x=data_2007["gdpPercap"], y=data_2007["lifeExp"], alpha=0.5)
+
+ax.set_xlabel("GDP (USD) per capita")
+ax.set_ylabel("life expectancy (years)")
+
    +
    +

    This is the result but we realize that a linear scale is not ideal here:

    +
    +Gapminder data plotted using a linear scale +
    +
    • +

  • Your task is to switch to a log scale and arrive at this result:

    +
    +Gapminder data plotted using log scale +
    +
    • +

  • What does alpha=0.5 do?

    • +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+
+

Exercise Customization-2: preparing a plot for publication (15 min)

+

Often we need to create figures for presentation slides and for publications +but both have different requirements: for presentation slides you have the whole +screen but for a figure in a publication you may only have few centimeters/inches.

+

For figures that go to print it is good practice to look at them at the size +they will be printed in and then often fonts and tickmarks are too small.

+

Your task is to make the tickmarks and the axis label font larger, using +Matplotlib parts of a figure +and web search, and to arrive at this:

+
+Gapminder data plotted with larger font and larger ticks +
+
+

In data-visualization.md:

+ +

In data-visualization.md:

+ +

In data-visualization.md:

+ +
+
+

Data formats with Pandas and Numpy

+

In data-formats.rst:

+
+

Exercise

+
    +

  • Create an arbitrary python object (for example, a string or a list). Pickle it.

    +

    Read the pickled object back in and check if it matches the original one.

    +
    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create the example dataset:

    +
    import pandas as pd
+import numpy as np
+
+n_rows = 100000
+
+dataset = pd.DataFrame(
+    data={
+        'string': np.random.choice(('apple', 'banana', 'carrot'), size=n_rows),
+        'timestamp': pd.date_range("20130101", periods=n_rows, freq="s"),
+        'integer': np.random.choice(range(0,10), size=n_rows),
+        'float': np.random.uniform(size=n_rows),
+    },
+)
+
    +
    +
    • +

  • Save the dataset dataset as CSV. Load the dataset into a variable dataset_csv.

    • +

  • Use dataset.compare(dataset_csv) to check if loaded dataset matches the original one.

    • +
+
+

In data-formats.rst:

+ +

In data-formats.rst:

+
+

Exercise

+
    +

  • Create an example numpy array:

    +
    n = 1000
+
+data_array = np.random.uniform(size=(n,n))
+
    +
    +
    • +

  • Store the array as a npy.

    • +

  • Read the dataframe back in and compare it to the original one. Does the data match?

    • +
+
+

In data-formats.rst:

+ +
+
+

Scripts

+

In scripts.rst:

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and the weather_data file and upload them to your jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Note: If you haven’t downloaded the file directly to your jupyterlab folder, it will be located in your Downloads folder or the folder you selected. In jupyterlab click on the ‘upload file’ button, navigate to the folder containing the file and select it to load it into your jupyterlab folder.

    +
    2. +

  2. Open a terminal in jupyter (File -> New -> Terminal).

    3. +

  3. Convert the jupyter script to a python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+

In scripts.rst:

+
+

Scripts-2

+
    +

  1. Take the python script we have written in the preceding exercise and use +argparse to specify the input and output files and allow the start and end dates to be set. +The start and end dates should be optional parameters with the defaults as they are in the current script.

    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from Mai 2020 to October 2020). +Also use data for cairo (https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv)

    3. +
+
+

In scripts.rst:

+ +

In scripts.rst:

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab. +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+

In scripts.rst:

+ +
+
+

Web APIs with Python

+

In web-apis.ipynb:

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+

In web-apis.ipynb:

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+

In web-apis.ipynb:

+ +
+
+

SciPy

+

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+

In scipy.rst:

+ +

In scipy.rst:

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+

In scipy.rst:

+ +
+
+

Library ecosystem

+

In libraries.rst:

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+

In libraries.rst:

+ +

In libraries.rst:

+
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+

In libraries.rst:

+ +
+
+

Parallel programming

+

In parallel.rst:

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+

In parallel.rst:

+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+

In parallel.rst:

+
+

Parallel-2, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+

In parallel.rst:

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+
+

Dependency management

+

In dependencies.rst:

+
+

Dependencies-1 (15 min)

+

Please discuss in breakout rooms and answer via collaborative document the +following questions:

+
    +

  • How do you install Python packages (libraries) that you use in your work? +From PyPI using pip? From other places using pip? Using conda?

    • +

  • How do you track/record the dependencies? Do you write them into a file or README? Into +requirements.txt or environment.yml?

    • +

  • If you track dependencies in a file, why do you do this?

    • +

  • Have you ever experienced that a project needed a different version of a Python +library than the one on your computer? If yes, how did you solve it?

    • +
+
+

In dependencies.rst:

+ +

In dependencies.rst:

+
+

Dependencies-2 (15 min)

+
+
+

Chloe just joined your team and will be working on her Master Thesis. She is +quite familiar with Python, still finishing some Python assignments (due in a +few weeks) and you give her a Python code for analyzing and plotting your +favorite data. The thing is that your Python code has been developed by +another Master Student (from last year) and requires a older version of +Numpy (1.18.1) and Matplotlib (3.1.3) (otherwise the code fails). The code +could probably work with a recent version of Python but has been validated with +Python 3.7 only. Having no idea what the code does, she decides that the best +approach is to create an isolated environment with the same dependencies +that were used previously. This will give her a baseline for future upgrade and +developments.

+

For this first exercise, we will be using conda for creating an isolated environment.

+
    +

  1. Create a conda environment:

    +
    $ conda create --name python37-env python=3.7 numpy=1.18.1 matplotlib=3.1.3
+
    +
    +
    2. +
+

Conda environments can also be managed (create, update, delete) from the +anaconda-navigator. Check out the corresponding documentation here.

+
    +

  1. Activate the environment:

    +
    $ conda activate python37-env
+
    +
    +
    +

    conda activate versus source activate

    +

    If you do not have a recent version of Anaconda or anaconda has not been +setup properly, you may encounter an error. With older version of anaconda, +you can try:

    +
    $ source activate python37-env
+
    +
    +
    +
    2. +

  2. Open a Python console and check that you have effectively the right version for each package:

    +
    import numpy
+import matplotlib
+
+print('Numpy version: ', numpy.__version__)
+print('Matplotlib version: ', matplotlib.__version__)
+
    +
    +

    Or use the one-liner if you have access to a terminal like bash

    +

    python -c “import numpy; print(numpy.__version__)” +python -c “import matplotlib;print(matplotlib.__version__)”

    +
    3. +

  3. Deactivate the environment:

    +
    $ conda deactivate
+
    +
    +
    4. +

  4. Check Numpy and Matplotlib versions in the default environment to make +sure they are different from python37-env.

    5. +
+

There is no need to specify the conda environment when using deactivate. It +deactivates the current environment.

+
+

Remark

+
    +

  • Sometimes the package version you would need does not seem to be +available. You may have to select another conda channel +for instance conda-forge. Channels can then +be indicated when installing a package:

    +
    $ conda install -c conda-forge matplotlib=3.1.3
+
    +
    +
    • +

  • We will see below that rather than specifying the list of dependencies as +argument of conda create, it is recommended to record dependencies in +a file.

    • +
+
+
+

In dependencies.rst:

+
+

Dependencies-3 (15 min, optional)

+

This is the same exercise as before but we use virtualenv rather than conda.

+
    +

  1. Create a venv:

    +
    $ python3 -m venv scicomp
+
    +
    +

    Here scicomp is the name of the virtual environment. It creates a new +folder called scicomp.

    +
    2. +

  2. Activate it. To activate your newly created virtual environment locate the +script called activate and execute it.

    +
      +

    • Linux/Mac-OSX: look at bin folder in the scicomp folder:

      +
      $ source scicomp/bin/activate
+
      +
      +
      • +

    • Windows: most likely you can find it in the Scripts folder.

      • +
    +
    3. +

  3. Install Numpy 1.18.1 and Matplotlib 3.1.3 into the virtual environment:

    +
    $ pip install numpy==1.18.1
+$ pip install matplotlib==3.1.3
+
    +
    +
    4. +

  4. Deactivate it:

    +
    $ deactivate
+
    +
    +
    5. +
+
+

In dependencies.rst:

+
+

Dependencies-4 (15 min)

+
    +

  • Create the file environment.yml or requirements.txt

    • +
  • +
    Create an environment based on these dependencies:
      +

    • Conda: $ conda env create --file environment.yml

      • +

    • Virtual environment: First create and activate, then $ pip install -r requirements.txt

      • +
    +
    +
    +
    • +
  • +
    Freeze the environment:
      +

    • Conda: $ conda env export > environment.yml

      • +

    • Virtual environment: $ pip freeze > requirements.txt

      • +
    +
    +
    +
    • +

  • Have a look at the generated (“frozen”) file.

    • +
+
+
+
+

Binder

+

In binder.rst:

+
+

Binder-1 (10 min)

+

Lea is a PhD student in computational biology and after 2 years of intensive +work, she is finally ready to publish her first paper. The code she has used +for analyzing her data is available on GitHub but her supervisor who is an +advocate of open science told her that sharing code is not sufficient.

+

Why is it possibly not enough to share “just” your code? +What problems can you anticipate 2-5 years from now?

+

We form small groups (4-5 persons) and discuss in groups. If the workshop is +online, each group will join a breakout room. +If joining a group is not possible or practical, we use the shared document +to discuss this collaboratively.

+

Each group write a summary (bullet points) of the discussion in the workshop +shared document (the link will be provided by your instructors).

+
+

In binder.rst:

+
+

Exercise/demo: Making your notebooks reproducible by anyone (15 min)

+

Instructor demonstrates this:

+
    +

  • Creates a GitHub repository

    • +

  • Uploads the notebook file

    • +

  • Then we look at the statically rendered version of the notebook on GitHub

    • +

  • Create a requirements.txt file which contains:

    +
    pandas==1.2.3
+matplotlib==3.4.2
+
    +
    +
    • +

  • Commit and push also this file to your notebook repository.

    • +

  • Visit https://mybinder.org and copy paste the code under “Copy the text below …” into your README.md:

    +../_images/binder.jpg +
    • +

  • Check that your notebook repository now has a “launch binder” +badge in your README.md file on GitHub.

    • +

  • Try clicking the button and see how your repository is launched +on Binder (can take a minute or two). Your notebooks can now be expored and executed in the cloud.

    • +

  • Enjoy being fully reproducible!

    • +
+
+

In binder.rst:

+
+

Binder-3 (optional)

+

Everything you deposit on Zenodo is meant to be kept (long-term archive). +Therefore we recommend to practice with the Zenodo “sandbox” (practice/test area) +instead: https://sandbox.zenodo.org

+
    +

  1. Link GitHub with Zenodo:

    2. +
+
+
    +

  • Go to https://sandbox.zenodo.org (or to https://zenodo.org for the real upload later, after practicing).

    • +

  • Log in to Zenodo with your GitHub account. Be aware that you may need to +authorize Zenodo application (Zenodo will redirect you back to GitHub for +Authorization).

    • +

  • Choose the repository webhooks options.

    • +

  • From the drop-down menu next to your email address at the top of the page, select GitHub.

    • +

  • You will be presented with a list of all your Github repositories.

    • +
+
+
    +

  1. Archiving a repo:

    2. +
+
+
    +

  • Select a repository you want to archive on Zenodo.

    • +

  • Toggle the “on” button next to the repository ou need to archive.

    • +

  • Click on the Repo that you want to reserve.

    • +

  • Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release.

    • +
+
+
    +

  1. Trigger Zenodo to Archive your repository

    2. +
+
+
    +

  • Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI.

    • +

  • If this is the first release of your code then you should give it a +version number of v1.0.0. Add description for your release then click the +Publish release button.

    • +

  • Zenodo takes an archive of your GitHub repository each time you create a new Release.

    • +
+
+
    +

  1. To ensure that everything is working:

    2. +
+
+
    +

  • Go to https://zenodo.org/account/settings/github/ (or the corresponding +sandbox at https://sandbox.zenodo.org/account/settings/github/), or the +Upload page (https://zenodo.org/deposit), you will find your repo is +listed.

    • +

  • Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo.

    • +

  • You can edit the archive on Zenodo and/or publish a new version of your software.

    • +

  • It is recommended that you add a description for your repo and fill in other metadata in the edit page. Instead of editing metadata +manually, you can also add a .zenodo.json or a CITATION.cff file to your repo and Zenodo will infer the metadata from this file.

    • +

  • Your code is now published on a Github public repository and archived on Zenodo.

    • +

  • Update the README file in your repository with the newly created zenodo badge.

    • +
+
+
+

In binder.rst:

+
+

Binder-4 (10 min)

+

We will be using an existing Zenodo DOI 10.5281/zenodo.3886864 to start Binder:

+
+
    +

  • Go to https://mybinder.org and fill information using Zenodo DOI (as shown on the animation below):

    • +
+https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif +
    +

  • You can also get a Binder badge and update the README file in the +repository. It is good practice to add both the Zenodo badge and the +corresponding Binder badge.

    • +
+
+
+
+
+

Packaging

+

In packaging.rst:

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/genindex/index.html b/branch/rkdarst--remove-catfacts-jsonl/genindex/index.html new file mode 100644 index 00000000..2bcdd957 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/genindex/index.html @@ -0,0 +1,140 @@ + + + + + + Index — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ + +

Index

+ +
+ +
+ + +
+
+
+ +
+ +
+

© Copyright 2020-2022, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/guide/index.html b/branch/rkdarst--remove-catfacts-jsonl/guide/index.html new file mode 100644 index 00000000..711c4c82 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/guide/index.html @@ -0,0 +1,256 @@ + + + + + + + + + + + + + + + Instructor’s guide — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Instructor’s guide

+
+

Learner personas

+

A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

+

A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

+

B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

+

Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren’t familiar.

+

Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter

+
+
+

About each section

+

In general, “Python for Scientific Computing could be a multi-year +course. We can’t even pretend to really teach even a small fraction +of it. We can, however, introduce people to things that can very +easily be missed in the typical academic career path.

+
    +

  • Python intro: We can’t really replace a Python tutorial, but +here we try to outline some of the main points. We don’t go over +this in the course.

    • +

  • Jupyter: Jupyter is somewhat useful, but the main reason we go +over it is that it provides a convenient user interface for the +other programming lessons (it’s easier to spend a bit of time with +Jupyter than expect people to be able to use some +editor/IDE/shell/etc). So, we do start from the beginning, so that +people can do the other lessons, but also try to teach some advanced +tips and tricks.

    • +

  • Numpy: The basic of much of the rest of scipy, so we need to +cover it. We try to get the main principles out, but if someone +already knows it this can be a bit boring. We try to make sure +everyone comes out with an appreciation for vectorization and +broadcasting.

    • +

  • Pandas: A lot of similar goals to the Numpy section, especially +the concepts behind Dataframes that one needs to know in order to +read other documentation.

    • +

  • Visualization: Matplotlib is getting a bit old, but is still the +backbone of other plotting packages. We try to get forth the ideas +of the matplotlib API that can be seen in other packages and the +importance of scripted plots.

    • +

  • Data formats: Input/output/storage is a common task, and can +easily either be a bottleneck or a huge mess. This lessons tries to +show some best practices with data formats and, as usual, get the +idea to not “do it yourself”. Pandas is used as a common framework, +but we should point out there are plenty of other options.

    • +

  • Scripts: The most important lesson here is to break out of +Jupyter/run buttons of editors. If you can’t make actual programs +with an actual interface, you can’t scale up.

    +
      +

    • This is the first lesson to introduce the command line. We +recommend being as simple as possible: at least demonstrate the +JupyterLab terminal and discuss the bigger picture behind what it +means and why.

      • +

    • This is also the first lesson to use non-Jupyter code editor. We +recommend again being simple: use the JupyterLab code editor to +start off, and carefully explain what is going on.

      • +
    +
    • +

  • Scipy: We don’t cover much here (this is super short), but the +point is scipy exists and the concept of wrapping existing C/fortran +libraries and so on.

    • +

  • Library ecosystem: This was an overview of the types of packages +available in the “scipy ecosystem”, which is a large and ill-defined +thing. But there is another point: choosing what to use. Do you +trust a half-done thing published on someone’s personal webpage? If +it’s on Github? How do you make your code more reusable? When +coming from academic courses, you get a “build it yourself” idea, +which isn’t sustainable in research.

    • +

  • Parallel programming:

    • +

  • Dependencies: The main point here is environments, another thing +you often don’t learn in courses.

    +
      +

    • There is a lot of material here. Consider what you will demo, +what will be done as exercises, and what is advanced/optional. +However, it is the fourth-day lesson that is most interactive, so +it is OK if it take a while to go through everything.

      • +

    • If someone else installs Anaconda for a user (e.g. admin-managed +laptop), the conda environment creations (with --name, +possibly with --prefix too?) may not work. Be prepared for +this and mention it. You don’t need to solve the problem but +acknowledge that the lesson becomes a demo. The virtualenv part +should hopefully work for them.

      • +
    +
    • +

  • Binder: Binder exists and can help make code +reproducible/reusable by others.

    • +

  • Packaging: How to make your code reusable by others. By the +time we get here, people are tired and the topics get involved. We +more explicitly say “you might want to watch and take this as a +demo”.

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/index.html b/branch/rkdarst--remove-catfacts-jsonl/index.html new file mode 100644 index 00000000..20c1ec95 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/index.html @@ -0,0 +1,342 @@ + + + + + + + + + + + + + + + Python for Scientific Computing — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python for Scientific Computing

+
+

Attending the course 22-25.november.2022?

+

See the course page here. +Whether you are or aren’t, the course material is below.

+
+

Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing some of the main Python tools for +computing: Jupyter for interactive analysis, NumPy and SciPy for +numerical analysis, matplotlib for visualization, and so on. In +addition, it talks about how python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python, because your work is more than the raw +code you write.

+

This course (like any course) can’t teach you Python… it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to.

+
+

Prerequisites

+ +

These are not prerequisites:

+
    +

  • Any external libraries, e.g. numpy

    • +

  • Knowing how to make scripts or use Jupyter

    • +
+
+
+

Videos

+

Videos from the 2021 instance of this course can be found in +this YouTube playlist.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

(prereq)

Introduction to Python

30 min

Jupyter

60 min

NumPy or Advanced NumPy

60 min

Pandas

60 min

Data visualization with Matplotlib

30 min

Data formats with Pandas and Numpy

60 min

Scripts

30 min

Web APIs with Python

15 min

SciPy

30 min

Library ecosystem

45 min

Parallel programming

30 min

Dependency management

30 min

Binder

60 min

Packaging

+
+
+
+

Reference

+ +
+
+

Who is the course for?

+

The course is targeted towards these learner personas:

+
    +

  • A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don’t know. They want to be able +to do their research more efficiently and make sure that they are +using the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren’t sure if they +are going in the right direction.

    • +

  • A2 can use numpy and pandas, but have learned little bits here and +there and hasn’t had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages)

    • +

  • B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves.

    • +
+
+
+

Motivation

+
+

Why Python

+

Python has become popular, largely due to good reasons. It’s very easy +to get started, there’s lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities.

+
+
+

Why not Python for Scientific Computing

+

While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools.

+
    +

  • Implementing performance-critical kernels. Python is a very +slow language, which often doesn’t matter if you can offload the +heavy lifting to fast compiled code, e.g. by using Numpy array +operations. But if what you’re trying to do isn’t vectorizable +then you’re out of luck. An alternative to Python, albeit much less +mature and with a smaller ecosystem, but which provides very fast +generated code, is Julia.

    • +

  • Creating libraries that can be called from other languages. In this +case you’ll often want to create a library with a C interface, which +can then be called from most languages. Suitable languages for this +sort of task, depending on what you are doing, could be Rust, C, +C++, or Fortran.

    • +

  • You really like static typing, or functional programming +approaches. Haskell might be what you’re looking for.

    • +
+
+
+

Python 2 vs Python 3

+

Python 3.0 came out in September 2008 and was just slightly different +enough that most code had to be changed, which meant that many +projects ignored it for many years. It was about 3-5 years until the +differences were reduced enough (and better transition plans came out, +so that it was reasonable to use a single code for both versions) that +it become more and more adopted in the scientific community. Python 2 +finally became unsupported in 2020, and by now Python 3 is the defacto +standard.

+

At this point, all new projects should use Python 3, and existing +actively developed projects should be upgraded to use it. Still, you +might find some old unmaintained tools that are only compatible with +Python 2.

+
+
+
+

Credits

+

This course was originally designed by Janne Blomqvist.

+

In 2020 it was completely redesigned by a team of the following:

+
    +

  • Authors: Radovan Bast, Richard Darst, Anne Fouilloux, Thor Wikfeldt, …

    • +

  • Editor:

    • +

  • Testers and advisors: Enrico Glerean

    • +
+

We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

+
+
+

See also

+
    +

  • High Performance Data Analytics in Python +<https://enccs.github.io/HPDA-Python/> is a logical follow-up to +this lesson that goes more in-depth to tools of high-performance +and large-scale Python.

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/installation/index.html b/branch/rkdarst--remove-catfacts-jsonl/installation/index.html new file mode 100644 index 00000000..ce6ca025 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/installation/index.html @@ -0,0 +1,353 @@ + + + + + + + + + + + + + + + Software installation — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Software installation

+

This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or some other way access to it. For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line for some lessons).

+

If you need installation help, show this page to someone around you +and they can probably do all you need

+
+

Generic list of tools required

+

Note: The actual installation instructions are below. This is a +generic description which will help those who already understand all +of the tools.

+
    +

  • Python 3 (Anaconda is recommended, it will include everything)

    +
      +

    • With some extra packages installed. They are all included in +Aanconda, and are listed in the environment.yml file you can +find under miniconda below.

      • +
    +
    • +

  • Text editor (several lessons, can also be done through Jupyterlab)

    • +

  • Command-line shell (several lessons, can also be done through Jupyterlab)

    • +

  • git (not needed, this lesson is usually done as a demo)

    • +
+
+

Generic instructions with miniconda and an environment file (advanced)

+

This is the advanced, minimal method of installing the Python +packages. For most people, we recommend Anaconda (below). You +will actually learn about miniconda during the workshop. This +doesn’t provide the graphical Anaconda navigator, so you’ll need to +activate the miniconda environment using the command line.

+

You can read how to install miniconda from the CodeRefinery +installation instructions.

+

Then this environment file +contains all packages needed, and can be installed with:

+
$ conda env create -f https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/software/environment.yml
+
+
+

Each time you start a new shell, you need to activate miniconda (if +you don’t do run conda init), and then you need to activate the +proper environment with conda activate python-for-scicomp.

+

We might have missed some packages, though, which can be later +installed with conda install.

+
+
+
+

Python

+

We expect you to have a working Python installation with some common +libraries. We recommend that you install the Anaconda python +distribution. The +Anaconda Navigator +provides a convenient way to access the software.

+
+

Other options

+

We recommend Anaconda, Anaconda Navigator, and JupyterLab in these +instructions because it is simple and can be used by everyone. As +you advance in your career, we +recommend that you explore other options as well, but +that can come later.

+

Any other Python distribution which you can install libraries into +would work, but because there are so many different ways to do this, +we don’t support them. You would need the extra libraries mentioned +in the Miniconda instructions above.

+
+
+

JupyterLab

+

We do most of the lessons from JupyterLab (and JupyterLab provides +most of the other tools we need). If you install the full +Anaconda distribution, this will be available and can be started +either through Anaconda Navigator or command line.

+
+
+

Verification of Python and JupyterLab

+
+

Watch the video

+

See this verification in video form - if you can do this, you are +ready to go for day one. Your exact steps may be a bit different.

+
+

You should be able to start JupyterLab. You can do this from the +Anaconda Navigator (recommended if you have it):

+
+../_images/anaconda-navigator-jupyterlab.png +
+

Starting JupyterLab from the Anaconda Navigator.

+
+
+

… or you can start JupyterLab from the command line:

+
$ jupyter-lab
+(... Jupyter starts in a web browser)
+
+
+

Verify that you can start a Jupyter notebook. We will learn how to +do this in day 1, but you can try running print("Hello, world!") +if you want.

+
+../_images/jupyterlab-notebook.png +
+

Starting a Jupyter Notebook from JupyterLab.

+
+
+
+
+
+

Text editor

+

For one portion of the course, you will need a text editor. If you +don’t know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need - no extra installation +needed.

+
+

Other editors

+

Because we need to be simple in our teaching, we only teach the +most basic editors. We encourage you to try out more advanced ones +yourself.

+

For other editors, see the CodeRefinery instructions. You don’t +exactly need a terminal editor - the graphical ones, such as VSCode or +whatever you use now, will work as well.

+
+
+
+

Command line

+

You need access to the command line for some lessons. JupyterLab +includes it, so no extra installation is needed. If you want to +test in advance:

+
    +

  • You can start it from JupyterLab (recommended):

    +
    +../_images/jupyterlab-terminal.png +
    +

    From the JupyterLab launcher, select “Terminal”.

    +
    +
    +
    • +
+
+

Other ways to access the command line

+
    +

  • From the Anaconda Navigator:

    +
    +../_images/anaconda-prompt.png +
    +

    From the Anaconda Navigator, you can select “environments” on the +left, then click on one, then the arrow, then “Open terminal”.

    +
    +
    +
    • +

  • From your operating system’s terminal applications, if you activate +Anaconda.

    • +
+
+
+

Verification of the command line

+

To verify command line usage, type the following commands (without the +$), and you should see the corresponding output that lists the +Python version:

+
$ python -V
+Python 3.8.3
+
+## Or python3...
+$ python3 -V
+Python 3.8.3
+
+
+

Any version of Python 3 through a recent Anaconda should work for the +course.

+
+
+
+

Zoom

+

If this is an online workshop, it might use Zoom. You can see +CodeRefinery instructions for it.

+
+
+

Need help?

+

If you have access, come to one of the installation help sessions. +Or, ask your colleagues: these are standard tools and you can +definitely find someone can help you get set up!

+
+
+

See also

+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/jupyter/index.html b/branch/rkdarst--remove-catfacts-jsonl/jupyter/index.html new file mode 100644 index 00000000..2d0ccbd6 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/jupyter/index.html @@ -0,0 +1,421 @@ + + + + + + + + + + + + + + + Jupyter — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Jupyter

+
+

Questions

+
    +

  • What is the purpose of a “Computational narrative”?

    • +

  • What role does Jupyter play in development?

    • +

  • When is Jupyter not a good tool?

    • +
+
+
+

Objectives

+

This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.

+
    +

  • Be able to use Jupyter to run examples for the rest of the course.

    • +

  • Be able to run Jupyter in a directory do your own work.

    • +

  • You won’t be a Jupyter expert after this, but should be able to do the rest of the course.

    • +
+
+
+

What is Jupyter?

+

Jupyter is a web-based interactive computing system. It is most well known for having the notebook file format and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a computational narrative.

+

Jupyter is good for data exploration and interactive work.

+

We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.

+
+
+

Getting started with Jupyter

+
    +

  • Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run jupyter-lab. You can also start in from Anaconda Navigator.

    • +
+

For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need.

+

Here, we see a tour of the JupyterLab interface:

+

Main UI tour

+
+
+

Exercises 1

+
+

Exercises: Jupyter-1

+
    +

  1. Start Jupyter in the directory you want to use for this course.

    +
      +

    • If you are starting from the navigator, change to the directory you want to use.

      • +

    • If you are starting from the command line, you should navigate to the directory you want to use first.

      • +
    +
    2. +

  2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.

    3. +

  3. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.

    4. +

  4. (optional, advanced) Look at the notebook file in a text +editor. How does it work?

    5. +
+

If everything works for you, this will end very quickly. You can begin reading the next sections independently.

+
+
+
+

Running code in Jupyter

+

A notebook is divided into cells. Each cell has some input, and when it is executed an output appears right below it.

+

There are different types of cells: primarily code cells and markdown cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving style to text - you can check out this reference. For example the previous sentence is:

+
Markdown is a lightweight way of giving *style* to `text` - you 
+can check out [this reference](https://commonmark.org/help/).
+
+
+

notebook UI

+

When using keyboard shortcuts, you can switch between edit mode and command mode with Enter and Esc.

+

You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:

+
    +

  • Ctrl-Enter: Run cell

    • +

  • Shift-Enter: Run cell and select cell below

    • +

  • Alt-Enter: Run cell and insert new cell below

    • +

  • a / b: insert new cell above/below

    • +

  • m / y: markdown cell / code cell

    • +

  • x: cut cell

    • +

  • c: copy cell

    • +

  • v: paste cell

    • +

  • d, d: delete cell

    • +
+

Now, let’s look at some code samples:

+
+
+
for i in range(3):
+    print(i)
+
+
+
+
+
0
+1
+2
+
+
+
+
+
+
+
print(sum(range(5)))
+
+
+
+
+
10
+
+
+
+
+

By convention, if the last thing in a cell is an object, that object gets printed:

+
+
+
sum(range(5))
+sum(range(10))
+
+
+
+
+
45
+
+
+
+
+

In addition to raw cells, there are magics, which exist outside of Python. They are a property of the runtime itself (in Python’s case, they come from IPython. For example, the following cell magic %%bash turns the cell into a shell script (may not work on all operating systems):

+
+
+
%%bash
+for x in $(seq 3) ; do
+    echo $x
+done
+
+
+
+
+
1
+2
+3
+
+
+
+
+
    +

  • A cell magic starts with %%, goes on the first line of a cell, and applies to the whole cell

    • +

  • A line magic starts with %, goes on any line, and applies to that line.

    • +
+
+
+

Exercises 2

+
+

Exercises: Jupyter-2

+
    +

  1. Run some trivial code, such as print(1).

    2. +

  2. Run some slightly less trivial code, like print out the first +ten Fibonacci numbers.

    3. +

  3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the reference to add a heading, bullet list, and some (bold, italic, or inline code)

    4. +

  4. Use the %%timeit magic function to time your Fibonacci +function.

    5. +

  5. Again using %%timeit, figure out the fastest way to sum the +numbers 0 to 1000000.

    6. +

  6. Once you are done, close your notebooks and other tabs you don’t need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.

    7. +
+
+ +
+
+

Why Jupyter?

+
    +

  • Being able to edit, check, re-edit quickly is great for prototyping and testing new ideas

    +
      +

    • Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.

      • +
    +
    • +

  • You can make a complete story - in one place. No more having code, figures, and description in different places.

    +
      +

    • Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.

      • +
    +
    • +

  • Notebook as an interactive publication itself - for example the discovery of gravitational waves data is released as a notebook.

    • +

  • Jupyter Notebooks display on Github - low-barrier way to share your analysis.

    • +

  • Teaching - great for getting difficult software distribution out of the way.

    • +
+
+
+

Why not Jupyter?

+

Jupyter is great for many things, but there are some problems if not used well:

+
    +

  • They don’t promote modularity, and once you get started in a +notebook it can be hard to migrate to modules.

    • +

  • They are difficult to test. There are things to run notebooks as +unit tests like nbval, but it’s not +perfect.

    • +

  • Notebooks can be version controlled +(nbdime helps with that), but +there are still limitations.

    • +

  • You can change code after you run it and run code out of order. +This can make debugging hard and results irreproducible if you +aren’t careful.

    • +

  • Notebooks aren’t named by default and tend to acquire a bunch of +unrelated stuff. Be careful with organization!

    • +

  • Once lots of code is in notebooks, it can be hard to change to +proper programs that can be scripted.

    • +
+

You can read more about these downsides https://scicomp.aalto.fi/scicomp/jupyter-pitfalls/.

+

But these downsides aren’t specific to Jupyter! They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.

+
+
+

Exercises 3

+
+

Exercises: Jupyter-3

+

(optional) Discuss the following in groups:

+
    +

  1. Have any of you used Jupyter in a way that became impossible to +maintain: too many files, code all spread out, not able to find +your code and run it in the right order. How did you solve that?

    2. +

  2. On the other hand, what are your successes with Jupyter?

    3. +

  3. How can you prevent these problems by better development strategies?

    4. +
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Jupyter is powerful and can be used for interactive work

    • +

  • … but not the end solution when you need to scale up.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/libraries/index.html b/branch/rkdarst--remove-catfacts-jsonl/libraries/index.html new file mode 100644 index 00000000..5c3b2bc1 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/libraries/index.html @@ -0,0 +1,489 @@ + + + + + + + + + + + + + + + Library ecosystem — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Library ecosystem

+
+

Questions

+
    +

  • What happens when you need some method Beyond what we discuss in this course, what is available?

    • +

  • How do you decide what to build on for your work?

    • +
+
+
+

Objectives

+
    +

  • Know of some other available packages, but don’t necessarily know +how to use them.

    • +

  • Be able to evaluate what you should reuse and what you should +develop yourself.

    • +
+
+

You can’t do everything yourself. In fact, once we heard a quote such +as this:

+
+

When you are a student, you are expected to do everything +yourself, and that is how you are evaluated. When you become a +researcher, you have to be able to reuse what others have done. +We don’t have much practice in doing this. +– A student

+
+

In this lesson, we’ll talk about the broader ecosystem in Python: all +the resources you have available to you. Perhaps we can even classify +this into two types:

+
    +

  • Well-maintained libraries that are used by many others.

    • +

  • A wide variety of public code that might work but isn’t necessarily +well-maintained (for example, code from articles).

    • +
+

We’ll start with the first then go to the second.

+
+

Glossary

+
+
Library

A collection of code used by a program.

+
+
Package

A library that has been made easily installable and reusable. +Often published on public repositories such as the Python Package +Index

+
+
Dependency

A requirement of another program, not included in that program.

+
+
+
+
+

The Python/SciPy ecosystem

+

This section is nothing more than a tour of what exists in Python. +You aren’t expected to particularly remember any of these right now, +but searching for these repositories is a starting point of a lot of +future work.

+

The “core” packages could be considered. Many other packages build on +these, and others that try to do similar things often try to conform +to their interfaces (especially numpy):

+
    +

  • Python

    • +

  • Numpy - arrays, everything builds on this

    • +

  • Scipy - scientific functions (not necessarily a lot builds on this)

    • +

  • matplotlib - plotting, many other plotting tools build on this

    • +

  • pandas - data structures

    • +

  • IPython / Jupyter: interactive work

    • +
+
+

Core numerics libraries

+
    +

  • numpy - arrays and array math.

    • +

  • scipy - software +for math, science, and engineering.

    • +
+
+
+

Plotting

+
    +

  • matplotlib - base plotting package, +somewhat low level but almost everything builds on it.

    • +

  • seaborn - higher level plotting +interface; statistical graphics.

    • +

  • mayavi - 3D plotting

    • +

  • PIL - image manipulation. The +original PIL is no longer maintained, the new “Pillow” is a drop-in +replacement.

    • +
+
+
+

Data analysis and other important core packages

+ +
+
+

Interactive computing and human interface

+
    +

  • Interactive computing

    +
      +

    • IPython - nicer interactive interpreter

      • +

    • Jupyter (notebook, lab, hub, …) - +web-based interface to IPython and other languages

      • +
    +
    • +

  • Testing

    +
      +

    • pytest - automated testing interface

      • +
    +
    • +

  • Documentation

    +
      +

    • Sphinx - documentation generator +(also used for this lesson…)

      • +
    +
    • +

  • Development environments

    +
      +

    • Spyder - interactive Python +development environment.

      • +
    +
    • +

  • Binder - load any git repository in +Jupyter automatically, good for reproducible research

    • +
+
+
+

Speeding up code and parallelism

+
    +

  • PyMPI - Message +Passing Interface (MPI) in Python for parallelizing jobs.

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • numba - just in time compiling of +functions for speed-up

    • +

  • PyPy - Python written in Python so that +it can internally optimize more.

    • +

  • Dask - distributed array data structure for +distributed computation

    • +

  • Joblib - easy embarrassingly +parallel computing

    • +

  • IPyParallel - easy +parallel task engine

    • +

  • numexpr - Fast evaluation of +array expressions by automatically compiling the arithmetic.

    • +
+
+
+

Machine learning

+

If you need some machine learning, you probably already know what you +need and this list is short and irrelevant.

+ +
+
+
+

Connecting Python to other languages

+

As we discussed with Scipy, very many of the above packages aren’t +written in Python: they are written in some other language and have a +Python interface. Python is written in C, and thus has great C +interfaces. This contributes to two things:

+
    +

  • Extending Python by writing your own modules in C.

    +
      +

    • It’s actually common to first have (or write) an analysis package +in C or C++, then make the Python interface. Then it can be +supported by other languages, too.

      • +

    • Or one starts an analysis package in Python, and slowly moves bits +of it to C over time as there is need.

      • +
    +
    • +

  • Embedding Python, where you have another primary application +that uses Python under the hood as an internal scripting language.

    • +
+

These features aren’t exactly unique to Python, but Python does +support them very well. Read more: Extending and embedding Python.

+
+

Tools for interfacing with other languages

+

These days, one rarely directly extends the Python interpreter, but uses

+
    +

  • cffi and ctypes - interface to C +and compatible libraries

    • +

  • cython - easily make C extensions for +Python, also interface to C libraries

    • +

  • f2py - interface to Fortran +code

    • +

  • swig - connect to a variety of programming languages.

    • +

  • Boost.python - Another Python/C++ interface

    • +

  • TODO: Julia modules for Python?

    • +
+
+
+
+

Evaluating Python packages for reuse

+

Above, we talked about well-maintained mainstream packages. Do you +trust random code you find online (for example included in a paper)?

+

Especially consider scientific results, which have to be correct. +Still, you also can’t build everything yourself, so you have to +carefully evaluate the situation.

+

Below are some things to consider:

+
    +

  • Are there releases? Have they been going on for a while?

    • +

  • Are releases installable without copy-paste?

    • +

  • Are dependencies handled well?

    • +

  • Does the code randomly change, so that it no longer works with your +code. Is this relevant?

    • +

  • Is there good documentation, that not just tells how to use it but +how it works?

    • +

  • Is there automated testing? What’s your evaluation of the risk of +undetectable scientific errors?

    • +

  • Is there a community, or is it one person? Is it backed by some +organization? Does it have a permanent home?

    • +

  • Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) +where a community could form?

    • +

  • Do others post issues and make contributions? Are these issues +dealt with in a timely manner? Can you search past bug reports?

    • +

  • Is the software citeable?

    • +
+
+
+

Is your work reuseable?

+

Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a CodeRefinery workshop will make +sure you have the tools to produce high-quality, reusable code.

+
+
+

What’s next?

+
    +

  • The CodeRefinery workshop mentioned +above will prepare you for others to reuse your code and for you to +contribute to other code.

    • +

  • The upcoming Dependency management lesson will teach you how to +record and manage dependencies so that anyone can seamlessly reuse +your code.

    • +
+
+
+

Exercises

+
+

Libraries 1.1: Libraries in your work

+

What libraries do you use in your work? What have you made, which +you could have reused from some other source. What have you used +from some other source that you wished you had re-created?

+

Discuss in your groups or HackMD.

+
+ +
+

Libraries 1.2: Evaluating packages

+

Below are some links to some packages, both public and made by the +authors of this lesson. Evaluate them, considering “would I use +this in my project?”

+
    +

  1. https://github.com/networkx/networkx/

    2. +

  2. some code on webpage in a paper’s footnote

    3. +

  3. https://github.com/rkdarst/pcd

    4. +

  4. https://github.com/dftlibs/numgrid

    5. +

  5. https://github.com/rkdarst/dynbench

    6. +

  6. https://vpython.org/

    7. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • Almost everything you need can already be found, except your +incremental work.

    • +

  • When do you build on that other work, and when do you create +things yourself?

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/numpy-advanced/index.html b/branch/rkdarst--remove-catfacts-jsonl/numpy-advanced/index.html new file mode 100644 index 00000000..2b5e30ca --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/numpy-advanced/index.html @@ -0,0 +1,572 @@ + + + + + + + + + + + + + + + Advanced NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Advanced NumPy

+
+

Questions

+
    +

  • How can NumPy be so fast?

    • +

  • Why are some things fast and some things slow?

    • +

  • How can I control whether NumPy makes a copy or operates in-place?

    • +
+
+
+

Objectives

+
    +

  • Understand why NumPy has so many specialized functions for specific operations

    • +

  • Understand the underlying machinery of the Numpy ndarray object

    • +

  • Understand when and why NumPy makes a copy of the data rather than a view

    • +
+

This is intended as a follow-up to the basic NumPy lesson. The intended +audience for this advanced lesson is those who have used NumPy before and +now want to learn how to get the most out of this amazing package.

+
+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the NumPy package can be really +fast. How does it do that? We will dive into how NumPy works behind the scenes +and use this knowledge to our advantage. This lesson also serves as an +introduction to reading the definitive work on this topic: +Guide to NumPy by +Travis E. Oliphant, its initial creator.

+
+

NumPy can be really fast

+

Python, being an interpreted programming language, is quite slow. Manipulating +large amounts of numbers using Python’s build-in lists would be impractically +slow for any serious data analysis. Yet, the numpy package can be really fast.

+

How fast can NumPy be? Let’s race NumPy against C. The contest will be to sum +together 100 000 000 random numbers. We will give the C version below, you get +to write the NumPy version:

+
#include <stdlib.h>
+#include <stdio.h>
+#define N_ELEMENTS 100000000
+int main(int argc, char** argv) {
+    double* a = (double*) malloc(sizeof(double) * N_ELEMENTS);
+    int i;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        a[i] = (double) rand() / RAND_MAX;
+    }
+    double sum = 0;
+    for(i=0; i<N_ELEMENTS; ++i) {
+        sum += a[i];
+    }
+    printf("%f", sum);
+    return 0;
+}
+
+
+
+
+

Exercise 1

+
+

Exercises: Numpy-Advanced-1

+

Write a Python script that uses NumPy to generate 100 million (100000000) +random numbers and add them all together. Time how long it takes to execute. +Can you beat the C version?

+

If you are having trouble with this, we recommend completing the +basic NumPy lession before continuing with this +advanced lesson. If you are taking a live course - don’t +worry, watch and learn and explore some during the exercises!

+
+ +
+
+

The libraries behind the curtain: MKL and BLAS

+

NumPy is fast because it outsources most of its heavy lifting to heavily +optimized math libraries, such as Intel’s Math Kernel Library (MKL), +which are in turn derived from a Fortran library called +Basic Linear Algebra Subprograms (BLAS). +BLAS for Fortran was published in 1979 +and is a collection of algorithms for common mathematical operations that are +performed on arrays of numbers. Algorithms such as matrix multiplication, +computing the vector length, etc. The API of the BLAS library was later +standardized, and today there are many modern implementations available. These +libraries represent over 40 years of optimizing efforts and make use of +specialized CPU instructions for manipulating arrays. +In other words, they are fast.

+

One of the functions inside the BLAS library is a +function +to compute the “norm” of a vector, which is the same as computing its length, using the +Pythagorean theorem: +\(\sqrt(a[0]^2 + a[1]^2 + \ldots)\).

+

Let’s race the BLAS function versus a naive “manual” version of computing the vector norm. +We start by creating a decently long vector filled with random numbers:

+
import numpy as np
+rng = np.random.default_rng(seed=0)
+a = rng.random(100_000_000)
+
+
+

We now implement the Pythagorean theorem using basic NumPy functionality and +use %%timeit to record how long it takes to execute:

+
%%timeit
+l = np.sqrt(np.sum(a ** 2))
+print(l)
+
+
+

And here is the version using the specialized BLAS function norm():

+
%%timeit
+l = np.linalg.norm(a)
+print(l)
+
+
+
+
+

NumPy tries to avoid copying data

+

Understanding the kind of operations that are expensive (take a long time) and +which ones are cheap can be surprisingly hard when it comes to NumPy. A big +part of data processing speed is memory management. Copying big arrays takes +time, so the less of that we do, the faster our code runs. The rules of when +NumPy copies data are not trivial and it is worth your while to take a closer +look at them. This involves developing an understanding of how NumPy’s +numpy.ndarray datastructure works behind the scenes.

+
+

An example: matrix transpose

+

Transposing a matrix means that all rows become columns and all columns become +rows. All off-diagonal values change places. Let’s see how long NumPy’s +transpose function takes, by transposing a huge (10 000 ✕ 20 000) +rand() matrix:

+
import numpy as np
+a = np.random.rand(10_000, 20_000)
+print(f'Matrix `a` takes up {a.nbytes / 10**6} MB')
+
+
+

Let’s time the transpose() method:

+
%%timeit
+b = a.transpose()
+
+
+

It takes mere nanoseconds to transpose 1600 MB of data! How?

+
+
+

The ndarray exposed

+

The first thing you need to know about numpy.ndarray is that the +memory backing it up is always a flat 1D array. For example, a 2D matrix is +stored with all the rows concatenated as a single long vector.

+../_images/01_memory_layout.svg

NumPy is faking the second dimension behind the scenes! When we request the +element at say, [2, 3], NumPy converts this to the correct index in the +long 1D array [11].

+
+
    +

  • Converting [2, 3] → [11] is called “raveling”

    • +

  • The reverse, converting [11] → [2, 3] is called “unraveling”

    • +
+
+

The implications of this are many, so take let’s take some time to understand +it properly by writing our own ravel() function.

+
+
+
+

Exercise 2

+
+

Exercises: Numpy-Advanced-2

+

Write a function called ravel() that takes the row and column of an +element in a 2D matrix and produces the appropriate index in an 1D array, +where all the rows are concatenated. See the image above to remind yourself +how each row of the 2D matrix ends up in the 1D array.

+

The function takes these inputs:

+
+
    +

  • row The row of the requested element in the matrix as integer index.

    • +

  • col The column of the requested element in the matrix as integer index.

    • +

  • n_rows The total number of rows of the matrix.

    • +

  • n_cols The total number of columns of the matrix.

    • +
+
+

Here are some examples of input and desired output:

+
+
    +

  • ravel(2, 3, n_rows=4, n_cols=4) → 11

    • +

  • ravel(2, 3, n_rows=4, n_cols=8) → 19

    • +

  • ravel(0, 0, n_rows=1, n_cols=1) → 0

    • +

  • ravel(3, 3, n_rows=4, n_cols=4) → 15

    • +

  • ravel(3_465, 18_923, n_rows=10_000, n_cols=20_000) → 69_318_923

    • +
+
+
+ +
+
+

Strides

+

As seen in the exercise, to get to the next row, we have to skip over +n_cols indices. To get to the next column, we can just add 1. To generalize +this code to work with an arbitrary number of dimensions, NumPy has the concept +of “strides”:

+
np.zeros((4, 8)).strides           # (64, 8)
+np.zeros((4, 5, 6, 7, 8)).strides  # (13440, 2688, 448, 64, 8)
+
+
+

The strides attribute contains for each dimension, the number of bytes (not array indexes) we +have to skip over to get to the next element along that dimension. For example, +the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we +have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of +double-precision floating point numbers. Each one of those bad boys takes up 8 +bytes, so all the indices are multiplied by 8 to get to the proper byte in the +memory array. To move to the next column in the matrix, we skip ahead 8 bytes.

+

So now we know the mystery behind the speed of transpose(). NumPy can avoid +copying any data by just modifying the strides of the array:

+
import numpy as np
+
+a = np.random.rand(10_000, 20_000)
+b = a.transpose()
+
+print(a.strides)  # (160000, 8)
+print(b.strides)  # (8, 160000)
+
+
+
+

Another example: reshaping

+

Modifying the shape of an array through numpy.reshape() is also +accomplished without any copying of data by modifying the strides:

+
a = np.random.rand(20_000, 10_000)
+print(f'{a.strides=}')  # (80000, 8)
+b = a.reshape(40_000, 5_000)
+print(f'{b.strides=}')  # (40000, 8)
+c = a.reshape(20_000, 5_000, 2)
+print(f'{c.strides=}')  # (80000, 16, 8)
+
+
+
+
+
+

Exercises 3

+
+

Exercises: Numpy-Advanced-3

+

A little known feature of NumPy is the numpy.stride_tricks module +that allows you to modify the strides attribute directly. Playing +around with this is very educational.

+
    +

  1. Create your own transpose() function that will transpose a 2D matrix +by reversing its shape and strides attributes using +numpy.lib.stride_tricks.as_strided().

    2. +

  2. Create a (5 ✕ 100 000 000 000) array containing on the first row all +1’s, the second row all 2’s, and so on. Start with an 1D array +a = np.array([1., 2., 3., 4., 5.]) +and modify its shape and strides attributes using +numpy.lib.stride_tricks.as_strided() to obtain the desired 2D +matrix:

    +
    array([[1., 1., 1., ..., 1., 1., 1.],
+       [2., 2., 2., ..., 2., 2., 2.],
+       [3., 3., 3., ..., 3., 3., 3.],
+       [4., 4., 4., ..., 4., 4., 4.],
+       [5., 5., 5., ..., 5., 5., 5.]])
+
    +
    +
    3. +
+
+ +
+
+

A fast thing + a fast thing = a fast thing?

+

If numpy.transpose() is fast, and numpy.reshape() is fast, then +doing them both must be fast too, right?:

+
# Create a large array
+a = np.random.rand(10_000, 20_000)
+
+
+

Measuring the time it takes to first transpose and then reshape:

+
%%timeit -n 1 -r 1
+a.T.reshape(40_000, 5_000)
+
+
+

In this case, the data actually had to be copied and it’s super slow (it takes +seconds instead of nanoseconds). When the array is first created, it is laid +out in memory row-by-row (see image above). The transpose left the data laid +out in memory column-by-column. To see why the copying of data was inevitable, +look at what happens to this smaller (2 ✕ 3) matrix after transposition and +reshaping. You can verify for yourself there is no way to get the final array +based on the first array and some clever setting of the strides:

+
a = np.array([[1, 2, 3], [4, 5, 6]])
+
+print('Original array:')
+print(a)
+
+print('\nTransposed:')
+print(a.T)
+
+print('\nTransposed and then reshaped:')
+print(a.T.reshape(2, 3))
+
+
+
+
+

Copy versus view

+

Whenever NumPy constructs a new array by modifying the strides instead of +copying data, we way it created a “view”. This also happens when we select only +a portion of an existing matrix. Whenever a view is created, the +numpy.ndarray object will have a reference to the original array in +its base attribute:

+
a = np.zeros((5, 5))
+print(a.base)  # None
+b = a[:2, :2]
+print(b.base.shape)  # (5, 5)
+
+
+
+

Warning

+

When you create a large array and select only a portion of it, the large +array will stay in memory if a view was created!

+
+

The new array b object has a pointer to the same memory buffer as the array +it has been derived from:

+
print(a.__array_interface__['data'])
+print(b.__array_interface__['data'])
+
+
+

Views are created by virtue of modifying the value of the shape attribute +and, if necessary, apply an offset to the pointer into the memory buffer so it +no longer points to the start of the buffer, but somewhere in the middle:

+
b = a[1:3, 1:3]   # This view does not start at the beginning
+offset = b.__array_interface__['data'][0] - a.__array_interface__['data'][0]
+print('Offset:', offset, 'bytes')  # Offset: 48 bytes
+
+
+../_images/02_views.svg

Since the base array and its derived view share the same memory, any changes to +the data in a view also affects the data in the base array:

+
b[0, 0] = 1.
+print(a)  # Original matrix was modified
+
+
+

Whenever you index an array, NumPy will attempt to create a view. Whether or +not that succeeds depends on the memory layout of the array and what kind of +indexing operation was done. If no view can be created, NumPy will create a new +array and copy over the selected data:

+
c = a[[0, 2]]  # Select rows 0 and 2
+print(c.base)  # None. So not a view.
+
+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • The best way to make your code more efficient is to learn more about the +NumPy API and use specialized functions whenever possible.

    • +

  • NumPy will avoid copying data whenever it can. Whether it can depends on +what kind of layout the data is currently in.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/numpy/index.html b/branch/rkdarst--remove-catfacts-jsonl/numpy/index.html new file mode 100644 index 00000000..bde2aefe --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/numpy/index.html @@ -0,0 +1,640 @@ + + + + + + + + + + + + + + + NumPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

NumPy

+
+

Questions

+
    +

  • Why use NumPy instead of pure python?

    • +

  • How to use basic NumPy?

    • +

  • What is vectorization?

    • +
+
+
+

Objectives

+
    +

  • Understand the Numpy array object

    • +

  • Be able to use basic NumPy functionality

    • +

  • Understand enough of NumPy to seach for answers to the rest of your questions ;)

    • +
+

We expect most people to be able to do all the basic exercises +here. It is probably quite easy for many people; we have advanced +exercises at the end in that case.

+
+

So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible.

+
+

What is an array?

+

For example, consider [1, 2.5, 'asdf', False, [1.5, True]] - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately.

+

NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it.

+

An array is a ‘grid’ of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has:

+
    +

  • dtype - data type. Arrays always contain one type

    • +

  • shape - shape of the data, for example 3×2 or 3×2×500 or even +500 (one dimensional) or [] (zero dimensional).

    • +

  • data - raw data storage in memory. This can be passed to C or +Fortran code for efficient calculations.

    • +
+

To test the performance of pure Python vs NumPy we can write in our jupyter notebook:

+

Create one list and one ‘empty’ list, to store the result in

+
a = list(range(10000))
+b = [ 0 ] * 10000
+
+
+

In a new cell starting with %%timeit, loop through the list a and fill the second list b with a squared

+
%%timeit
+for i in range(len(a)):
+  b[i] = a[i]**2
+
+
+

That looks and feels quite fast. But let’s take a look at how NumPy performs for the same task.

+

So for the NumPy example, create one array and one ‘empty’ array to store the result in

+
import numpy as np
+a = np.arange(10000)
+b = np.zeros(10000)
+
+
+

In a new cell starting with %%timeit, fill b with a squared

+
%%timeit
+b = a ** 2
+
+
+

We see that compared to working with numpy arrays, working with traditional python lists is actually slow.

+
+
+

Creating arrays

+

There are different ways of creating arrays (numpy.array(), numpy.ndarray.shape, numpy.ndarray.size):

+
a = np.array([1,2,3])               # 1-dimensional array (rank 1)
+b = np.array([[1,2,3],[4,5,6]])     # 2-dimensional array (rank 2)
+
+b.shape                             # the shape (rows,columns)
+b.size                              # number of elements
+
+
+

In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content (numpy.zeros(), numpy.ones(), numpy.full(), numpy.eye(), numpy.arange(), numpy.linspace()):

+
np.zeros((2, 3))             # 2x3 array with all elements 0
+np.ones((1,2))               # 1x2 array with all elements 1
+np.full((2,2),7)             # 2x2 array with all elements 7
+np.eye(2)                    # 2x2 identity matrix
+
+np.arange(10)                # Evenly spaced values in an interval
+np.linspace(0,9,10)          # same as above, see exercise
+
+c = np.ones((3,3))
+d = np.ones((3, 2), 'bool')  # 3x2 boolean array
+
+
+

Arrays can also be stored and read from a (.npy) file (numpy.save(), numpy.load()):

+
np.save('x.npy', a)           # save the array a to a .npy file
+x = np.load('x.npy')          # load an array from a .npy file and store it in variable x
+
+
+

In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array (numpy.ndarray.dtype, numpy.ndarray.astype()):

+
d.dtype                    # datatype of the array
+d.astype('int')            # change datatype from boolean to integer
+
+
+

In the last example, .astype('int'), it will make a copy of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed.

+
+
+

Exercises 1

+
+

Exercises: Numpy-1

+
    +

  1. Datatypes Try out np.arange(10) and np.linspace(0,9,10), what is the difference? Can you adjust one to do the same as the other?

    2. +

  2. Datatypes Create a 3x2 array of random float numbers (check numpy.random.random()) between 0 and 1. Now change the arrays datatype to int (array.astype). How does the array look like?

    3. +

  3. Reshape Create a 3x2 array of random integer numbers between 0 and 10. Change the shape of the array (check array.reshape) in any way possible. What is not possible?

    4. +

  4. NumPyI/O Save above array to .npy file (numpy.save()) and read it in again.

    5. +
+
+ +
+
+

Array maths and vectorization

+

Clearly, you can do math on arrays. Math in NumPy is very fast because it is +implemented in C or Fortran - just like most other high-level languages such as +R, Matlab, etc do.

+

By default, basic arithmetic (+, -, *, /) in NumPy is +element-by-element. That is, the operation is performed for each element in the +array without you having to write a loop. We say an operation is “vectorized” +when the looping over elements is carried out by NumPy internally, which uses +specialized CPU instructions for this that greatly outperform a regular Python +loop.

+

Note that unlike Matlab, where * means matrix multiplication, NumPy uses +* to perform element-by-element multiplication and uses the @ symbol to +perform matrix multiplication:

+
a = np.array([[1,2],[3,4]])
+b = np.array([[5,6],[7,8]])
+
+# Addition
+c = a + b
+d = np.add(a,b)
+
+# Matrix multiplication
+e = a @ b
+f = np.dot(a, b)
+
+
+

Other common mathematical operations include: - (numpy.subtract), * (numpy.multiply), / (numpy.divide), .T (numpy.transpose()), numpy.sqrt, numpy.sum(), numpy.mean(), …

+
+
+

Exercises 2

+
+

Exercises: Numpy-2

+ +
+ +
+
+

Indexing and Slicing

+
+

See also

+

Numpy basic indexing docs

+
+

NumPy has many ways to extract values out of arrays:

+
    +

  • You can select a single element

    • +

  • You can select rows or columns

    • +

  • You can select ranges where a condition is true.

    • +
+

Clever and efficient use of these operations is a key to NumPy’s +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C.

+
a = np.arange(16).reshape(4, 4)  # 4x4 matrix from 0 to 15
+a[0]                             # first row
+a[:,0]                           # first column
+a[1:3,1:3]                       # middle 2x2 array
+
+a[(0, 1), (1, 1)]                # second element of first and second row as array
+
+
+

Boolean indexing on above created array:

+
idx = (a > 0)      # creates boolean matrix of same size as a
+a[idx]             # array with matching values of above criterion
+
+a[a > 0]           # same as above in one line
+
+
+
+
+

Exercises 3

+
+

Exercise: Numpy-3

+
a = np.eye(4)
+b = a[:,0]
+b[0] = 5
+
+
+
    +

  • View vs copy Try out above code. How does a look like before b has changed and after? How could it be avoided?

    • +
+
+ +
+
+

Types of operations

+

There are different types of standard operations in NumPy:

+

ufuncs, “universal functions”: These are element-by-element +functions with standardized arguments:

+
    +

  • One, two, or three input arguments

    • +

  • For example, a + b is similar to np.add(a, b) but the ufunc +has more control.

    • +

  • out= output argument, store output in this array (rather than +make a new array) - saves copying data!

    • +

  • See the full reference

    • +

  • They also do broadcasting (ref). Can you add a 1-dimensional array of shape (3) +to an 2-dimensional array of shape (3, 2)? With broadcasting you +can!

    +
    a = np.array([[1, 2, 3],
+              [4, 5, 6]])
+b = np.array([10, 10, 10])
+a + b                       # array([[11, 12, 13],
+                            #        [14, 15, 16]])
+
    +
    +

    Broadcasting is smart and consistent about what it does, which I’m +not clever enough to explain quickly here: the manual page on +broadcasting. +The basic idea is that it expands dimensions of the smaller array so +that they are compatible in shape.

    +
    • +
+

Array methods do something to one array:

+
    +

  • Some of these are the same as ufuncs:

    +
    x = np.arange(12)
+x.shape = (3, 4)
+x                    #  array([[ 0,  1,  2,  3],
+                     #         [ 4,  5,  6,  7],
+                     #         [ 8,  9, 10, 11]])
+x.max()              #  11
+x.max(axis=0)        #  array([ 8,  9, 10, 11])
+x.max(axis=1)        #  array([ 3,  7, 11])
+
    +
    +
    • +
+

Other functions: there are countless other functions covering +linear algebra, scientific functions, etc.

+
+
+

Exercises 4

+
+

Exercises: Numpy-4

+
    +

  • In-place addition: Create an array, add it to itself using a +ufunc.

    • +

  • In-place addition (advanced): Create an array of +dtype='float', and an array of dtype='int'. Try to use the +int array is the output argument of the first two arrays.

    • +

  • Output arguments and timing Repeat the initial b = a ** +2 example using the output arguments and time it. Can you make +it even faster using the output argument?

    • +
+
+ +
+
+

Linear algebra and other advanced math

+

In general, you use arrays (n-dimensions), not matrixes +(specialized 2-dimensional) in NumPy.

+

Internally, NumPy doesn’t invent its own math routines: it relies on +BLAS +and LAPACK to do this kind +of math - the same as many other languages.

+
    +

  • Linear algebra in numpy

    • +

  • Many, many other array functions

    • +

  • Scipy has even +more functions

    • +

  • Many other libraries use NumPy arrays as the standard data +structure: they take data in this format, and return it similarly. +Thus, all the other packages you may want to use are compatible

    • +

  • If you need to write your own fast code in C, NumPy arrays can be +used to pass data. This is known as extending Python.

    • +
+
+
+

Additional exercises

+
+

Numpy-5

+

If you have extra time, try these out. These are advanced and +optional, and will not be done in most courses.

+
    +

  1. Reverse a vector. Given a vector, reverse it such that the last +element becomes the first, e.g. [1, 2, 3] => [3, 2, 1]

    2. +

  2. Create a 2D array with zeros on the borders and 1 inside.

    3. +

  3. Create a random array with elements [0, 1), then add 10 to all +elements in the range [0.2, 0.7).

    4. +

  4. What is np.round(0.5)? What is np.round(1.5)? Why?

    5. +

  5. In addition to np.round, explore numpy.ceil, numpy.floor, +numpy.trunc. In particular, take note of how they behave with +negative numbers.

    6. +

  6. Recall the identity \(\sin^2(x) + \cos^2(x) = 1\). Create a +random 4x4 array with values in the range [0, 10). Now test the +equality with numpy.equal. What result do you get with +numpy.allclose() instead of np.equal?

    7. +

  7. Create a 1D array with 10 random elements. Sort it.

    8. +

  8. What’s the difference between np_array.sort() and +np.sort(np_array)?

    9. +

  9. For the random array in question 8, instead of sorting it, perform +an indirect sort. That is, return the list of indices which would +index the array in sorted order.

    10. +

  10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next +combine them into a single 8x4 array with the content of the zeros +array on top and the ones on the bottom. Finally, do the same, +but create a 4x8 array with the zeros on the left and the ones on +the right.

    11. +

  11. NumPy functionality Create two 2D arrays and do matrix multiplication +first manually (for loop), then using the np.dot function. Use %%timeit +to compare execution times. What is happening?

    12. +
+
+ +
+
+

See also

+ +
+

Keypoints

+
    +

  • NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally.

    • +

  • Be aware of some NumPy specific peculiarities

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/objects.inv b/branch/rkdarst--remove-catfacts-jsonl/objects.inv new file mode 100644 index 00000000..e5c9d9bf Binary files /dev/null and b/branch/rkdarst--remove-catfacts-jsonl/objects.inv differ diff --git a/branch/rkdarst--remove-catfacts-jsonl/packaging/index.html b/branch/rkdarst--remove-catfacts-jsonl/packaging/index.html new file mode 100644 index 00000000..f92e8892 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/packaging/index.html @@ -0,0 +1,503 @@ + + + + + + + + + + + + + + + Packaging — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Packaging

+
+

Questions

+
    +

  • How to organize Python projects larger than one script?

    • +

  • What is a good file and folder structure for Python projects?

    • +

  • How can you make your Python functions most usable by your collaborators?

    • +

  • How to prepare your code to make a Python package?

    • +

  • How to publish your Python package?

    • +
+
+
+

Objectives

+
    +

  • Learn to identify the components of a Python package

    • +

  • Learn to create a Python package

    • +

  • Learn to publish a Python package

    • +
+
+
+

Organizing Python projects

+

Python projects often start as a single script or Jupyter notebook but +they can grow out of a single file.

+

In the Scripts episode we have also learned how to import functions +and objects from other Python files (modules). Now we will take it a step further.

+

Recommendations:

+ +

To have a concrete but still simple example, we will create a project +consisting of 3 functions, each in its own file. We can then imagine that each +file would contain many more functions. To make it more interesting, +one of these functions will depend on an external library: scipy.

+

These are the 3 files:

+
+
adding.py
+
def add(x, y):
+    return x + y
+
+
+
+
+
subtracting.py
+
def subtract(x, y):
+    return x - y
+
+
+
+
+
integrating.py
+
from scipy import integrate
+
+
+def integral(function, lower_limit, upper_limit):
+    return integrate.quad(function, lower_limit, upper_limit)
+
+
+
+

We will add a fourth file:

+
+
__init__.py
+
"""
+Example calculator package.
+"""
+
+from .adding import add
+from .subtracting import subtract
+from .integrating import integral
+
+__version__ = "0.1.0"
+
+
+
+

This __init__.py file will be the interface of our package/library. +It also holds the package docstring and the version string. +Note how it imports functions from the various modules using relative imports +(with the dot).

+

This is how we will arrange the files in the project folder/repository:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+└── README.md
+
+
+

Now we are ready to test the package. For this we need to be in the “root” +folder, what we have called the project-folder. We also need to have +scipy available in our environment:

+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+

The package is not yet pip-installable, though. We will make this possible in +the next section.

+
+
+

Testing a local pip install

+

To make our example package pip-installable we need to add one more file:

+
project-folder
+├── calculator
+│   ├── adding.py
+│   ├── __init__.py
+│   ├── integrating.py
+│   └── subtracting.py
+├── LICENSE
+├── README.md
+└── setup.py
+
+
+

This is how setup.py looks:

+
+
setup.py
+
import setuptools
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    # adapt "myname" to something unique
+    # if you want to test the upload to test-PyPI
+    name="calculator-myname",
+    version="0.1.0",
+    author="Firstname Lastname",
+    author_email="firstname.lastname@example.org",
+    description="A small example package",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://example.org",
+    packages=setuptools.find_packages(),
+    install_requires=[
+        "scipy",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.6',
+)
+
+
+
+

Note how our package requires scipy and we decided to not pin the version +here (see Version pinning for package creators).

+

Now we have all the building blocks to test a local pip install. This is a good +test before trying to upload a package to PyPI or test-PyPI +(see PyPI (The Python Package Index) and (Ana)conda)

+
+
+

Exercises 1

+
+

Packaging-1

+

To test a local pip install:

+
    +

  • Create a new folder outside of our example project

    • +

  • Create a new virtual environment (Dependency management)

    • +

  • Install the example package from the project folder +into the new environment: $ pip install /path/to/project-folder/

    • +

  • Test the local installation:

    • +
+
from calculator import add, subtract, integral
+
+print(add(2, 3))
+print(subtract(2, 3))
+print(integral(lambda x: x * x, 0.0, 1.0))
+
+
+
+
+
+

Sharing packages via PyPI

+

Once we are able to pip-install the example package locally, we are ready for +upload.

+

We exercise by uploading to test-PyPI, not the +real PyPI, so that if we mess things up, nothing bad +happens.

+

We need two more things:

+
    +

  • We will do this using Twine so you need +to pip install that, too.

    • +

  • You need an account on test-PyPI.

    • +
+

Let’s try it out. First we create the distribution package:

+
$ python setup.py sdist
+
+
+

We need twine:

+
$ pip install twine
+
+
+

And use twine to upload the distribution files to test-PyPI:

+
$ twine upload -r testpypi dist/*
+
+Uploading distributions to https://test.pypi.org/legacy/
+Enter your username:
+Enter your password:
+
+
+

Once this is done, create yet another virtual environment and try to install from test-PyPI (adapt “myname”):

+
$ pip install -i https://test.pypi.org/simple/ calculator-myname
+
+
+
+
+

Tools that simplify sharing via PyPI

+

The solution that we have used to create the example package (using +setuptools and twine) is not the only approach. There are many ways to +achieve this and we avoided going into too many details and comparisons to not +confuse too much. If you web-search this, you will also see that recently the +trend goes towards using pyproject.toml as more general alternative to +setup.py.

+

There are at least two tools which try to make the packaging and PyPI interaction easier:

+ +
+
+

Building a conda package and share it

+
+

Demo

+

Most people will watch and observe this, due to speed which we will +move.

+
+
+

Prerequisites

+

To create a conda package, conda-build package is required. You may install it with Anaconda Navigator or from the command line:

+
$ conda install conda-build
+
+
+
+

The simplest way for creating a conda package for your python script is to +first publish it in PyPI following the steps explained +above.

+
+

Building a python package with conda skeleton pypi

+

Once build, the conda package can be installed locally. For this example, we +will use runtest. runtest is a numerically tolerant end-to-end test +library for research software.

+
    +

  1. Create pypi skeleton:

    +
    $ conda skeleton pypi runtest
+
    +
    +

    The command above will create a new folder called runtest containing a file meta.yaml, the conda recipe for runtest.

    +
    2. +

  2. Edit meta.yaml and update requirements:

    +
    requirements:
+  host:
+    - pip
+    - python
+    - flit
+  run:
+    - python
+    - flit
+
    +
    +

    In the requirements above, we specified what is required for the host and for running the package.

    +
    +

    Remark

    +

    For pure python recipes, this is all you need for building a python package with conda. +If your package needs to be built (for instance compilation), you would need additional files e.g. build.sh (to build on Linux/Mac-OSX) and bld.bat (to build on Windows systems). You can also add test scripts for testing your package. See documentation

    +
    +
    3. +

  3. Build your package with conda

    +

    Your package is now ready to be build with conda:

    +
    $ conda-build runtest
+
    +
    +
    +

    Conda package location

    +

    Look at the messages produced while building. The location of the local conda package is given (search for anaconda upload):

    +
    ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2
+
    +
    +

    The prefix ~/anaconda3/ may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder win-64 differs too (for instance linux-64 on Linux machines).

    +

    The conda package we have created is specific to your platform (here win-64). It can be converted to other platforms using conda convert.

    +
    +
    4. +

  4. Check within new environment

    +

    It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments.

    +
    $ conda create -n local-runtest --use-local runtest
+
    +
    +

    We can then check runtest has been successfully installed in local-runtest conda environment. Open a new Terminal with local-runtest environment (either from the command line:

    +
    $ conda activate local-runtest
+
    +
    +

    or via Anaconda Navigator (Open Terminal), import runtest and +check its version:

    +
    import runtest
+print(runtest.__version__)
+
    +
    +
    5. +
+
+

Building a conda package from scratch

+

It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the conda-build documentation for more information.

+
+

To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a conda channel (see below).

+
+
+

Publishing a python package

+
    +

  • Upload your package to Anaconda.org: see instructions here. +Please note that you will have to create an account on Anaconda.

    • +

  • Upload your package to conda-forge: +conda-forge is a conda channel: it contains community-led collection of +recipes, build infrastructure and distributions for the conda package +manager. Anyone can public conda packages to conda-forge if certain +guidelines are respected.

    • +

  • Upload your package to bioconda: bioconda is +a very popular channel for the conda package manager specializing in +bioinformatics software. As for conda-forge, you need to follow their +guidelines when +building conda recipes.

    • +
+

You can also create your own conda channel +for publishing your packages.

+
+

Keypoints

+
    +

  • Organize your code for publishing

    • +

  • Pypi

    • +

  • conda

    • +
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/pandas/index.html b/branch/rkdarst--remove-catfacts-jsonl/pandas/index.html new file mode 100644 index 00000000..015fd445 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/pandas/index.html @@ -0,0 +1,729 @@ + + + + + + + + + + + + + + + Pandas — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Pandas

+
+

Questions

+
    +

  • How do I learn a new Python package?

    • +

  • How can I use pandas dataframes in my research?

    • +
+
+
+

Objectives

+
    +

  • Learn simple and some more advanced usage of pandas dataframes

    • +

  • Get a feeling for when pandas is useful and know where to find more information

    • +

  • Understand enough of pandas to be able to read its documentation.

    • +
+
+

Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including:

+ +

Let’s get a flavor of what we can do with pandas. We will be working with an +example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:

+
import pandas as pd
+
+
+

We can download the data from this GitHub repository +by visiting the page and saving it to disk, or by directly reading into +a DataFrame:

+
url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv"
+titanic = pd.read_csv(url, index_col='Name')
+
+
+

We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:

+
# print the first 5 lines of the dataframe
+titanic.head()
+
+# print summary statistics for each column
+titanic.describe()
+
+
+

Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38% of passengers survived, etc.

+

Let’s say we’re interested in the survival probability of different +age groups. With two one-liners, we can find the average age of those +who survived or didn’t survive, and plot corresponding histograms of +the age distribution (pandas.DataFrame.groupby(), pandas.DataFrame.hist()):

+
print(titanic.groupby("Survived")["Age"].mean())
+
+
+
titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10),
+             layout=(2,1), zorder=2, sharex=True, rwidth=0.9);
+
+
+

Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let’s get back to basics.

+
+

Getting help

+

Series and DataFrames have a lot functionality, but +how can we find out what methods are available and how they work? One way is to visit +the API reference +and reading through the list. +Another way is to use the autocompletion feature in Jupyter and type e.g. +titanic["Age"]. in a notebook and then hit TAB twice - this should open +up a list menu of available methods and attributes.

+

Jupyter also offers quick access to help pages (docstrings) which can be +more efficient than searching the internet. Two ways exist:

+
    +

  • Write a function name followed by question mark and execute the cell, e.g. +write titanic.hist? and hit SHIFT + ENTER.

    • +

  • Write the function name and hit SHIFT + TAB.

    • +
+
+
+

What’s in a dataframe?

+

As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +pandas.DataFrame +is composed of rows and columns:

+../_images/01_table_dataframe.svg

Each column of a dataframe is a pandas.Series object +- a dataframe is thus a collection of series:

+
# print some information about the columns
+titanic.info()
+
+
+

Unlike a NumPy array, a dataframe can combine multiple data types, such as +numbers and text, but the data in each column is of the same type. So we say a +column is of type int64 or of type object.

+

Let’s inspect one column of the Titanic passanger list data (first downloading +and reading the titanic.csv datafile into a dataframe if needed, see above):

+
titanic["Age"]
+titanic.Age          # same as above
+type(titanic["Age"])
+
+
+

The columns have names. Here’s how to get them (columns):

+
titanic.columns
+
+
+

However, the rows also have names! This is what Pandas calls the index:

+
titanic.index
+
+
+

We saw above how to select a single column, but there are many ways of +selecting (and setting) single or multiple rows, columns and values. We can +refer to columns and rows either by number or by their name +(loc, iloc, +at, iat):

+
titanic.loc['Lam, Mr. Ali',"Age"]          # select single value by row and column
+titanic.loc[:'Lam, Mr. Ali',"Survived":"Age"]  # slice the dataframe by row and column *names*
+titanic.iloc[0:2,3:6]                      # same slice as above by row and column *numbers*
+
+titanic.at['Lam, Mr. Ali',"Age"] = 42      # set single value by row and column *name* (fast)
+titanic.at['Lam, Mr. Ali',"Age"]           # select single value by row and column *name* (fast)
+titanic.iat[0,5]                           # select same value by row and column *number* (fast)
+
+titanic["is_passenger"] = True             # set a whole column
+
+
+

Dataframes also support boolean indexing, just like we saw for numpy +arrays:

+
titanic[titanic["Age"] > 70]
+# ".str" creates a string object from a column
+titanic[titanic.index.str.contains("Margaret")]
+
+
+

What if your dataset has missing data? Pandas uses the value numpy.nan +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:

+
titanic.isna()                    # returns boolean mask of NaN values
+titanic.dropna()                  # drop missing values
+titanic.dropna(how="any")         # or how="all"
+titanic.dropna(subset=["Cabin"])  # only drop NaNs from one column
+titanic.fillna(0)                 # replace NaNs with zero
+titanic.fillna(method='ffill')    # forward-fill NaNs
+
+
+
+
+

Exercises 1

+
+

Exploring dataframes

+
+
    +

  • Have a look at the available methods and attributes using the +API reference +or the autocomplete feature in Jupyter.

    • +

  • Try out a few methods using the Titanic dataset and have a look at +the docstrings (help pages) of methods that pique your interest

    • +

  • Compute the mean age of the first 10 passengers by slicing and the pandas.DataFrame.mean() method

    • +

  • (Advanced) Using boolean indexing, compute the survival rate +(mean of “Survived” values) among passengers over and under the average age.

    • +
+
+ +
+
+
+

Tidy data

+

The above analysis was rather straightforward thanks to the fact +that the dataset is tidy.

+../_images/tidy_data.png +

In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data.

+

What would untidy data look like? Here’s an example from +some run time statistics from a 1500 m running event:

+
runners = pd.DataFrame([
+              {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240},
+              {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300},
+              {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360},
+          ])
+
+
+

What makes this data untidy is that the column names 400, 800, 1200, 1500 +indicate the distance ran. In a tidy dataset, this distance would be a variable +on its own, making each runner-distance pair a separate observation and hence a +separate row.

+

To make untidy data tidy, a common operation is to “melt” it, +which is to convert it from wide form to a long form:

+
runners = pd.melt(runners, id_vars="Runner",
+              value_vars=[400, 800, 1200, 1500],
+              var_name="distance",
+              value_name="time"
+          )
+
+
+

In this form it’s easier to filter, group, join +and aggregate the data, and it’s also easier to model relationships +between variables.

+

The opposite of melting is to pivot data, which can be useful to +view data in different ways as we’ll see below.

+

For a detailed exposition of data tidying, have a look at +this article.

+
+
+

Working with dataframes

+

We saw above how we can read in data into a dataframe using the read_csv() function. +Pandas also understands multiple other formats, for example using read_excel, +read_hdf, read_json, etc. (and corresponding methods to write to file: +to_csv, to_excel, to_hdf, to_json, etc.)

+

But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array (see +DataFrame docs:

+
dates = pd.date_range('20130101', periods=6)
+df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD'))
+
+
+

or a dictionary (see same docs):

+
df = pd.DataFrame({'A': ['dog', 'cat', 'dog', 'cat', 'dog', 'cat', 'dog', 'dog'],
+                   'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'],
+                   'C': np.array([3] * 8, dtype='int32'),
+                   'D': np.random.randn(8),
+                   'E': np.random.randn(8)})
+
+
+

There are many ways to operate on dataframes. Let’s look at a +few examples in order to get a feeling of what’s possible +and what the use cases can be.

+

We can easily split and concatenate dataframes:

+
sub1, sub2, sub3 = df[:2], df[2:4], df[4:]
+pd.concat([sub1, sub2, sub3])
+
+
+

When pulling data from multiple dataframes, a powerful pandas.DataFrame.merge method is +available that acts similarly to merging in SQL. Say we have a dataframe containing the age of some athletes:

+
age = pd.DataFrame([
+    {"Runner": "Runner 4", "Age": 18},
+    {"Runner": "Runner 2", "Age": 21},
+    {"Runner": "Runner 1", "Age": 23},
+    {"Runner": "Runner 3", "Age": 19},
+])
+
+
+

We now want to use this table to annotate the original runners table from +before with their age. Note that the runners and age dataframes have a +different ordering to it, and age has an entry for Dave which is not +present in the runners table. We can let Pandas deal with all of it using +the merge method:

+
# Add the age for each runner
+runners.merge(age, on="Runner")
+
+
+

In fact, much of what can be done in SQL +is also possible with pandas.

+

groupby is a powerful method which splits a dataframe and aggregates data +in groups. To see what’s possible, let’s return to the Titanic dataset. Let’s +test the old saying “Women and children first”. We start by creating a new +column Child to indicate whether a passenger was a child or not, based on +the existing Age column. For this example, let’s assume that you are a +child when you are younger than 12 years:

+
titanic["Child"] = titanic["Age"] < 12
+
+
+

Now we can test the saying by grouping the data on Sex and then creating further sub-groups based on Child:

+
titanic.groupby(["Sex", "Child"])["Survived"].mean()
+
+
+

Here we chose to summarize the data by its mean, but many other common +statistical functions are available as dataframe methods, like +std, min, +max, cumsum, +median, skew, +var etc.

+
+
+

Exercises 2

+
+

Analyze the Titanic passenger list dataset

+
+

In the Titanic passenger list dataset, +investigate the family size of the passengers (i.e. the “SibSp” column).

+
    +

  • What different family sizes exist in the passenger list? Hint: try the unique() method

    • +

  • What are the names of the people in the largest family group?

    • +

  • (Advanced) Create histograms showing the distribution of family sizes for +passengers split by the fare, i.e. one group of high-fare passengers (where +the fare is above average) and one for low-fare passengers +(Hint: instead of an existing column name, you can give a lambda function +as a parameter to hist() to compute a value on the fly. For example +lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich").

    • +
+
+ +
+
+
+

Time series superpowers

+

An introduction of pandas wouldn’t be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates available through +an API of the Nobel prize organisation at +https://api.nobelprize.org/v1/laureate.csv .

+

Unfortunately this API does not allow “non-browser requests”, so +pandas.read_csv will not work. We can either open the above link in +a browser and download the file, or use the JupyterLab interface by clicking +“File” and “Open from URL”, and then save the CSV file to disk.

+

We can then load and explore the data:

+
# File → Open from URL → enter https://api.nobelprize.org/v1/laureate.csv
+# This opens it in JupyterLab but also saves it as laureate.csv
+nobel = pd.read_csv("laureate.csv")
+nobel.head()
+
+
+

This dataset has three columns for time, “born”/”died” and “year”. +These are represented as strings and integers, respectively, and +need to be converted to datetime format. pandas.to_datetime() +makes this easy:

+
# the errors='coerce' argument is needed because the dataset is a bit messy
+nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce')
+nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce')
+nobel["year"] = pd.to_datetime(nobel["year"], format="%Y")
+
+
+

Pandas knows a lot about dates (using dt):

+
print(nobel["born"].dt.day)
+print(nobel["born"].dt.year)
+print(nobel["born"].dt.weekday)
+
+
+

We can add a column containing the (approximate) lifespan in years rounded +to one decimal:

+
nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1)
+
+
+

and then plot a histogram of lifespans:

+
nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9)
+
+
+

Finally, let’s see one more example of an informative plot (boxplot()) +produced by a single line of code:

+
nobel.boxplot(column="lifespan", by="category")
+
+
+
+
+

Exercises 3

+
+

Analyze the Nobel prize dataset

+
+
    +

  • What country has received the largest number of Nobel prizes, and how many? +How many countries are represented in the dataset? Hint: use the describe method +on the bornCountryCode column.

    • +

  • Create a histogram of the age when the laureates received their Nobel prizes. +Hint: follow the above steps we performed for the lifespan.

    • +

  • List all the Nobel laureates from your country.

    • +
+

Now more advanced steps:

+
    +

  • Now define an array of 4 countries of your choice and extract +only laureates from these countries:

    +
    countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4])
+subset = nobel.loc[nobel['bornCountry'].isin(countries)]
+
    +
    +
    • +

  • Use groupby() to compute how many nobel prizes each country received in +each category. The size() method tells us how many rows, hence nobel +prizes, are in each group:

    +
    nobel.groupby(['bornCountry', 'category']).size()
+
    +
    +
    • +

  • (Optional) Create a pivot table to view a spreadsheet like structure, and view it

    +
    +
      +

    • First add a column “number” to the nobel dataframe containing 1’s +(to enable the counting below). We need to make a copy of +subset, because right now it is only a view:

      +
      subset = subset.copy()
+subset.loc[:, 'number'] = 1
+
      +
      +
      • +

    • Then create the pivot_table():

      +
      table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum)
+
      +
      +
      • +
    +
    +
    • +

  • (Optional) Install the seaborn visualization library if you don’t +already have it, and create a heatmap of your table:

    +
    import seaborn as sns
+sns.heatmap(table,linewidths=.5);
+
    +
    +
    • +

  • Play around with other nice looking plots:

    +
    sns.violinplot(y="year", x="bornCountry", inner="stick", data=subset);
+
    +
    +
    sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5);
+
    +
    +
    subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))]
+sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm");
+
    +
    +
    sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count");
+
    +
    +
    • +
+
+ +
+
+
+

Beyond the basics

+

Larger DataFrame operations might be faster using eval() with string expressions, see:

+
import pandas as pd
+nrows, ncols = 100000, 100
+rng = np.random.RandomState(42)
+df1, df2, df3, df4 = (pd.DataFrame(rng.rand(nrows, ncols))
+                      for i in range(4))
+
+
+

Adding dataframes the pythonic way yields:

+
%timeit df1 + df2 + df3 + df4
+# 80ms
+
+
+

And by using eval():

+
%timeit pd.eval('df1 + df2 + df3 + df4')
+# 40ms
+
+
+

We can assign function return lists as dataframe columns:

+
def fibo(n):
+    """Compute Fibonacci numbers. Here we skip the overhead from the
+    recursive function calls by using a list. """
+    if n < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif n < 2:
+        return n
+    memo = [0]*(n+1)
+    memo[0] = 0
+    memo[1] = 1
+    for i in range(2, n+1):
+        memo[i] = memo[i-1] + memo[i-2]
+    return memo
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = fibo(99)
+
+
+

There is much more to Pandas than what we covered in this lesson. Whatever your +needs are, chances are good there is a function somewhere in its API. And when there is not, you can always +apply your own functions to the data using apply:

+
from functools import lru_cache
+
+@lru_cache
+def fib(x):
+    """Compute Fibonacci numbers. The @lru_cache remembers values we
+    computed before, which speeds up this function a lot."""
+    if x < 0:
+        raise NotImplementedError('Not defined for negative values')
+    elif x < 2:
+        return x
+    else:
+        return fib(x - 2) + fib(x - 1)
+
+df = pd.DataFrame({'Generation': np.arange(100)})
+df['Number of Rabbits'] = df['Generation'].apply(fib)
+
+
+

Note that the numpy precisision for integers caps at int64 while python ints are unbounded – +limited by memory size. Thus, the result from fibonacci(99) would be erroneous when +using numpy ints. The type of df[‘Number of Rabbits’][99] given by both functions above +is in fact <class ‘int’>.

+
+

Keypoints

+
    +

  • pandas dataframes are a good data structure for tabular data

    • +

  • Dataframes allow both simple and advanced analysis in very compact form

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/parallel-pi-multiprocessing/index.html b/branch/rkdarst--remove-catfacts-jsonl/parallel-pi-multiprocessing/index.html new file mode 100644 index 00000000..bd9d8ea3 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/parallel-pi-multiprocessing/index.html @@ -0,0 +1,358 @@ + + + + + + + + + + + + + + + Python multithreading solution — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Python multithreading solution

+

Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare).

+
+
+
import random
+
+
+
+
+
+
+
def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+    
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+
+
+
+
+
%%timeit
+# Do it just for timing
+n, n_inside_circle = sample(10**6)
+
+
+
+
+
371 ms ± 198 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do the actual calculation (the previous result doesn't get saved)
+n, n_inside_circle = sample(10**6)
+
+
+
+
+

This is the “calculate answer” phase.

+
+
+
pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+
+
+
3.142308
+
+
+
+
+
+

Do it in parallel with multiprocessing

+

This divides the calculation into 10 tasks and runs sample on each of them. Then it re-combines the results.

+
+
+
import multiprocessing.pool
+pool = multiprocessing.pool.Pool()
+# The default pool makes one process per CPU
+
+
+
+
+
+
+
%%timeit
+# Do it once to time it
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
235 ms ± 2.01 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = pool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
pool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.139152
+
+
+
+
+
+
+

Do it in “parallel” with threads

+

To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process.

+
+
+
threadpool = multiprocessing.pool.ThreadPool()
+
+
+
+
+
+
+
%%timeit -o
+# Do it once to time it
+threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
385 ms ± 3.61 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+
+
<TimeitResult : 385 ms ± 3.61 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)>
+
+
+
+
+
+
+
# Do it again to get the results, since the results of the above
+# cell aren't accessible because of the %%timeit magic.
+results = threadpool.map(sample, [10**5] * 10)
+
+
+
+
+
+
+
threadpool.close()
+
+
+
+
+
+
+
n_sum = sum(x[0] for x in results)
+n_inside_circle_sum = sum(x[1] for x in results)
+pi = 4.0 * (n_inside_circle_sum / n_sum)
+pi
+
+
+
+
+
3.14264
+
+
+
+
+
+
+

Future ideas

+

You could make a separate calculate function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.

+

Notice the similarity to split-apply-combine or map-reduce which is a specialization of split-apply-combine.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/parallel/index.html b/branch/rkdarst--remove-catfacts-jsonl/parallel/index.html new file mode 100644 index 00000000..f7188ec4 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/parallel/index.html @@ -0,0 +1,629 @@ + + + + + + + + + + + + + + + Parallel programming — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Parallel programming

+
+

Questions

+
    +

  • When you need more than one processor, what do you do?

    • +

  • How can we use more than one processor/core in Python?

    • +
+
+
+

Objectives

+
    +

  • Understand the major strategies of parallelizing code

    • +

  • Understand mechanics of the multiprocessing package

    • +

  • Know when to use more advanced packages or approaches

    • +
+
+
+

Modes of parallelism

+

You realize you do have more computation to do than you can on one processor? +What do you do?

+
    +

  1. Profile your code, identify the actual slow spots.

    2. +

  2. Can you improve your code in those areas? Use an existing library?

    3. +

  3. Are there are any low-effort optimizations that you can make?

    4. +

  4. Consider using numba or +cython to accelerate key functions.

    5. +

  5. Think about parallelizing.

    6. +
+

Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers).

+

Parallel computing is when many different tasks are carried out +simultaneously. There are three main models:

+
    +

  • Embarrassingly parallel: the code does not need to +synchronize/communicate with other instances, and you can run +multiple instances of the code separately, and combine the results +later. If you can do this, great! (array jobs, task queues, +workflow management tools)

    • +

  • Multithreading: Parallel threads need to communicate and do so via +the same memory (variables, state, etc). (OpenMP, threading)

    • +

  • Multiprocessing, message passing: Different processes manage +their own memory segments. They share data by communicating (passing +messages) as needed. (multiprocessing, MPI).

    • +
+
+

Warning

+

Parallel programming is not magic, but many things can go wrong and +you can get unexpected results or difficult to debug problems. +Parallel programming is a fascinating world to get involved in, but +make sure you invest enough time to do it well.

+

See the video by Raymond Hettinger (“See Also” at bottom +of page) for an entertaining take on this.

+
+
+
+

Multithreading and the GIL

+

The designers of the Python language made the choice +that only one thread in a process can run actual Python code +by using the so-called global interpreter lock (GIL). +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python. +At first glance, this is bad for parallelism. But it’s not all bad!:

+
    +

  • External libraries (NumPy, SciPy, Pandas, etc), written in C or other +languages, can release the lock and run multi-threaded.

    • +

  • Most input/output releases the GIL, and input/output is slow. The +threading library can be used to multithread I/O.

    • +

  • Python libraries like multiprocessing and mpi4py run multiple +Python processes and this circumvents the GIL.

    • +
+

Consider the following code which does a symmetrical matrix inversion +of a fairly large matrix:

+
import numpy as np
+import time
+
+A = np.random.random((4000,4000))
+A = A * A.T
+time_start = time.time()
+np.linalg.inv(A)
+time_end = time.time()
+print("time spent for inverting A is", round(time_end - time_start,2), 's')
+
+
+

If we run this in a Jupyter notebook or through a Python script, it +will automatically use multithreading through OpenMP. We can force +NumPy to use only one thread by setting an environment variable +(either export OMP_NUM_THREADS=1 or export MKL_NUM_THREADS=1, +depending on how NumPy is compiled on your machine), +and this will normally result in significantly longer runtime.

+
+

See also

+ +
+
+
+

multiprocessing

+

As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +multiprocessing module. +The interface is a lot like threading, but in the background creates +new processes to get around the global interpreter lock.

+

To show an example, +the split-apply-combine +or map-reduce paradigm is +quite useful for many scientific workflows. Consider you have this:

+
def square(x):
+    return x*x
+
+
+

You can apply the function to every element in a list using the +map() function:

+
>>> list(map(square, [1, 2, 3, 4, 5, 6]))
+[1, 4, 9, 16, 25, 36]
+
+
+

The multiprocessing.pool.Pool class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list:

+
>>> from multiprocessing import Pool
+>>> with Pool() as pool:
+...     pool.map(square, [1, 2, 3, 4, 5, 6])
+[1, 4, 9, 16, 25, 36]
+
+
+
+

Warning

+

Running the above example interactively in a Jupyter notebook +or through an Python/IPython terminal may or may not work on your +computer! This is a feature and not a bug, as covered in the +documentation.

+

Fortunately, there is a fork of multiprocesssing called +multiprocess which does +work in interactive environments. All we have to do is install it +by pip install multiprocess and change the import statement: +from multiprocess import Pool.

+
+
+
+

Exercises, multiprocessing

+
+

Parallel-1, multiprocessing

+

Here, you find some code which calculates pi by a stochastic +algorithm. You don’t really need to worry how the algorithm works, +but it computes random points in a 1x1 square, and computes the +number that fall into a circle. Copy it into a Jupyter notebook +and use the %%timeit cell magic on the computation part (the +one highlighted line after timeit below):

+
import random
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x**2 + y**2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+%%timeit
+n, n_inside_circle = sample(10**6)
+
+pi = 4.0 * (n_inside_circle / n)
+pi
+
+
+

Using the multiprocessing.pool.Pool code from the lesson, run +the sample function 10 times, each with 10**5 samples +only. Combine the results and time the calculation. What is the +difference in time taken?

+

NOTE: If you’re working in an interactive environment and this +doesn’t work with the multiprocessing module, install and use +the multiprocess module instead!

+

(optional, advanced) Do the same but with +multiprocessing.pool.ThreadPool instead. This works identically +to Pool, but uses threads instead of different processes. +Compare the time taken.

+ +
+
+

(advanced) Parallel-2 Running on a cluster

+

How does the pool know how many CPUs to take? What happens if you +run on a computer cluster and request only part of the CPUs on a +node?

+ +
+
+
+

MPI

+

The message passing interface (MPI) approach to parallelization +is that:

+
    +

  • Tasks (cores) have a rank and are numbered 0, 1, 2, 3, …

    • +

  • Each task (core) manages its own memory

    • +

  • Tasks communicate and share data by sending messages

    • +

  • Many higher-level functions exist to distribute information to other tasks +and gather information from other tasks

    • +

  • All tasks typically run the entire code and we have to be careful to avoid +that all tasks do the same thing

    • +
+

Introductory MPI lessons where Python is included:

+ +

These blog posts are good for gentle MPI/mpi4py introduction:

+ +

Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together.

+

Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work:

+
import random
+import time
+from mpi4py import MPI
+
+
+def sample(n):
+    """Make n trials of points in the square.  Return (n, number_in_circle)
+
+    This is our basic function.  By design, it returns everything it\
+    needs to compute the final answer: both n (even though it is an input
+    argument) and n_inside_circle.  To compute our final answer, all we
+    have to do is sum up the n:s and the n_inside_circle:s and do our
+    computation"""
+    n_inside_circle = 0
+    for i in range(n):
+        x = random.random()
+        y = random.random()
+        if x ** 2 + y ** 2 < 1.0:
+            n_inside_circle += 1
+    return n, n_inside_circle
+
+
+comm = MPI.COMM_WORLD
+size = comm.Get_size()
+rank = comm.Get_rank()
+
+n = 10 ** 7
+
+if size > 1:
+    n_task = int(n / size)
+else:
+    n_task = n
+
+t0 = time.perf_counter()
+_, n_inside_circle = sample(n_task)
+t = time.perf_counter() - t0
+
+print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+n_inside_circle = comm.gather(n_inside_circle, root=0)
+print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}")
+
+if rank == 0:
+    pi_estimate = 4.0 * sum(n_inside_circle) / n
+    print(
+        f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds"
+    )
+
+
+
+
+

Exercises, MPI

+
+

Parallel-2, MPI

+

We can do this as exercise or as demo. Note that this example requires mpi4py and a +MPI installation such as for instance OpenMPI.

+
    +

  • Try to run this example on one core: $ python example.py.

    • +

  • Then compare the output with a run on multiple cores (in this case 2): $ mpiexec -n 2 python example.py.

    • +

  • Can you guess what the comm.gather function does by looking at the print-outs right before and after.

    • +

  • Why do we have the if-statement if rank == 0 at the end?

    • +

  • Why did we use _, n_inside_circle = sample(n_task) and not n, n_inside_circle = sample(n_task)?

    • +
+ +
+
+
+

Coupling to other languages

+

As mentioned further up in “Multithreading and the GIL”, Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP “directly”.

+

However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don’t +need parallelism, but need to make an optimized algorithm for a small part of the code.

+

Two strategies are common:

+
    +

  • Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization:

    +
    +
      +

    • C: use the cffi package (C foreign function interface). ctypes is a similar but slightly more primitive module that is in the standard library.

      • +

    • C++: use pybind11

      • +

    • Fortran: create a C interface using iso_c_binding and then couple the C layer to Python +using cffi

      • +

    • Rust: use PyO3

      • +
    +
    +
    • +

  • Let compiled languages do the shared-memory parallelization part (as in above +point) and let Python do the MPI work and distribute tasks across nodes using +an mpi4py layer.

    • +
+

Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course.

+

Before you take this route, profile the application first to be sure where +the bottleneck is.

+

Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason.

+
+
+

Dask and task queues

+

There are other strategies that go completely beyond the manual +parallelization methods above. We won’t go into much detail.

+
+

Dask

+

Dask is a array model extension and task +scheduler. By using the new array classes, you can automatically +distribute operations across multiple CPUs.

+

Dask is very popular for data analysis and is used by a number of high-level Python libraries:

+
    +

  • Dask arrays scale NumPy (see also xarray

    • +

  • Dask dataframes scale Pandas workflows

    • +

  • Dask-ML scales Scikit-Learn

    • +
+

Dask divides arrays into many small pieces (chunks), as small as necessary to fit it into memory. Operations are delayed (lazy computing) e.g. tasks are queue and no computation is performed until you actually ask values to be computed (for instance print mean values). Then data is loaded into memory and computation proceeds in a streaming fashion, block-by-block.

+
+

Example from dask.org

+
# Arrays implement the Numpy API
+import dask.array as da
+x = da.random.random(size=(10000, 10000),
+                     chunks=(1000, 1000))
+x + x.T - x.mean(axis=0)
+# It runs using multiple threads on your machine.
+# It could also be distributed to multiple machines
+
+
+
+
+
+
+

Exercises, Dask

+
+

Dask-Examples (optional)

+

Dask examples illustrate the usage of dask and can be run interactively through mybinder. Start an interactive session on mybinder and test/run a few dask examples.

+
+
+

Task queues

+

A task queue has a scheduler which takes a list of small jobs and +distributes them to runners for computation. It serves as a +synchronization layer and may be useful for embarrassingly parallel jobs.

+

There are different descriptions of task queues in Python. Job runners ask +the queue for the task which needs to be done next. If you can divide +your job into many small parts, this may be useful to you. However, +if you have a cluster with a job scheduler, this may be a bit +redundant.

+
+
+
+

See also

+ +
+

Keypoints

+
    +

  • Pure Python is not very good for highly parallel code.

    • +

  • Luckily it interfaces to many things which are good, and give +you the full control you need.

    • +

  • Combining vectorized functions (NumPy, Scipy, pandas, etc.) with +the parallel strategies listed here will get you very far.

    • +

  • Another popular framework similar to multiprocessing is +joblib.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/python/index.html b/branch/rkdarst--remove-catfacts-jsonl/python/index.html new file mode 100644 index 00000000..f8ea0198 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/python/index.html @@ -0,0 +1,306 @@ + + + + + + + + + + + + + + + Introduction to Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Introduction to Python

+
+

Questions

+
    +

  • What are the basic blocks of Python language?

    • +

  • How are functions and classes defined in Python?

    • +
+
+
+

Objectives

+
    +

  • Get a very short introduction to Python types and syntax

    • +

  • Be able to follow the rest of the examples in the course, even if you don’t understand everything perfectly.

    • +
+

We expect everyone to be able to know the following basic material +to follow the course (though it is not everything you need to +know about Python).

+
+

If you are not familiar with Python, here is a very short +introduction. It will not be enough to do everything in this course, +but you will be able to follow along a bit more than you would otherwise.

+
+

See also

+

This page contains an overview of the basics of Python. You can +also refer to This Python overview from a different lesson +which is slightly more engaging.

+
+
+

Scalars

+

Scalar types, that is, single elements of various types:

+
i = 42       # integer
+i = 2**77    # Integers have arbitrary precision
+g = 3.14     # floating point number
+c = 2 - 3j   # Complex number
+b = True     # boolean
+s = "Hello!" # String (Unicode)
+q = b'Hello' # bytes (8-bit values)
+
+
+

Read more: int, float, complex, +bool, str, bytes.

+
+
+

Collections

+

Collections are data structures capable of storing multiple values.

+
l = [1, 2, 3]                      # list
+l[1]                               # lists are indexed by int
+l[1] = True                        # list elements can be any type
+d = {"Janne": 123, "Richard": 456} # dictionary
+d["Janne"]
+s = set(("apple", "cherry", "banana", "apple")) # Set of unique values
+s
+
+
+

Read more: list, tuple, dict, set.

+
+
+

Control structures

+

Python has the usual control structures, that is conditional +statements and loops. For example, the The if statement statement:

+
x = 2
+if x == 3:
+    print('x is 3')
+elif x == 2:
+    print('x is 2')
+else:
+    print('x is something else')
+
+
+

While loops loop until some condition is met:

+
x = 0
+while x < 42:
+    print('x is ', x)
+    x += 0.2
+
+
+

For loops loop over some collection of values:

+
xs = [1, 2, 3, 4]
+for x in xs:
+    print(x)
+
+
+

Often you want to loop over a sequence of integers, in that case the +range() function is useful:

+
for x in range(9):
+    print(x)
+
+
+

Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the enumerate() +function:

+
xs = [1, 'hello', 'world']
+for ii, x in enumerate(xs):
+    print(ii, x)
+
+
+
+
+

Functions and classes

+

Python functions are defined by the Function definitions keyword. They take a +number of arguments, and return a number of return values.

+
def hello(name):
+    """Say hello to the person given by the argument"""
+    print('Hello', name)
+    return 'Hello ' + name
+
+hello("Anne")
+
+
+

Classes are defined by the Class definitions keyword:

+
class Hello:
+    def __init__(self, name):
+        self._name = name
+    def say(self):
+        print('Hello', self._name)
+
+h = Hello("Richard")
+h.say()
+
+
+
+
+

Python type system

+

Python is strongly and dynamically typed.

+

Strong here means, roughly, that it’s not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior).

+
x = 42
+type(x)
+x + "hello"
+
+
+

Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type:

+
x = 42
+x = "hello"
+
+
+

Jargon: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation.

+

??? (lesson here)

+
+

Keypoints

+
    +

  • Python offers a nice set of basic types as many other programming languages

    • +

  • Python is strongly typed and dynamically typed

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/quick-reference/index.html b/branch/rkdarst--remove-catfacts-jsonl/quick-reference/index.html new file mode 100644 index 00000000..063a1bd4 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/quick-reference/index.html @@ -0,0 +1,161 @@ + + + + + + + + + + + + + + + Quick reference — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/scipy/index.html b/branch/rkdarst--remove-catfacts-jsonl/scipy/index.html new file mode 100644 index 00000000..dd56b77b --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/scipy/index.html @@ -0,0 +1,319 @@ + + + + + + + + + + + + + + + SciPy — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

SciPy

+
+

Questions

+
    +

  • When you need more advanced mathematical functions, where do you +look?

    • +
+
+
+

Objectives

+
    +

  • Understand that SciPy exists and what kinds of things it has.

    • +

  • Understand the importance of using external libraries and how to +use them.

    • +

  • Understand the purpose of wrapping existing C/Fortran code.

    • +

  • Non-objective: know details of everything (or anything) in SciPy.

    • +
+
+
+

See also

+ +
+

SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms.

+
+

What’s in SciPy?

+

Briefly, it contains functionality for

+
    +

  • Special functions (Bessel, Gamma, etc.)

    • +

  • Numerical integration

    • +

  • Optimization

    • +

  • Interpolation

    • +

  • Fast Fourier Transform (FFT)

    • +

  • Signal processing

    • +

  • Linear algebra (more complete than in NumPy)

    • +

  • Sparse matrices

    • +

  • Statistics

    • +

  • More I/O routine, e.g. Matrix Market format for sparse matrices, +MATLAB files (.mat), etc.

    • +
+

Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages.

+

Most functions are documented ridiculously well from a scientific +standpoint: you aren’t just using some unknown function, but have a +full scientific description and citation to the method and +implementation.

+
+
+

Exercises: use SciPy

+

These exercises do not exist because you might need these +functions someday. They are because you will need to read +documentation and understand documentation of an an external library +eventually.

+
+

1: Numerical integration

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Define a function of one variable and using +scipy.integrate.quad +calculate the integral of your function in the +interval [0.0, 4.0]. Then vary the interval and also modify the function and check +whether scipy can integrate it.

+
+ +
+
+

2: Sparse matrices

+
+

Exercise

+

Do the following exercise or read the documentation and +understand the relevant functions of SciPy:

+

Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional format argument when you create the +sparse matrix make a difference?

+

Then, compare to how long it takes if you’d instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy dot +method to calculate the matrix-vector product.

+

Can you figure out a quick rule of thumb when it’s worth using a +sparse matrix representation vs. a dense representation?

+
+ +
+
+
+

See also

+ +
+

Keypoints

+
    +

  • When you need advance math or scientific functions, let’s just +admit it: you do a web search first.

    • +

  • But when you see something in SciPy come up, you know your +solutions are in good hands.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/scripts/index.html b/branch/rkdarst--remove-catfacts-jsonl/scripts/index.html new file mode 100644 index 00000000..ae44cebf --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/scripts/index.html @@ -0,0 +1,528 @@ + + + + + + + + + + + + + + + Scripts — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Scripts

+
+

Questions

+
    +

  • Why are command line programs useful, compared to Jupyter +notebooks and similar?

    • +

  • How to create a Python script?

    • +

  • How to generalize a Python script?

    • +
+
+
+

Objectives

+
    +

  • Learn how to streamline your Python notebooks by creating repeatable Python scripts

    • +

  • Learn how to import other Python files

    • +

  • Learn to parse command line arguments in Python

    • +
+
+
+

Why scripts?

+

So far we have been learning Python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype Python code so we may think that is more than enough for your day to day work.

+

But after several weeks of hard work with Python, you may end up:

+
    +

  • either with 10 different notebooks (so that you can run them concurrently)

    • +

  • or with a very long notebook which is becoming hardly readable!

    • +
+

Let’s imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks?

+

In this episode, we will learn how to automate your work using Python scripts so that

+
    +

  • you do not need to manually configure your notebooks to be able to run with different parameters

    • +

  • can easily run you work via other tools, such as on computing clusters.

    • +
+
+
+

From Jupyter notebooks to Python scripts

+
+
+

Save as Python script

+

Jupyter notebooks can be parameterized for instance using papermill. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate Python scripts. This will also force you to modularize your code. See CodeRefinery’s lesson on Modular code development.

+

Within JupyterLab, you can export any Jupyter notebook to a Python script:

+
+https://jupyterlab.readthedocs.io/en/stable/_images/exporting_menu.png +
+

Select File (top menu bar) → Export Notebook as → Export notebook to Executable Script.

+
+
+

Actually, you could also export your notebook in many other formats. +Check the JupyterLab documentation for more information. +If you are working by the command line (File → New → Terminal), you can also convert files in the terminal by running:

+
$ jupyter nbconvert --to script your_notebook_name.ipynb
+
+
+
+
+

Exercises 1

+
+

Scripts-1

+
    +

  1. Download the weather_observations.ipynb and the weather_data file and upload them to your jupyterlab. The script plots the temperature data for Tapiola in Espoo. The data is originally from rp5.kz and was slightly adjusted for this lecture.

    +

    Note: If you haven’t downloaded the file directly to your jupyterlab folder, it will be located in your Downloads folder or the folder you selected. In jupyterlab click on the ‘upload file’ button, navigate to the folder containing the file and select it to load it into your jupyterlab folder.

    +
    2. +

  2. Open a terminal in jupyter (File -> New -> Terminal).

    3. +

  3. Convert the jupyter script to a python script by calling:

    +
    $ jupyter nbconvert --to script weather_observations.ipynb
+
    +
    +
    4. +

  4. Run the script (note: you may have python3 rather than python):

    +
    $ python weather_observations.py
+
    +
    +
    5. +
+
+
+
+

Command line arguments with sys.argv

+

We now have a python script that is callable from the command line (e.g. for use on an HPC system). +However, this code is still not adjustable, as we still need to have a copy for each single +time range we want to plot, or need to modify our file whenever we want to just change parameters. +What we need is to allow arguments to be put in from the command line in order to have the same code +plot information for different time ranges without odifying the code itself. This can be achieved by +using pythons sys package, which provides access to arguments given to the python interpreter at +startup in the sys.argv list. The first (i.e. sys.argv[0] entry of this array is the called script, +and any further argument (separated by space) is appended to this list. Lets see how it works:

+

We modify the weather_observations.py script such that we allow start +and end times as well as the output file to be passed in as arguments to the function:

+
import sys
+import pandas as pd
+
+# set start and end time
+start_date = pd.to_datetime(sys.argv[1],dayfirst=True)
+end_date = pd.to_datetime(sys.argv[2],dayfirst=True)
+
+output_file_name = sys.argv[3]
+
+...
+
+# select the data
+weather = weather[weather['Local time'].between(start_date,end_date)]
+...
+
+fig.savefig(output_file_name)
+
+
+

We can try it out:

+
$ python weather_observations.py 01/03/2021 31/05/2021 spring_in_tapiola.png
+
+
+
+

Discussion

+
    +

  • Does it work?

    • +

  • Why is this better than modifying the script every time I want it to +plot data for a different period?

    • +

  • What problems do you expect when using this approach (using sys.argv)?

    • +
+
+

This approach is brittle and more robust solutions exist that allow you to fully +customize your scripts and generate help texts at the same time:

+
    +

  • argparse: +built-in to Python, this is the one that we will show below.

    • +

  • doctopt: you write the help text and this generates a parser for you.

    • +

  • click: another nice +library for command line interfaces - very easy to use.

    • +
+
+
+

Parsing command line arguments with argparse

+

Argparse not only gives you descriptive command line arguments, it also automatically +generates a --help option for you. To use argparse you first set up a parser +by calling parser = argparse.ArgumentParser() and then you add arguments using +parser.add_argument(args). There are two different types of arguments:

+
    +

  • Positional arguments

    • +

  • Optional arguments

    • +
+

Positional arguments are detected by their order, while optional arguments need to be +given with their respective flags ( like --name or -n). +The following example would parse a positional argument Name of type string +and an optional argument date of type string which defaults to 01/01/2000.

+
import argparse
+
+parser = argparse.ArgumentParser()
+# One positional and one optional argument
+parser.add_argument('name', type=str, metavar="N",
+                    help="The name of the subject")
+parser.add_argument('-d', '--date', type=string, default="01/01/2000",
+                    help="Birth date of the subject")
+
+args = parser.parse_args()
+
+print(args.name + " was born on " + args.date)
+
+
+

If this code was in birthday.py and we would call python birthday.py --help it +would show the following message:

+
usage: birthday.py [-h] [-d DATE] N
+
+positional arguments:
+  N                     The name of the subject
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d DATE, --date DATE  Birth date of the subject
+
+
+
+
+

Exercises 2

+
+

Scripts-2

+
    +

  1. Take the python script we have written in the preceding exercise and use +argparse to specify the input and output files and allow the start and end dates to be set. +The start and end dates should be optional parameters with the defaults as they are in the current script.

    2. +

  2. Execute your script for a few different time intervals (e.g. from January 2019 to June 2020, or from Mai 2020 to October 2020). +Also use data for cairo (https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv)

    3. +
+
+ +
+

Discussion

+

What was the point of doing this?

+

Now you can do this:

+
$ python weather_observations.py --help
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola.png
+$ python weather_observations.py -s 1/12/2020 -e 31/12/2020 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_dec.png
+$ python weather_observations.py -s 1/2/2021 -e 28/2/2021 https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_tapiola.csv temperature_tapiola_feb.png
+$ python weather_observations.py https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output temperature_cairo.png
+
+
+
    +

  • We can now process different input files without changing the script.

    • +

  • We can select multiple time ranges without modifying the script.

    • +

  • This way we can also loop over file patterns (using shell loops or similar) or use +the script in a workflow management system and process many files in parallel.

    • +

  • By changing from sys.argv to argparse we made the script more robust against +user input errors and also got a help text (accessible via --help).

    • +
+
+
+
+

Load larger option lists using config files

+

In the above example we only allowed the input and output files along with start and end dates to be selected by command line arguments. +This already leads to a quite large command line call. Now imagine, that we also want to allow the user to select more specific information +from the dataset, define specific X and Y labels, write their own +title etc. Now imagine to put all this into the command line:

+
$ python weather_observations.py --input https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv --output rain_in_tapiola.png --xlabel "Days in June" --ylabel "Rainfall in mm" --title "Rainfall in Cairo" --data_column RRR --start 01/06/2021 --end 30/06/2021
+
+
+

This is an even larger line, needs scrolling and becomes quite inconvenient to modify. +Instead of putting all of this into the command line, you could think about storing and modifying the arguments in a config file. +There are several ways, how config files can be stored. You can use a simple Parameter = Value +format, and parse it yourself, or you can use e.g. the JSON or YAML formats. +For both parsers exist that can save you some work, and both formats also allow you to use +more complex input data, like lists, or dictionaries. We won’t go into the details of the formats, and will only give +a short example using YAML here.

+

The YAML file format can be simple or very complex allowing a large variety of data structures to be stored. +One benefit of YAML is that there is already a Python module (yaml) available for parsing it and it +directly parses numbers as numbers and text as strings, making conversions unnecessary (the same is true for JSON +with the json package).

+

The Python module optionsparser.py provides a simple parser for YAML styled options files. +Similar to argparse, it takes a dict of required options, along with a dict of optional parameters. +Required arguments need to specify a type. Optional argument types are derived from their default values.

+

In our example above, we could for example add optional parameters that allow the selection of other weather data +from the dataset (precipitation …), set the labels and titles explicitly etc.

+

In the YAML format, names and values are separated by :. Our above example would therefore translate to the following YAML file:

+
input:        https://raw.githubusercontent.com/AaltoSciComp/python-for-scicomp/master/resources/data/scripts/weather_cairo.csv
+output:       rain_in_cairo.png
+xlabel:       Days in June
+ylabel:       Rainfall in mm
+title:        Rainfall in Cairo
+data_column:  RRR
+start:        01/06/2021
+end:          30/06/2021
+
+
+
+
+

Exercises 3 (optional)

+
+

Scripts-3

+
    +

  1. Download the optionsparser.py +function and load it into your working folder in Jupyterlab. +Modify the previous script to use a config file parser to read all arguments. The config file is passed in as a single argument on the command line +(using e.g. argparse or sys.argv) still needs to be read from the command line.

    2. +

  2. Run your script with different config files.

    3. +
+
+ +
+

Further reading

+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/search/index.html b/branch/rkdarst--remove-catfacts-jsonl/search/index.html new file mode 100644 index 00000000..21ffdb6c --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/search/index.html @@ -0,0 +1,154 @@ + + + + + + Search — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+
+ +
+ +
+

© Copyright 2020-2022, The contributors.

+
+ + Built with Sphinx using a + theme + provided by Read the Docs. + + +
+
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/searchindex.js b/branch/rkdarst--remove-catfacts-jsonl/searchindex.js new file mode 100644 index 00000000..f6ef54e2 --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"docnames": ["binder", "data-formats", "data-visualization", "dependencies", "exercises", "guide", "index", "installation", "jupyter", "libraries", "numpy", "numpy-advanced", "packaging", "pandas", "parallel", "parallel-pi-multiprocessing", "python", "quick-reference", "scipy", "scripts", "web-apis"], "filenames": ["binder.rst", "data-formats.rst", "data-visualization.md", "dependencies.rst", "exercises.md", "guide.rst", "index.rst", "installation.rst", "jupyter.ipynb", "libraries.rst", "numpy.rst", "numpy-advanced.rst", "packaging.rst", "pandas.rst", "parallel.rst", "parallel-pi-multiprocessing.ipynb", "python.rst", "quick-reference.rst", "scipy.rst", "scripts.rst", "web-apis.ipynb"], "titles": ["Binder", "Data formats with Pandas and Numpy", "Data visualization with Matplotlib", "Dependency management", "List of exercises", "Instructor\u2019s guide", "Python for Scientific Computing", "Software installation", "Jupyter", "Library ecosystem", "NumPy", "Advanced NumPy", "Packaging", "Pandas", "Parallel programming", "Python multithreading solution", "Introduction to Python", "Quick reference", "SciPy", "Scripts", "Web APIs with Python"], "terms": {"alon": 0, "mai": [0, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 19, 20], "suffici": [0, 4, 20], "what": [0, 2, 3, 4, 5, 6, 7, 11, 12, 14, 16, 19, 20], "my": [0, 1, 2, 3, 4, 9, 10, 13], "python": [0, 2, 5, 8, 10, 11, 13, 14, 18], "repositori": [0, 3, 4, 9, 12, 13], "publish": [0, 3, 4, 5, 9, 11], "learn": [0, 1, 2, 3, 4, 5, 6, 7, 11, 12, 13, 14, 17, 19, 20], "about": [0, 2, 3, 4, 6, 7, 8, 9, 10, 11, 13, 14, 16, 18, 19], "custom": [0, 9, 19, 20], "befor": [0, 1, 2, 3, 4, 7, 10, 11, 12, 13, 14], "we": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "work": [0, 1, 2, 3, 5, 6, 7, 8, 10, 11, 14, 19], "group": [0, 2, 4, 8, 9, 13], "let": [0, 1, 2, 4, 6, 8, 10, 11, 12, 13, 14, 18, 19, 20], "": [0, 1, 2, 3, 4, 6, 7, 8, 10, 11, 12, 14, 15, 16, 19, 20], "take": [0, 1, 4, 5, 8, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "an": [0, 1, 3, 5, 6, 8, 9, 12, 13, 14, 15, 16, 18, 19, 20], "exampl": [0, 1, 3, 6, 7, 8, 9, 10, 12, 13, 16, 18, 19, 20], "geospati": 0, "analysi": [0, 1, 2, 3, 6, 8, 11, 13, 14], "where": [0, 1, 2, 3, 4, 5, 6, 9, 10, 11, 13, 14, 18], "first": [0, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "import": [0, 1, 2, 3, 4, 5, 8, 10, 11, 12, 13, 14, 15, 18, 19, 20], "would": [0, 2, 3, 4, 7, 9, 10, 11, 12, 13, 14, 16, 19], "pleas": [0, 3, 4, 7, 12], "note": [0, 2, 4, 7, 10, 12, 13, 14, 19, 20], "necessari": [0, 3, 11, 12, 14], "instal": [0, 1, 2, 4, 5, 6, 9, 13, 14], "ani": [0, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 19], "packag": [0, 2, 5, 6, 7, 10, 11, 13, 14, 19], "mention": [0, 1, 5, 7, 9, 13, 14], "below": [0, 1, 2, 3, 4, 6, 7, 8, 9, 11, 12, 13, 14, 18, 19, 20], "osgeo": 0, "ogr": 0, "osr": 0, "gdal": 0, "depend": [0, 1, 5, 6, 9, 10, 11, 12, 14], "you": [0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "thi": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "have": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "libgdal": 0, "its": [0, 1, 2, 4, 10, 11, 12, 13, 14, 20], "develop": [0, 3, 4, 6, 8, 9, 11, 13, 19, 20], "header": 0, "alreadi": [0, 3, 4, 5, 7, 9, 10, 13, 19], "system": [0, 3, 4, 7, 8, 12, 14, 19, 20], "inform": [0, 4, 9, 12, 13, 14, 18, 19, 20], "version": [0, 4, 6, 7, 8, 11, 12, 14], "us": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 20], "etc": [0, 4, 5, 6, 9, 10, 11, 13, 14, 18, 19, 20], "lea": [0, 4], "phd": [0, 4, 5, 6], "student": [0, 3, 4, 5, 6, 9], "biologi": [0, 4], "after": [0, 2, 4, 8, 10, 11, 14, 19], "2": [0, 12, 15, 16], "year": [0, 2, 3, 4, 5, 6, 9, 11, 13, 20], "intens": [0, 4], "she": [0, 3, 4], "final": [0, 2, 4, 6, 10, 11, 13, 14, 15], "readi": [0, 2, 4, 7, 12], "her": [0, 3, 4], "paper": [0, 3, 4, 9, 10], "The": [0, 1, 2, 4, 5, 6, 7, 8, 10, 12, 13, 14, 15, 16, 18, 19, 20], "ha": [0, 1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 18, 20], "analyz": [0, 3, 20], "data": [0, 3, 5, 6, 8, 10, 14, 16, 19], "avail": [0, 3, 4, 5, 7, 9, 11, 12, 13, 18, 19, 20], "github": [0, 2, 3, 4, 5, 6, 8, 9, 13, 14], "supervisor": [0, 4], "who": [0, 2, 3, 4, 5, 7, 9, 11, 13, 14], "advoc": [0, 4], "open": [0, 1, 3, 4, 6, 7, 9, 12, 13, 18, 19, 20], "scienc": [0, 1, 4, 6, 9, 13, 14, 20], "told": [0, 4], "possibli": [0, 4, 5, 6], "just": [0, 1, 2, 3, 4, 6, 9, 10, 11, 13, 14, 15, 18, 19], "problem": [0, 1, 2, 4, 5, 8, 14, 19], "anticip": [0, 4], "5": [0, 2, 3, 6, 8, 11, 13, 14, 15, 18, 20], "now": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19], "form": [0, 4, 6, 7, 9, 13], "small": [0, 1, 2, 4, 5, 9, 10, 11, 12, 14], "person": [0, 2, 4, 5, 9, 16, 20], "discuss": [0, 3, 4, 5, 6, 8, 9], "If": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 14, 16, 19, 20], "workshop": [0, 4, 7, 9], "onlin": [0, 4, 7, 9], "each": [0, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 15, 18, 19, 20], "join": [0, 3, 4, 13], "breakout": [0, 3, 4], "room": [0, 3, 4], "possibl": [0, 1, 2, 3, 4, 5, 8, 10, 11, 12, 13, 14, 16, 20], "practic": [0, 2, 3, 4, 5, 6, 8, 9, 12, 19, 20], "document": [0, 1, 3, 4, 5, 8, 9, 12, 13, 14, 18, 19, 20], "collabor": [0, 3, 4, 6, 12], "write": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 12, 13, 14, 19, 20], "summari": [0, 3, 4, 13], "bullet": [0, 4, 8], "point": [0, 1, 2, 4, 5, 6, 8, 9, 10, 11, 14, 15, 16, 19, 20], "provid": [0, 1, 2, 3, 4, 5, 6, 7, 10, 13, 14, 19, 20], "instructor": [0, 4, 6], "allow": [0, 1, 2, 4, 11, 13, 14, 18, 19, 20], "mani": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "remot": [0, 2, 7], "user": [0, 2, 4, 5, 13, 14, 19, 20], "It": [0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 12, 14, 16, 18, 19, 20], "repo2dock": 0, "contain": [0, 1, 3, 4, 7, 8, 10, 11, 12, 13, 16, 18, 19, 20], "imag": [0, 1, 4, 9, 11], "docker": 0, "project": [0, 1, 2, 4, 6, 9], "includ": [0, 1, 3, 4, 7, 9, 10, 11, 13, 14, 18], "configur": [0, 2, 19], "file": [0, 4, 6, 8, 9, 10, 12, 13, 14, 18, 20], "standalon": 0, "local": [0, 4, 19], "laptop": [0, 5], "servic": 0, "freeli": 0, "tutori": [0, 5, 13, 14], "main": [0, 2, 4, 5, 6, 8, 11, 14, 18], "fork": [0, 14], "add": [0, 1, 2, 3, 4, 8, 10, 11, 12, 13, 19], "requir": [0, 2, 4, 9, 12, 13, 14, 19], "credit": 0, "juliett": 0, "taka": 0, "logilab": 0, "opendreamkit": 0, "2017": 0, "In": [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 16, 19, 20], "earlier": 0, "episod": [0, 3, 12, 19], "visual": [0, 1, 5, 6, 13], "matplotlib": [0, 3, 5, 6, 9, 17, 19], "panda": [0, 2, 3, 5, 6, 9, 14, 17, 19], "pd": [0, 1, 2, 4, 13, 19], "pyplot": [0, 2, 4, 19], "plt": [0, 2, 4, 19], "url": [0, 2, 4, 12, 13, 20], "http": [0, 2, 3, 4, 6, 7, 8, 9, 12, 13, 14, 19, 20], "raw": [0, 2, 4, 6, 7, 8, 10, 13, 19, 20], "githubusercont": [0, 2, 4, 7, 13, 19], "com": [0, 2, 4, 7, 9, 13, 19, 20], "plotli": [0, 2, 4], "dataset": [0, 1, 2, 19], "master": [0, 2, 3, 4, 7, 11, 13, 19], "gapminder_with_cod": [0, 2, 4], "csv": [0, 2, 4, 13, 19], "read_csv": [0, 1, 2, 4, 13, 19], "data_2007": [0, 2, 4], "2007": [0, 2, 4], "fig": [0, 2, 4, 19], "ax": [0, 2, 4, 19], "subplot": [0, 2, 4, 19], "scatter": [0, 2, 4], "x": [0, 1, 2, 3, 4, 8, 10, 12, 13, 14, 15, 16, 18, 19, 20], "gdppercap": [0, 2, 4], "y": [0, 1, 2, 3, 4, 8, 10, 12, 13, 14, 15, 19], "lifeexp": [0, 2, 4], "alpha": [0, 2, 4, 13], "0": [0, 1, 2, 4, 6, 8, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "set_xscal": [0, 2, 4], "log": [0, 20], "set_xlabel": [0, 2, 4, 19], "gdp": [0, 2, 4], "usd": [0, 2, 4, 13], "per": [0, 2, 4, 8, 14, 15], "capita": [0, 2, 4], "set_ylabel": [0, 2, 4, 19], "life": [0, 2, 4, 20], "expect": [0, 2, 3, 4, 5, 6, 7, 9, 10, 16, 19], "via": [0, 3, 4, 9, 14, 17, 19, 20], "static": [0, 4, 6, 16], "demonstr": [0, 2, 4, 5], "upload": [0, 4, 12, 19], "Then": [0, 2, 4, 7, 9, 13, 14, 15, 18], "look": [0, 2, 3, 4, 6, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "render": [0, 4, 20], "txt": [0, 3, 4], "which": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19], "commit": [0, 4], "push": [0, 4, 8], "also": [0, 2, 4, 5, 12, 13, 16, 19, 20], "visit": [0, 4, 13, 20], "mybind": [0, 4, 14], "org": [0, 2, 4, 6, 8, 9, 12, 13, 17, 20], "copi": [0, 4, 8, 9, 10, 13, 14, 19], "past": [0, 3, 4, 8, 9], "under": [0, 4, 7, 9, 13, 14], "text": [0, 1, 3, 4, 6, 8, 12, 13, 19, 20], "readm": [0, 3, 4, 12], "md": [0, 4, 8, 12], "check": [0, 1, 3, 4, 8, 9, 10, 12, 14, 18, 19, 20], "launch": [0, 4], "badg": [0, 4], "try": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 19, 20], "click": [0, 4, 7, 13, 19], "button": [0, 4, 5, 8, 19], "see": [0, 2, 4, 12, 13, 19, 20], "minut": [0, 4, 13], "two": [0, 1, 3, 4, 8, 9, 10, 12, 13, 14, 19], "expor": [0, 4], "execut": [0, 1, 3, 4, 8, 10, 11, 13, 19], "cloud": 0, "enjoi": [0, 4], "being": [0, 1, 2, 3, 4, 5, 10, 11], "fulli": [0, 1, 4, 19], "gener": [0, 1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "purpos": [0, 8, 18], "access": [0, 3, 4, 13, 15, 19, 20], "built": [0, 2, 4, 12, 19], "oper": [0, 3, 4, 6, 7, 8, 11, 12, 13, 14], "cern": 0, "openair": 0, "research": [0, 1, 3, 5, 6, 7, 9, 12, 13, 19], "archiv": [0, 1, 4], "digit": 0, "identifi": [0, 12, 14], "thei": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "everyth": [0, 2, 4, 5, 6, 7, 8, 9, 14, 15, 16, 18, 19], "deposit": [0, 4], "meant": [0, 4, 6], "kept": [0, 4], "long": [0, 1, 3, 4, 7, 9, 11, 13, 18, 19, 20], "term": [0, 1, 2, 3, 4], "therefor": [0, 3, 4, 19], "recommend": [0, 1, 2, 3, 4, 5, 7, 11, 12, 14, 19, 20], "sandbox": [0, 4], "test": [0, 1, 2, 4, 6, 7, 8, 9, 10, 11, 13, 14, 18, 20], "area": [0, 4, 6, 14], "instead": [0, 1, 3, 4, 8, 10, 11, 13, 14, 18, 19], "go": [0, 2, 4, 5, 6, 7, 9, 12, 14, 19, 20], "real": [0, 2, 4, 12], "later": [0, 1, 2, 3, 4, 7, 11, 14, 20], "account": [0, 4, 12], "Be": [0, 2, 3, 4, 5, 8, 9, 10, 16], "awar": [0, 4, 10, 14], "need": [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20], "author": [0, 1, 4, 6, 9, 12], "applic": [0, 1, 3, 4, 7, 9, 14, 20], "redirect": [0, 4], "back": [0, 1, 4, 9, 11, 13], "choos": [0, 1, 2, 4, 5, 20], "webhook": [0, 4], "drop": [0, 3, 4, 9, 13], "down": [0, 4, 8, 14, 20], "menu": [0, 4, 8, 13, 19], "next": [0, 2, 3, 4, 8, 10, 11, 12, 14, 20], "email": [0, 4], "address": [0, 4], "top": [0, 2, 4, 10, 13, 18, 19, 20], "page": [0, 4, 6, 7, 8, 10, 13, 14, 16, 18, 19, 20], "select": [0, 2, 3, 4, 7, 8, 10, 11, 13, 19], "present": [0, 1, 2, 4, 6, 13, 20], "list": [0, 2, 3, 6, 8, 9, 10, 11, 14, 15, 16, 20], "all": [0, 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 19, 20], "repo": [0, 4], "want": [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 16, 19, 20], "toggl": [0, 4], "ou": [0, 4], "reserv": [0, 4], "releas": [0, 4, 8, 9, 14], "trigger": [0, 4], "automat": [0, 2, 3, 4, 9, 14, 19, 20], "download": [0, 4, 6, 13, 19, 20], "zip": [0, 4], "ball": [0, 4], "new": [0, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19, 20], "regist": [0, 4], "should": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 15, 19], "give": [0, 1, 2, 3, 4, 8, 10, 11, 13, 14, 19, 20], "number": [0, 1, 2, 3, 4, 8, 10, 11, 13, 14, 16, 18, 19], "v1": [0, 4, 13], "descript": [0, 4, 7, 8, 12, 14, 18, 19], "time": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 14, 15, 16, 18, 19, 20], "To": [0, 2, 3, 4, 7, 10, 11, 12, 13, 14, 15, 19, 20], "ensur": [0, 4, 5, 6, 13], "set": [0, 2, 3, 4, 7, 11, 13, 14, 16, 19], "correspond": [0, 3, 4, 7, 13, 20], "find": [0, 2, 3, 4, 6, 7, 8, 9, 13, 14, 19, 20], "ad": [0, 3, 4, 12, 13, 20], "edit": [0, 4, 6, 7, 8, 12], "softwar": [0, 3, 4, 6, 8, 9, 12], "fill": [0, 3, 4, 10, 11, 13], "other": [0, 2, 3, 4, 5, 6, 8, 11, 12, 13, 16, 19, 20], "metadata": [0, 1, 4], "manual": [0, 2, 4, 7, 10, 11, 14, 19, 20], "json": [0, 4, 19, 20], "citat": [0, 4, 18], "cff": [0, 4], "infer": [0, 4], "public": [0, 8, 9, 12], "updat": [0, 4, 12], "newli": [0, 3, 4], "rather": [0, 3, 4, 10, 11, 13, 19], "than": [0, 1, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "specifi": [0, 3, 4, 12, 14, 19, 20], "when": [0, 1, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "exist": [0, 1, 2, 4, 5, 6, 8, 9, 11, 13, 14, 18, 19], "5281": [0, 4], "3886864": [0, 4], "start": [0, 1, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 19], "shown": [0, 4], "anim": [0, 4], "good": [0, 1, 2, 3, 4, 6, 8, 9, 10, 12, 13, 14, 18, 19], "both": [0, 2, 4, 6, 8, 9, 10, 11, 13, 14, 15, 19], "how": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19], "do": [1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "your": [1, 2, 5, 6, 7, 8, 10, 11, 12, 13, 14, 18, 19, 20], "right": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14], "ar": [1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "clean": 1, "preprocess": [1, 4, 19], "everi": [1, 2, 9, 10, 14, 19], "load": [1, 4, 9, 10, 13, 14, 20], "distinguish": 1, "characterist": 1, "differ": [1, 3, 6, 7, 8, 10, 12, 13, 14, 16, 18, 19], "read": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 16, 18, 20], "varieti": [1, 4, 9, 18, 19], "mean": [1, 4, 5, 6, 8, 10, 11, 13, 14, 15, 16], "re": [1, 3, 4, 6, 8, 9, 10, 13, 14, 15, 19], "memori": [1, 4, 10, 11, 13, 14], "while": [1, 4, 5, 6, 9, 10, 11, 12, 13, 16, 19], "wai": [1, 3, 4, 8, 10, 11, 12, 13, 14, 18, 19, 20], "disk": [1, 2, 4, 9, 13], "consid": [1, 4, 5, 9, 10, 14], "randomli": [1, 4, 9, 20], "datafram": [1, 2, 5, 14], "variou": [1, 2, 4, 12, 16], "column": [1, 4, 10, 11, 13], "np": [1, 2, 4, 10, 11, 13, 14], "n_row": [1, 4, 11], "100000": [1, 4, 13], "string": [1, 4, 12, 13, 16, 19, 20], "random": [1, 2, 3, 4, 9, 10, 11, 13, 14, 15, 18, 20], "choic": [1, 3, 4, 6, 13, 14], "appl": [1, 4, 16, 20], "banana": [1, 4, 16], "carrot": [1, 4], "size": [1, 2, 4, 10, 13, 14, 18], "timestamp": [1, 4], "date_rang": [1, 4, 13], "20130101": [1, 4, 13], "period": [1, 4, 13, 19], "freq": [1, 4, 13], "integ": [1, 4, 10, 11, 13, 16], "rang": [1, 3, 4, 8, 10, 13, 14, 15, 16, 19, 20], "10": [1, 2, 8, 9, 10, 11, 13, 14, 15, 18, 19], "float": [1, 4, 10, 11, 16], "uniform": [1, 4], "info": [1, 13], "multipl": [1, 4, 10, 11, 13, 14, 15, 16, 19], "collect": [1, 4, 9, 11, 12, 13, 14, 20], "anoth": [1, 2, 3, 4, 5, 9, 10, 12, 13, 14, 16, 19, 20], "n": [1, 2, 4, 8, 10, 11, 12, 13, 14, 15, 19, 20], "1000": [1, 4, 14, 19, 20], "data_arrai": [1, 4], "here": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 20], "diment": 1, "one": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20], "contigu": 1, "block": [1, 4, 12, 14, 16, 18], "individu": [1, 7, 20], "whole": [1, 2, 4, 8, 13, 18], "must": [1, 11], "sourc": [1, 6, 8, 9, 12, 13, 18, 20], "eleg": 1, "scipi": [1, 3, 5, 6, 10, 12, 14], "save": [1, 2, 4, 8, 10, 13, 15], "without": [1, 2, 3, 4, 6, 7, 9, 10, 11, 12, 13, 15, 16, 19, 20], "chang": [1, 2, 4, 6, 8, 9, 10, 11, 13, 14, 19], "For": [1, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 16, 18, 19, 20], "easili": [1, 2, 3, 5, 8, 9, 13, 16, 19], "our": [1, 2, 4, 7, 10, 11, 12, 13, 14, 15, 19, 20], "singl": [1, 3, 4, 6, 10, 11, 12, 13, 16, 19, 20], "piec": [1, 14], "organ": [1, 8, 9], "2d": [1, 4, 10, 11], "nest": 1, "dictionari": [1, 2, 4, 13, 16, 19, 20], "black": [1, 20], "white": 1, "png": [1, 2, 4, 19], "might": [1, 4, 5, 6, 7, 9, 12, 13, 18, 20], "nxm": 1, "decid": [1, 3, 4, 9, 10, 12], "program": [1, 2, 3, 5, 6, 8, 9, 11, 12, 16, 19, 20], "follow": [1, 3, 4, 6, 7, 8, 11, 12, 13, 14, 16, 18, 19], "There": [1, 2, 3, 4, 5, 8, 10, 12, 13, 14, 19, 20], "case": [1, 3, 4, 6, 8, 10, 11, 13, 14, 16, 20], "standard": [1, 2, 3, 4, 6, 7, 10, 11, 14], "xkcd": 1, "927": 1, "usual": [1, 3, 4, 5, 7, 8, 16, 20], "ll": [1, 3, 4, 6, 7, 9, 13, 19], "fast": [1, 4, 6, 9, 10, 13, 14, 18], "space": [1, 6, 10, 19], "effici": [1, 5, 6, 10, 11, 13], "easi": [1, 2, 3, 6, 8, 9, 10, 13, 19], "everybodi": 1, "els": [1, 2, 4, 5, 13, 14, 16, 20], "lead": [1, 19], "field": [1, 20], "certain": [1, 3, 12], "human": 1, "readabl": [1, 19], "enought": 1, "code": [1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 18, 19, 20], "share": [1, 3, 4, 8, 11, 14], "m": [1, 2, 3, 4, 8, 10, 13, 15], "support": [1, 3, 4, 7, 9, 13, 14, 18], "some": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 16, 18, 19, 20], "howev": [1, 2, 3, 5, 13, 14, 19, 20], "through": [1, 4, 5, 7, 10, 11, 13, 14], "librari": [1, 2, 3, 5, 6, 7, 10, 12, 13, 14, 18, 19, 20], "tabl": [1, 4, 13], "describ": [1, 4, 6, 12, 13], "name": [1, 2, 3, 4, 5, 8, 12, 13, 14, 16, 18, 19, 20], "storag": [1, 5, 10], "ok": [1, 2, 5, 13], "bad": [1, 3, 4, 9, 11, 12, 14], "none": [1, 4, 11, 14, 20], "modul": [1, 4, 8, 9, 11, 12, 14, 18, 19, 20], "warn": 1, "best": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 18], "debug": [1, 8, 14], "creat": [1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 18, 19, 20], "riski": 1, "unpickl": 1, "from": [1, 2, 5, 6, 7, 8, 9, 10, 11, 13, 16, 18], "trust": [1, 5, 9], "own": [1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 19, 20], "serial": 1, "suit": 1, "variabl": [1, 2, 4, 8, 10, 13, 14, 16, 18], "inspect": [1, 13, 20], "wb": [1, 4], "f": [1, 4, 7, 10, 11, 14, 18, 20], "dump": [1, 4], "rb": [1, 4], "data_array_pickl": 1, "match": [1, 4, 10], "origin": [1, 4, 6, 9, 10, 11, 13, 19, 20], "my_object": [1, 4], "my_pickled_object": [1, 4], "print": [1, 2, 3, 4, 7, 8, 10, 11, 12, 13, 14, 16, 18, 19, 20], "far": [1, 14, 19, 20], "most": [1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 14, 18], "popular": [1, 3, 6, 12, 14], "shareabl": 1, "big": [1, 4, 9, 11], "veri": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 19], "nice": [1, 4, 13, 16, 19, 20], "interfac": [1, 3, 4, 5, 6, 8, 12, 13, 14, 18, 19, 20], "to_csv": [1, 4, 13], "function": [1, 2, 4, 6, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20], "index": [1, 2, 4, 9, 11, 12, 13, 16], "fals": [1, 4, 10], "dataset_csv": [1, 4], "routin": [1, 10, 18], "well": [1, 6, 7, 8, 9, 14, 18, 19, 20], "savetxt": 1, "data_array_csv": 1, "loadtxt": 1, "care": [1, 8, 14], "enough": [1, 4, 5, 6, 10, 13, 14, 16, 19], "decim": [1, 4, 10, 13], "place": [1, 3, 4, 8, 10, 11], "so": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19], "won": [1, 3, 8, 14, 19], "t": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 18, 19, 20], "lose": 1, "doubl": [1, 11], "16": [1, 4, 10, 11, 14, 19], "normal": [1, 2, 4, 14, 18, 20], "test_numb": 1, "sqrt": [1, 10, 11], "test_fil": 1, "sqrt2": 1, "w": [1, 20], "close": [1, 2, 4, 8, 15], "r": [1, 2, 3, 4, 10, 11, 12, 20], "test_number2": 1, "float64": [1, 4, 10], "readlin": 1, "calcul": [1, 3, 4, 10, 12, 13, 14, 15, 18], "distanc": [1, 13], "between": [1, 3, 4, 8, 10, 13, 19, 20], "ab": 1, "avoid": [1, 2, 3, 4, 10, 12, 14], "even": [1, 2, 3, 4, 5, 9, 10, 14, 15, 16, 19, 20], "infal": 1, "whether": [1, 4, 6, 11, 13, 18], "written": [1, 3, 4, 9, 10, 14, 18, 19], "compar": [1, 4, 10, 14, 15, 18, 19], "row": [1, 4, 10, 11, 13], "last": [1, 3, 4, 8, 10], "sometim": [1, 3, 4, 13, 14], "round": [1, 4, 10, 13, 14], "due": [1, 3, 4, 6, 10, 12], "complex": [1, 16, 19], "technic": [1, 7], "reason": [1, 2, 3, 5, 6, 14], "high": [1, 2, 4, 5, 6, 9, 10, 13, 14], "ineffici": 1, "wise": 1, "repres": [1, 4, 11, 13, 18], "nativ": [1, 20], "suffer": 1, "pyarrow": 1, "pip": [1, 3, 4, 14], "demo": [1, 5, 7, 14], "temporari": 1, "frame": 1, "quickli": [1, 4, 8, 10], "julia": [1, 6, 9], "to_feath": 1, "read_feath": 1, "dataset_feath": 1, "said": [1, 20], "columnar": [1, 9], "commonli": 1, "usabl": [1, 4, 9, 12], "languag": [1, 2, 6, 8, 10, 11, 12, 16, 18], "c": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 16, 18], "java": 1, "matlab": [1, 2, 10, 18], "to_parquet": 1, "read_parquet": 1, "dataset_parquet": 1, "more": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "complic": [1, 3], "complet": [1, 4, 6, 8, 11, 13, 14, 18], "same": [1, 3, 4, 8, 10, 11, 13, 14, 15, 16, 19, 20], "cannot": [1, 3, 4], "result": [1, 2, 3, 4, 8, 9, 10, 11, 13, 14, 15, 18], "error": [1, 3, 4, 9, 10, 13, 19, 20], "temporarili": 1, "data_array_npi": [1, 4], "savez": 1, "npz": 1, "data_array0": 1, "data_array1": 1, "idea": [1, 3, 4, 5, 8, 9, 10, 13, 14], "spars": [1, 4], "matric": [1, 4], "dedic": 1, "save_npz": 1, "load_npz": 1, "huge": [1, 3, 5, 6, 11], "pytabl": [1, 9], "h5py": [1, 9], "perform": [1, 4, 6, 10, 11, 13, 14, 18], "larg": [1, 4, 5, 6, 9, 11, 14, 19], "amount": [1, 3, 6, 11, 20], "especi": [1, 5, 9, 10], "multidimension": [1, 10], "physic": [1, 4, 13], "to_hdf": [1, 13], "h5": 1, "mode": [1, 8, 20], "dataset_hdf5": 1, "read_hdf": [1, 13], "come": [1, 2, 3, 5, 7, 8, 11, 18], "default": [1, 3, 4, 8, 10, 13, 14, 15, 19, 20], "anaconda": [1, 2, 5, 6, 7, 8, 12], "h5_file": 1, "create_dataset": 1, "again": [1, 3, 4, 5, 8, 10, 15, 20], "full": [1, 7, 10, 14, 18], "data_array_h5": 1, "h5netcdf": 1, "often": [1, 2, 3, 4, 5, 6, 9, 10, 12, 13, 14, 16, 20], "faster": [1, 3, 4, 10, 11, 13, 14, 15], "offici": 1, "A": [1, 2, 4, 5, 6, 8, 9, 10, 12, 13, 14, 20], "great": [1, 2, 4, 8, 9, 14], "xarrai": [1, 14], "spatial": 1, "tempor": 1, "dimens": [1, 10, 11], "those": [1, 4, 7, 10, 11, 13, 14], "relat": [1, 6, 12], "make": [1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20], "simul": 1, "to_xarrai": 1, "to_netcdf": 1, "nc": 1, "engin": [1, 9], "xr": 1, "dataset_xarrai": 1, "open_dataset": 1, "dataset_netcdf4": 1, "to_panda": 1, "dataarrai": 1, "data_array_xarrai": 1, "open_dataarrai": 1, "data_array_netcdf4": 1, "to_numpi": 1, "advantag": [1, 4, 11, 14], "e": [1, 2, 4, 5, 6, 10, 11, 12, 13, 14, 18, 19, 20], "g": [1, 2, 4, 5, 6, 10, 12, 13, 14, 16, 18, 19, 20], "z": [1, 4, 10], "tell": [1, 2, 3, 4, 9, 11, 13, 20], "grid": [1, 10], "situat": [1, 3, 4, 9, 14], "As": [1, 3, 7, 9, 11, 12, 13, 14], "further": [1, 6, 12, 13, 14, 20], "doe": [1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "web": [1, 2, 6, 7, 8, 9, 12, 18], "request": [1, 2, 9, 11, 13, 14], "deal": [1, 13], "rest": [1, 2, 4, 5, 8, 10, 16], "api": [1, 5, 6, 11, 13, 14], "rare": [1, 9], "keep": [1, 3, 4, 9, 10, 20], "unless": [1, 3, 4, 8, 9, 10, 14], "layer": [1, 14], "lot": [1, 4, 5, 6, 8, 9, 13, 14, 18, 19], "interconnect": 1, "similarli": [1, 10, 13, 20], "to_json": [1, 13], "read_json": [1, 13], "dataset_json": 1, "openpyxl": 1, "quick": [1, 2, 4, 6, 13, 18], "social": [1, 20], "econom": 1, "plenti": [1, 5], "them": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 18, 19, 20], "optim": [1, 9, 11, 14, 18], "heavili": [1, 11], "One": [1, 2, 4, 10, 11, 13, 19], "networkx": [1, 4, 9], "tool": [1, 2, 3, 5, 6, 8, 10, 13, 14, 19, 20], "igraph": 1, "potenti": 1, "becaus": [1, 3, 4, 6, 7, 8, 10, 11, 13, 14, 15, 18], "charact": [1, 20], "addition": 1, "compress": 1, "much": [1, 2, 4, 5, 6, 8, 9, 12, 13, 14, 20], "alloc": [1, 10], "known": [1, 4, 8, 10, 11], "partial": 1, "larger": [1, 2, 4, 12, 13, 20], "comput": [1, 2, 3, 4, 5, 7, 8, 10, 11, 13, 14, 15, 18, 19, 20], "had": [1, 4, 5, 6, 9, 11], "mb": [1, 11], "exactli": [1, 4, 7, 9, 10], "57": 1, "360": [1, 13], "81": [1, 2, 4, 13], "12": [1, 2, 4, 10, 13, 14, 19], "9": [1, 2, 3, 4, 10, 13, 14, 16], "6": [1, 2, 3, 4, 10, 11, 12, 13, 14, 15], "67": 1, "true": [1, 4, 10, 13, 16, 19], "82": [1, 2, 4], "35": 1, "8": [1, 2, 4, 7, 10, 11, 13, 16, 19, 20], "96": [1, 2, 4, 13], "89": 1, "41": 1, "7": [1, 2, 3, 4, 8, 10, 11, 13, 14, 15], "29": [1, 13], "92": 1, "74": [1, 2, 4], "rel": [1, 2, 4, 9, 12], "poor": [1, 4, 13], "base": [1, 2, 3, 4, 8, 9, 11, 13], "mostli": 1, "dimension": [1, 2, 4, 10], "shape": [1, 4, 10, 11], "23": [1, 13, 20], "690": 1, "294": 1, "63": 1, "13": [1, 2, 4, 10], "72": 1, "27": 1, "97": 1, "64": [1, 11, 12, 13], "28": [1, 19, 20], "kind": [1, 3, 4, 10, 11, 13, 18], "better": [1, 3, 4, 6, 8, 9, 18, 19], "determin": [1, 16], "solv": [1, 3, 4, 5, 8], "previous": [1, 3, 4], "framework": [1, 5, 6, 10, 14], "specif": [1, 3, 8, 10, 11, 12, 14, 18, 19], "priorit": 1, "initi": [1, 4, 10, 11, 20], "futur": [1, 3, 4, 8, 9, 14], "ve": [1, 4, 14], "procedur": [1, 2], "script": [1, 2, 3, 5, 6, 8, 9, 11, 12, 14], "alwai": [1, 4, 10, 11, 13, 20], "reproduc": [1, 3, 5, 6, 9, 19], "throughout": 1, "turn": [1, 3, 8, 11], "plot": [1, 3, 5, 8, 13, 19], "averag": [1, 4, 13, 20], "head": [1, 4, 8, 13, 20], "onc": [1, 4, 8, 9, 12, 15], "finish": [1, 3, 4, 14], "peopl": [1, 2, 3, 4, 5, 7, 8, 10, 12, 13, 20], "io": [1, 3, 6, 14, 20], "comparison": [1, 12], "notebook": [1, 2, 3, 7, 8, 9, 10, 12, 13, 14, 20], "don": [1, 4, 5, 6, 7, 8, 9, 11, 13, 14, 16, 20], "happen": [2, 4, 8, 9, 10, 11, 12, 14], "can": [2, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 18, 19, 20], "produc": [2, 4, 9, 11, 12, 13], "prefer": [2, 4, 9, 20], "abl": [2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 16, 19], "simpl": [2, 3, 4, 5, 7, 8, 9, 12, 13, 14, 15, 19, 20], "tweak": 2, "know": [2, 3, 4, 5, 6, 7, 9, 10, 11, 13, 14, 16, 18], "orient": [2, 4, 6], "v": [2, 7, 8, 10, 18], "help": [2, 4, 5, 8, 19], "clau": 2, "o": [2, 4, 10, 12, 14, 15, 18], "wilk": 2, "fundament": 2, "thing": [2, 3, 4, 5, 6, 8, 9, 10, 12, 14, 18], "i": [2, 3, 4, 5, 7, 11, 12, 13, 14, 15, 16, 18, 19, 20], "over": [2, 4, 5, 9, 10, 11, 13, 16, 19], "autom": [2, 4, 9, 12, 19], "friend": [2, 20], "think": [2, 14, 19], "figur": [2, 4, 8, 18, 19], "autogener": 2, "part": [2, 4, 5, 8, 10, 11, 14, 20], "pipelin": [2, 3], "out": [2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 18, 19], "sent": 2, "printer": 2, "post": [2, 9, 14], "process": [2, 4, 9, 11, 14, 15, 18, 19, 20], "No": [2, 8], "bite": 2, "regener": 2, "50": 2, "dai": [2, 4, 5, 7, 9, 13, 19], "submiss": 2, "deadlin": 2, "left": [2, 4, 6, 7, 8, 10, 11], "perfect": [2, 4, 8, 9], "within": [2, 12, 19], "probabl": [2, 3, 4, 7, 9, 10, 13, 14, 18], "wide": [2, 3, 4, 9, 13], "seaborn": [2, 4, 9, 13], "level": [2, 4, 5, 6, 9, 10, 14], "statist": [2, 4, 9, 13, 18], "altair": [2, 4], "declar": [2, 4], "home": [2, 4, 7, 9, 20], "interact": [2, 4, 5, 6, 8, 12, 14], "graph": [2, 4, 9], "bokeh": [2, 4], "plotnin": [2, 4], "implement": [2, 4, 6, 10, 11, 14, 18], "grammar": [2, 4], "graphic": [2, 4, 7, 9], "ggplot2": [2, 4], "ggplot": [2, 4], "pyngl": [2, 4], "weather": [2, 4, 19], "forecast": [2, 4], "commun": [2, 4, 6, 9, 12, 13, 14, 20], "k3d": [2, 4], "jupyt": [2, 5, 6, 7, 9, 10, 12, 13, 14, 20], "extens": [2, 4, 8, 9, 14], "3d": [2, 4, 9], "famili": [2, 4, 13, 20], "perhap": [2, 9], "build": [2, 5, 9, 11, 18], "feel": [2, 4, 9, 10, 13], "familiar": [2, 3, 4, 5, 6, 16], "abov": [2, 4, 7, 8, 9, 10, 11, 12, 13, 14, 15, 19, 20], "chanc": [2, 10, 13], "somebodi": 2, "knowledg": [2, 11], "adjust": [2, 4, 10, 19], "low": [2, 4, 8, 9, 13, 14], "draw": 2, "abstract": 2, "qualiti": [2, 9], "type": [2, 4, 5, 6, 7, 8, 9, 13, 18, 19, 20], "line": [2, 4, 5, 6, 8, 10, 12, 13, 14, 18, 20], "strength": 2, "matter": [2, 6], "sinc": [2, 4, 10, 11, 13, 15, 20], "typic": [2, 3, 4, 5, 14, 16], "fit": [2, 14], "But": [2, 4, 5, 6, 8, 9, 10, 13, 14, 18, 19, 20], "run": [2, 3, 5, 7, 11, 12, 13, 15, 19], "u": [2, 4, 11, 13, 14, 18, 19, 20], "method": [2, 4, 7, 9, 10, 11, 13, 14, 18, 20], "displai": [2, 4, 8, 20], "inlin": [2, 4, 8], "en": [2, 4, 20], "wikipedia": [2, 4, 19], "wiki": [2, 4], "anscomb": [2, 4], "27s_quartet": [2, 4], "data_x": [2, 4], "11": [2, 4, 10, 11, 14], "14": [2, 4, 10, 16], "4": [2, 11, 13, 14, 15, 16, 18], "data_i": [2, 4], "04": [2, 4], "95": [2, 4], "58": [2, 4], "33": [2, 4], "24": [2, 4], "26": [2, 4], "84": [2, 4], "68": [2, 4, 20], "e69f00": [2, 4], "label": [2, 4, 19], "axi": [2, 4, 10, 14], "set_titl": [2, 4, 19], "titl": [2, 4, 8, 19, 20], "uncom": [2, 4], "like": [2, 3, 4, 5, 6, 8, 9, 10, 11, 13, 14, 19, 20], "savefig": [2, 4, 19], "server": [2, 7, 20], "cluster": [2, 19], "call": [2, 3, 4, 6, 8, 11, 12, 13, 14, 19, 20], "agg": 2, "valu": [2, 4, 10, 11, 13, 14, 16, 19, 20], "56b4e9": [2, 4], "data2_i": [2, 4], "77": [2, 4, 16], "009e73": [2, 4], "second": [2, 4, 9, 10, 11, 14, 20], "multipli": [2, 4, 10, 11, 18], "element": [2, 4, 10, 11, 14, 16, 18], "data2_y_sc": [2, 4], "legend": [2, 4], "search": [2, 4, 9, 12, 13, 18, 20], "clue": [2, 4], "At": [2, 4, 6, 14], "end": [2, 3, 4, 8, 10, 11, 12, 14, 19, 20], "qualit": 2, "palett": [2, 4], "opim": 2, "vision": 2, "defici": 2, "clauswilk": 2, "dataviz": 2, "pitfal": [2, 8], "html": [2, 4, 6, 20], "okab": 2, "k": 2, "ito": 2, "2008": [2, 6], "univers": [2, 6, 10, 20], "design": [2, 4, 6, 14, 15], "cud": 2, "That": [2, 4, 10], "friendli": 2, "colorblind": 2, "understand": [2, 4, 7, 10, 11, 13, 14, 16, 18, 20], "approach": [2, 3, 4, 6, 12, 14, 19], "though": [2, 4, 7, 12, 14, 15, 16], "dual": 2, "outsid": [2, 4, 8, 12], "scope": [2, 14], "lesson": [2, 4, 5, 6, 7, 8, 9, 11, 13, 14, 16, 19], "modern": [2, 6, 11], "option": [2, 5, 8, 10, 13, 18], "separ": [2, 3, 10, 13, 14, 15, 19], "pass": [2, 4, 9, 10, 14, 19, 20], "around": [2, 4, 7, 11, 13, 14, 18], "tradit": [2, 10], "mimic": 2, "carri": [2, 10, 14], "global": [2, 4, 14, 18], "xlabel": [2, 4, 19], "ylabel": [2, 4, 19], "internet": [2, 13], "mix": 2, "although": 2, "compact": [2, 13], "wrap": [2, 5, 18], "send": [2, 8, 14, 20], "less": [2, 4, 6, 8, 10, 11, 20], "risk": [2, 9], "unrel": [2, 8], "modifi": [2, 4, 11, 18, 19], "entir": [2, 14], "latter": 2, "accept": [2, 20], "linear": [2, 4, 11, 18], "yield": [2, 13], "surpris": 2, "introduc": [2, 5, 6], "enhanc": 2, "almost": [2, 6, 9], "aspect": 2, "studi": [2, 8, 20], "cheatsheet": [2, 13, 17], "among": [2, 4, 13], "pre": 2, "defin": [2, 3, 4, 5, 11, 13, 16, 18, 19, 20], "theme": 2, "sheet": 2, "instanc": [2, 3, 4, 6, 12, 14, 16, 19], "either": [2, 3, 4, 5, 7, 8, 12, 13, 14, 19], "input": [2, 4, 5, 8, 10, 11, 14, 15, 19], "imposs": [2, 4, 8], "rememb": [2, 9, 13], "strategi": [2, 4, 8, 14], "mind": 2, "answer": [2, 3, 4, 10, 14, 15], "fetch": [2, 4], "snippet": [2, 4], "overview": [2, 4, 5, 13, 16], "realiz": [2, 4, 14], "ideal": [2, 4], "task": [2, 4, 5, 6, 9, 10, 15, 19], "switch": [2, 4, 8], "arriv": [2, 4], "transpar": [2, 4], "slide": [2, 4], "screen": [2, 4], "onli": [2, 3, 4, 6, 7, 11, 12, 13, 14, 19], "few": [2, 3, 4, 10, 13, 14, 19], "centimet": [2, 4], "inch": [2, 4], "font": [2, 4, 20], "tickmark": [2, 4], "too": [2, 4, 5, 8, 9, 11, 12, 14], "tick_param": [2, 4], "fontsiz": [2, 4], "major": [2, 3, 4, 14], "length": [2, 4, 11, 20], "minor": [2, 4], "labels": [2, 4], "doubt": [2, 4], "brows": [2, 4, 8], "link": [2, 9, 13, 19], "recent": [2, 3, 4, 7, 12], "simpli": [2, 4], "interest": [2, 3, 4, 12, 13, 14], "structur": [2, 4, 9, 10, 12, 13, 19], "numpi": [2, 3, 5, 6, 9, 13, 14, 17, 18], "arrai": [2, 4, 6, 9, 11, 13, 14, 18, 19], "bit": [2, 4, 5, 6, 7, 9, 13, 14, 16], "feed": [2, 4], "simplifi": [2, 3, 4], "kei": [2, 4, 8, 10, 14, 20], "imagin": [2, 4, 6, 12, 19], "were": [2, 3, 4, 6, 9], "pydata": [2, 4, 17], "And": [2, 4, 6, 11, 12, 13], "caught": [2, 4], "ey": [2, 4, 10], "simple_violinplot": [2, 4], "d": [2, 4, 8, 10, 13, 16, 18, 19], "seem": [2, 3, 4, 9, 18], "sn": [2, 4, 13], "violinplot": [2, 4, 13], "set_them": [2, 4], "across": [2, 4, 14], "sever": [2, 4, 6, 7, 9, 19], "default_rng": [2, 4, 11], "p": [2, 4, 20], "40": [2, 4, 11, 20], "arang": [2, 4, 10, 13], "show": [2, 4, 5, 6, 7, 9, 12, 13, 14, 19, 20], "distribut": [2, 3, 4, 6, 7, 8, 9, 12, 13, 14], "violin": [2, 4], "light": [2, 4], "inner": [2, 4, 13], "h": [2, 4, 11, 16, 19], "reveal": [2, 4], "25146044": [2, 4], "27005437": [2, 4], "78778386": [2, 4], "27832843": [2, 4], "88147169": [2, 4], "76439276": [2, 4], "87844934": [2, 4], "49695422": [2, 4], "59252953": [2, 4], "00342116": [2, 4], "26038963": [2, 4], "15118015": [2, 4], "69725111": [2, 4], "60361933": [2, 4], "22137264": [2, 4], "86174242": [2, 4], "45950762": [2, 4], "32352988": [2, 4], "56724895": [2, 4], "42215312": [2, 4], "34419915": [2, 4], "46123886": [2, 4], "56953795": [2, 4], "95292133": [2, 4], "clutter": [2, 4], "remov": [2, 3, 4], "l1": [2, 4], "l2": [2, 4], "focu": [2, 4], "set_yticklabel": [2, 4], "clarifi": 2, "move": [2, 9, 11, 12, 20], "manuscript": 2, "five": 3, "tensorflow": [3, 9], "get": [3, 4, 5, 6, 7, 9, 10, 11, 14, 15, 16, 18, 19, 20], "me": 3, "colleagu": [3, 7], "conflict": 3, "reus": [3, 4, 14], "relianc": 3, "extern": [3, 5, 6, 12, 14, 18], "compon": [3, 12], "Into": [3, 4], "yml": [3, 4, 7], "why": [3, 4, 5, 10, 11, 14, 20], "ever": [3, 4, 20], "experienc": [3, 4], "ye": [3, 4, 11], "did": [3, 4, 8, 14, 20], "similar": [3, 4, 5, 9, 10, 14, 15, 19, 20], "driven": 3, "channel": [3, 4, 12], "ecosystem": [3, 5, 6], "tradition": 3, "bundl": 3, "old": [3, 4, 5, 6, 8, 9, 13], "handl": [3, 9, 10, 13, 14], "pro": 3, "creation": [3, 5], "con": 3, "aim": 3, "tri": [3, 5], "scientif": [3, 4, 5, 9, 10, 14, 18], "speed": [3, 10, 11, 12, 13], "up": [3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 18, 19], "becom": [3, 4, 5, 6, 9, 10, 11, 19], "quit": [3, 4, 10, 11, 14, 19], "easier": [3, 5, 6, 12, 13, 19, 20], "harder": 3, "made": [3, 4, 9, 13, 14, 19], "inc": [3, 4], "free": [3, 4, 20], "academ": [3, 4, 5], "non": [3, 4, 5, 8, 10, 13, 18], "commerci": [3, 4], "minim": [3, 4, 7, 8, 9, 10], "maintain": [3, 4, 8, 9], "replac": [3, 4, 5, 9, 13], "hous": [3, 4], "largest": [3, 4, 13], "meet": 3, "coupl": 3, "older": [3, 4, 9], "encount": [3, 4], "mistak": 3, "someth": [3, 10, 12, 14, 16, 18], "export": [3, 4, 14, 19], "replic": [3, 4, 20], "chloe": [3, 4], "team": [3, 4, 6], "still": [3, 4, 5, 6, 8, 9, 10, 12, 19], "assign": [3, 4, 8, 13], "week": [3, 4, 19], "favorit": [3, 4], "been": [3, 4, 5, 6, 9, 11, 12, 14, 19], "18": [3, 4, 13], "otherwis": [3, 4, 16], "fail": [3, 4], "could": [3, 4, 5, 6, 7, 9, 10, 14, 15, 19, 20], "valid": [3, 4, 20], "baselin": [3, 4, 5, 6], "upgrad": [3, 4, 6], "python37": [3, 4], "env": [3, 4, 7, 19], "delet": [3, 4, 8], "navig": [3, 4, 7, 8, 12, 19], "setup": [3, 4, 12], "properli": [3, 4, 11], "With": [3, 4, 7, 10, 13, 20], "consol": [3, 4], "effect": [3, 4], "__version__": [3, 4, 12], "Or": [3, 4, 7, 9], "liner": [3, 4, 13], "termin": [3, 4, 5, 7, 12, 14, 19], "bash": [3, 4, 8], "deactiv": [3, 4], "sure": [3, 4, 5, 6, 7, 9, 14], "current": [3, 4, 11, 19], "indic": [3, 4, 10, 11, 13], "argument": [3, 4, 10, 13, 14, 15, 16, 18, 20], "virtualenv": [3, 4, 5], "venv": [3, 4], "python3": [3, 4, 7, 19], "scicomp": [3, 4, 7, 8, 19], "virtual": [3, 4, 12], "folder": [3, 4, 12, 19], "locat": [3, 4, 9, 19], "linux": [3, 4, 12], "mac": [3, 4, 12], "osx": [3, 4, 12], "bin": [3, 4, 13, 19], "window": [3, 4, 12], "command": [3, 4, 5, 6, 8, 12, 13], "unexpect": [3, 14], "behaviour": 3, "ran": [3, 13], "state": [3, 14, 20], "These": [3, 4, 6, 9, 10, 11, 12, 13, 14, 18, 20], "mitig": 3, "yaml": [3, 12, 19], "recreat": 3, "exact": [3, 7], "delai": [3, 14], "dure": [3, 4, 7, 11, 16], "review": 3, "refer": [3, 4, 8, 10, 11, 13, 16], "section": [3, 4, 8, 9, 12], "coderefineri": [3, 7, 8, 9, 19], "03": [3, 19], "mainten": 3, "coexist": 3, "freez": [3, 4], "frozen": [3, 4], "somepackag": 3, "attach": 3, "git": [3, 7, 9], "along": [3, 8, 11, 16, 19], "binder": [3, 5, 6, 9], "session": [3, 4, 7, 8, 14], "talk": [3, 6, 9, 20], "express": [3, 4, 9, 13, 20], "py": [3, 4, 8, 12, 14, 19], "pyproject": [3, 12], "toml": [3, 12], "meta": [3, 4, 12, 20], "directli": [3, 4, 9, 10, 11, 13, 14, 19], "difficult": [3, 8, 14, 20], "narrowli": 3, "taken": [3, 4, 14, 20], "install_requir": [3, 12], "19": [3, 4, 11, 13], "undefin": [3, 16], "alongsid": 3, "minimum": 3, "maximum": [3, 13], "issu": [3, 9, 20], "consum": 3, "poetri": [3, 12], "pipenv": 3, "altern": [3, 6, 12], "pyenv": 3, "micropipenv": 3, "lightweight": [3, 8, 20], "rule": [3, 4, 11, 18], "miniforg": 3, "mambaforg": 3, "resourc": [3, 4, 9, 19], "aalto": [3, 8], "fi": [3, 8, 20], "trace": 3, "mainli": 4, "helper": 4, "teach": [4, 5, 6, 7, 8, 9], "event": [4, 13], "cover": [4, 5, 6, 10, 13, 14], "subset": [4, 13], "ipynb": [4, 19], "directori": [4, 8], "cours": [4, 5, 7, 8, 9, 10, 11, 14, 16], "stuff": [4, 8], "done": [4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15], "browser": [4, 7, 8, 13, 20], "editor": [4, 5, 6, 8], "begin": [4, 5, 8, 11], "independ": [4, 8, 12], "trivial": [4, 8, 11], "slightli": [4, 6, 8, 14, 16, 19], "ten": [4, 8], "fibonacci": [4, 8, 13], "markdown": [4, 8, 12], "cell": [4, 8, 10, 13, 14, 15], "bold": [4, 8], "ital": [4, 8], "timeit": [4, 8, 10, 11, 13, 14, 15, 18], "magic": [4, 8, 14, 15], "fastest": [4, 8], "sum": [4, 8, 10, 11, 13, 14, 15], "1000000": [4, 8], "tab": [4, 8, 13, 20], "hint": [4, 8, 13], "thin": [4, 8], "sidebar": [4, 8], "shut": [4, 8], "kernel": [4, 6, 8, 11], "b": [4, 5, 6, 8, 10, 11, 13, 16, 20], "repeat": [4, 8, 10, 11, 19], "increment": [4, 8, 9], "tupl": [4, 8, 10, 16], "new_a": [4, 8], "new_b": [4, 8], "statement": [4, 8, 14, 16], "hand": [4, 8, 18], "comment": [4, 8, 19], "output": [4, 5, 7, 8, 10, 11, 14, 19], "relet": [4, 8], "395": [4, 8], "loop": [4, 8, 10, 15, 16, 19, 20], "std": [4, 8, 13, 15], "dev": [4, 8, 13, 15], "becam": [4, 6, 8], "spread": [4, 8], "order": [4, 5, 8, 10, 13, 19], "On": [4, 8], "success": [4, 8], "prevent": [4, 8, 14], "rst": 4, "datatyp": [4, 10], "linspac": [4, 10], "3x2": [4, 10], "int": [4, 10, 11, 13, 14, 16], "astyp": [4, 10], "reshap": [4, 10], "numpyi": [4, 10], "npy": [4, 10], "dtype": [4, 10, 13], "int64": [4, 10, 13], "eg": [4, 10], "zero": [4, 10, 11, 13, 18], "mayb": [4, 10], "cast": [4, 10], "randint": [4, 10], "matrix": [4, 10, 14, 18], "dot": [4, 10, 12, 18], "leav": [4, 10], "paramet": [4, 10, 13, 19], "elementwis": [4, 10], "enabl": [4, 10, 13], "given": [4, 10, 12, 13, 14, 16, 19], "view": [4, 10, 13], "mere": [4, 10, 11], "henc": [4, 10, 13], "addit": [4, 6, 8, 11, 12, 19], "itself": [4, 8, 10, 19], "ufunc": [4, 10, 11], "id": [4, 5, 10, 20], "third": [4, 10], "notic": [4, 9, 10, 14, 15], "return": [4, 10, 11, 12, 13, 14, 15, 16, 18, 20], "wa": [4, 5, 6, 9, 10, 11, 13, 19], "actual": [4, 5, 7, 9, 10, 11, 14, 15, 19, 20], "slower": [4, 10], "10000": [4, 10, 14, 18], "squar": [4, 10, 14, 15], "extra": [4, 7, 10], "revers": [4, 10, 11], "vector": [4, 5, 11, 14, 18], "border": [4, 10, 20], "insid": [4, 10, 11], "ceil": [4, 10], "floor": [4, 10], "trunc": [4, 10], "particular": [4, 10, 18, 20], "behav": [4, 10], "neg": [4, 10, 13], "recal": [4, 10], "ident": [4, 10, 14], "sin": [4, 10], "co": [4, 10], "4x4": [4, 10], "equal": [4, 10], "allclos": [4, 10], "1d": [4, 10, 11], "sort": [4, 6, 9, 10], "np_arrai": [4, 10], "question": 4, "indirect": [4, 10], "ones": [4, 7, 10, 11], "combin": [4, 8, 10, 13, 14, 15], "8x4": [4, 10], "content": [4, 8, 10, 20], "bottom": [4, 10, 14, 20], "4x8": [4, 10], "rand": [4, 10, 11, 13, 18], "100": [4, 10, 11, 13, 20], "halfwai": [4, 10], "nearest": [4, 10], "posit": [4, 10, 19], "75": [4, 10], "trun": [4, 10], "oo": [4, 10], "s2c2": [4, 10], "argsort": [4, 10], "concaten": [4, 10, 11, 13], "slow": [4, 6, 8, 10, 11, 14, 18], "million": [4, 11, 20], "100000000": [4, 11], "togeth": [4, 6, 11, 14, 17], "beat": [4, 11], "troubl": [4, 11], "basic": [4, 5, 6, 7, 10, 11, 14, 15, 16, 18, 20], "lession": [4, 11], "continu": [4, 11], "live": [4, 11], "worri": [4, 11, 14], "watch": [4, 5, 6, 11, 12, 20], "100_000_000": [4, 11], "ravel": [4, 11], "appropri": [4, 11], "remind": [4, 11], "yourself": [4, 5, 6, 7, 9, 11, 19], "col": [4, 11, 13], "total": [4, 11], "n_col": [4, 11], "desir": [4, 11], "3_465": [4, 11], "18_923": [4, 11], "10_000": [4, 11], "20_000": [4, 11], "69_318_923": [4, 11], "def": [4, 11, 12, 13, 14, 15, 16, 18], "littl": [4, 5, 6, 9, 11], "featur": [4, 9, 11, 13, 14], "stride_trick": [4, 11], "stride": 4, "attribut": [4, 11, 13, 20], "plai": [4, 8, 11, 13], "educ": [4, 6, 11, 20], "transpos": [4, 10], "lib": [4, 11], "as_strid": [4, 11], "000": [4, 11, 20], "obtain": [4, 11, 19], "By": [4, 5, 8, 10, 11, 14, 15, 19, 20], "infinit": [4, 11], "100_000_000_000": [4, 11], "autocomplet": [4, 13], "docstr": [4, 12, 13], "piqu": [4, 13], "ag": [4, 13], "slice": [4, 13], "boolean": [4, 10, 13, 16], "surviv": [4, 13], "rate": [4, 13], "iloc": [4, 13], "loc": [4, 13], "nasser": [4, 13], "mr": [4, 13], "nichola": [4, 13], "adel": [4, 13], "achem": [4, 13], "investig": [4, 13], "sibsp": [4, 13], "uniqu": [4, 9, 12, 13, 16], "histogram": [4, 13], "split": [4, 13, 14, 15], "fare": [4, 13], "lambda": [4, 12, 13], "hist": [4, 13], "fly": [4, 13], "df": [4, 13], "rich": [4, 13], "member": [4, 13], "class": [4, 5, 6, 10, 11, 13, 14], "rwidth": [4, 13], "countri": [4, 13, 20], "receiv": [4, 13], "borncountrycod": [4, 13], "laureat": [4, 13], "step": [4, 7, 12, 13, 14], "lifespan": [4, 13], "extract": [4, 10, 13, 20], "country1": [4, 13], "country2": [4, 13], "country3": [4, 13], "country4": [4, 13], "borncountri": [4, 13], "isin": [4, 13], "groupbi": [4, 13], "categori": [4, 13], "pivot": [4, 13], "spreadsheet": [4, 13], "count": [4, 13], "pivot_t": [4, 13], "aggfunc": [4, 13], "heatmap": [4, 13], "linewidth": [4, 13], "stick": [4, 13], "swarmplot": [4, 13], "subset_physchem": [4, 13], "chemistri": [4, 13], "catplot": [4, 13], "swarm": [4, 13], "956": [4, 13], "287": [4, 13], "born": [4, 13, 19], "datetim": [4, 13], "to_datetim": [4, 13, 19], "coerc": [4, 13], "age_nobel": [4, 13], "dt": [4, 13], "365": [4, 13], "25": [4, 11, 13, 14, 20], "figsiz": [4, 13], "sweden": [4, 13], "firstnam": [4, 12, 13], "surnam": [4, 13], "color": [4, 20], "arbitrari": [4, 11, 16], "object": [4, 6], "pickl": 4, "store": [4, 10, 11, 16, 18, 19, 20], "weather_observ": [4, 19], "weather_data": [4, 19], "jupyterlab": [4, 5, 8, 13, 17, 19], "temperatur": [4, 19], "tapiola": [4, 19], "espoo": [4, 19], "rp5": [4, 19], "kz": [4, 19], "lectur": [4, 19, 20], "haven": [4, 19, 20], "convert": [4, 11, 12, 13, 18, 19], "nbconvert": [4, 19], "preced": [4, 19], "argpars": 4, "date": [4, 9, 13, 19, 20], "interv": [4, 10, 18, 19], "januari": [4, 19], "2019": [4, 14, 19], "june": [4, 19], "2020": [4, 6, 10, 19], "octob": [4, 19], "cairo": [4, 19], "aaltoscicomp": [4, 7, 19], "weather_cairo": [4, 19], "parser": [4, 19, 20], "argumentpars": [4, 19], "add_argu": [4, 19], "str": [4, 13, 16, 19], "01": [4, 15, 18, 19], "dd": [4, 19], "mm": [4, 19], "yyyi": [4, 19], "2021": [4, 6, 19], "arg": [4, 19], "parse_arg": [4, 19], "start_dat": [4, 19], "dayfirst": [4, 19], "end_dat": [4, 19], "observ": [4, 12, 13, 19], "celsiu": [4, 19], "nicer": [4, 9, 19], "autofmt_xd": [4, 19], "optionspars": [4, 19], "config": 4, "sy": 4, "argv": [4, 11], "usr": [4, 19], "utf": [4, 19, 20], "get_paramet": [4, 19], "confg": [4, 19], "06": [4, 19], "data_column": [4, 19], "pars": 4, "sampl": [4, 8, 14, 15, 20], "queri": [4, 20], "www": [4, 14, 20], "boredapi": [4, 20], "j": [4, 20], "particip": [4, 20], "price": [4, 13, 20], "expressj": [4, 20], "3943506": [4, 20], "regard": [4, 20], "encod": [4, 20], "gzip": [4, 20], "identif": [4, 20], "agent": [4, 20], "password": [4, 12, 20], "token": [4, 20], "beauti": [4, 20], "soup": [4, 20], "relev": [4, 9, 18, 20], "integr": [4, 8, 12], "quad": [4, 12, 18], "vari": [4, 18], "myfunct": [4, 18], "fortran": [4, 5, 6, 9, 10, 11, 14, 18], "quadpack": [4, 18], "assum": [4, 6, 13, 18], "pretti": [4, 9, 18], "doc": [4, 6, 10, 13, 18], "05": [4, 18, 19, 20], "algebra": [4, 11, 18], "product": [4, 18], "macro": [4, 18], "measur": [4, 11, 13, 18], "dens": [4, 18], "thumb": [4, 18], "worth": [4, 11, 18], "represent": [4, 18], "densiti": [4, 18], "csc": [4, 18], "spare": [4, 18], "bsr": [4, 18], "coo": [4, 18], "csr": [4, 18], "fairli": [4, 14, 18], "lil": [4, 18], "dok": [4, 18], "sai": [4, 5, 9, 10, 11, 13, 16, 18, 20], "insert": [4, 8, 18], "7m": [4, 18], "42m": [4, 18], "1600m": [4, 18], "toarrai": [4, 18], "64m": [4, 18], "time_spars": [4, 18], "matrix2": [4, 18], "time_ful": [4, 18], "3f": [4, 18], "wish": [4, 9], "hackmd": [4, 9], "anyth": [4, 9, 18], "footnot": [4, 9], "rkdarst": [4, 9], "pcd": [4, 9], "dftlib": [4, 9], "numgrid": [4, 9], "dynbench": [4, 9], "vpython": [4, 9], "doesn": [4, 6, 7, 9, 10, 14, 15], "fine": [4, 9], "action": [4, 9], "workflow": [4, 9, 14, 19], "green": [4, 9], "put": [4, 9, 10, 19], "correct": [4, 9, 11], "miss": [4, 5, 7, 9, 13], "clearli": [4, 9, 10, 13], "anymor": [4, 9], "ancient": [4, 9], "pull": [4, 9, 13], "websit": [4, 9, 20], "disappear": [4, 9], "goe": [4, 6, 8, 9, 10, 12, 14], "everyon": [4, 5, 7, 8, 9, 16], "somewher": [4, 9, 11, 13, 20], "improv": [4, 9, 14], "isn": [4, 5, 6, 9], "pi": [4, 14, 15], "stochast": [4, 14, 15], "algorithm": [4, 11, 14, 18], "realli": [4, 5, 6, 14], "1x1": [4, 14], "fall": [4, 14], "circl": [4, 14], "highlight": [4, 14], "trial": [4, 14, 15, 20], "number_in_circl": [4, 14, 15], "n_inside_circl": [4, 14, 15], "pool": [4, 14, 15], "environ": [4, 5, 8, 9, 12, 14], "threadpool": [4, 14, 15], "thread": [4, 14], "multithread": 4, "longer": [4, 9, 11, 14], "pure": [4, 10, 12, 14], "simultan": [4, 14], "cpu": [4, 10, 11, 14, 15], "node": [4, 14], "schedul": [4, 14], "permiss": [4, 14, 20], "upset": [4, 14], "slurm": [4, 14], "slurm_cpus_per_task": [4, 14], "whatev": [4, 7, 8, 13, 14], "hood": [4, 9, 14], "experi": [4, 14, 19], "mpi4pi": [4, 14], "openmpi": [4, 14], "core": [4, 14], "mpiexec": [4, 14], "guess": [4, 14], "comm": [4, 14], "gather": [4, 14], "rank": [4, 10, 14], "_": [4, 14], "n_task": [4, 14], "7854305": [4, 14], "dart": [4, 14], "10000000": [4, 14], "estim": [4, 14], "141722": [4, 14], "spent": [4, 14], "parallelis": [4, 14], "mpirun": [4, 14], "mpi_test": [4, 14], "3926634": [4, 14], "3925910": [4, 14], "1410176": [4, 14], "twice": [4, 13, 14], "onto": [4, 14], "root": [4, 12, 14], "convention": [4, 14], "condit": [4, 10, 14, 16], "underscor": [4, 14], "unimport": [4, 14], "illustr": [4, 11, 14, 20], "usag": [4, 7, 10, 13, 14, 19], "pypi": [4, 9], "track": 4, "record": [4, 9, 11], "thesi": 4, "isol": [4, 12], "zenodo": 4, "doi": 4, "path": [4, 5, 9, 12, 20], "subtract": [4, 10, 12], "earli": [5, 6, 20], "career": [5, 6, 7], "theoret": [5, 6], "themselv": [5, 6], "aren": [5, 6, 8, 9, 15, 18], "direct": [5, 6], "a2": [5, 6], "hasn": [5, 6], "comprehens": [5, 6, 9], "introduct": [5, 6, 11, 13, 14, 18], "mid": [5, 6], "late": [5, 6], "undergradu": [5, 6], "syntax": [5, 6, 16, 19], "manner": [5, 6, 9], "prerequisit": 5, "crash": [5, 6], "Not": [5, 13], "multi": [5, 14], "pretend": 5, "fraction": 5, "intro": [5, 13], "outlin": 5, "somewhat": [5, 9], "conveni": [5, 7, 19], "spend": 5, "shell": [5, 7, 8, 19], "advanc": [5, 6, 8, 13, 18], "tip": 5, "trick": [5, 11], "principl": 5, "someon": [5, 7], "bore": 5, "appreci": 5, "broadcast": [5, 10], "goal": 5, "concept": [5, 10, 11], "behind": 5, "backbon": 5, "forth": 5, "seen": [5, 11], "format": [5, 6, 8, 9, 10, 13, 18, 19, 20], "common": [5, 7, 9, 10, 11, 13, 14, 16, 18, 20], "bottleneck": [5, 14], "mess": [5, 12], "break": 5, "scale": [5, 6, 8, 14, 20], "least": [5, 12, 16], "bigger": 5, "pictur": 5, "off": [5, 11], "carefulli": [5, 9], "explain": [5, 10, 12], "super": [5, 11], "short": [5, 6, 9, 13, 16, 19], "ill": 5, "half": 5, "webpag": [5, 9], "reusabl": [5, 9], "sustain": 5, "parallel": [5, 6, 19], "materi": [5, 6, 13, 16], "exercis": [5, 6], "fourth": [5, 12], "admin": 5, "manag": [5, 6, 9, 11, 12, 14, 19], "conda": [5, 7], "prefix": [5, 12], "prepar": [5, 6, 9, 12], "acknowledg": 5, "hopefulli": 5, "tire": 5, "topic": [5, 9, 11], "involv": [5, 11, 14], "explicitli": [5, 19], "util": 6, "numer": [6, 12, 13], "broader": [6, 9], "expert": [6, 8], "found": [6, 9, 20], "youtub": 6, "playlist": 6, "prereq": 6, "30": [6, 19, 20], "min": [6, 13], "60": 6, "15": [6, 10, 11], "45": [6, 8], "guid": [6, 11, 13], "target": 6, "toward": [6, 12], "learner": [6, 14], "persona": 6, "particularli": [6, 9], "basi": 6, "excel": [6, 13], "glue": 6, "battl": [6, 18], "machin": [6, 12, 14], "deep": 6, "embrac": 6, "anybodi": 6, "bother": 6, "acquir": [6, 8], "licens": [6, 12], "extrem": 6, "todai": [6, 11], "certainli": 6, "critic": 6, "offload": 6, "heavi": [6, 11], "lift": [6, 11], "compil": [6, 9, 12, 14, 16, 18], "vectoriz": 6, "luck": 6, "albeit": 6, "matur": 6, "smaller": [6, 10, 11, 20], "suitabl": 6, "rust": [6, 14], "haskel": 6, "came": 6, "septemb": 6, "ignor": 6, "until": [6, 14, 16], "reduc": [6, 14, 15], "transit": 6, "plan": 6, "adopt": 6, "unsupport": 6, "defacto": 6, "activ": [6, 7, 8, 9, 12], "unmaintain": 6, "compat": [6, 9, 10], "jann": [6, 16], "blomqvist": 6, "redesign": 6, "radovan": 6, "bast": 6, "richard": [6, 16], "darst": 6, "ann": [6, 16], "fouilloux": 6, "thor": 6, "wikfeldt": 6, "tester": 6, "advisor": [6, 8], "enrico": 6, "glerean": 6, "carpentri": 6, "conduct": 6, "topic_fold": 6, "polici": 6, "analyt": [6, 14], "encc": 6, "hpda": 6, "logic": 6, "depth": 6, "3": [7, 12, 14, 15, 16, 18], "aanconda": 7, "init": 7, "proper": [7, 8, 11], "explor": [7, 8, 10, 11, 14], "lab": [7, 8, 9], "verifi": [7, 11], "1": [7, 15, 16], "hello": [7, 16], "world": [7, 14, 16], "portion": [7, 11], "encourag": 7, "vscode": 7, "launcher": 7, "arrow": 7, "ask": [7, 14, 20], "definit": [7, 11, 16, 20], "hour": 7, "narr": 8, "role": [8, 10], "interleav": 8, "tour": [8, 9, 20], "divid": [8, 10, 14, 15], "appear": 8, "primarili": 8, "bar": [8, 19], "style": [8, 19, 20], "previou": [8, 12, 15, 19], "sentenc": 8, "commonmark": 8, "keyboard": 8, "shortcut": 8, "enter": [8, 12, 13], "esc": 8, "ctrl": 8, "shift": [8, 13], "alt": 8, "cut": 8, "convent": 8, "properti": 8, "runtim": [8, 14, 16], "ipython": [8, 9, 14, 20], "seq": 8, "echo": 8, "appli": [8, 11, 13, 14, 15, 20], "Being": 8, "prototyp": [8, 19], "tend": 8, "phase": [8, 15], "stori": 8, "discoveri": 8, "gravit": 8, "wave": 8, "barrier": 8, "promot": 8, "modular": [8, 19], "hard": [8, 11, 19], "migrat": 8, "unit": 8, "nbval": 8, "control": [8, 10, 11, 14, 20], "nbdime": 8, "limit": [8, 13], "irreproduc": 8, "bunch": 8, "downsid": 8, "balanc": 8, "power": [8, 10, 13, 20], "beyond": [9, 14], "necessarili": 9, "fact": [9, 13, 20], "heard": 9, "quot": 9, "classifi": [9, 12], "articl": [9, 13, 18], "noth": [9, 12], "conform": 9, "math": [9, 11, 18], "higher": [9, 14], "mayavi": 9, "pil": 9, "manipul": [9, 11], "pillow": 9, "statsmodel": 9, "sympi": 9, "symbol": [9, 10], "network": 9, "hdf5": 9, "dateutil": 9, "pytz": 9, "arithmet": [9, 10], "timezon": 9, "databas": 9, "convers": [9, 19], "interpret": [9, 11, 14, 19], "hub": 9, "pytest": 9, "sphinx": 9, "spyder": 9, "pympi": 9, "messag": [9, 12, 14, 19], "mpi": 9, "job": [9, 14], "cython": [9, 14], "numba": [9, 14], "intern": [9, 10], "dask": 9, "joblib": [9, 14], "embarrassingli": [9, 14], "ipyparallel": 9, "numexpr": 9, "irrelev": 9, "pytorch": 9, "nltk": 9, "natur": [9, 10], "scikit": [9, 14, 17], "predict": 9, "thu": [9, 10, 13, 18], "contribut": [9, 13], "extend": [9, 10], "slowli": 9, "embed": 9, "primari": 9, "cffi": [9, 14], "ctype": [9, 14], "f2py": 9, "swig": 9, "boost": 9, "todo": 9, "mainstream": 9, "undetect": 9, "perman": 9, "host": [9, 12], "site": 9, "gitlab": 9, "bitbucket": 9, "dealt": 9, "bug": [9, 14, 19], "report": [9, 19], "citeabl": 9, "upcom": 9, "anyon": [9, 12], "seamlessli": 9, "detail": [9, 12, 13, 14, 18, 19], "except": 9, "seach": 10, "flexibl": 10, "asdf": 10, "background": [10, 14, 20], "500": 10, "empti": 10, "len": 10, "ndarrai": 10, "2x3": 10, "1x2": 10, "2x2": 10, "evenli": 10, "bool": [10, 16], "occas": 10, "special": [10, 11, 12, 13, 15, 18], "instruct": [10, 11, 12], "greatli": 10, "outperform": 10, "regular": 10, "unlik": [10, 13], "mathemat": [10, 11, 18], "clever": [10, 11], "cleverli": 10, "selector": 10, "benefit": [10, 19], "middl": [10, 11], "idx": 10, "criterion": 10, "three": [10, 13, 14, 20], "ref": 10, "smart": 10, "consist": [10, 11, 12], "expand": 10, "max": [10, 13, 20], "countless": 10, "invent": 10, "reli": 10, "bla": 10, "lapack": 10, "scientist": 10, "peculiar": 10, "underli": 11, "machineri": 11, "intend": 11, "audienc": 11, "amaz": 11, "impract": 11, "seriou": [11, 20], "yet": [11, 12], "dive": 11, "scene": 11, "serv": [11, 14], "travi": 11, "oliph": 11, "creator": [11, 12], "race": 11, "against": [11, 19], "contest": 11, "stdlib": 11, "stdio": 11, "n_element": 11, "argc": 11, "char": 11, "malloc": 11, "sizeof": 11, "rand_max": 11, "printf": 11, "outsourc": 11, "intel": 11, "deriv": [11, 19], "subprogram": 11, "1979": 11, "effort": [11, 14], "word": 11, "norm": 11, "pythagorean": 11, "theorem": 11, "ldot": 11, "naiv": 11, "decent": 11, "rng": [11, 13], "seed": 11, "l": [11, 16], "linalg": [11, 14], "expens": 11, "cheap": 11, "surprisingli": 11, "closer": 11, "datastructur": 11, "diagon": 11, "20": 11, "nbyte": 11, "nanosecond": 11, "1600": 11, "flat": 11, "fake": 11, "unravel": 11, "implic": 11, "skip": [11, 13], "13440": 11, "2688": 11, "448": 11, "byte": [11, 16], "ahead": 11, "precis": [11, 16], "boi": 11, "mysteri": 11, "160000": 11, "accomplish": 11, "80000": 11, "40_000": 11, "5_000": 11, "40000": 11, "laid": 11, "inevit": 11, "transposit": 11, "ntranspos": 11, "whenev": [11, 19], "construct": [11, 20], "stai": 11, "pointer": 11, "buffer": 11, "__array_interface__": 11, "virtu": 11, "offset": 11, "48": 11, "affect": 11, "attempt": 11, "succe": 11, "layout": [11, 13], "grow": 12, "cake": 12, "concret": 12, "lower_limit": 12, "upper_limit": 12, "__init__": [12, 16], "hold": 12, "arrang": 12, "setuptool": 12, "fh": 12, "long_descript": 12, "adapt": 12, "mynam": 12, "lastnam": 12, "author_email": 12, "long_description_content_typ": 12, "find_packag": 12, "osi": 12, "approv": 12, "mit": 12, "python_requir": 12, "pin": 12, "ana": 12, "twine": 12, "sdist": 12, "testpypi": 12, "dist": 12, "legaci": 12, "usernam": 12, "solut": 12, "achiev": [12, 19], "confus": 12, "trend": 12, "flit": 12, "simplest": 12, "runtest": 12, "toler": 12, "recip": [12, 20], "sh": 12, "bld": 12, "bat": 12, "anaconda3": 12, "win": 12, "py38_0": 12, "tar": 12, "bz2": 12, "sub": [12, 13], "platform": 12, "successfulli": 12, "anywher": 12, "forg": 12, "led": 12, "infrastructur": 12, "guidelin": 12, "respect": [12, 13, 19], "bioconda": 12, "bioinformat": 12, "brief": 13, "train": 13, "flash": 13, "thorough": 13, "cookbook": 13, "flavor": 13, "kaggl": 13, "competit": 13, "index_col": 13, "ticket": 13, "sibl": 13, "spous": 13, "512": 13, "38": 13, "didn": 13, "zorder": 13, "sharex": 13, "hit": 13, "offer": [13, 16], "mark": 13, "saw": 13, "tabular": 13, "compos": 13, "passang": 13, "datafil": 13, "iat": 13, "lam": 13, "ali": 13, "42": [13, 16], "is_passeng": 13, "70": 13, "margaret": 13, "nan": 13, "forward": 13, "backward": 13, "isna": 13, "mask": 13, "dropna": 13, "cabin": 13, "fillna": 13, "ffill": 13, "straightforward": 13, "thank": 13, "untidi": 13, "1500": 13, "runner": [13, 14], "400": 13, "800": 13, "128": 13, "1200": 13, "192": 13, "240": 13, "80": 13, "160": 13, "300": 13, "288": 13, "pair": [13, 20], "melt": 13, "id_var": 13, "value_var": 13, "var_nam": 13, "value_nam": 13, "filter": 13, "aggreg": 13, "model": [13, 14], "relationship": 13, "opposit": 13, "exposit": [13, 14], "read_excel": 13, "to_excel": 13, "scratch": 13, "randn": 13, "abcd": 13, "dog": 13, "cat": [13, 20], "int32": 13, "sub1": 13, "sub2": 13, "sub3": 13, "concat": 13, "merg": 13, "act": 13, "sql": 13, "athlet": 13, "21": 13, "annot": 13, "entri": [13, 19], "dave": 13, "women": 13, "children": 13, "child": 13, "younger": 13, "sex": 13, "chose": 13, "summar": 13, "cumsum": 13, "median": 13, "skew": 13, "var": 13, "wouldn": 13, "abil": [13, 20], "organis": 13, "nobelpr": 13, "unfortun": 13, "di": 13, "messi": 13, "weekdai": 13, "approxim": [13, 14, 20], "boxplot": 13, "eval": 13, "nrow": 13, "ncol": 13, "randomst": 13, "df1": 13, "df2": 13, "df3": 13, "df4": 13, "80m": 13, "40m": 13, "fibo": 13, "overhead": 13, "recurs": 13, "rais": 13, "notimplementederror": 13, "elif": [13, 16], "memo": 13, "rabbit": 13, "99": 13, "functool": 13, "lru_cach": 13, "fib": 13, "precisis": 13, "cap": 13, "unbound": 13, "erron": 13, "processor": 14, "mechan": 14, "profil": 14, "spot": 14, "acceler": 14, "hardwar": 14, "supercomput": 14, "synchron": 14, "openmp": 14, "segment": 14, "wrong": 14, "fascin": 14, "invest": 14, "video": 14, "raymond": 14, "hetting": 14, "entertain": 14, "lock": 14, "glanc": 14, "circumv": [14, 16], "symmetr": 14, "invers": 14, "4000": 14, "time_start": 14, "inv": 14, "time_end": 14, "invert": 14, "forc": [14, 19], "omp_num_thread": 14, "mkl_num_thread": 14, "significantli": 14, "shouldn": 14, "unix": 14, "embark": 14, "oppos": 14, "map": [14, 15], "paradigm": 14, "36": 14, "equival": [14, 20], "fortun": 14, "multiprocesss": 14, "introductori": 14, "rantahar": 14, "pdc": 14, "blog": 14, "gentl": 14, "kth": 14, "se": 14, "08": 14, "comm_world": 14, "get_siz": 14, "get_rank": 14, "t0": 14, "perf_count": 14, "pi_estim": 14, "nnumber": 14, "workaround": 14, "foreign": 14, "primit": 14, "pybind11": 14, "iso_c_bind": 14, "pyo3": 14, "rout": 14, "Of": 14, "overcom": 14, "ml": 14, "chunk": 14, "lazi": 14, "proce": 14, "stream": 14, "fashion": 14, "da": 14, "redund": 14, "concurr": [14, 19], "safe": 14, "scalabl": 14, "highli": 14, "luckili": 14, "371": 15, "198": 15, "\u00b5": 15, "142308": 15, "235": 15, "n_sum": 15, "n_inside_circle_sum": 15, "139152": 15, "385": 15, "61": 15, "timeitresult": 15, "14264": 15, "regardless": 15, "perfectli": 16, "engag": 16, "3j": 16, "unicod": 16, "q": 16, "capabl": 16, "123": 16, "456": 16, "cherri": 16, "dict": [16, 19, 20], "met": 16, "sequenc": 16, "iter": 16, "enumer": 16, "ii": 16, "keyword": [16, 20], "self": 16, "_name": 16, "strongli": [16, 19], "dynam": 16, "strong": 16, "roughli": 16, "invok": 16, "behavior": 16, "redefin": 16, "jargon": 16, "associ": 16, "rvalu": 16, "lvalu": 16, "reifi": 16, "datacamp": 17, "briefli": 18, "bessel": 18, "gamma": 18, "interpol": 18, "fourier": 18, "transform": 18, "fft": 18, "signal": 18, "market": 18, "mat": 18, "ridicul": 18, "standpoint": 18, "unknown": 18, "somedai": 18, "eventu": 18, "admit": 18, "streamlin": 19, "hardli": 19, "willing": 19, "suppos": 19, "rerun": 19, "parameter": 19, "papermil": 19, "attract": 19, "soon": 19, "your_notebook_nam": 19, "callabl": 19, "hpc": 19, "odifi": 19, "startup": 19, "append": [19, 20], "output_file_nam": 19, "31": 19, "spring_in_tapiola": 19, "brittl": 19, "robust": 19, "doctopt": 19, "detect": 19, "flag": 19, "2000": 19, "metavar": 19, "subject": [19, 20], "birth": 19, "birthdai": 19, "exit": 19, "weather_tapiola": 19, "temperature_tapiola": 19, "temperature_tapiola_dec": 19, "temperature_tapiola_feb": 19, "temperature_cairo": 19, "pattern": 19, "got": 19, "rain_in_tapiola": 19, "rainfal": 19, "rrr": 19, "scroll": 19, "inconveni": 19, "unnecessari": 19, "precipit": 19, "translat": 19, "rain_in_cairo": 19, "jupytext": 19, "emb": 20, "readthedoc": 20, "latest": 20, "homepag": 20, "ifram": 20, "requests_documentation_url": 20, "connect": 20, "cycl": 20, "authent": 20, "apipheni": 20, "catfact": 20, "ninja": 20, "endpoint": 20, "response_cont": 20, "bird": 20, "biolog": 20, "clock": 20, "angl": 20, "sun": 20, "earth": 20, "magnet": 20, "owner": 20, "243": 20, "decod": 20, "response_json": 20, "beforehand": 20, "finnish": 20, "hipolab": 20, "finland": 20, "domain": 20, "abo": 20, "web_pag": 20, "alpha_two_cod": 20, "akademi": 20, "provinc": 20, "cou": 20, "central": 20, "ostrobothnia": 20, "param": 20, "prone": 20, "cook": 20, "6553978": 20, "narrow": 20, "khan": 20, "academi": 20, "khanacademi": 20, "7154873": 20, "minpric": 20, "maxpric": 20, "6081071": 20, "deflat": 20, "aliv": 20, "cowboi": 20, "charset": 20, "173": 20, "etag": 20, "zzmnm3omcrctfbs6": 20, "jmv4buyrgo": 20, "wed": 20, "nov": 20, "2022": 20, "22": 20, "gmt": 20, "vegur": 20, "br": 20, "restrict": 20, "imgur": 20, "doctyp": 20, "equiv": 20, "viewport": 20, "width": 20, "devic": 20, "css": 20, "bodi": 20, "f0f0f2": 20, "margin": 20, "pad": 20, "ui": 20, "blinkmacsystemfont": 20, "sego": 20, "san": 20, "helvetica": 20, "neue": 20, "arial": 20, "serif": 20, "div": 20, "600px": 20, "5em": 20, "auto": 20, "2em": 20, "fdfdff": 20, "radiu": 20, "box": 20, "shadow": 20, "2px": 20, "3px": 20, "7px": 20, "rgba": 20, "02": 20, "38488f": 20, "decor": 20, "media": 20, "700px": 20, "h1": 20, "literatur": 20, "prior": 20, "coordin": 20, "href": 20, "iana": 20, "bs4": 20, "beautifulsoup": 20, "find_al": 20, "get_text": 20, "longitud": 20, "jsonlin": 20, "excess": 20, "hundr": 20, "thousand": 20, "writer": 20, "jsonl": 20, "sleep": 20, "reader": 20, "obj": 20, "speci": 20, "housecat": 20, "africa": 20, "foot": 20, "feli": 20, "nigrip": 20, "Its": 20, "weight": 20, "pound": 20, "162": 20, "bitten": 20, "annual": 20, "treat": 20, "kitten": 20, "stage": 20, "trait": 20, "109": 20}, "objects": {}, "objtypes": {}, "objnames": {}, "titleterms": {"binder": [0, 4], "question": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "object": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 18, 19, 20], "why": [0, 2, 6, 8, 19], "i": [0, 1, 6, 8, 9, 10], "sometim": 0, "enough": 0, "share": [0, 12], "your": [0, 3, 4, 9], "code": [0, 8, 9], "exercis": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "1": [0, 1, 2, 3, 4, 8, 9, 10, 11, 12, 13, 14, 18, 19, 20], "10": [0, 4], "min": [0, 2, 3, 4], "comput": [0, 6, 9], "environ": [0, 3, 7], "demo": [0, 4, 12], "make": [0, 4], "notebook": [0, 4, 19], "reproduc": [0, 2, 4], "anyon": [0, 4], "15": [0, 2, 3, 4], "how": [0, 3], "can": [0, 1, 3, 11], "get": [0, 2, 8, 13], "doi": 0, "from": [0, 3, 4, 12, 14, 19, 20], "zenodo": 0, "3": [0, 1, 2, 3, 4, 6, 8, 10, 11, 13, 19, 20], "option": [0, 3, 4, 7, 14, 19], "creat": [0, 3, 10], "link": [0, 4, 20], "4": [0, 1, 3, 4, 10], "keypoint": [0, 1, 2, 3, 8, 9, 10, 11, 12, 13, 14, 16, 18, 20], "data": [1, 2, 4, 9, 11, 13, 20], "format": [1, 4], "panda": [1, 4, 13], "numpi": [1, 4, 10, 11], "what": [1, 8, 9, 10, 13, 18], "type": [1, 10, 16], "v": [1, 3, 4, 6], "structur": [1, 16], "file": [1, 3, 7, 19], "look": 1, "store": 1, "arbitrari": 1, "python": [1, 3, 4, 6, 7, 9, 12, 15, 16, 19, 20], "pickl": 1, "kei": 1, "featur": 1, "solut": [1, 2, 4, 8, 10, 11, 13, 14, 15, 18, 19], "tidi": [1, 13], "csv": 1, "comma": 1, "separ": 1, "valu": 1, "reduc": 1, "precis": 1, "feather": 1, "requir": [1, 3, 7, 20], "addit": [1, 10], "packag": [1, 3, 4, 9, 12], "parquet": 1, "2": [1, 2, 3, 4, 6, 8, 9, 10, 11, 13, 14, 18, 19, 20], "arrai": [1, 10], "npy": 1, "hdf5": 1, "hierarch": 1, "version": [1, 3], "5": [1, 4, 10], "netcdf4": 1, "network": 1, "common": 1, "form": 1, "other": [1, 7, 9, 10, 14], "json": 1, "javascript": 1, "notat": 1, "excel": 1, "graph": 1, "adjenc": 1, "list": [1, 4, 7, 13, 19], "gt": 1, "graphml": 1, "etc": 1, "benefit": 1, "binari": 1, "thing": [1, 11], "rememb": 1, "see": [1, 3, 6, 7, 8, 9, 10, 11, 14, 18], "also": [1, 3, 6, 7, 8, 9, 10, 11, 14, 18], "visual": [2, 4], "matplotlib": [2, 4], "repeat": 2, "ar": 2, "we": 2, "start": [2, 8], "extend": [2, 4], "previou": [2, 4], "exampl": [2, 4, 11, 14], "color": 2, "ha": 2, "two": 2, "differ": [2, 4, 20], "interfac": [2, 9], "do": [2, 3, 15], "emphas": 2, "thi": 2, "style": 2, "custom": [2, 4], "plot": [2, 4, 9], "log": [2, 4], "scale": [2, 4], "prepar": [2, 4], "public": [2, 3, 4], "adapt": [2, 4], "galleri": [2, 4], "an": [2, 4, 7, 10, 11], "explor": [2, 4, 13], "discuss": [2, 19], "depend": [3, 4], "manag": [3, 4], "you": 3, "track": 3, "project": [3, 12], "pypi": [3, 12], "The": [3, 9, 11], "index": [3, 10], "ana": 3, "conda": [3, 4, 12], "anaconda": [3, 4], "miniconda": [3, 4, 7], "mamba": [3, 4], "cloud": [3, 4], "forg": [3, 4], "isol": 3, "activ": [3, 4, 20], "versu": [3, 4, 11], "sourc": [3, 4], "remark": [3, 4, 12], "problem": 3, "might": 3, "happen": 3, "manual": 3, "instal": [3, 7, 12], "record": 3, "put": 3, "too": 3, "strict": 3, "counter": 3, "product": 3, "hint": 3, "updat": 3, "commun": 3, "part": 3, "report": 3, "thesi": 3, "pin": 3, "creator": 3, "full": 4, "jupyt": [4, 8, 19], "advanc": [4, 7, 10, 11, 14, 20], "datafram": [4, 13], "analyz": [4, 13], "titan": [4, 13], "passeng": [4, 13], "dataset": [4, 13], "nobel": [4, 13], "prize": [4, 13], "script": [4, 19], "web": [4, 20], "api": [4, 20], "webapi": [4, 20], "request": [4, 20], "suggest": [4, 20], "bore": [4, 20], "examin": [4, 20], "respons": [4, 20], "header": [4, 20], "scrape": [4, 20], "webpag": [4, 20], "scipi": [4, 9, 18], "librari": [4, 9, 11], "ecosystem": [4, 9], "work": [4, 9, 13], "evalu": [4, 9], "parallel": [4, 9, 14, 15], "program": [4, 14], "multiprocess": [4, 14, 15], "run": [4, 8, 14], "cluster": [4, 14], "mpi": [4, 14], "dask": [4, 14], "instructor": 5, "": [5, 9, 13, 18], "guid": 5, "learner": 5, "persona": 5, "about": 5, "each": 5, "section": 5, "scientif": 6, "attend": 6, "cours": 6, "22": 6, "25": 6, "novemb": 6, "2022": 6, "prerequisit": [6, 12], "video": [6, 7], "refer": [6, 17], "who": 6, "motiv": 6, "credit": 6, "softwar": 7, "gener": 7, "tool": [7, 9, 12], "instruct": 7, "jupyterlab": 7, "verif": 7, "watch": 7, "text": 7, "editor": 7, "command": [7, 19], "line": [7, 19], "wai": 7, "access": 7, "zoom": 7, "need": 7, "help": [7, 13], "glossari": 9, "core": 9, "numer": [9, 18], "analysi": 9, "import": 9, "interact": 9, "human": 9, "speed": 9, "up": [9, 20], "machin": 9, "learn": 9, "connect": 9, "languag": [9, 14], "reus": 9, "reuseabl": 9, "next": 9, "math": 10, "vector": 10, "slice": 10, "oper": 10, "linear": 10, "algebra": 10, "realli": 11, "fast": 11, "behind": 11, "curtain": 11, "mkl": 11, "bla": 11, "tri": 11, "avoid": 11, "copi": 11, "matrix": 11, "transpos": 11, "ndarrai": 11, "expos": 11, "stride": 11, "anoth": 11, "reshap": 11, "A": 11, "view": 11, "organ": 12, "test": 12, "local": 12, "pip": 12, "via": 12, "simplifi": 12, "build": 12, "skeleton": 12, "locat": 12, "scratch": 12, "publish": 12, "time": 13, "seri": 13, "superpow": 13, "beyond": 13, "basic": 13, "mode": 14, "multithread": [14, 15], "gil": 14, "coupl": 14, "task": 14, "queue": 14, "org": 14, "thread": 15, "futur": 15, "idea": 15, "introduct": 16, "scalar": 16, "collect": 16, "control": 16, "function": 16, "class": 16, "system": 16, "quick": 17, "us": [18, 19], "integr": 18, "spars": 18, "matric": 18, "save": [19, 20], "argument": 19, "sy": 19, "argv": 19, "pars": 19, "argpars": 19, "load": 19, "larger": 19, "config": 19, "further": 19, "read": 19, "retriev": 20, "which": 20, "paramet": 20, "after": 20, "disk": 20, "wrap": 20}, "envversion": {"sphinx.domains.c": 2, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 8, "sphinx.domains.index": 1, "sphinx.domains.javascript": 2, "sphinx.domains.math": 2, "sphinx.domains.python": 3, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.todo": 2, "sphinx.ext.intersphinx": 1, "sphinx": 57}, "alltitles": {"Binder": [[0, "binder"], [4, "binder"]], "Questions": [[0, "questions-0"], [1, "questions-0"], [2, "questions-0"], [3, "questions-0"], [8, "questions-0"], [9, "questions-0"], [10, "questions-0"], [11, "questions-0"], [12, "questions-0"], [13, "questions-0"], [14, "questions-0"], [16, "questions-0"], [18, "questions-0"], [19, "questions-0"], [20, "questions-0"]], "Objectives": [[0, "objectives-0"], [1, "objectives-0"], [2, "objectives-0"], [3, "objectives-0"], [8, "objectives-0"], [9, "objectives-0"], [10, "objectives-0"], [11, "objectives-0"], [12, "objectives-0"], [13, "objectives-0"], [14, "objectives-0"], [16, "objectives-0"], [18, "objectives-0"], [19, "objectives-0"], [20, "objectives-0"]], "Why is it sometimes not enough to share your code?": [[0, "why-is-it-sometimes-not-enough-to-share-your-code"]], "Exercise 1": [[0, "exercise-1"], [1, "exercise-1"], [11, "exercise-1"]], "Binder-1 (10 min)": [[0, "exercise-0"], [4, "exercise-0"]], "Sharing a computing environment with Binder": [[0, "sharing-a-computing-environment-with-binder"]], "Binder exercise/demo": [[0, "binder-exercise-demo"]], "Exercise/demo: Making your notebooks reproducible by anyone (15 min)": [[0, "exercise-1"], [4, "exercise-1"]], "How can I get a DOI from Zenodo?": [[0, "how-can-i-get-a-doi-from-zenodo"]], "Binder-3 (optional)": [[0, "exercise-2"], [4, "exercise-2"]], "Create a Binder link for your Zenodo DOI": [[0, "create-a-binder-link-for-your-zenodo-doi"]], "Binder-4 (10 min)": [[0, "exercise-3"], [4, "exercise-3"]], "Keypoints": [[0, "keypoints-0"], [1, "keypoints-0"], [2, "keypoints-0"], [3, "keypoints-0"], [8, "keypoints-0"], [9, "keypoints-0"], [10, "keypoints-0"], [11, "keypoints-0"], [12, "keypoints-0"], [13, "keypoints-0"], [14, "keypoints-0"], [16, "keypoints-0"], [18, "keypoints-0"], [20, "keypoints-0"]], "Data formats with Pandas and Numpy": [[1, "data-formats-with-pandas-and-numpy"], [4, "data-formats-with-pandas-and-numpy"]], "What is a data format?": [[1, "what-is-a-data-format"]], "Data type vs. data structure vs. file format": [[1, null]], "What to look for in a file format?": [[1, "what-to-look-for-in-a-file-format"]], "Storing arbitrary Python objects": [[1, "storing-arbitrary-python-objects"]], "Pickle": [[1, "pickle"]], "Key features": [[1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null], [1, null]], "Exercise": [[1, "exercise-0"], [1, "exercise-1"], [1, "exercise-2"], [4, "exercise-0"], [4, "exercise-1"], [4, "exercise-2"], [4, "exercise-0"], [4, "exercise-1"], [18, "exercise-0"], [18, "exercise-1"]], "Solution": [[1, "solution-0"], [1, "solution-1"], [1, "solution-2"], [2, "solution-0"], [2, "solution-1"], [2, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [4, "solution-0"], [4, "solution-1"], [4, "solution-2"], [13, "solution-0"], [13, "solution-1"], [13, "solution-2"], [14, "solution-0"], [14, "solution-1"], [14, "solution-2"], [18, "solution-0"], [18, "solution-1"], [19, "solution-0"], [19, "solution-1"]], "Storing tidy data": [[1, "storing-tidy-data"]], "CSV (comma-separated values)": [[1, "csv-comma-separated-values"]], "Storing data in CSVs can reduce data precision": [[1, null]], "Feather": [[1, "feather"]], "Requires additional packages": [[1, null], [1, null], [1, null], [1, null]], "Parquet": [[1, "parquet"]], "Exercise 2": [[1, "exercise-2"], [11, "exercise-2"]], "Storing array data": [[1, "storing-array-data"]], "npy (numpy array format)": [[1, "npy-numpy-array-format"]], "HDF5 (Hierarchical Data Format version 5)": [[1, "hdf5-hierarchical-data-format-version-5"]], "NetCDF4 (Network Common Data Form version 4)": [[1, "netcdf4-network-common-data-form-version-4"]], "Exercise 3": [[1, "exercise-3"]], "Other file formats": [[1, "other-file-formats"]], "JSON (JavaScript Object Notation)": [[1, "json-javascript-object-notation"]], "Excel": [[1, "excel"]], "Graph formats (adjency lists, gt, GraphML etc.)": [[1, "graph-formats-adjency-lists-gt-graphml-etc"]], "Benefits of binary file formats": [[1, "benefits-of-binary-file-formats"]], "Things to remember": [[1, "things-to-remember"]], "See also": [[1, "see-also"], [3, "see-also"], [6, "see-also"], [7, "see-also"], [8, "see-also"], [9, "see-also"], [10, "see-also"], [11, "see-also"], [14, "see-also"], [18, "see-also"]], "Data visualization with Matplotlib": [[2, "data-visualization-with-matplotlib"], [4, "data-visualization-with-matplotlib"]], "Repeatability/reproducibility": [[2, "repeatability-reproducibility"]], "Why are we starting with Matplotlib?": [[2, "why-are-we-starting-with-matplotlib"]], "Getting started with Matplotlib": [[2, "getting-started-with-matplotlib"]], "Exercise: Matplotlib": [[2, "exercise-matplotlib"]], "Exercise Matplotlib-1: extend the previous example (15 min)": [[2, "exercise-0"], [4, "exercise-0"]], "Why these colors?": [[2, "discussion-0"]], "Matplotlib has two different interfaces": [[2, "matplotlib-has-two-different-interfaces"]], "Why do we emphasize this?": [[2, "discussion-1"]], "Styling and customizing plots": [[2, "styling-and-customizing-plots"]], "Exercises: Styling and customization": [[2, "exercises-styling-and-customization"]], "Exercise Customization-1: log scale in Matplotlib (15 min)": [[2, "exercise-1"], [4, "exercise-1"]], "Exercise Customization-2: preparing a plot for publication (15 min)": [[2, "exercise-2"], [4, "exercise-2"]], "Exercise Customization-3: adapting a gallery example": [[2, "exercise-3"], [4, "exercise-3"]], "An example exploration": [[2, "solution-3"], [4, "solution-3"]], "Discussion": [[2, "discussion-2"], [19, "discussion-0"], [19, "discussion-1"]], "Dependency management": [[3, "dependency-management"], [4, "dependency-management"]], "How do you track dependencies of your project?": [[3, "how-do-you-track-dependencies-of-your-project"]], "Exercises 1": [[3, "exercises-1"], [8, "exercises-1"], [10, "exercises-1"], [12, "exercises-1"], [13, "exercises-1"], [19, "exercises-1"], [20, "exercises-1"]], "Dependencies-1 (15 min)": [[3, "exercise-0"], [4, "exercise-0"]], "PyPI (The Python Package Index) and (Ana)conda": [[3, "pypi-the-python-package-index-and-ana-conda"]], "PyPI": [[3, null]], "Conda": [[3, null]], "Anaconda vs. miniconda vs. conda vs. mamba vs. Anaconda Cloud vs. conda-forge": [[3, "solution-0"], [4, "solution-0"]], "Creating isolated environments": [[3, "creating-isolated-environments"]], "Exercises 2": [[3, "exercises-2"], [8, "exercises-2"], [10, "exercises-2"], [13, "exercises-2"], [19, "exercises-2"], [20, "exercises-2"]], "Dependencies-2 (15 min)": [[3, "exercise-1"], [4, "exercise-1"]], "conda activate versus source activate": [[3, "callout-0"], [4, "callout-0"]], "Remark": [[3, "callout-1"], [4, "callout-1"], [12, "callout-1"]], "Exercises 3": [[3, "exercises-3"], [8, "exercises-3"], [10, "exercises-3"], [11, "exercises-3"], [13, "exercises-3"], [20, "exercises-3"]], "Dependencies-3 (15 min, optional)": [[3, "exercise-2"], [4, "exercise-2"]], "Problems that might happen with manual installation": [[3, "problems-that-might-happen-with-manual-installation"]], "Recording dependencies": [[3, "recording-dependencies"]], "Putting too strict requirements can be counter-productive": [[3, null]], "Dependencies 4": [[3, "dependencies-4"]], "Dependencies-4 (15 min)": [[3, "exercise-3"], [4, "exercise-3"]], "Hint: Updating packages from dependency files": [[3, null]], "How to communicate the dependencies as part of a report/thesis/publication": [[3, "how-to-communicate-the-dependencies-as-part-of-a-report-thesis-publication"]], "Version pinning for package creators": [[3, "version-pinning-for-package-creators"]], "List of exercises": [[4, "list-of-exercises"]], "Full list": [[4, "full-list"]], "Jupyter": [[4, "jupyter"], [8, "jupyter"]], "Exercises: Jupyter-1": [[4, "exercise-0"], [8, "exercise-0"]], "Exercises: Jupyter-2": [[4, "exercise-1"], [8, "exercise-1"]], "Solutions: Jupyter-2": [[4, "solution-0"], [8, "solution-0"]], "Exercises: Jupyter-3": [[4, "exercise-2"], [8, "exercise-2"]], "NumPy": [[4, "numpy"], [10, "numpy"]], "Exercises: Numpy-1": [[4, "exercise-0"], [10, "exercise-0"]], "Solutions: Numpy-1": [[4, "solution-0"], [10, "solution-0"]], "Exercises: Numpy-2": [[4, "exercise-1"], [10, "exercise-1"]], "Solutions: Numpy-2": [[4, "solution-1"], [10, "solution-1"]], "Exercise: Numpy-3": [[4, "exercise-2"], [10, "exercise-2"]], "Solution: Numpy-3": [[4, "solution-2"], [10, "solution-2"]], "Exercises: Numpy-4": [[4, "exercise-3"], [10, "exercise-3"]], "Solution: Numpy-4": [[4, "solution-3"], [10, "solution-3"]], "Numpy-5": [[4, "exercise-4"], [10, "exercise-4"]], "Solution Numpy-5": [[4, "solution-4"], [10, "solution-4"]], "Advanced NumPy": [[4, "advanced-numpy"], [11, "advanced-numpy"]], "Exercises: Numpy-Advanced-1": [[4, "exercise-0"], [11, "exercise-0"]], "Solutions: Numpy-Advanced-1": [[4, "solution-0"], [11, "solution-0"]], "Exercises: Numpy-Advanced-2": [[4, "exercise-1"], [11, "exercise-1"]], "Solutions: Numpy-Advanced-2": [[4, "solution-1"], [11, "solution-1"]], "Exercises: Numpy-Advanced-3": [[4, "exercise-2"], [11, "exercise-2"]], "Solutions: Numpy-Advanced-3": [[4, "solution-2"], [11, "solution-2"]], "Pandas": [[4, "pandas"], [13, "pandas"]], "Exploring dataframes": [[4, "exercise-0"], [13, "exercise-0"]], "Analyze the Titanic passenger list dataset": [[4, "exercise-1"], [13, "exercise-1"]], "Analyze the Nobel prize dataset": [[4, "exercise-2"], [13, "exercise-2"]], "Scripts": [[4, "scripts"], [19, "scripts"]], "Scripts-1": [[4, "exercise-0"], [19, "exercise-0"]], "Scripts-2": [[4, "exercise-1"], [19, "exercise-1"]], "Scripts-3": [[4, "exercise-2"], [19, "exercise-2"]], "Web APIs with Python": [[4, "web-apis-with-python"], [20, "web-apis-with-python"]], "Exercise WebAPIs-1: Request different activity suggestions from the Bored API": [[4, "exercise-0"], [20, "exercise-0"]], "Exercise WebAPIs-2: Examine request and response headers": [[4, "exercise-1"], [20, "exercise-1"]], "Exercise WebAPIs-3: Scrape links from a webpage (Advanced)": [[4, "exercise-2"], [20, "exercise-2"]], "SciPy": [[4, "scipy"], [18, "scipy"]], "Library ecosystem": [[4, "library-ecosystem"], [9, "library-ecosystem"]], "Libraries 1.1: Libraries in your work": [[4, "exercise-0"], [9, "exercise-0"]], "Libraries 1.1": [[4, "solution-0"], [9, "solution-0"]], "Libraries 1.2: Evaluating packages": [[4, "exercise-1"], [9, "exercise-1"]], "Libraries 1.2": [[4, "solution-1"], [9, "solution-1"]], "Parallel programming": [[4, "parallel-programming"], [14, "parallel-programming"]], "Parallel-1, multiprocessing": [[4, "exercise-0"], [14, "exercise-0"]], "(advanced) Parallel-2 Running on a cluster": [[4, "exercise-1"], [14, "exercise-1"]], "Parallel-2, MPI": [[4, "exercise-2"], [14, "exercise-2"]], "Dask-Examples (optional)": [[4, "exercise-3"], [14, "exercise-3"]], "Packaging": [[4, "packaging"], [12, "packaging"]], "Packaging-1": [[4, "exercise-0"], [12, "exercise-0"]], "Instructor\u2019s guide": [[5, "instructor-s-guide"]], "Learner personas": [[5, "learner-personas"]], "About each section": [[5, "about-each-section"]], "Python for Scientific Computing": [[6, "python-for-scientific-computing"]], "Attending the course 22-25.november.2022?": [[6, null]], "Prerequisites": [[6, "prerequisites-0"], [12, "callout-0"]], "Videos": [[6, null]], "Reference": [[6, null]], "Who is the course for?": [[6, "who-is-the-course-for"]], "Motivation": [[6, "motivation"]], "Why Python": [[6, "why-python"]], "Why not Python for Scientific Computing": [[6, "why-not-python-for-scientific-computing"]], "Python 2 vs Python 3": [[6, "python-2-vs-python-3"]], "Credits": [[6, "credits"]], "Software installation": [[7, "software-installation"]], "Generic list of tools required": [[7, "generic-list-of-tools-required"]], "Generic instructions with miniconda and an environment file (advanced)": [[7, null]], "Python": [[7, "python"]], "Other options": [[7, null]], "JupyterLab": [[7, "jupyterlab"]], "Verification of Python and JupyterLab": [[7, "verification-of-python-and-jupyterlab"]], "Watch the video": [[7, null]], "Text editor": [[7, "text-editor"]], "Other editors": [[7, null]], "Command line": [[7, "command-line"]], "Other ways to access the command line": [[7, null]], "Verification of the command line": [[7, "verification-of-the-command-line"]], "Zoom": [[7, "zoom"]], "Need help?": [[7, "need-help"]], "What is Jupyter?": [[8, "what-is-jupyter"]], "Getting started with Jupyter": [[8, "getting-started-with-jupyter"]], "Running code in Jupyter": [[8, "running-code-in-jupyter"]], "Why Jupyter?": [[8, "why-jupyter"]], "Why not Jupyter?": [[8, "why-not-jupyter"]], "Glossary": [[9, "glossary"]], "The Python/SciPy ecosystem": [[9, "the-python-scipy-ecosystem"]], "Core numerics libraries": [[9, "core-numerics-libraries"]], "Plotting": [[9, "plotting"]], "Data analysis and other important core packages": [[9, "data-analysis-and-other-important-core-packages"]], "Interactive computing and human interface": [[9, "interactive-computing-and-human-interface"]], "Speeding up code and parallelism": [[9, "speeding-up-code-and-parallelism"]], "Machine learning": [[9, "machine-learning"]], "Connecting Python to other languages": [[9, "connecting-python-to-other-languages"]], "Tools for interfacing with other languages": [[9, "tools-for-interfacing-with-other-languages"]], "Evaluating Python packages for reuse": [[9, "evaluating-python-packages-for-reuse"]], "Is your work reuseable?": [[9, "is-your-work-reuseable"]], "What\u2019s next?": [[9, "what-s-next"]], "Exercises": [[9, "exercises"]], "What is an array?": [[10, "what-is-an-array"]], "Creating arrays": [[10, "creating-arrays"]], "Array maths and vectorization": [[10, "array-maths-and-vectorization"]], "Indexing and Slicing": [[10, "indexing-and-slicing"]], "Types of operations": [[10, "types-of-operations"]], "Exercises 4": [[10, "exercises-4"]], "Linear algebra and other advanced math": [[10, "linear-algebra-and-other-advanced-math"]], "Additional exercises": [[10, "additional-exercises"]], "NumPy can be really fast": [[11, "numpy-can-be-really-fast"]], "The libraries behind the curtain: MKL and BLAS": [[11, "the-libraries-behind-the-curtain-mkl-and-blas"]], "NumPy tries to avoid copying data": [[11, "numpy-tries-to-avoid-copying-data"]], "An example: matrix transpose": [[11, "an-example-matrix-transpose"]], "The ndarray exposed": [[11, "the-ndarray-exposed"]], "Strides": [[11, "strides"]], "Another example: reshaping": [[11, "another-example-reshaping"]], "A fast thing + a fast thing = a fast thing?": [[11, "a-fast-thing-a-fast-thing-a-fast-thing"]], "Copy versus view": [[11, "copy-versus-view"]], "Organizing Python projects": [[12, "organizing-python-projects"]], "Testing a local pip install": [[12, "testing-a-local-pip-install"]], "Sharing packages via PyPI": [[12, "sharing-packages-via-pypi"]], "Tools that simplify sharing via PyPI": [[12, "tools-that-simplify-sharing-via-pypi"]], "Building a conda package and share it": [[12, "building-a-conda-package-and-share-it"]], "Demo": [[12, "demo-0"]], "Building a python package with conda skeleton pypi": [[12, "building-a-python-package-with-conda-skeleton-pypi"]], "Conda package location": [[12, "callout-2"]], "Building a conda package from scratch": [[12, "callout-3"]], "Publishing a python package": [[12, "publishing-a-python-package"]], "Getting help": [[13, "callout-0"]], "What\u2019s in a dataframe?": [[13, "what-s-in-a-dataframe"]], "Tidy data": [[13, "tidy-data"]], "Working with dataframes": [[13, "working-with-dataframes"]], "Time series superpowers": [[13, "time-series-superpowers"]], "Beyond the basics": [[13, "beyond-the-basics"]], "Modes of parallelism": [[14, "modes-of-parallelism"]], "Multithreading and the GIL": [[14, "multithreading-and-the-gil"]], "multiprocessing": [[14, "multiprocessing"]], "Exercises, multiprocessing": [[14, "exercises-multiprocessing"]], "MPI": [[14, "mpi"]], "Exercises, MPI": [[14, "exercises-mpi"]], "Coupling to other languages": [[14, "coupling-to-other-languages"]], "Dask and task queues": [[14, "dask-and-task-queues"]], "Dask": [[14, "dask"]], "Example from dask.org": [[14, "discussion-0"]], "Exercises, Dask": [[14, "exercises-dask"]], "Task queues": [[14, "task-queues"]], "Python multithreading solution": [[15, "python-multithreading-solution"]], "Do it in parallel with multiprocessing": [[15, "do-it-in-parallel-with-multiprocessing"]], "Do it in \u201cparallel\u201d with threads": [[15, "do-it-in-parallel-with-threads"]], "Future ideas": [[15, "future-ideas"]], "Introduction to Python": [[16, "introduction-to-python"]], "Scalars": [[16, "scalars"]], "Collections": [[16, "collections"]], "Control structures": [[16, "control-structures"]], "Functions and classes": [[16, "functions-and-classes"]], "Python type system": [[16, "python-type-system"]], "Quick reference": [[17, "quick-reference"]], "What\u2019s in SciPy?": [[18, "what-s-in-scipy"]], "Exercises: use SciPy": [[18, "exercises-use-scipy"]], "1: Numerical integration": [[18, "numerical-integration"]], "2: Sparse matrices": [[18, "sparse-matrices"]], "Why scripts?": [[19, "why-scripts"]], "From Jupyter notebooks to Python scripts": [[19, "from-jupyter-notebooks-to-python-scripts"]], "Save as Python script": [[19, "save-as-python-script"]], "Command line arguments with sys.argv": [[19, "command-line-arguments-with-sys-argv"]], "Parsing command line arguments with argparse": [[19, "parsing-command-line-arguments-with-argparse"]], "Load larger option lists using config files": [[19, "load-larger-option-lists-using-config-files"]], "Exercises 3 (optional)": [[19, "exercises-3-optional"]], "Further reading": [[19, null]], "Requests": [[20, "requests"]], "Retrieve data from API": [[20, "retrieve-data-from-api"]], "API which requires parameters": [[20, "api-which-requires-parameters"]], "After exercises: Saving retrieved data to disk": [[20, "after-exercises-saving-retrieved-data-to-disk"]], "Wrap-up": [[20, "wrap-up"]]}, "indexentries": {}}) \ No newline at end of file diff --git a/branch/rkdarst--remove-catfacts-jsonl/web-apis/index.html b/branch/rkdarst--remove-catfacts-jsonl/web-apis/index.html new file mode 100644 index 00000000..f5f4e0bb --- /dev/null +++ b/branch/rkdarst--remove-catfacts-jsonl/web-apis/index.html @@ -0,0 +1,810 @@ + + + + + + + + + + + + + + + Web APIs with Python — Python for Scientific Computing documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Web APIs with Python

+
+

Questions

+
    +

  • Have you ever needed to get some data from somewhere else on the web?

    • +
+
+
+

Objectives

+
    +

  • Understand a web server and API and why might you need to talk to one.

    • +

  • Basics of the requests Python library

    • +

  • Some lightweight recommendations on saving data when you get to more serious data download.

    • +
+
+
+

Requests

+

Requests is a Python library that makes requests to web servers. It provides a nice interface and is one of the go-to tools. It does the raw data-download for simple web servers.

+

First, let’s take a tour of the Requests webpage. Below, we embed the Requests website into a Jupyter notebook, but you might want to open it in another browser tab: https://requests.readthedocs.io/en/latest/

+
+
+
# Embed the requests homepage
+from IPython.display import IFrame
+requests_documentation_url = "https://requests.readthedocs.io/en/latest/"
+IFrame(requests_documentation_url, '100%', '30%')
+
+
+
+
+
+ +
+
+
+
+

Retrieve data from API

+

An API (Application Programming Interface) is the definition of the way computer programs communicate with each other. We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us. This is called the request-response cycle.

+

We can find a list of some free APIs (available without authentication) at https://apipheny.io/free-api/#apis-without-key . These APIs can be used for developing and testing our code.

+

Let’s make a request to the Cat Fact API. If we go to https://catfact.ninja/, it gives us the definitions:

+
    +

  • GET /fact is the API endpoint.

    • +

  • GET is the type of request we make and

    • +

  • /fact is the path.

    • +
+

You can even test this in your web browser: https://catfact.ninja/fact

+

Using the Requests library, we do this with get().

+
+
+
# Import
+import requests
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make a request
+response = requests.get(url)
+
+
+
+
+

The requests.Response object tells us what the server said. We can access the response content using content.

+
+
+
response_content = response.content
+
+# Display
+display(response_content)
+
+
+
+
+
b'{"fact":"Like birds, cats have a homing ability that uses its biological clock, the angle of the sun, and the Earth\'s magnetic field. A cat taken far from its home can return to it. But if a cat\'s owners move far from its home, the cat can\'t find them.","length":243}'
+
+
+
+
+

The response content is in the JSON format and Requests gives us the json() method that decodes it and returns the corresponding data as Python objects. This is equivalent to json.load().

+
+
+
response_json = response.json()
+
+# Display
+display(response_json)
+
+
+
+
+
{'fact': "Like birds, cats have a homing ability that uses its biological clock, the angle of the sun, and the Earth's magnetic field. A cat taken far from its home can return to it. But if a cat's owners move far from its home, the cat can't find them.",
+ 'length': 243}
+
+
+
+
+

(Note that, normally, we could study the API documentation to check the response format beforehand. However, many times manual inspection and trial-and-error is needed, as we did here.)

+
+
+

API which requires parameters

+

Let’s then examine another API which accepts parameters to specify the information request. In particular, we will request a list of Finnish universities from http://universities.hipolabs.com using the /search end point and a parameter country with value Finland, like this: +http://universities.hipolabs.com/search?country=Finland .

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search?country=Finland'
+
+# Make a request
+response = requests.get(url)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+
[{'country': 'Finland',
+  'domains': ['abo.fi'],
+  'web_pages': ['http://www.abo.fi/'],
+  'alpha_two_code': 'FI',
+  'name': 'Abo Akademi University',
+  'state-province': None},
+ {'country': 'Finland',
+  'domains': ['cou.fi'],
+  'web_pages': ['http://www.cou.fi/'],
+  'alpha_two_code': 'FI',
+  'name': 'Central Ostrobothnia University of Applied Sciences',
+  'state-province': None}]
+
+
+
+
+

URLs containing parameters can always be constructed manually using the & character and then listing the parameter (key, value) pairs as above.

+

However, Requests allows us to provide the parameters as a dictionary of strings, using the params keyword argument to get(). This is easier to read and less error-prone.

+
+
+
# URL
+url = 'http://universities.hipolabs.com/search'
+
+# Make the parameter dictionary
+parameters = {'country' : 'Finland'}
+
+# Get response
+response = requests.get(url, params=parameters)
+
+# Decode JSON
+response_json = response.json()
+
+# Display
+display(response_json[:2])
+
+
+
+
+
[{'country': 'Finland',
+  'domains': ['abo.fi'],
+  'web_pages': ['http://www.abo.fi/'],
+  'alpha_two_code': 'FI',
+  'name': 'Abo Akademi University',
+  'state-province': None},
+ {'country': 'Finland',
+  'domains': ['cou.fi'],
+  'web_pages': ['http://www.cou.fi/'],
+  'alpha_two_code': 'FI',
+  'name': 'Central Ostrobothnia University of Applied Sciences',
+  'state-province': None}]
+
+
+
+
+
+
+

Exercises 1

+
+

Exercise WebAPIs-1: Request different activity suggestions from the Bored API

+

Go to the documentation page of the Bored API. The Bored API is an open API which can be used to randomly generate activity suggestions.

+

Let’s examine the first sample query on the page http://www.boredapi.com/api/activity/ with a sample JSON response

+
{
+    "activity": "Learn Express.js",
+    "accessibility": 0.25,
+    "type": "education",
+    "participants": 1,
+    "price": 0.1,
+    "link": "https://expressjs.com/",
+    "key": "3943506"
+} 
+
+
+

Let’s replicate the query and see if we can get another random suggestion.

+
+
+
+
# Import module
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Send the request using the get() function
+response = requests.get(url)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+
+
+
+
+
{'activity': 'Learn a new recipe',
+ 'type': 'cooking',
+ 'participants': 1,
+ 'price': 0,
+ 'link': '',
+ 'key': '6553978',
+ 'accessibility': 0.05}
+
+
+
+
+

Next, let’s try to narrow down the suggestions by adding some parameters

+
    +

  • type

    • +

  • participants

    • +
+

All possible parameter values are presented at the bottom of the bored documentation page. Relevant parts in the Requests documentation

+
+
+
# Define some parameters
+params = {
+    'type' : 'education',
+    'participants' : 1,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display("Response")
+display(response.json())
+
+
+
+
+
'Response'
+
+
+
{'activity': 'Watch a Khan Academy lecture on a subject of your choosing',
+ 'type': 'education',
+ 'participants': 1,
+ 'price': 0,
+ 'link': 'https://www.khanacademy.org/',
+ 'key': '7154873',
+ 'accessibility': 0}
+
+
+
+
+

Let’s narrow the request further with more parameters

+
    +

  • price range

    • +

  • accessibility range

    • +
+

(All possible parameter values are again presented at the bottom of the document page.)

+
+
+
# Define some parameters
+params = {
+    'type' : 'social',
+    'participants' : 2,
+    'minprice' : 0,
+    'maxprice' : 1000,
+}
+
+# Send the request using get() with parameters
+response = requests.get(url, params)
+
+
+
+
+
+
+
# Show the JSON content of the response
+display(response.json())
+display("")
+
+
+
+
+
{'activity': "Text a friend you haven't talked to in a long time",
+ 'type': 'social',
+ 'participants': 2,
+ 'price': 0.05,
+ 'link': '',
+ 'key': '6081071',
+ 'accessibility': 0.2}
+
+
+
''
+
+
+
+
+
+
+

Exercises 2

+
+

Exercise WebAPIs-2: Examine request and response headers

+

Request headers are similar to request parameters but usually define meta information regarding, e.g., content encoding (gzip, utf-8) or user identification (user-agent/user ID/etc., password/access token/etc.).

+

Let’s first make a request.

+
+
+
+
# Import modules
+import requests
+
+# URL of the activity API end point
+url = "http://www.boredapi.com/api/activity/"
+
+# Make the request using the get() function
+response = requests.get(url)
+
+
+
+
+

We can access the headers of the original request

+
+
+
display("Request headers")
+display(dict(response.request.headers))
+
+
+
+
+
'Request headers'
+
+
+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive'}
+
+
+
+
+

We can also access the headers of the response

+
+
+
display("Response headers")
+display(dict(response.headers))
+
+
+
+
+
'Response headers'
+
+
+
{'Server': 'Cowboy',
+ 'Connection': 'keep-alive',
+ 'X-Powered-By': 'Express',
+ 'Access-Control-Allow-Origin': '*',
+ 'Access-Control-Allow-Headers': 'Origin, X-Requested-With, Content-Type, Accept',
+ 'Content-Type': 'application/json; charset=utf-8',
+ 'Content-Length': '173',
+ 'Etag': 'W/"ad-zZMnm3OMcRctfbS6/JmV4bUyRGo"',
+ 'Date': 'Wed, 23 Nov 2022 22:22:05 GMT',
+ 'Via': '1.1 vegur'}
+
+
+
+
+

In many cases, the default headers

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive'}
+
+
+

added automatically by Requests are sufficient. However, similarly to parameters, we can pass custom headers to the get function as an argument.

+

This is useful when, for example, the API has restricted access and requires a user ID and/or password as a part of the headers.

+
{'User-Agent': 'python-requests/2.28.1',
+ 'Accept-Encoding': 'gzip, deflate, br',
+ 'Accept': '*/*',
+ 'Connection': 'keep-alive',
+ 'example-user-id' : 'example-password'}
+
+
+

For examples of APIs using this type of authentication, see

+ +

For more on authentication, see also Requests documentation.

+
+
+

Exercises 3

+ +
+
+
# Import module
+import requests
+
+# Define webpage to scrape
+url = "http://www.example.com/"
+
+# Make a request for the URL
+response = requests.get(url)
+
+# Examine the response
+display(response.content)
+
+
+
+
+
b'<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n    <meta charset="utf-8" />\n    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1" />\n    <style type="text/css">\n    body {\n        background-color: #f0f0f2;\n        margin: 0;\n        padding: 0;\n        font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;\n        \n    }\n    div {\n        width: 600px;\n        margin: 5em auto;\n        padding: 2em;\n        background-color: #fdfdff;\n        border-radius: 0.5em;\n        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n    }\n    a:link, a:visited {\n        color: #38488f;\n        text-decoration: none;\n    }\n    @media (max-width: 700px) {\n        div {\n            margin: 0 auto;\n            width: auto;\n        }\n    }\n    </style>    \n</head>\n\n<body>\n<div>\n    <h1>Example Domain</h1>\n    <p>This domain is for use in illustrative examples in documents. You may use this\n    domain in literature without prior coordination or asking for permission.</p>\n    <p><a href="https://www.iana.org/domains/example">More information...</a></p>\n</div>\n</body>\n</html>\n'
+
+
+
+
+
+
+
# Looks like HTML :) Let's access it using the text attribute
+html = response.text
+
+print(html)
+
+
+
+
+
<!doctype html>
+<html>
+<head>
+    <title>Example Domain</title>
+
+    <meta charset="utf-8" />
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style type="text/css">
+    body {
+        background-color: #f0f0f2;
+        margin: 0;
+        padding: 0;
+        font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+        
+    }
+    div {
+        width: 600px;
+        margin: 5em auto;
+        padding: 2em;
+        background-color: #fdfdff;
+        border-radius: 0.5em;
+        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);
+    }
+    a:link, a:visited {
+        color: #38488f;
+        text-decoration: none;
+    }
+    @media (max-width: 700px) {
+        div {
+            margin: 0 auto;
+            width: auto;
+        }
+    }
+    </style>    
+</head>
+
+<body>
+<div>
+    <h1>Example Domain</h1>
+    <p>This domain is for use in illustrative examples in documents. You may use this
+    domain in literature without prior coordination or asking for permission.</p>
+    <p><a href="https://www.iana.org/domains/example">More information...</a></p>
+</div>
+</body>
+</html>
+
+
+
+
+
+
+
# Import beautiful soup module
+from bs4 import BeautifulSoup
+
+# Create soup
+soup = BeautifulSoup(html, 'html.parser')
+
+
+
+
+
+
+
# Extract page title from the HTML
+print(f"Found title: {soup.title.text}")
+
+
+
+
+
Found title: Example Domain
+
+
+
+
+
+
+
# Extract links (hrefs) from the HTML
+for link in soup.find_all('a'):
+    print(f"Found link: {link.get('href')}")
+
+
+
+
+
Found link: https://www.iana.org/domains/example
+
+
+
+
+
+
+
# Extract all text from the HTML
+print(f"Found text: {soup.get_text()}")    
+
+
+
+
+
Found text: 
+
+
+Example Domain
+
+
+
+
+
+
+
+Example Domain
+This domain is for use in illustrative examples in documents. You may use this
+    domain in literature without prior coordination or asking for permission.
+More information...
+
+
+
+
+
+
+

After exercises: Saving retrieved data to disk

+

Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudal study.

+

To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don’t, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).

+

For example, let’s retrieve three cat facts and save them to a JSONLINES file using the jsonlines library.

+
+
+
# Import
+import requests
+import jsonlines
+import time
+
+# URL
+url = 'https://catfact.ninja/fact'
+
+# Make three requests in loop and make a list of response JSON objects
+for i in range(3):
+
+    # Logging
+    print(f"Make request {i}")
+
+    # Make a request
+    response = requests.get(url)
+    
+    # Decode to JSON
+    response_json = response.json()
+                
+    # Open a jsonlines writer in 'append' mode 
+    with jsonlines.open('catfacts.jsonl', mode='a') as writer:
+
+        # Write
+        writer.write(response_json)
+        
+    # Sleep for one second between requests
+    time.sleep(1)
+
+
+
+
+
Make request 0
+
+
+
Make request 1
+
+
+
Make request 2
+
+
+
+
+

We can then read the objects from the disk using the same library.

+
+
+
# Open a jsonlines reader
+with jsonlines.open('catfacts.jsonl', mode='r') as reader:
+    
+    # Read and display
+    for obj in reader:
+        display(obj)
+
+
+
+
+
{'fact': 'There is a species of cat smaller than the average housecat. It is native to Africa and it is the Black-footed cat (Felis nigripes). Its top weight is 5.5 pounds.',
+ 'length': 162}
+
+
+
{'fact': 'Approximately 40,000 people are bitten by cats in the U.S. annually.',
+ 'length': 68}
+
+
+
{'fact': "The way you treat kittens in the early stages of it's life will render it's personality traits later in life.",
+ 'length': 109}
+
+
+
+
+
+
+

Wrap-up

+
+

Keypoints

+
    +

  • Requests is a common tool

    • +

  • Web APIs may often require some trial and error, but actually getting data is usually not that difficult

    • +

  • Storing all the data and processing it well can be a much larger issue.

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/branch/rkdarst--strict-warnings-check/_images/01_table_dataframe.svg b/branch/rkdarst--strict-warnings-check/_images/01_table_dataframe.svg new file mode 100644 index 00000000..9bd1c217 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_images/01_table_dataframe.svg @@ -0,0 +1,262 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + column + DataFrame + + + row + + + diff --git a/branch/rkdarst--strict-warnings-check/_images/anaconda-prompt.png b/branch/rkdarst--strict-warnings-check/_images/anaconda-prompt.png new file mode 100644 index 00000000..aed5bd80 Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/anaconda-prompt.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/exercise-4.1.png b/branch/rkdarst--strict-warnings-check/_images/exercise-4.1.png new file mode 100644 index 00000000..465f23f2 Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/exercise-4.1.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/exercise-4.2.png b/branch/rkdarst--strict-warnings-check/_images/exercise-4.2.png new file mode 100644 index 00000000..82da2a7a Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/exercise-4.2.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/exercise-4.3-linear.png b/branch/rkdarst--strict-warnings-check/_images/exercise-4.3-linear.png new file mode 100644 index 00000000..0b35e77a Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/exercise-4.3-linear.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/exercise-4.3-log.png b/branch/rkdarst--strict-warnings-check/_images/exercise-4.3-log.png new file mode 100644 index 00000000..d92a30b4 Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/exercise-4.3-log.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/exercise-4.4.png b/branch/rkdarst--strict-warnings-check/_images/exercise-4.4.png new file mode 100644 index 00000000..fb11e972 Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/exercise-4.4.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/getting-started.png b/branch/rkdarst--strict-warnings-check/_images/getting-started.png new file mode 100644 index 00000000..e1a0a81f Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/getting-started.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/main-ui.png b/branch/rkdarst--strict-warnings-check/_images/main-ui.png new file mode 100644 index 00000000..93b2ea43 Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/main-ui.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/notebook-ui.png b/branch/rkdarst--strict-warnings-check/_images/notebook-ui.png new file mode 100644 index 00000000..a2bf1b3b Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/notebook-ui.png differ diff --git a/branch/rkdarst--strict-warnings-check/_images/tidy_data.png b/branch/rkdarst--strict-warnings-check/_images/tidy_data.png new file mode 100644 index 00000000..16bc116a Binary files /dev/null and b/branch/rkdarst--strict-warnings-check/_images/tidy_data.png differ diff --git a/branch/rkdarst--strict-warnings-check/_sources/binder.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/binder.rst.txt new file mode 100644 index 00000000..a09c9e35 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/binder.rst.txt @@ -0,0 +1,132 @@ +Binder +====== + +.. questions:: + + - Why sharing code is not sufficient? + - How to share computational environment? + - What is Binder? + - How to binderize my python repository? + - How to publish my python repository? + +.. objectives:: + + - Learn about reproducible computational environments + - Learn to create and share custom computing environments with myBinder + - Learn to get a DOI from zenodo for a repository. + + + +Why isn't enough to share your code? +------------------------------------ + +Before we work in group and write our thoughts on why we need more than sharing our codes for reproducible research, let's take an example from geospatial analysis where the first `import` in the code would be (please note that it is not necessary to install any of the packages mentioned below): + + +:: + + from osgeo import ogr, osr, gdal + + +Depending on how you install this python package, it may be necessary to have `libgdal` and its development headers already installed on your system; with information on the version you have used, etc. + + +.. challenge:: Binder-1 (10 mn) + + Lea is a PhD student in computational biology and after 2 years of intensive work, she is finally ready to publish her first paper. The code she has used for analyzing her data is available on github but her supervisor who is an advocate of Open Science told her that sharing code is not sufficient. + + 1. Why isn't enough to share your code? + + We form small groups (4-5 persons) and discuss in groups. If the workshop is online, each group will join a breakout room. + + Each group write a summary (bullet points) of the discussion in the workshop shared document (the link will be provided by your instructors). + + +Binder +------ + +`Binder `__ allows you to create custom computing environments that can be shared and used by many remote users. It uses `repo2docker `__ to create a container image (`docker `__ image) of a project using information contained in included configuration files. + +Repo2docker is a standalone package that you can install locally on your laptop but an `online Binder `__ service is freely available. This is what we will be using in the tutorial. + +How can I share my computing environment with myBinder? +------------------------------------------------------- + +The main objective of this exercise is to learn to fork a repository and add a requirement file to share the computational environment with myBinder. + + +.. image:: https://opendreamkit.org/public/images/use-cases/reproducible_logbook.png + +Credit: `Juliette Taka, Logilab and the OpenDreamKit project (2017) `_ + + +.. challenge:: Binder-2 (15 mn) + + 1. Fork `the following github repository + `_. In the top-right corner of the page, click Fork. + + .. image:: https://docs.github.com/assets/images/help/repository/fork_button.jpg + + 2. Follow instruction given `here `__ to share the forked repository via `Binder `_. + +How can I get a DOI from Zenodo? +--------------------------------- + +`Zenodo `__ is a general purpose open-access repository built and operated by `CERN `__ and `OpenAIRE `__ that allows researchers to archive and get a `Digital Object Identifier (DOI) `__ to data that they share. + +.. challenge:: Binder-3 (optional) + + **Everything you deposit on Zenodo is meant to be kept (long-term archive) so we recommend to use a repository you really wish to archive for this exercise.** + + 1. **Link GitHub with Zenodo**: + + - Go to `https://zenodo.org `_ + - Log in to Zenodo with your GitHub account. Be aware that you may need to authorize Zenodo application (Zenodo will redirect you back to GitHub for Authorization) + - Choose the repository webhooks options + - From the drop-down menu next to your email address at the top of the page, select GitHub. + - You will be presented with a list of all your Github repositories + + 2. **Archiving a repo**: + + - Select a repository you want to archive on Zenodo. + - Toggle the "on" button next to the repository ou need to archive. + - Click on the Repo that you want to reserve. + - Click on Create release button at the top of the page. Zenodo will redirect you back to GitHub’s repo page to generate a release + + 3. **Trigger Zenodo to Archive your repository** + + - Go to GitHub and create a release. Zenodo will automatically download a .zip-ball of each new release and register a DOI. + - If this is the first release of your code then you should give it a version number of v1.0.0. Add description for your release then click the Publish release button. + - Zenodo takes an archive of your GitHub repository each time you create a new Release + + 4. **To ensure that everything is working**: + + - Go to https://zenodo.org/account/settings/github/, or the Upload page (https://zenodo.org/deposit), you will find your repo is listed + - Click on the repo, Zenodo will redirect you to a page that contains a DOI for your repo will the information that you added to the repo. + - You can edit the archive on Zenodo and/or publish a new version of your software. + - It is recommended that you add a description for your repo and fill in other metadata in the edit page. + - Your code is now published on a Github public repository and archived on Zenodo. + - Update the README file in your repository with the newly created zenodo badge. + + +Create a Binder link for your Zenodo DOI +---------------------------------------- + +Rather than specifying a github repository when launching binder, you can instead use a Zenodo DOI. + +.. challenge:: Binder-4 (10 mn) + + We will be using an existing Zenodo DOI `10.5281/zenodo.3886864 `_ to start myBinder: + + - Go to `https://mybinder.org `__ and fill information using Zenodo DOI (as shown on the figure below) + + .. image:: https://miro.medium.com/max/1050/1*xOABVY2hNtVmjV5-LXreFw.gif + + - You can also get Binder badge and update the README file in the repository. It is good practice to add both the zenodo badge and the corresponding binder badge. + + +.. keypoints:: + + - Sharing reproducible computational environments + - myBinder + - Zenodo DOI diff --git a/branch/rkdarst--strict-warnings-check/_sources/data-visualization.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/data-visualization.rst.txt new file mode 100644 index 00000000..bd739215 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/data-visualization.rst.txt @@ -0,0 +1,435 @@ +Data visualization with Matplotlib +================================== + +.. questions:: + + - When to use Matplotlib for data visualization? + - When to prefer other libraries? + +.. objectives:: + + - Be able to create simple plots and tweak them + - Know about object-oriented vs pyplot interfaces of Matplotlib + - Be able to adapt gallery examples + - Know how to look for help + - Know that other tools exist + + +Repeatability/reproducibility +----------------------------- + +From `Claus O. Wilke: "Fundamentals of Data Visualization" `__: + + *One thing I have learned over the years is that automation is your friend. I + think figures should be autogenerated as part of the data analysis pipeline + (which should also be automated), and they should come out of the pipeline + ready to be sent to the printer, no manual post-processing needed.* + +- **No manual post-processing**. This will bite you when you need to regenerate 50 + figures one day before submission deadline or regenerate a set of figures + after the person who created them left the group. +- **Use free tools**: Python or R. +- There is not the one perfect language and **not the one perfect library** for everything. +- Within Python, many libraries exist: + `Matplotlib `__, + `Seaborn `__, + `Altair `__, + `Plotly `__, + `Bokeh `__, + `ggplot `__, + `PyNGL `__, + and many others. +- Two main families of libraries: procedural (e.g. Matplotlib) and declarative + (using grammar of graphics). + + +Why are we learning Matplotlib? +------------------------------- + +- Matplotlib is perhaps the most "standard" Python plotting library. +- Many libraries build on top of Matplotlib. +- MATLAB users will feel familiar. +- Even if you choose to use another library (see above list), chances are high + that you need to adapt a Matplotlib plot of somebody else. +- Libraries that are built on top of Matplotlib may need knowledge of Matplotlib + for custom adjustments. + + +Getting started with Matplotlib +------------------------------- + +Let us create our first plot (the highlighted line is only needed in a Jupyter notebook +to show the generated figure in the notebook, we don't need this when running this as script): + +.. code-block:: python + :emphasize-lines: 1 + + %matplotlib inline + + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + +This is the result: + +.. image:: data-visualization/getting-started.png + +When plotting using a script, you often want to also save the generated figure: + +.. code-block:: python + :emphasize-lines: 3 + + # ... rest of the script + + fig.savefig("my-plot.png") + + plt.show() + +This code snipped also contains ``plt.show()`` to show the figure on screen. We +did not need this in a Jupyter notebook. + +When running a Matplotlib script on a remote server without a "display" (e.g. +compute cluster), you may need to add this line: + +.. code-block:: python + :emphasize-lines: 2 + + import matplotlib.pyplot as plt + matplotlib.use("Agg") + + # ... rest of the script + + +.. challenge:: Exercises: Visualization-1 + + - Extend the previous plot by also plotting this set of values but this time + using a different color (``#56B4E9``):: + + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + + - Then add another color (``#009E73``) which plots the second dataset, scaled + by 2.0. + + - Can you try to find out how to add a legend to the plot? + + At the end it should look like this one: + + .. image:: data-visualization/exercise-4.1.png + + +.. solution:: + + .. code-block:: python + :emphasize-lines: 11,16,18-19,24 + + %matplotlib inline + + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + # this is dataset 2 + data2_y = [9.14, 8.14, 8.74, 8.77, 9.26, 8.10, 6.13, 3.10, 9.13, 7.26, 4.74] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00", label='set 1') + ax.scatter(x=data_x, y=data2_y, c="#56B4E9", label='set 2') + + scaled = [y*2.0 for y in data2_y] + ax.scatter(x=data_x, y=scaled, c="#009E73", label='set 2 (scaled)') + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + ax.legend() + + +.. discussion:: + + Why these colors? This qualitative color palette is opimized for all color-vision + deficiencies, see https://clauswilke.com/dataviz/color-pitfalls.html and + `Okabe, M., and K. Ito. 2008. "Color Universal Design (CUD): + How to Make Figures and Presentations That Are Friendly to Colorblind People." `__. + + +Matplotlib has two different interfaces +--------------------------------------- + +When plotting with matplotlib, it is very important to know and understand that +there are **two approaches** even though the reasons of this dual approach is +outside the scope of this lesson. + +- The more modern option is an **object-oriented interface** (the ``fig`` and ``ax`` objects + can be configured separately and passed around to functions): + +.. code-block:: python + :emphasize-lines: 8-14 + + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + fig, ax = plt.subplots() + + ax.scatter(x=data_x, y=data_y, c="#E69F00") + + ax.set_xlabel("we should label the x axis") + ax.set_ylabel("we should label the y axis") + ax.set_title("some title") + +- The more traditional option mimics MATLAB plotting and uses the **pyplot interface** (``plt`` carries + the global settings): + +.. code-block:: python + :emphasize-lines: 8-12 + + import matplotlib.pyplot as plt + + # this is dataset 1 from + # https://en.wikipedia.org/wiki/Anscombe%27s_quartet + data_x = [10.0, 8.0, 13.0, 9.0, 11.0, 14.0, 6.0, 4.0, 12.0, 7.0, 5.0] + data_y = [8.04, 6.95, 7.58, 8.81, 8.33, 9.96, 7.24, 4.26, 10.84, 4.82, 5.68] + + plt.scatter(x=data_x, y=data_y, c="#E69F00") + + plt.xlabel("we should label the x axis") + plt.ylabel("we should label the y axis") + plt.title("some title") + +When searching for help on the internet, you will find both approaches, they +can also be mixed. Although the pyplot interface looks more compact, **we +recommend to learn and use the object oriented interface.** + + +.. challenge:: Exercises: Visualization-2 + + Imagine we wanted to learn how to create a histogram and web searched + "matplotlib plot histogram stack overflow" and found https://stackoverflow.com/a/5328669:: + + import matplotlib.pyplot as plt + import numpy as np + + mu, sigma = 100, 15 + x = mu + sigma * np.random.randn(10000) + hist, bins = np.histogram(x, bins=50) + width = 0.7 * (bins[1] - bins[0]) + center = (bins[:-1] + bins[1:]) / 2 + plt.bar(center, hist, align='center', width=width) + plt.show() + + - Try this example out in the Jupyter notebook. + - Change the number of bins to 20. + - Convert it from pyplot interface to using the object oriented interface. + + At the end it should look like this one: + + .. image:: data-visualization/exercise-4.2.png + + +.. solution:: + + .. code-block:: python + :emphasize-lines: 6,10-11 + + import matplotlib.pyplot as plt + import numpy as np + + mu, sigma = 100, 15 + x = mu + sigma * np.random.randn(10000) + hist, bins = np.histogram(x, bins=20) + width = 0.7 * (bins[1] - bins[0]) + center = (bins[:-1] + bins[1:]) / 2 + + fig, ax = plt.subplots() + ax.bar(center, hist, align='center', width=width) + + +.. discussion:: + + Why did we do this? One day you may want to write functions which wrap + around Matplotlib function calls and then you can send ``fig`` and ``ax`` + into these functions and there is less risk that adjusting figures changes + settings also for unrelated figures created in other functions. + + When using the pyplot interface, settings are modified for the entire + ``plt`` package. The latter is acceptable for linear scripts but may yield + surprising results when introducing functions to enhance/abstract Matplotlib + calls. + + +Styling and customizing plots +----------------------------- + +- Matplotlib allows to customize almost every aspect of a plot. +- It is useful to study `Matplotlib parts of a figure `__ + so that we know what to search for to customize things. +- You can also select among pre-defined themes/ + `style sheets `__, for instance: + +.. code-block:: python + + plt.style.use('ggplot') + +- **Do not customize "manually"** using a graphical program (not easily repeatable/reproducible). + + +.. challenge:: Exercises: Visualization-3 + + In this exercise we will learn how to use log scales. + To demonstrate this we first fetch some data to plot: + + .. code-block:: python + + # we use plotly, a different visualization library (more about this later) + # to fetch some data + import plotly.express as px + + # we will be interested in the lifeExp and gdpPercap columns + data = px.data.gapminder().query("year == 2007") + data + + - Try the above snippet in a notebook and it will give you an overview over the data. + + - Then we can plot the data, first using a linear scale: + + .. code-block:: python + + fig, ax = plt.subplots() + + ax.scatter(x=data["gdpPercap"], y=data["lifeExp"], alpha=0.5) + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + + This is the result but we realize that a linear scale is not ideal here: + + .. image:: data-visualization/exercise-4.3-linear.png + + - Your task is to switch to a log scale and arrive at this result: + + .. image:: data-visualization/exercise-4.3-log.png + + - What does ``alpha=0.5`` do? + - Try adding ``plt.style.use('ggplot')``. + +.. solution:: + + .. code-block:: python + :emphasize-lines: 4 + + fig, ax = plt.subplots() + + ax.scatter(x=data["gdpPercap"], y=data["lifeExp"], alpha=0.5) + ax.set_xscale("log") + ax.set_xlabel("GDP (USD) per capita") + ax.set_ylabel("life expectancy (years)") + + +.. challenge:: Exercises: Visualization-4 + + Often we need to create figures for presentation slides and for publications + but both have different requirements: for presentation slides you have the whole + screen but for a figure in a publication you may only have few centimeters/inches. + + For figures that go to print it is good practice to look at them at the size + they will be printed in and then often fonts and tickmarks are too small. + + Your task is to make the tickmarks and the axis label font larger, using + `Matplotlib parts of a figure `__ + and web search, and to arrive at this: + + .. image:: data-visualization/exercise-4.4.png + + +.. solution:: + + .. code-block:: python + :emphasize-lines: 5-10 + + fig, ax = plt.subplots() + + ax.scatter(x=data["gdpPercap"], y=data["lifeExp"], alpha=0.5) + ax.set_xscale("log") + ax.set_xlabel("GDP (USD) per capita", fontsize=15) + ax.set_ylabel("life expectancy (years)", fontsize=15) + ax.tick_params(which="major", length=10) + ax.tick_params(which="minor", length=5) + ax.tick_params(labelsize=15) + ax.tick_params(labelsize=15) + + +How to choose between the many libraries +---------------------------------------- + +`Matplotlib `__ is probably the most standard and most +widely used library. However it is a relatively low-level interface for +drawing (in terms of abstractions, not in terms of quality) and does not +provide statistical functions. Some figures require typing and tweaking many lines of code. + +Many other visualization libraries exist with their own strengths, it is also a +matter of personal preferences: + +- `Seaborn `__: high-level interface to + Matplotlib, statistical functions built in. +- `Altair `__: declarative visualization (R users + will be more at home), statistics built in. +- `Plotly `__: interactive graphs. +- `Bokeh `__: also here good for interactivity. +- `ggplot `__: R users will be more at home. +- `PyNGL `__: used in the weather forecast community. +- `K3D `__: Jupyter notebook extension for 3D visualization + +What many people do (including the present instructor) is to browse existing example +galleries for inspiration and to start with an example that is already close to +what we have in mind and then to replace the example with own data and to +customize the looks. + +Example galleries and demos: + +- `Matplotlib `__ +- `Seaborn `__ +- `Altair `__ + (not part of default Anaconda installation) +- `Plotly `__ +- `Bokeh `__ +- `ggplot `__ + (not part of default Anaconda installation) +- `PyNGL `__ + (not part of default Anaconda installation) +- `K3D `__ + +Let's practice this! + + +.. challenge:: Exercises: Visualization-5 + + - Browse the various example galleries (links above). + - Take an example that is close to your recent visualization project or simply interests you. + - Try to reproduce this example in the Jupyter notebook. + - If you have time, try to tweak it. + + +.. keypoints:: + + - Avoid manual post-processing, script everything. + - Browse a number of example galleries to help you choose the library that fits best your work/style. + - Figures for presentation slides and figures for manuscripts have different requirements. + - Think about color-vision deficiencies when choosing colors. Use existing solutions for this problem. diff --git a/branch/rkdarst--strict-warnings-check/_sources/dependencies.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/dependencies.rst.txt new file mode 100644 index 00000000..c14cb442 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/dependencies.rst.txt @@ -0,0 +1,350 @@ +Dependency management +===================== + +.. questions:: + + - Do you expect your code to work in one year? Five? What if it + uses ``numpy`` or ``tensorflow`` or ``random-github-package`` ? + - How can my collaborators get the same results as me? What about + future me? + - How can my collaborators easily install my codes with all the necessary dependencies? + - How can I make it easy for my colleagues to reproduce my results? + - How can I work on two (or more) projects with different and conflicting dependencies? + +.. objectives:: + + - Learn how to record dependencies + - Be able to communicate the dependencies as part of a report/thesis/publication + - Learn how to use isolated environments for different projects + - Simplify the use and reuse of scripts and projects + + +How do you track dependencies of your project? +---------------------------------------------- + +* **Dependency**: Reliance on a external component. In this case, a + separately installed software package such as ``numpy``. + +.. challenge:: Dependencies-1 (15 min) + + Please discuss **in breakout rooms** and answer via **collaborative document** the + following questions: + + - How do you install Python packages (libraries) that you use in your work? + From PyPI using pip? From other places using pip? Using conda? + - How do you track/record the dependencies? Do you write them into a file or README? Into + ``requirements.txt`` or ``environment.yml``? + - If you track dependencies in a file, why do you do this? + - Have you ever experienced that a project needed a different version of a Python + library than the one on your computer? If yes, how did you solve it? + + +PyPI (The Python Package Index) and (Ana)conda +---------------------------------------------- + +- PyPI (The Python Package Index) and Conda are popular packaging/dependency + management tools. + +- When you run ``pip install`` you typically install from `PyPI + `__ but one can also ``pip install`` from a GitHub + repository and similar. + +- When you run ``conda install`` you typically install from `Anaconda Cloud + `__ but there are many community-driven conda channels + and you can create your own. + + +Why are there two ecosystems? + +- PyPI is traditionally for Python-only packages but it is no problem to also + distribute packages written in other languages as long as they provide a + Python interface. + +- Conda is more general and while it contains many Python packages and packages + with a Python interface, it is often used to also distribute packages which + do not contain any Python (e.g. C or C++ packages). + +- Many libraries and tools are distributed in both ecosystems. + + +In the packaging episode we will meet PyPI and Anaconda again and practice how +to share Python packages. + + +Creating isolated environments +------------------------------ + +Isolated environments solve a couple of problems: + +- You can install specific, also older, versions into them. + +- You can create one for each project and no problem if the two projects + require different versions. + +- If you make some mistake and install something you did not want or need, you + can remove the environment and create a new one. + + +.. challenge:: Dependencies-2 (15 min) + + Chloe just joined your team and will be working on her Master Thesis. She is + quite familiar with Python, still finishing some Python assignments (due in a + few weeks) and you give her a Python code for analyzing and plotting your + favorite data. The thing is that your Python code has been developed by + another Master Student (from last year) and requires a pretty old version of + Numpy (1.13.1) and Matplotlib (2.2.2) (otherwise the code fails). The code + could probably work with a recent version of Python but has been validated with + Python 3.6 only. Having no idea what the code does, she decides that the best + approach is to **create an isolated environment** with the same dependencies used + previously. This will give her a baseline for future upgrade and + developments. + + For this first exercise, we will be using conda for creating an isolated environment. + + 1. Create a conda environment:: + + $ conda create --name python36-env python=3.6 numpy=1.13.1 matplotlib=2.2.2 + + Conda environments can also be managed (create, update, delete) from the + **anaconda-navigator**. Check out the corresponding documentation `here + `_. + + 2. Activate the environment:: + + $ conda activate python36-env + + .. callout:: conda activate versus source activate + + If you do not have a recent version of Anaconda or anaconda has not been + setup properly, you may encounter an error. With older version of anaconda, + you can try:: + + $ source activate python36-env + + 3. Open a Python console and check that you have effectively the right version for each package:: + + import numpy + import matplotlib + + print('Numpy version: ', numpy.__version__) + print('Matplotlib version: ', matplotlib.__version__) + + 4. Deactivate the environment:: + + $ conda deactivate + + 5. Check Numpy and Matplotlib versions in the default environment to make + sure they are different from **python36-env**. + + There is no need to specify the conda environment when using deactivate. It + deactivates the current environment. + + .. callout:: Remark + + - Sometimes the package version you would need does not seem to be + available. You may have to select another `conda channel + `_ + for instance `conda-forge `_. Channels can then + be indicated when installing a package:: + + $ conda install -c conda-forge matplotlib=2.2.0 + + - We will see below that rather than specifying the list of dependencies as + argument of ``conda create``, it is recommended to record dependencies in + a file. + + +.. challenge:: Dependencies-3 (15 min, optional) + + This is the same exercise as before but we use virtualenv rather than conda. + + + 1. Create a venv:: + + $ python -m venv scicomp + + Here ``scicomp`` is the name of the virtual environment. It creates a new + folder called ``scicomp``. + + 2. Activate it. To activate your newly created virtual environment locate the + script called ``activate`` and execute it. + + - **Linux/Mac-OSX**: look at ``bin`` folder in the ``scicomp`` folder:: + + $ source scicomp/bin/activate + + - **Windows**: most likely you can find it in the ``Scripts`` folder. + + 3. Install Numpy 1.13.1 and Matplotlib 2.2.2 into the virtual environment:: + + $ pip install numpy==1.13.1 + $ pip install matplotlib==2.2.2 + + 4. Deactivate it:: + + $ deactivate + + +Recording dependencies +---------------------- + +There are two standard ways to record dependencies for Python projects.: + +Using a ``requirements.txt`` (used by virtual environment) file which looks like this:: + + numpy + matplotlib + pandas + scipy + +Or using an ``environments.yml`` (for conda) file which looks like this:: + + name: my-environment + + dependencies: + - numpy + - matplotlib + - pandas + - scipy + +But all of these dependencies evolve so before publishing our work +it can be very useful for future generations and for the future you +to **pin dependencies** to versions. + +Here are the two files again, but this time with versions pinned: + +``requirements.txt`` with versions:: + + numpy==1.19.2 + matplotlib==3.3.2 + pandas==1.1.2 + scipy==1.5.2 + +``environments.yml`` with versions:: + + name: my-environment + + dependencies: + - python=3.6 + - numpy=1.19.2 + - matplotlib=3.3.2 + - pandas=1.1.2 + - scipy=1.5.2 + +- Conda can also read and write ``requirements.txt``. +- ``requirements.txt`` can also refer to packages on Github. +- ``environments.yml`` can also contain a ``pip`` section. +- See also: https://coderefinery.github.io/reproducible-research/03-dependencies/#dependencies. + + +.. challenge:: Dependencies-4 (15 min) + + - Create the file ``environment.yml`` or ``requirements.txt`` + + - Create an environment based on these dependencies: + - Conda: ``$ conda create --name myenvironment --file requirements.txt`` + - Virtual environment: First create and activate, then ``$ pip install -r requirements.txt`` + + - Freeze the environment: + - Conda: ``$ conda list --export > requirements.txt`` or ``$ conda env export > environment.yml`` + - Virtual environment: ``$ pip freeze > requirements.txt`` + + - Have a look at the generated ("frozen") file. + + +Tip: instead of installing packages with ``$ pip install somepackage``, what I do is +to add ``somepackage`` to ``requirements.txt`` or ``environment.yml`` and install +from the file, then you have a trace of all installed dependencies. + + +How to communicate the dependencies as part of a report/thesis/publication +-------------------------------------------------------------------------- + +Each notebook or script or project which depends on libraries should come with +either a ``requirements.txt`` or a ``environment.yml``, unless you are creating +and distributing this project as Python package (see next section). + +- Attach a ``requirements.txt`` or a ``environment.yml`` to your thesis. +- Even better: put ``requirements.txt`` or a ``environment.yml`` in your Git repository along your code. +- Even better: also binderize your analysis pipeline (more about that in a later session). + + +Version pinning for package creators +------------------------------------ + +We will talk about packaging in a different session but when you create a library and package +projects, you express dependencies either in ``setup.py`` or ``pyproject.toml`` +(PyPI) or ``meta.yaml`` (conda). + +These dependencies will then be used by either other libraries (who in turn +write their own ``setup.py`` or ``pyproject.toml`` or ``meta.yaml``) or by +people directly (filling out ``requirements.txt`` or a ``environment.yml``). + +Now as a library creator you have a difficult choice. You can either pin versions very +narrowly like here (example taken from ``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy==1.19.2', + 'matplotlib==3.3.2' + 'pandas==1.1.2' + 'scipy==1.5.2' + ] + # ... + +or you can define a range or keep them undefined like here (example taken from +``setup.py``): + +.. code-block:: python + :emphasize-lines: 3-6 + + # ... + install_requires=[ + 'numpy', + 'matplotlib' + 'pandas' + 'scipy' + ] + # ... + +Should we pin the versions here or not? + +- Pinning versions here would be good for reproducibility. + +- However pinning versions may make it difficult for this library to be used in a project alongside other + libraries with conflicting version dependencies. + +- Therefore **as library creator make the version requirements as wide as possible**. + + - Set minimum version when you know of a reason: ``>=2.1`` + + - Sometimes set maximum version to next major version (``<4``) (when + you currently use ``3.x.y``) when you expect issues with next + major version. + +- As the "end consumer" of libraries, define your dependencies as narrowly as possible. + + +See also +-------- + +Other tools for dependency management: + +- `Poetry `__: dependency management and packaging +- `Pipenv `__: dependency management, alternative to Poetry +- `pyenv `__: if you need different Python versions for different projects +- `micropipenv `__: lightweight tool to "rule them all" + +Other resources: + +- https://scicomp.aalto.fi/scicomp/packaging-software/ + + +.. keypoints:: + + - Install dependencies by first recording them in ``requirements.txt`` or + ``environment.yml`` and install using these files, then you have a trace. + - Use isolated environments and avoid installing packages system-wide. diff --git a/branch/rkdarst--strict-warnings-check/_sources/guide.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/guide.rst.txt new file mode 100644 index 00000000..cb4a3190 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/guide.rst.txt @@ -0,0 +1,32 @@ +Instructor's guide +================== + +Learner personas +---------------- + +A is a early career PhD researcher who has been using Python a bit, +but is not sure what they know or don't know. They want to be able to +do their research more efficiently and make sure that they are using +the right tools. A may know that numpy exists, etc. and could +theoretically read some about it themselves, but aren't sure if they +are going in the right direction. + +A2 can use numpy and pandas, but have learned little bits here and +there and hasn't had a comprehensive introduction. They want to +ensure they are using best practices. (Baseline of high-level +packages) + +B is a mid-to-late undergraduate student who has used Python in some +classes. They have possibly learned the syntax and enough to use it +in courses, but in a course-like manner where they are expected to +create everything themselves. + + +Prerequisites: +- Knowing basic Python syntax +- Watch the command line crash course, if you aren't familiar. + +Not prerequisites: +- Any external libraries, e.g. numpy +- Knowing how to make scripts or use Jupyter + diff --git a/branch/rkdarst--strict-warnings-check/_sources/index.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/index.rst.txt new file mode 100644 index 00000000..5a4ba507 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/index.rst.txt @@ -0,0 +1,188 @@ +=============================== +Python for Scientific Computing +=============================== + +.. admonition:: Attending the course 14-23.sep? + + `See the course page here + `__, + below is the course material. + +Python is a modern, object-oriented programming language, which has +become popular in several areas of software development. This course +discusses how Python can be utilized in scientific computing. The +course starts by introducing the main Python package for numerical +computing, NumPy, and discusses then SciPy toolbox for various +scientific computing tasks as well as visualization with the +Matplotlib package. In addition, it talks about *how* python is used: +related scientific libraries, reproducibility, and the broader +ecosystem of science in Python. + +This course (like any course) can't teach you Python... it can show +your some examples, let you see how experts do things, and prepare you +to learn yourself as you need to. + +.. _prerequisites: + +.. prereq:: + + - Knowing basic Python syntax. We assume that you can do some + Python programming, but not much more that that. We don't cover + standard Python programming. + - Watch or read the `command line crash course + `__, if you aren't + familiar. + - You should be able to use a text editor to edit files some. + - The :doc:`software installation ` described below + (basically, anaconda). + + These are not prerequisites: + + - Any external libraries, e.g. numpy + - Knowing how to make scripts or use Jupyter + + + +.. csv-table:: + :widths: auto + :delim: ; + + (prereq) ; :doc:`python` + 30 min ; :doc:`jupyter` + 60 min ; :doc:`numpy` + 60 min ; :doc:`data-visualization` + 60 min ; :doc:`scripts` + 30 min ; :doc:`dependencies` + 15 min ; :doc:`scipy` + 60 min ; :doc:`pandas` + 45 min ; :doc:`parallel` + 30 min ; :doc:`libraries` + 60 min ; :doc:`packaging` + 30 min ; :doc:`binder` + + +.. toctree:: + :maxdepth: 1 + :caption: The lesson + :hidden: + + python + jupyter + numpy + data-visualization + scripts + dependencies + scipy + pandas + parallel + libraries + packaging + binder + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + installation + quick-reference + guide + + +.. _learner-personas: + +Who is the course for? +====================== + +The course is targeted towards these learner personas: + +* A is a early career PhD researcher who has been using Python a bit, + but is not sure what they know or don't know. They want to be able + to do their research more efficiently and make sure that they are + using the right tools. A may know that numpy exists, etc. and could + theoretically read some about it themselves, but aren't sure if they + are going in the right direction. + +* A2 can use numpy and pandas, but have learned little bits here and + there and hasn't had a comprehensive introduction. They want to + ensure they are using best practices. (Baseline of high-level + packages) + +* B is a mid-to-late undergraduate student who has used Python in some + classes. They have possibly learned the syntax and enough to use it + in courses, but in a course-like manner where they are expected to + create everything themselves. + + +Motivation +========== + +Why Python +---------- + +Python has become popular, largely due to good reasons. It's very easy +to get started, there's lots of educational material, a huge amount of +libraries for doing everything imaginable. Particularly in the +scientific computing space, there is the Numpy, Scipy, and matplotlib +libraries which form the basis of almost everything. Numpy and Scipy +are excellent examples of using Python as a glue language, meaning to +glue together battle-tested and well performing code and present them +with an easy to use interface. Also machine learning and deep +learning frameworks have embraced python as the glue language of +choice. And finally, Python is open source, meaning that anybody can +download and install it on their computer, without having to bother +with acquiring a license or such. This makes it easier to distribute +your code e.g. to collaborators in different universities. + + +Why not Python for Scientific Computing +--------------------------------------- + +While Python is extremely popular in scientific computing today, there +are certainly things better left to other tools. + +- Implementing performance-critical kernels. Python is a **very** + slow language, which often doesn't matter if you can offload the + heavy lifting to fast compiled code, e.g. by using Numpy array + operations. But if what you're trying to do isn't *vectorizable* + then you're out of luck. An alternative to Python, albeit much less + mature and with a smaller ecosystem, but which provides very fast + generated code, is *Julia*. + +- Creating libraries that can be called from other languages. In this + case you'll often want to create a library with a C interface, which + can then be called from most languages. Suitable languages for this + sort of task, depending on what you are doing, could be Rust, C, + C++, or Fortran. + +- You really like static typing, or functional programming + approaches. *Haskell* might be what you're looking for. + + +Python 2 vs Python 3 +-------------------- + +There are two slightly incompatible versions of Python being used +today, 2 and 3. Most large projects have supported 3 for a long time +already, and have announced dropping Python 2 support for future +versions (or have already done so), so at this point you should use +version 3 unless you're working on an existing project that for some +reason hasn't yet been ported to version 3. Accordingly, in this +course we will use Python 3. For more info, see `Python 3 +statement `_ by many other the major +projects. + + + +Credits +======= + +This course was originally designed by Janne Blomqvist. + +In 2020 it was completely redesigned by a team of the following: + +* Authors: Radovan Bast, Richard Darst, Anne Fouilloux, ... +* Editor: +* Testers and advisors: Enrico Glerean + +We follow The Carpentries Code of Conduct: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html + diff --git a/branch/rkdarst--strict-warnings-check/_sources/installation.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/installation.rst.txt new file mode 100644 index 00000000..02dcbfd9 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/installation.rst.txt @@ -0,0 +1,133 @@ +Software installation +===================== + +This page contains instructions for installing the required software +on your computer. +Please make sure before the course that you have all the required software +installed or in any other way access to it. + +For example, the workshop could be done with a remote Jupyter +server, as long as you can use the terminal from the Jupyter (you need +to be able to access the command line sometime). + + +List of software needed during the course +------------------------------------------ + +* Zoom (not needed for 'non interactive' people following the workshop on Twitch) +* Pyhton 3 (Anaconda is suggested) + * numpy + * pandas + * scipy + * matplotlib +* Jupyter lab +* Text editor +* git + + +Python +------ + +We expect you to have a working Python installation with some common +libraries. We recommend that you install the `Anaconda python +distribution `__. For +more information on installing anaconda, you can see `the CodeRefinery +instructions `__. + +Any other Python distribution which you can install libraries into +would work, but because there are so many different ways to do this, +we don't support them. + + +Command line +~~~~~~~~~~~~ + +There are different ways to start the command line. + +* From the Anaconda Navigator: + + .. figure:: img/installation/anaconda-prompt.png + :class: with-border + + From the Anaconda Navigator, you can select "environments" on the + left, then click on one, then the arrow, then "Open terminal". + +* You can try from the Jupyter terminal. + + + +Verify the installation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. admonition:: Watch the video + + See this `verification in video form + `__ - if you can do this, you are + ready to go for day one. + +You should be able to start JupyterLab. You can do this from the +`Anaconda Navigator `__ (recommended if you have it), or from the command +line like this: + +.. code-block:: console + + $ jupyter lab + (... Jupyter starts in a web browser) + +To verify command line usage: + +.. code-block:: console + + $ python -V + Python 3.8.3 + + ## Or python3... + $ python3 -V + Python 3.8.3 + +Any version of Python 3 through Anaconda should work for the course. + + +Text editor +----------- + +For one portion of the course, you will need a text editor. If you +don't know what to use, you can use the text editor that comes from +JupyterLab and it will do everything you need. + +For other editors, see the `CodeRefinery instructions +`__. You don't +exactly need a terminal editor - the graphical ones, such as VSCode or +whatever you use now, will work as well. + + + +Command line +------------ + +See above under "command line". + +TODO. You can see the `CodeRefinery instructions +`__ for more +advanced ways of doing things. + + +git +--- + +On the very last day, we use git. See the `CodeRefinery instructions +`__. + +Verify: + +.. code-block:: console + + $ git --version + git version 2.17.1 + +Zoom +---- + +If this is an online workshop, it might use zoom. You can see +`CodeRefinery instructions for it +`__. diff --git a/branch/rkdarst--strict-warnings-check/_sources/jupyter.ipynb.txt b/branch/rkdarst--strict-warnings-check/_sources/jupyter.ipynb.txt new file mode 100644 index 00000000..9222fbab --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/jupyter.ipynb.txt @@ -0,0 +1,400 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter\n", + "\n", + "\n", + "```{questions}\n", + "\n", + " - What is the purpose of a \"Computational narrative\"?\n", + " - What role does Jupyter play in development?\n", + "```\n", + "\n", + "```{objectives}\n", + "\n", + " This part will be too easy for some people, and slow for others. Still, we need to take some time to get everyone on the same page.\n", + "\n", + " - Be able to use Jupyter to run examples for the rest of the course.\n", + " - Be able to run Jupyter in a directory do your own work.\n", + " - You won't be a Jupyter expert after this, but should be able to do the rest of the course.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is Jupyter?\n", + "\n", + "Jupyter is a web-based interactive computing system. It is most well known for having the *notebook file format* and Jupyter Notebook / Jupyter Lab. A notebook format contains both the input and the output of the code along documentation, all interleaved to create what is called a *computational narrative*.\n", + "\n", + "Jupyter is good for data exploration and interactive work, and making \n", + "\n", + "**We use Jupyter a lot in this course because it is a good way that everyone can follow along, and minimizes the differences between operating systems.**\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting started with Jupyter\n", + "\n", + "* Start JupyterLab: there are different ways. From the command line, activate your anaconda environment and run `jupyter-lab`. You can also start in from Anaconda Navigator.\n", + "\n", + "For practical purposes, JupyterLab is an integrated development environment that combines file browsing, notebooks, and code editing. There are many extensions that let you do whatever you may need." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here, we see a tour of the JupyterLab interface:\n", + "\n", + "![Main UI tour](img/jupyter/main-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{challenge} Exercises: Jupyter-1\n", + "\n", + " 1. Start Jupyter in the directory you want to use for this course.\n", + " - If you are starting from the navigator, change to the directory you want to use.\n", + " - If you are starting from the command line, you should navigate to the directory you want to use first.\n", + "\n", + " 2. Create a Python 3 notebook file. Save it. In the next section, you will add stuff to it.\n", + "\n", + " 4. (optional, but will be done in future lessons) Explore the file browser, try making some non-notebook text/py/md files and get used to that.\n", + "\n", + " 5. (optional, advanced) Look at the notebook file in a text\n", + " editor. How does it work?\n", + "\n", + "If everything works for you, this will end very quickly. You can begin reading the next sections independently.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Running code in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A notebook is divided into **cells**. Each cell has some **input**, and when it is executed an **output** appears right below it.\n", + "\n", + "There are different types of cells: primarily **code** cells and **markdown** cells. You can switch between them with the menu bar above. Code cells run whatever language your notebook uses. Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/). For example the previous sentence is:\n", + "\n", + "```\n", + "Markdown is a lightweight way of giving *style* to `text` - you can check out [this reference](https://commonmark.org/help/).\n", + "```\n", + "\n", + "![notebook UI](img/jupyter/notebook-ui.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When using keyboard shortcuts, you can switch between edit mode and command mode with `Enter` and `Esc`. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You enter code in a cell, and push the run button to run it. There are also some important shortcut keys:\n", + "* `Ctrl-Enter`: Run cell\n", + "* `Shift-Enter`: Run cell and select cell below\n", + "* `Alt-Enter`: Run cell and insert new cell below\n", + "* `a` / `b`: insert new cell above/below\n", + "* `m` / `y`: markdown cell / code cell\n", + "* `x`: delete cell" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now, let's look at some code samples:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0\n", + "1\n", + "2\n" + ] + } + ], + "source": [ + "for i in range(3):\n", + " print(i)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "10\n" + ] + } + ], + "source": [ + "print(sum(range(5)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By convention, if the last thing in a cell is an object, that object gets printed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "45" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sum(range(5))\n", + "sum(range(10))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to raw cells, there are **magics**, which exist outside of Python. They are a property of the runtime itself (in Python's case, they come from **IPython**. For example, the following cell magic `%%bash` turns the cell into a shell script (may not work on all operating systems):" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1\n", + "2\n", + "3\n" + ] + } + ], + "source": [ + "%%bash\n", + "for x in $(seq 3) ; do\n", + " echo $x\n", + "done" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "* A **cell magic** starts with `%%`, goes on the first line of a cell, and applies to the whole cell\n", + "* A **line magic** starts with `%`, goes on any line, and applies to that line." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{challenge} Exercises: Jupyter-2\n", + "\n", + " 1. Run some trivial code, such as ``print(1)``.\n", + "\n", + " 2. Run some slightly less trivial code, like print out the first\n", + " ten [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number).\n", + "\n", + " 3. Make a Markdown cell above your code cell and give it a title and some description of your function. Use the [reference](https://commonmark.org/help/) to add a heading, bullet list, and some (bold, italic, or inline code)\n", + "\n", + " 4. Use the ``%%timeit`` magic function to time your Fibonacci\n", + " function.\n", + "\n", + " 5. Again using ``%%timeit``, figure out the fastest way to sum the\n", + " numbers 0 to 1000000.\n", + " \n", + " 6. Once you are done, close your notebooks and other tabs you don't need. Check the running sessions (hint: thin left sidebar) and shut down these kernels.\n", + "```\n", + "\n", + "`````{solution} Solutions: Jupyter-2\n", + "\n", + "1. --\n", + "\n", + "2. Simple fibonacci code\n", + "\n", + " ```python\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " print(a)\n", + " a, b = b, a+b\n", + " ```\n", + "\n", + "3. Markdown description\n", + "\n", + " ```md\n", + " # Fibonacci\n", + " * Start with two variables `a` and `b`\n", + " * Repeat 10 times\n", + " * Print old `a`, then increment both\n", + " * Makes use of the Python *tuple assignment*: `a, b = new_a, new_b`\n", + " ```\n", + "\n", + "4. In this case, the print() statements get out of hand, so we comment that out. In general, writing output usually takes a lot of time reletive to the computation, so we don't want to time that (unless output is the main point of the code, then we do have to time it!\n", + "\n", + " ```ipython\n", + " %%timeit\n", + " a, b = 0, 1\n", + " for i in range(10):\n", + " #print(a)\n", + " a, b = b, a+b\n", + " ```\n", + " ```\n", + " 395 ns ± 10.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n", + " ```\n", + "\n", + "5. --\n", + "\n", + "6. --\n", + "\n", + "`````" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why Jupyter?\n", + "\n", + "- Being able to **edit, check, re-edit** quickly is great for **prototyping and testing new ideas**\n", + " - Tends to be best either at the very beginning (getting started) or data analysis/plotting phases.\n", + "- You can make a **complete story** - in one place. No more having code, figures, and description in different places.\n", + " - Instead of sending plots to your advisor, send plots, the text there, and possibility of checking the code, too.\n", + "- Notebook as an interactive publication itself - for example the discovery of gravitational waves data is [released as a notebook](https://www.gw-openscience.org/tutorials/).\n", + "- Jupyter Notebooks display on Github - low-barrier way to share your analysis.\n", + "- Teaching - great for getting difficult software distribution out of the way." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why not Jupyter?\n", + "\n", + "Jupyter is great for many things, but there are some problems if not used well:\n", + "\n", + "- They **don't promote modularity**, and once you get started in a\n", + " notebook it can be hard to migrate to modules.\n", + "- They are **difficult to test**. There are things to run notebooks as\n", + " unit tests like [nbval](https://nbval.readthedocs.io/), but it's not\n", + " perfect.\n", + "- Notebooks can be **version controlled**\n", + " ([nbdime](https://nbdime.readthedocs.io/) helps with that), but\n", + " there are **still limitations**.\n", + "- You can **change code after you run it** and run code out of order.\n", + " This can make debugging hard and results irreproducible if you\n", + " aren't careful.\n", + "- Notebooks **aren't named by default** and tend to **acquire a bunch of\n", + " unrelated stuff**. Be careful with organization!\n", + "- Once lots of code is in notebooks, it can be **hard to change to\n", + " proper programs that can be scripted**.\n", + "\n", + "You can read more about these downsides .\n", + "\n", + "**But these downsides aren't specific to Jupyter!** They can easily happen in other sources, too. By studying these, you can make any code better, and find the right balance for what you do.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{challenge} Exercises: Jupyter-3\n", + "\n", + " (optional) Discuss the following in groups:\n", + "\n", + " 1. Have any of you used Jupyter in a way that became impossible to\n", + " maintain: too many files, code all spread out, not able to find\n", + " your code and run it in the right order. How did you solve that?\n", + "\n", + " 2. On the other hand, what are your successes with Jupyter?\n", + " \n", + " 3. How can you prevent these problems by better development strategies?\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## See also\n", + "\n", + "- The [CodeRefinery Jupyter lesson](https://coderefinery.github.io/jupyter/) has much more, and the source of some of the content above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{keypoints}\n", + "\n", + " - Jupyter is powerful and can be used for most work, but not the end solution of all problems\n", + "```" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.3" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--strict-warnings-check/_sources/libraries.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/libraries.rst.txt new file mode 100644 index 00000000..90b1716e --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/libraries.rst.txt @@ -0,0 +1,178 @@ +Library ecosystem +================= + +.. questions:: + + - Q1 + - Q2 + +.. objectives:: + + - O1 + - O2 + + + +In this part, we'll talk about the broader Python and SciPy ecosystem. +It's all lecture and discussion, no hands-on. Our goal isn't to teach +you about all of these packages, or even that you remember them. +Instead, you should see how things broadly fit together and how you +can always search for something that serves your purposes. + + + +Python +------ + +The base of it all. Python is written in C, and thus has great C +interfaces. This contributes to two things: + +* **Extending Python** by writing your own modules in C. + + * It's actually common to first have (or write) an analysis package + in C or C++, then make the Python interface. Then it can be + supported by other languages, too. + +* **Embedding Python**, where you have another primary application + that uses Python under the hood. + + + +Core numerics +------------- + +* numpy +* scipy + + + +Plotting +-------- + +* matplotlib +* seaborn +* mayavi +* PIL + + + +Data analysis and other important core packages +----------------------------------------------- + +* pandas +* statsmodels +* SymPy +* networkx +* h5py and PyTables +* dateutil and pytz + + + +Interactive computing and human interface +----------------------------------------- +* Interactive computing + + * IPython + * Jupyter (notebook, lab, hub, ...) + +* Testing + + * pytest + +* Documentation + + * Sphinx + +* Development environments + + * Spyder + +* Binder + + + +Interfacing with other languages +-------------------------------- + +* ctypes +* cython +* f2py +* swig +* Boost.python +* cffi + + + +Speeding up code and parallelism +-------------------------------- +* PyMPI +* cython +* numba +* PyPy +* Dask +* Joblib +* IPyParallel +* numexpr + + + +Machine learning +---------------- + +If you need some machine learning, you probably already know what you +need and this list is short and irrelevant. + +- tensorflow +- pytorch +- nltk +- scikit-learn + + + +Your stuff +---------- + +Every small project you do contributes a little bit to the Python and +SciPy ecosystem. This course has sort of started you on that path, +and a `CodeRefinery workshop ` will make +sure you have the tools to produce high-quality, reusable code. + + + +How do you know if you should use something? +-------------------------------------------- + +Do you trust a random package you find online? Especially for your +scientific results, which *have* to be correct. Still, you also +*can't* build everything yourself, so you have to decide what point to +start with. + +* Are there releases? Have they been going on for a while? + +* Is there automated testing? + +* Is there a community, or is it one person? Is it backed by some + organization? Does it have a permanent home? + +* Is it is a public hosting site (GitLab, GitHub, Bitbucket, etc) + where a community *could* form? + +* Do others post issues and make contributions? Are these issues + dealt with in a timely manner? Can you search past bug reports? + + + + + +See also +-------- + +* `Topical Software in the SciPy ecosystem + `__ - relatively + detailed (but not comprehensive) list of projects + + +.. keypoints:: + + - K1 + - K2 diff --git a/branch/rkdarst--strict-warnings-check/_sources/numpy.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/numpy.rst.txt new file mode 100644 index 00000000..4948518a --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/numpy.rst.txt @@ -0,0 +1,450 @@ +NumPy +===== + +.. questions:: + + - Why using NumPy instead of pure python? + - How to use basic NumPy? + +.. objectives:: + + - Be able to use basic NumPy functionality + - Understand enough of NumPy to seach for answers to the rest of your questions ;) + + +So, we already know about python lists, and that we can put all kinds of things in there. +But in scientific usage, lists are often not enough. They are slow and +not very flexible. + +.. highlight:: python + +What is an array? +----------------- + +For example, consider ``[1, 2.5, 'asdf', False, [1.5, True]]`` - +this is a Python list but it has different types for every +element. When you do math on this, every element has to be handled separately. + +NumPy is the most used library for scientific computing. +Even if you are not using it directly, chances are high that some library uses it in the background. +NumPy provides the high-performance multidimensional array object and tools to use it. + +An array is a 'grid' of values, with all the same types. It is indexed by tuples of +non negative indices and provides the framework for multiple +dimensions. An array has: + +* ``dtype`` - data type. Arrays always contain one type +* ``shape`` - shape of the data, for example ``3×2`` or ``3×2×500`` or even + ``500`` (one dimensional) or ``[]`` (zero dimensional). +* ``data`` - raw data storage in memory. This can be passed to C or + Fortran code for efficient calculations. + + +To test the performance of pure Python vs NumPy we can write in our jupyter notebook: + +Create one list and one 'empty' list, to store the result in :: + + a = list(range(10000)) + b = [ 0 ] * 10000 + +In a new cell starting with ``%%timeit``, loop through the list ``a`` and fill the second list ``b`` with ``a`` squared :: + + %%timeit + for i in range(len(a)): + b[i] = a[i]**2 + +That looks and feels quite fast. But let's take a look at how NumPy performs for the same task. + +So for the NumPy example, create one array and one 'empty' array to store the result in :: + + import numpy as np + a = np.arange(10000) + b = np.zeros(10000) + +In a new cell starting with ``%%timeit``, fill ``b`` with ``a`` squared :: + + %%timeit + b = a ** 2 + +We see that compared to working with numpy arrays, working with traditional python lists is actually slow. + + +Creating arrays +--------------- + +There are different ways of creating arrays:: + + a = np.array([1,2,3]) # 1-dimensional array (rank 1) + b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2) + + b.shape # the shape (rows,columns) + b.size # number of elements + +In addition to above ways of creating arrays, there are many other ways of creating arrays depending on content:: + + np.zeros((2, 3)) # 2x3 array with all elements 0 + np.ones((1,2)) # 1x2 array with all elements 1 + np.full((2,2),7) # 2x2 array with all elements 7 + np.eye(2) # 2x2 identity matrix + + np.arange(10) # Evenly spaced values in an interval + np.linspace(0,9,10) # same as above, see exercise + + c = np.ones((3,3)) + d = np.ones((3, 2), bool) # 3x2 boolean array + +Arrays can also be stored and read from a (.npy) file:: + + np.save('x.npy', a) # save the array a to a .npy file + x = np.load('x.npy') # load an array from a .npy file and store it in variable x + +In many occasions (especially when something goes different than expected) it is useful to check and control the datatype of the array:: + + d.dtype # datatype of the array + d.astype('int') # change datatype from boolean to integer + +In the last example, ``.astype('int')``, it will make a **copy** of the +array, and re-allocate data - unless the dtype is exactly the same as +before. Understanding and minimizing copies is one of the most +important things to do for speed. + + +.. challenge:: Exercises: Numpy-1 + + - **Datatypes** Try out ``np.arange(10)`` and ``np.linspace(0,9,10)``, what is the difference? Can you adjust one to do the same as the other? + + - **Datatypes** Create a 3x2 array of random float numbers (check ``np.random``) between 0 and 1. Now change the arrays datatype to int (``array.astype``). How does the array look like? + + - **Reshape** Create a 3x2 array of random integer numbers between 0 and 10. Reshape the array in any way possible. What is not possible? + + - **NumPyI/O** Save above array to .npy file (``np.save``) and read it in again. + +.. solution:: Solutions: Numpy-1 + + - **Datatypes** ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**, + while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**. + Both ``np.linspace`` and ``np.arange`` take dtype as an argument and can be adjusted to match each other in that way. + + - **Datatypes** eg ``a = np.random.random((3,2))``. ``a.astype('int')`` results in an all zero array, not as maybe expected the rounded int. + + - **Reshape** eg ``b = np.random.randint(0,10,(3,2))``. ``b.reshape((6,1))`` and ``b.reshape((2,3))`` possible. It is not possible to reshape to shapes using more or less elements than ``b.size = 6``. + + - **NumPyI/O** ``np.save('x.npy', b)`` and ``x = np.load('x.npy')`` + + + +Array maths +------------ + +Clearly, you can do math on arrays. Math in NumPy, is very fast +because it is implemented in C or Fortran - just like most other +high-level languages such as R, Matlab, etc do. + +By default, in NumPy all math is element-by-element. This is unlike +Matlab, where most things are element-by-element, but ``*`` becomes +array multiplication. NumPy values consistency and does not treat +2-dimensional arrays specially:: + + a = np.array([[1,2],[3,4]]) + b = np.array([[5,6],[7,8]]) + + c = a + b + d = np.add(a,b) + +Also: - (``np.subtract()``), * (``np.multiply()``), / (``np.divide()``), ``np.sqrt()``, ``np.sum()``, ``np.mean()``, ... + + +.. challenge:: Exercises: Numpy-2 + + - **Matrix multiplication** What is the difference between ``np.multiply`` and ``np.dot`` ? Try it. + - **Axis** What is the difference between ``np.sum(axis=1)`` vs + ``np.sum(axis=0)`` on a two-dimensional array? What if you leave out the axis parameter? + + +.. solution:: Solutions: Numpy-2 + + - **Matrix multiplication** ``np.multiply`` does elementwise multiplication on two arrays, while ``np.dot`` enables matrix multiplication. + - **Axis** ``axis=1`` does the operation (here: ``np.sum``) over each row, while axis=0 does it over each column. If axis is left out, the sum of the full array is given. + + + +Indexing and Slicing +-------------------- + +NumPy has many ways to extract values out of arrays: + +- You can select a single element +- You can select rows or columns +- You can select ranges where a condition is true. + +Clever and efficient use of these operations is a key to NumPy's +speed: you should try to cleverly use these selectors (written in C) +to extract data to be used with other NumPy functions written in C or +Fortran. This will give you the benefits of Python with most of the +speed of C. + +:: + + a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15 + a[0] # first row + a[:,0] # first column + a[1:3,1:3] # middle 2x2 array + + a[(0, 1), (1, 1)] # second element of first and second row as array + +Boolean indexing on above created array:: + + idx = (a > 0) # creates boolean matrix of same size as a + a[idx] # array with matching values of above criterion + + a[a > 0] # same as above in one line + + +.. challenge:: Exercise: Numpy-3 + + :: + + a = np.eye(4) + b = a[:,0] + b[0] = 5 + + - **View vs copy** Try out above code. How does ``a`` look like before ``b`` has changed and after? How could it be avoided? + +.. solution:: Solution: Numpy-3 + + - **View vs copy** The change in ``b`` has also changed the array ``a``! + This is because ``b`` is merely a view of a part of array ``a``. Both + variables point to the same memory. Hence, if one is changed, the other + one also changes. If you need to keep the original array as is, use + ``np.copy(a)``. + + +Types of operations +------------------- + +There are different types of standard operations in NumPy: + +**ufuncs**, "universal functions": These are element-by-element +functions with standardized arguments: + +- One, two, or three input arguments +- For example, ``a + b`` is similar to ``np.add(a, b)`` but the ufunc + has more control. +- ``out=`` output argument, store output in this array (rather than + make a new array) - saves copying data! +- See the `full reference + `__ + +- They also do **broadcasting**. Can you add a 1-dimensional array of shape `(3)` + to an 2-dimensional array of shape `(3, 2)`? With broadcasting you + can! + + :: + + a = np.array([[1, 2, 3], + [4, 5, 6]]) + b = np.array([10, 10, 10]) + a + b # array([[11, 12, 13], + # [14, 15, 16]]) + + Broadcasting is smart and consistent about what it does, which I'm + not clever enough to explain quickly here: `the manual page on + broadcasting + `__. + The basic idea is that it expands dimensions of the smaller array so + that they are compatible in shape. + +**Array methods** do something to one array: + +- Some of these are the same as ufuncs:: + + x = np.arange(12) + x.shape = (3, 4) + x # array([[ 0, 1, 2, 3], + # [ 4, 5, 6, 7], + # [ 8, 9, 10, 11]]) + x.max() # 11 + x.max(axis=0) # array([ 8, 9, 10, 11]) + x.max(axis=1) # array([ 3, 7, 11]) + +**Other functions**: there are countless other functions covering +linear algebra, scientific functions, etc. + + +.. challenge:: Exercises: Numpy-4 + + - **In-place addition**: Create an array, add it to itself using a + ufunc. + + - **In-place addition** (advanced): Create an array of + ``dtype='float'``, and an array of ``dtype='int'``. Try to use the + int array is the output argument of the first two arrays. + +.. solution:: Solution: Numpy-4 + + - **in-place addition**:: + + x = np.array([1, 2, 3]) + id(x) # get the memory-ID of x + np.add(x, x, x) # Third argument is output array + np.add(x, x, x) + print(x) + id(x) # get the memory-ID of x + # - notice it is the same + + You note that ``np.add()`` has a third argument that is the + output array (same as ``out=``), *and* the function returns that + same array. + + + +Linear algebra and other advanced math +-------------------------------------- + +In general, you use ``arrays`` (n-dimensions), not ``matrixes`` +(specialized 2-dimensional) in NumPy. + +Internally, NumPy doesn't invent its own math routines: it relies on +`BLAS +`__ +and `LAPACK `__ to do this kind +of math - the same as many other languages. + +- `Linear algebra in numpy + `__ + +- `Many, many other array functions + `__ + +- `Scipy `__ has even + more functions + +- Many other libraries use NumPy arrays as the standard data + structure: they take data in this format, and return it similarly. + Thus, all the other packages you may want to use are compatible + +- If you need to write your own fast code in C, NumPy arrays can be + used to pass data. This is known as `extending Python + `__. + + + + +Additional Exercises Numpy-6 +---------------------------- + +These are advanced and optional, and will not be done in most courses. + +1. Reverse a vector. Given a vector, reverse it such that the last + element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]`` + +2. Create a 2D array with zeros on the borders and 1 inside. + +3. Create a random array with elements [0, 1), then add 10 to all + elements in the range [0.2, 0.7). + +4. What is ``np.round(0.5)``? What is ``np.round(1.5)``? Why? + +5. In addition to ``np.round``, explore ``np.ceil``, ``np.floor``, + ``np.trunc``. In particular, take note of how they behave with + negative numbers. + +6. Recall the identity :math:`\sin^2(x) + \cos^2(x) = 1`. Create a + random 4x4 array with values in the range [0, 10). Now test the + equality with ``np.equal``. What result do you get with + ``np.allclose`` instead of ``np.equal``? + +7. Create a 1D array with 10 random elements. Sort it. + +8. What's the difference between ``np_array.sort()`` and + ``np.sort(np_array)``? + +9. For the random array in question 8, instead of sorting it, perform + an indirect sort. That is, return the list of indices which would + index the array in sorted order. + +10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next + combine them into a single 8x4 array with the content of the zeros + array on top and the ones on the bottom. Finally, do the same, + but create a 4x8 array with the zeros on the left and the ones on + the rigth. + +11. NumPy functionality Create two 2D arrays and do matrix multiplication + first manually (for loop), then using the np.dot function. Use %%timeit + to compare execution times. What is happening? + + +.. solution:: Solution Numpy-7 + + 1. One solution is:: + + a = np.array([1, 2, 3]) + a[::-1] + + 2. One solution is:: + + b = np.ones((10,10)) + b[:,[0, -1]]=0 + b[[0, -1],:]=0 + + 3. A possible solution is:: + + x = np.random.rand(100) + y = x + 10*(x >= 0.2)*(x < 0.7) + + 4. For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. + + 5. Let's test those functions with few negative and positive values:: + + a = np.array([-3.3, -2.5, -1.5, -0.75, -0.5, 0.5, 0.75, 1.5, 2.5, 3]) + np.round(a) + np.ceil(a) + np.floor(a) + np.trun(a) + + 6. One solution is:: + + x = 10*np.random.rand(4,4) + oo = np.ones((4,4)) + s2c2 = np.square(np.sin(x))+np.square(np.cos(x)) + np.equal(oo,s2c2) + np.allclose(oo,s2c2) + + 7. Sorting the array itself, without copying it:: + + x = np.random.rand(10) + x.sort() + + 8. NumPy.sort() returns a sorted copy of an array. + + 9. ``np.argsort(x)`` + + 10. One solution is:: + + z = np.zeros((4,4)) + o = np.ones((4,4)) + np.concatenate((z,o)) + np.concatenate((z,o),axis=1) + + 11. Using numpy without numpy functionality (np.dot) in this case, is still slow. + + + +See also +-------- + +* `NumPy manual `__ + + * `Basic array class reference `__ + * `Indexing + `__ + * `ufuncs `__ + +* `2020 Nature paper on NumPy's role and basic concepts `__ + + + +.. keypoints:: + + - NumPy is a powerful library every scientist using python should know about, since many other libraries also use it internally. + - Be aware of some NumPy specific peculiarities diff --git a/branch/rkdarst--strict-warnings-check/_sources/packaging.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/packaging.rst.txt new file mode 100644 index 00000000..bda67d33 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/packaging.rst.txt @@ -0,0 +1,167 @@ +Packaging +========= + +.. questions:: + + - How to organize larger Python projects? + - How can you make your Python functions most usable by your collaborators? + - How to prepare your code to make a Python package? + - How to publish your Python package? + +.. objectives:: + + - Learn to identify the components of a Python package + - Learn to create a Python package + - Learn to publish a Python package + + +Organizing Python projecs into modules +-------------------------------------- + +what is ``__init__.py`` and relative imports. + + +Best practices +-------------- + +- Add a license to your code (See `Software Licensing and Open source explained with cakes `__) +- Write a `README.md` file + +It is also recommended to `document your package `__. + +Birds-eye view of PyPI, pip, and Conda +-------------------------------------- + + +Python packages +--------------- + +.. challenge:: Packaging 1 + + TODO: - Create a very simple Python package and make it pip-installable + - Test to install it locally + + +Submit your package to PyPI +--------------------------- + +TODO: +- Show what is required. Remind about the importance of documentation, license, etc. +- Test-PyPI + + +Tools that simplify sharing via PyPI +------------------------------------ + +- poetry +- flit + + +Building a conda package and share it +------------------------------------- + +.. callout:: Prerequisites + + To create a conda package, `conda-build` package is required. You may install it with **Anaconda Navigator** or from the command line:: + + conda install conda-build + + +The simplest way for creating a conda package for your python script is to first publish it in `PyPI `__ following the steps explained above. + +Building a python package with conda skeleton pypi +*************************************************** + +Once build, the conda package can be installed locally. For this example, we will use `runtest `__. +`runtest `__ is a numerically tolerant end-to-end test library for research software. + +1. Create pypi skeleton:: + + conda skeleton pypi runtest + + The command above will create a new folder called `runtest` containing a file `meta.yaml`, the conda recipe for `runtest`. + +2. Edit `meta.yaml` and update requirements:: + + requirements: + host: + - pip + - python + - flit + run: + - python + - flit + + In the requirements above, we specified what is required for the `host `__ and for `running `__ the package. + + .. callout:: Remark + + For pure python recipes, this is all you need for building a python package with conda. + If your package needs to be built (for instance compilation), you would need additional files e.g. `build.sh` (to build on Linux/Mac-OSX) and `bld.bat` (to build on Windows systems). You can also add test scripts for testing your package. See `documentation `__ + + +3. Build your package with conda + + Your package is now ready to be build with conda:: + + conda-build runtest + + + .. callout:: Conda package location + + Look at the messages produced while building. The location of the local conda package is given (search for `anaconda upload`):: + + ~/anaconda3/conda-bld/win-64/runtest-2.2.1-py38_0.tar.bz2 + + The prefix `~/anaconda3/` may be different on your machine and depending on your operating system (Linux, Mac-OSX or Windows) the sub-folder `win-64` differs too (for instance `linux-64` on Linux machines). + + The conda package we have created is specific to your platform (here `win-64`). It can be converted to other platforms using `conda convert `__. + +4. Check within new environment + + It is not necessary to create a new conda environment to install it but as explained in previous episode, it is good practice to have isolated environments. + + :: + + conda create -n local-runtest --use-local runtest + + We can then check `runtest` has been successfully installed in `local-runtest` conda environment. Open a new Terminal with `local-runtest` environment (either from the command line:: + + conda activate local-runtest + + or via **Anaconda Navigator** (Open Terminal), import runtest and check its version:: + + import runtest + print(runtest.__version__) + + +.. callout:: Building a conda package from scratch + + It is possible to build a conda package from scratch without using conda skeleton. We recommend you to check the `conda-build documentation `__ for more information. + +To be able to share and install your local conda package anywhere (on other platforms), you would need to upload it to a `conda channel `__ (see below). + + + +Publishing a python package +**************************** + +- Upload your package to *Anaconda.org*: see instructions `here `__. Please note that you will have to create an account on Anaconda. + +- Upload your package to `conda-forge `__: conda-forge is a conda channel: it contains community-led collection of recipes, build infrastructure and distributions for the conda package manager. Anyone can public conda packages to conda-forge if certain `guidelines `__ are respected. + +- Upload your package to `bioconda `_: bioconda is a very popular channel for the conda package manager specializing in bioinformatics software. As for conda-forge, you need to follow their `guidelines `__ when building conda recipes. + +You can also `create your own conda channel `__ for publishing your packages. + +Version pinning +--------------- + +When to pin and when not to pin. + + +.. keypoints:: + + - Organize your code for publishing + - Pypi + - conda diff --git a/branch/rkdarst--strict-warnings-check/_sources/pandas.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/pandas.rst.txt new file mode 100644 index 00000000..a3b406c4 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/pandas.rst.txt @@ -0,0 +1,383 @@ +Pandas +====== + +.. questions:: + + - How do I learn a new Python package? + - How can I use pandas dataframes in my research? + +.. objectives:: + + - Learn simple and some more advanced usage of pandas dataframes + - Get a feeling for when pandas is useful and know where to find more information + + +Pandas is a Python package that provides high-performance and easy to use +data structures and data analysis tools. +This page provides a brief overview of pandas, but the open source community +developing the pandas package has also created excellent documentation and training +material, including: + +- a `Getting started guide `__ + (including tutorials and a 10 minute flash intro) +- a `"10 minutes to pandas" `__ + tutorial +- thorough `Documentation `__ containing a user guide, + API reference and contribution guide +- a `cheatsheet `__ +- a `cookbook `__. + +Let's get a flavor of what we can do with pandas. We will be working with an +example dataset containing the passenger list from the Titanic, which is often used in Kaggle competitions and data science tutorials. First step is to load pandas:: + + import pandas as pd + +We can download the data from `this GitHub repository `__ +by visiting the page and saving it to disk, or by directly reading into +a **dataframe**:: + + url = "https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/data/titanic.csv" + titanic = pd.read_csv(url) + +We can now view the dataframe to get an idea of what it contains and +print some summary statistics of its numerical data:: + + # print the first 5 lines of the dataframe + titanic.head() + + # print summary statistics for each column + titanic.describe() + + +Ok, so we have information on passenger names, survival (0 or 1), age, +ticket fare, number of siblings/spouses, etc. With the summary statistics we see that the average age is 29.7 years, maximum ticket price is 512 USD, 38\% of passengers survived, etc. + +Let's say we're interested in the survival probability of different age groups. With two one-liners, we can find the average age of those who survived or didn't survive, and plot corresponding histograms of the age distribution:: + + print(titanic.groupby("Survived")["Age"].mean()) + +:: + + titanic.hist(column='Age', by='Survived', bins=25, figsize=(8,10), + layout=(2,1), zorder=2, sharex=True, rwidth=0.9); + + +Clearly, pandas dataframes allows us to do advanced analysis with very few commands, but it takes a while to get used to how dataframes work so let's get back to basics. + + +What's in a dataframe? +---------------------- + +As we saw above, pandas dataframes are a powerful tool for working with tabular data. +A pandas +`DataFrame object `__ +is composed of rows and columns: + +.. image:: img/pandas/01_table_dataframe.svg + +Each column of a dataframe is a +`series object `__ +- a dataframe is thus a collection of series. Let's inspect one column of +the Titanic passanger list data (first downloading and reading the +titanic.csv datafile into a dataframe if needed, see above):: + + titanic["Age"] + titanic.Age # same as above + type(titanic["Age"]) + +The columns, rows and dtypes can be listed through corresponding +attributes:: + + titanic.columns + titanic.index + titanic.dtypes + +We saw above how to select a single column, but there are other ways of selecting +(and setting) single or multiple rows, columns and values:: + + titanic.at[0,"Age"] # select single value by row and column *name* (fast) + titanic.at[0,"Age"] = 42 # set single value by row and column *name* (fast) + titanic.iat[0,5] # select same value by row and column *number* (fast) + titanic.loc[0:2, "Name":"Age"] # slice the dataframe by row and column *names* + titanic.iloc[0:2,3:6] # same slice as above by row and column *numbers* + titanic["foo"] = "bar" # set a whole column + +Dataframes also support boolean indexing, just like we saw for ``numpy`` +arrays:: + + titanic[titanic["Age"] > 70] + # ".str" creates a string object from a column + titanic[titanic["Name"].str.contains("Margaret")] + +What if your dataset has missing data? Pandas uses the value ``np.nan`` +to represent missing data, and by default does not include it in any computations. +We can find missing values, drop them from our dataframe, replace them +with any value we like or do forward or backward filling:: + + titanic.isna() # returns boolean mask of NaN values + titanic.dropna() # drop missing values + titanic.dropna(how="any") # or how="all" + titanic.dropna(subset=["Cabin"]) # only drop NaNs from one column + titanic.fillna(0) # replace NaNs with zero + titanic.fillna(method='ffill') # forward-fill NaNs + + +.. callout:: Getting help + + Series and DataFrames have a lot functionality, but + how can we find out what methods are available and how they work? One way is to visit + the `API reference `__ + and reading through the list. + Another way is to use the autocompletion feature in Jupyter and type e.g. + ``titanic["Age"].`` in a notebook and then hit ``TAB`` twice - this should open + up a list menu of available methods and attributes. + + Jupyter also offers quick access to help pages (docstrings) which can be + more efficient than searching the internet. Two ways exist: + + - Write a function name followed by question mark and execute the cell, e.g. + write ``titanic.hist?`` and hit ``SHIFT + ENTER``. + - Write the function name and hit ``SHIFT + TAB``. + +.. challenge:: Exploring dataframes + + - Have a look at the available methods and attributes using the + `API reference `__ + or the autocomplete feature in Jupyter. + - Try out a few methods using the Titanic dataset and have a look at + the docstrings (help pages) of methods that pique your interest + - Compute the mean age of the first 10 passengers by slicing and the ``mean`` method + - (Advanced) Using boolean indexing, compute the survival rate + (mean of "Survived" values) among passengers over and under the average age. + +.. solution:: + + - Mean age of the first 10 passengers: ``titanic.iloc[:10,:]["Age"].mean()`` + or ``titanic.loc[:9,"Age"].mean()`` or ``df.iloc[:10,5].mean()``. + - Survival rate among passengers over and under average age: + ``titanic[titanic["Age"] > titanic["Age"].mean()]["Survived"].mean()`` and + ``titanic[titanic["Age"] < titanic["Age"].mean()]["Survived"].mean()``. + + +Tidy data +--------- + +The above analysis was rather straightforward thanks to the fact +that the dataset is *tidy*. + +.. image:: img/pandas/tidy_data.png + +In short, columns should be variables and rows should be measurements, +and adding measurements (rows) should then not require any changes to code +that reads the data. + +What would untidy data look like? Here's an example from +some run time statistics from a 1500 m running event:: + + df = pd.DataFrame([ + {'Runner': 'Runner 1', 400: 64, 800: 128, 1200: 192, 1500: 240}, + {'Runner': 'Runner 2', 400: 80, 800: 160, 1200: 240, 1500: 300}, + {'Runner': 'Runner 3', 400: 96, 800: 192, 1200: 288, 1500: 360}, + ]) + +To make untidy data tidy, a common operation is to "melt" it, +which is to convert it from wide form to a long form:: + + df = pd.melt(df, id_vars="Runner", + value_vars=[400, 800, 1200, 1500], + var_name="distance", + value_name="time" + ) + +In this form it's easier to **filter**, **group**, **join** +and **aggregate** the data, and it's also easier to model relationships +between variables. + +The opposite of melting is to *pivot* data, which can be useful to +view data in different ways as we'll see below. + +For a detailed exposition of data tidying, have a look at +`this article `__. + + + +Working with dataframes +----------------------- + +We saw above how we can read in data into a dataframe using the ``read_csv`` method. +Pandas also understands multiple other formats, for example using ``read_excel``, +``read_hdf``, ``read_json``, etc. (and corresponding methods to write to file: +``to_csv``, ``to_excel``, ``to_hdf``, ``to_json``, etc.) + +But sometimes you would want to create a dataframe from scratch. Also this can be done +in multiple ways, for example starting with a numpy array:: + + dates = pd.date_range('20130101', periods=6) + df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list('ABCD')) + +or a dictionary:: + + df = pd.DataFrame({'A': ['foo', 'bar', 'foo', 'bar', 'foo', 'bar', 'foo', 'foo'], + 'B': ['one', 'one', 'two', 'three', 'two', 'two', 'one', 'three'], + 'C': np.array([3] * 8, dtype='int32'), + 'D': np.random.randn(8), + 'E': np.random.randn(8)}) + +There are many ways to operate on dataframes. Let's look at a +few examples in order to get a feeling of what's possible +and what the use cases can be. + +We can easily split and concatenate or append dataframes:: + + sub1, sub2, sub3 = df[:2], df[2:4], df[4:] + pd.concat([sub1, sub2, sub3]]) + sub1.append([sub2, sub3]) # same as above + +Dataframes can also be merged similarly to in SQL:: + + m1 = df.loc[:3, "A":"B"] + m2 = df.loc[3:6, ["A", "D", "E"]] + # merge two dataframes on column "A" + pd.merge(m1, m2, on="A") + +In fact, much of what can be done in SQL +`is also possible with pandas `__. + +Functions can be applied to a whole dataframe or parts of it:: + + df.apply(np.cumsum) # you can also pass your own custom functions + df.loc[:, "C":"E"].apply(np.cumsum) + +Most common statistical functions are in fact already available +as dataframe methods, like ``std()``, ``min()``, ``max()``, +``cumsum()``, ``median()``, ``skew()``, ``var()`` etc. + +``pivot_table()`` and ``groupby()`` are two powerful methods which +are applied to dataframes to split and aggregate data in groups. +They work similarly but differ in the shape of the result. +To see what's possible, let's return to the Titanic dataset. +We start by rounding all ages to the nearest decade and then create +a pivot table showing the mean of fares split by gender and survival:: + + titanic["Age"] = titanic["Age"].round(-1) + pd.pivot_table(titanic, values="Fare", index=["Sex", "Survived"], + columns=["Age"], aggfunc=np.mean) + +The same operation with group-by is:: + + titanic.groupby(["Sex", "Survived", "Age"])["Fare"].mean() + + +.. challenge:: Analyze the Titanic passenger list dataset + + In the Titanic passenger list dataset, + investigate the family size of the passengers (i.e. the "SibSp" column). + + - What different family sizes exist in the passenger list? Hint: try the `unique` method + - What are the names of the people in the largest family group? + - (Advanced) Create histograms showing the distribution of family sizes for + passengers split by the fare, i.e. one group of high-fare passengers (where + the fare is above average) and one for low-fare passengers + (Hint: you can use the lambda function + ``lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich"``) + +.. solution:: Solution + + - Existing family sizes: ``df["SibSp"].unique()`` + - Names of members of largest family(ies): ``df[df["SibSp"] == 8]["Name"]`` + - ``df.hist("SibSp", lambda x: "Poor" if df["Fare"].loc[x] < df["Fare"].mean() else "Rich", rwidth=0.9)`` + + + + +Time series superpowers +----------------------- + +An introduction of pandas wouldn't be complete without mention of its +special abilities to handle time series. To show just a few examples, +we will use a new dataset of Nobel prize laureates:: + + nobel = pd.read_csv("http://api.nobelprize.org/v1/laureate.csv") + nobel.head() + +This dataset has three columns for time, "born"/"died" and "year". +These are represented as strings and integers, respectively, and +need to be converted to datetime format:: + + # the errors='coerce' argument is needed because the dataset is a bit messy + nobel["born"] = pd.to_datetime(nobel["born"], errors ='coerce') + nobel["died"] = pd.to_datetime(nobel["died"], errors ='coerce') + nobel["year"] = pd.to_datetime(nobel["year"], format="%Y") + +Pandas knows a lot about dates:: + + print(nobel["born"].dt.day) + print(nobel["born"].dt.year) + print(nobel["born"].dt.weekday) + +We can add a column containing the (approximate) lifespan in years rounded +to one decimal:: + + nobel["lifespan"] = round((nobel["died"] - nobel["born"]).dt.days / 365, 1) + +and then plot a histogram of lifespans:: + + nobel.hist(column='lifespan', bins=25, figsize=(8,10), rwidth=0.9) + +Finally, let's see one more example of an informative plot +produced by a single line of code:: + + nobel.boxplot(column="lifespan", by="category") + +.. challenge:: Analyze the Nobel prize dataset + + - What country has received the largest number of Nobel prizes, and how many? + How many countries are represented in the dataset? Hint: use the `describe()` method + on the ``bornCountryCode`` column. + - Create a histogram of the age when the laureates received their Nobel prizes. + Hint: follow the above steps we performed for the lifespan. + - List all the Nobel laureates from your country. + + Now more advanced steps: + + - First add a column “number” to the nobel dataframe containing 1’s + (to enable the counting below). + - Now define an array of 4 countries of your choice and extract + only laureates from these countries:: + + countries = np.array([COUNTRY1, COUNTRY2, COUNTRY3, COUNTRY4]) + subset = nobel.loc[nobel['bornCountry'].isin(countries)] + + - Create a pivot table to view a spreadsheet like structure, and view it:: + + table = subset.pivot_table(values="number", index="bornCountry", columns="category", aggfunc=np.sum) + + - (Optional) Install the **seaborn** visualization library if you don't + already have it, and create a heatmap of your table:: + + import seaborn as sns + sns.heatmap(table,linewidths=.5); + + - Play around with other nice looking plots:: + + sns.violinplot(y="year", x="bornCountry",inner="stick", data=subset); + + :: + + sns.swarmplot(y="year", x="bornCountry", data=subset, alpha=.5); + + :: + + subset_physchem = nobel.loc[nobel['bornCountry'].isin(countries) & (nobel['category'].isin(['physics']) | nobel['category'].isin(['chemistry']))] + sns.catplot(x="bornCountry", y="year", col="category", data=subset_physchem, kind="swarm"); + + :: + + sns.catplot(x="bornCountry", col="category", data=subset_physchem, kind="count"); + + + +.. keypoints:: + + - pandas dataframes are a good data structure for tabular data + - Dataframes allow both simple and advanced analysis in very compact form diff --git a/branch/rkdarst--strict-warnings-check/_sources/parallel-pi-multiprocessing.ipynb.txt b/branch/rkdarst--strict-warnings-check/_sources/parallel-pi-multiprocessing.ipynb.txt new file mode 100644 index 00000000..970dbada --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/parallel-pi-multiprocessing.ipynb.txt @@ -0,0 +1,303 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Python multithreading solution\n", + "Here, we will create a simple stochastic calculation of pi, and then parallelize it using multiprocessing (and multithreading to compare)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import random" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "def sample(n):\n", + " \"\"\"Make n trials of points in the square. Return (n, number_in_circle)\n", + " \n", + " This is our basic function. By design, it returns everything it\\\n", + " needs to compute the final answer: both n (even though it is an input\n", + " argument) and n_inside_circle. To compute our final answer, all we\n", + " have to do is sum up the n:s and the n_inside_circle:s and do our\n", + " computation\"\"\"\n", + " n_inside_circle = 0\n", + " for i in range(n):\n", + " x = random.random()\n", + " y = random.random()\n", + " if x**2 + y**2 < 1.0:\n", + " n_inside_circle += 1\n", + " return n, n_inside_circle" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "598 ms ± 29.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it just for timing\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Do the actual calculation (the previous result doesn't get saved)\n", + "n, n_inside_circle = sample(10**6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is the \"calculate answer\" phase." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.144548" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "pi = 4.0 * (n_inside_circle / n)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in parallel with multiprocessing\n", + "This divides the calculation into 10 tasks and runs `sample` on each of them. Then it re-combines the results." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import multiprocessing.pool\n", + "pool = multiprocessing.pool.Pool()\n", + "# The default pool makes one process per CPU" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "320 ms ± 38.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + } + ], + "source": [ + "%%timeit\n", + "# Do it once to time it\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = pool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "pool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.140768" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do it in \"parallel\" with threads\n", + "To compare. This should not be any faster, because the multiple Python functions can not run at the same time in the same process." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool = multiprocessing.pool.ThreadPool()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "635 ms ± 28.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n" + ] + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%timeit -o\n", + "# Do it once to time it\n", + "threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "# Do it again to get the results, since the results of the above\n", + "# cell aren't accessible because of the %%timeit magic.\n", + "results = threadpool.map(sample, [10**5] * 10)" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [], + "source": [ + "threadpool.close()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "3.142388" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "n_sum = sum(x[0] for x in results)\n", + "n_inside_circle_sum = sum(x[1] for x in results)\n", + "pi = 4.0 * (n_inside_circle_sum / n_sum)\n", + "pi" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Future ideas\n", + "\n", + "You could make a separate `calculate` function that take a list of results and returns pi. This can be used regardless of if it is done with multiprocessing or without.\n", + "\n", + "Notice the similarity to [split-apply-combine](https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html) or [map-reduce](https://en.wikipedia.org/wiki/MapReduce) which is a specialization of split-apply-combine." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/branch/rkdarst--strict-warnings-check/_sources/parallel.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/parallel.rst.txt new file mode 100644 index 00000000..457ffc9b --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/parallel.rst.txt @@ -0,0 +1,375 @@ +Parallel programming +==================== + +.. questions:: + + - When you need more than one processor, what do you do? + - How can we use more than one processor/core in Python? + +.. objectives:: + + - Understand the major strategies of parallelizing code + - Understand mechanics of the ``multiprocessing`` package + - Know when to use more advanced packages or approaches + + + +Modes of parallelism +-------------------- + +You realize you do have more computation to do than you can on one processor? +What do you do? + +1. Profile your code, identify the *actual* slow spots. + +2. Can you improve your code in those areas? Use an existing library? + +3. Are there are any low-effort optimizations that you can make? + +4. Think about parallelizing. + + +Many times in science, you want to parallelize your code: either if the computation +takes too much time on one core or when the code needs to be parallel to even +be allowed to run on a specific hardware (e.g. supercomputers). + +**Parallel computing** is when many different tasks are carried out +simultaneously. There are three main models: + +* **Embarrassingly parallel:** the code does not need to synchronize/communicate + with other instances, and you can run + multiple instances of the code separately, and combine the results + later. If you can do this, great! (array jobs, task queues) + +* **Shared memory parallelism:** Parallel threads need to communicate and do so via + the same memory (variables, state, etc). (OpenMP) + +* **Message passing:** Different processes manage their own memory segments. They share data + by communicating (passing messages) as needed. (Message Passing Interface (MPI)). + +Programming shared memory or message passing is beyond the scope of +this course, but the simpler strategies are most often used anyway. + +.. warning:: + + Parallel programming is not magic, but many things can go wrong and + you can get unexpected results or difficult to debug problems. + Parallel programming is a fascinating world to get involved in, but + make sure you invest enough time to do it well. + + See the video by Raymond Hettinger ("See Also" at bottom + of page) for an entertaining take on this. + + + +Multithreading and the GIL +-------------------------- + +The designers of the Python language made the choice +that **only one thread in a process can run actual Python code** +by using the so-called **global interpreter lock (GIL)**. +This means that approaches that may work in other languages (C, C++, Fortran), +may not work in Python without being a bit careful. +At first glance, this is bad for parallelism. *But it's not all bad!:* + +* External libraries (NumPy, SciPy, Pandas, etc), written in C or other + languages, can release the lock and run multi-threaded. Also, most + input/output releases the GIL, and input/output is slow. + +* If speed is important enough you need things parallel, you usually + wouldn't use pure Python. + +We won't cover threading in this course. + +.. seealso:: + + * `More on the global interpreter lock + `__ + * `Threading python module + `__. This is + very low level and you shouldn't use it unless you really know what + you are doing. + * We recommend you find a UNIX threading tutorial first before embarking + on using the `threading + `__ module. + + + +multiprocessing +--------------- + +As opposed to threading, Python has a reasonable way of doing +something similar that uses multiple processes: the +:py:mod:`multiprocessing` module. + +* The interface is a lot like threading, but in the background creates + new processes to get around the global interpreter lock. + +* There are low-level functions which have a lot of the same risks and + difficulties as when using :py:mod:`threading`. + +To show an example, +the `split-apply-combine `__ +or `map-reduce `__ paradigm is +quite useful for many scientific workflows. Consider you have this:: + + def square(x): + return x*x + +You can apply the function to every element in a list using the +:py:func:`map` function: + +.. code-block:: pycon + + >>> list(map(square, [1, 2, 3, 4, 5, 6])) + [1, 4, 9, 16, 25, 36] + +The :py:class:`multiprocessing.pool.Pool` class provides an equivalent but +parallelized (via multiprocessing) way of doing this. The pool class, +by default, creates one new process per CPU and does parallel +calculations on the list: + +.. code-block:: pycon + + >>> from multiprocessing import Pool + >>> with Pool() as pool: + ... pool.map(square, [1, 2, 3, 4, 5, 6]) + [1, 4, 9, 16, 25, 36] + + +.. challenge:: Parallel-1, multiprocessing + + Here, you find some code which calculates pi by a stochastic + algorithm. You don't really need to worry how the algorithm works, + but it computes random points in a 1x1 square, and computes the + number that fall into a circle. Copy it into a Jupyter notebook + and use the ``%%timeit`` cell magic on the computation part (the + one highlighted line after timeit below): + + .. code-block:: python + :emphasize-lines: 20 + + import random + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x**2 + y**2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + %%timeit + n, n_inside_circle = sample(10**6) + + pi = 4.0 * (n_inside_circle / n) + pi + + Using the :py:class:`multiprocessing.pool.Pool` code from the lesson, run + the ``sample`` function 10 times, each with ``10**5`` samples + only. Combine the results and time the calculation. What is the + difference in time taken? + + (optional, advanced) Do the same but with + :py:class:`multiprocessing.pool.ThreadPool` instead. This works identically + to ``Pool``, but uses threads instead of different processes. + Compare the time taken. + + .. solution:: + + See the finished notebook here: + + .. toctree:: + + parallel-pi-multiprocessing + + You notice the version with ``ThreadPool`` is no faster, and + probably takes even longer. This is because this is a + pure-Python function which can not run simultaneously in + multiple threads. + +.. challenge:: (advanced) Parallel-2 Running on a cluster + + How does the pool know how many CPUs to take? What happens if you + run on a computer cluster and request only part of the CPUs on a + node? + + .. solution:: + + Pool by default uses one process for each CPU on the node - it + doesn't know about your cluster's scheduling system. It's + possible that you have permission to use 2 CPUs but it is trying + to use 12. This is generally a bad situation, and will just + slow you down (and make other users on the same node upset)! + + You either need to be able to specify the number of CPUs to use + (and pass it the right number), or make it aware of the cluster + system. For example, on a Slurm cluster you would check the + environment variable ``SLURM_CPUS_PER_TASK``. + + Whatever you do, document what your code is doing under the + hood, so that other users know what is going on (we've learned + this from experience...). + + +MPI +--- + +The message passing interface (MPI) approach to parallelization +is that: + +- Tasks (cores) have a rank and are numbered 0, 1, 2, 3, ... +- Each task (core) manages its own memory +- Tasks communicate and share data by sending messages +- Many higher-level functions exist to distribute information to other tasks + and gather information from other tasks +- All tasks typically run the entire code and we have to be careful to avoid + that all tasks do the same thing + +Introductory MPI lessons where Python is included: + +- https://rantahar.github.io/introduction-to-mpi/ +- https://pdc-support.github.io/introduction-to-mpi/ + +These blog posts are good for gentle MPI/mpi4py introduction: + +- https://www.kth.se/blogs/pdc/2019/08/parallel-programming-in-python-mpi4py-part-1/ +- https://www.kth.se/blogs/pdc/2019/11/parallel-programming-in-python-mpi4py-part-2/ + +Those who use MPI in C, C++, Fortran, will probably understand the steps in the +following example. For learners new to MPI, we can explore this example +together. + +Here we reuse the example of approximating pi with a stochastic +algorithm from above, and we have highlighted the lines which are important +to get this MPI example to work: + +.. code-block:: python + :emphasize-lines: 3,23-25,29,39,42 + + import random + import time + from mpi4py import MPI + + + def sample(n): + """Make n trials of points in the square. Return (n, number_in_circle) + + This is our basic function. By design, it returns everything it\ + needs to compute the final answer: both n (even though it is an input + argument) and n_inside_circle. To compute our final answer, all we + have to do is sum up the n:s and the n_inside_circle:s and do our + computation""" + n_inside_circle = 0 + for i in range(n): + x = random.random() + y = random.random() + if x ** 2 + y ** 2 < 1.0: + n_inside_circle += 1 + return n, n_inside_circle + + + comm = MPI.COMM_WORLD + size = comm.Get_size() + rank = comm.Get_rank() + + n = 10 ** 7 + + if size > 1: + n_task = int(n / size) + else: + n_task = n + + t0 = time.perf_counter() + n, n_inside_circle = sample(n_task) + t = time.perf_counter() - t0 + + print(f"before gather: rank {rank}, n_inside_circle: {n_inside_circle}") + n_inside_circle = comm.gather(n_inside_circle, root=0) + print(f"after gather: rank {rank}, n_inside_circle: {n_inside_circle}") + + if rank == 0: + pi_estimate = 4.0 * sum(n_inside_circle) / n + print( + f"\nnumber of darts: {n}, estimate: {pi_estimate}, time spent: {t:.2} seconds" + ) + + +.. challenge:: Parallel-2, MPI + + We can do this as **exercise or as demo**. Note that this example requires ``mpi4py`` and a + MPI installation such as for instance `OpenMPI `__. + + - Try to run this example on one core: ``$ python example.py``. + - Then compare the output with a run on multiple cores (in this case 2): ``$ mpiexec -n 2 python example.py``. + - Can you guess what the ``comm.gather`` function does by looking at the print-outs right before and after. + - Why do we have the if-statement ``if rank == 0`` at the end? + + +Coupling to other languages +--------------------------- + +As mentioned further up in "Multithreading and the GIL", Python has the global +interpreter lock (GIL) which prevents us from using shared-memory +parallelization strategies like OpenMP "directly". + +However, an interesting workaround for this can be to couple Python with other +languages which do not have the GIL. This also works just as well when you don't +need parallelism, but need to make an optimized algorithm for a small part of the code. + +Two strategies are common: + +- Couple Python with compiled languages like C, C++, Fortran, or Rust and let those handle the shared-memory parallelization: + + - C: use the `cffi `__ package (C foreign function interface). :py:mod:`ctypes` is a similar but slightly more primitive module that is in the standard library. + - C++: use `pybind11 `__ + - Fortran: create a C interface using ``iso_c_binding`` and then couple the C layer to Python + using `cffi `__ + - Rust: use `PyO3 `__ + +- Let compiled languages do the shared-memory parallelization part (as in above + point) and let Python do the MPI work and distribute tasks across nodes using + an ``mpi4py`` layer. + +Coupling Python with other languages using the above tools is not difficult but +it goes beyond the scope of this course. + +Before you take this route, **profile the application** first to be sure where +the bottleneck is. + +Of course sometimes coupling languages is not about overcoming bottlenecks but +about combining existing programs which have been written in different +languages for whatever reason. + + +Dask and task queues +-------------------- + +This is another strategy. Text needed here ... + +.. todo:: + + - Not sure who? + + + +See also +-------- + +* `Thinking about Concurrency, Raymond Hettinger + `__. Good introduction to simple and + safe concurrent code. + +.. keypoints:: + + - Pure Python is not very good for highly parallel code. + - Luckily it interfaces to many things which *are* good, and give + you the full control you need. diff --git a/branch/rkdarst--strict-warnings-check/_sources/python.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/python.rst.txt new file mode 100644 index 00000000..a2be4448 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/python.rst.txt @@ -0,0 +1,169 @@ +Introduction to Python +====================== + +.. questions:: + + - What are the basic blocks of Python language? + - How are functions and classes defined in Python? + +.. objectives:: + + - Get a *very* short introduction to Python types and syntax + - Be able to follow the rest of the examples in the course, even if you don't understand everything perfectly. + +If you are not familiar with Python, a *very* short introduction; +first, the builtin scalar and collection types: + +Scalars +------- + +Scalar types, that is, single elements of various types: + +:: + + i = 42 # integer + i = 2**77 # Integers have arbitrary precision + g = 3.14 # floating point number + c = 2 - 3j # Complex number + b = True # boolean + s = "Hello!" # String (Unicode) + q = b'Hello' # bytes (8-bit values) + + +Collections +----------- + +Collections are data structures capable of storing multiple values. + +:: + + l = [1, 2, 3] # list + l[1] # lists are indexed by int + l[1] = True # list elements can be any type + d = {"Janne": 123, "Richard": 456} # dictionary + d["Janne"] + s = set(("apple", "cherry", "banana", "apple")) # Set of unique values + s + + +Control structures +------------------ + +Python has the usual control structures, that is conditional +statements and loops: + +:: + + x = 2 + if x == 3: + print('x is 3') + elif x == 2: + print('x is 2') + else: + print('x is something else') + + +While loops loop until some condition is met: + +:: + + x = 0 + while x < 42: + print('x is ', x) + x += 0.2 + + +For loops loop over some collection of values: + +:: + + xs = [1, 2, 3, 4] + for x in xs: + print(x) + + +Often you want to loop over a sequence of integers, in that case the +``range`` function is useful: + +:: + + for x in range(9): + print(x) + +Another common need is to iterate over a collection, but at the same +time also have an index number. For this there is the ``enumerate`` +function: + +:: + + xs = [1, 'hello', 'world'] + for ii, x in enumerate(xs): + print(ii, x) + + +Functions and classes +--------------------- + +Python functions are defined by the ``def`` keyword. They take a +number of arguments, and return a number of return values. + +:: + + def hello(name): + """Say hello to the person given by the argument""" + print('Hello', name) + return 'Hello ' + name + + hello("Anne") + +Classes are defined by the ``class`` keyword: + +:: + + class Hello: + def __init__(self, name): + self._name = name + def say(self): + print('Hello', self._name) + + h = Hello("Richard") + h.say() + + +Python type system +------------------ + +Python is strongly and dynamically typed. + +Strong here means, roughly, that it's not possible to circumvent the +type system (at least, not easily, and not without invoking undefined +behavior). + +:: + + x = 42 + type(x) + x + "hello" + +Dynamic typing means that types are determined at runtime, and a +variable can be redefined to refer to an instance of another type: + +:: + + x = 42 + x = "hello" + + +*Jargon*: Types are associated with rvalues, not lvalues. In +statically typed language, types are associated with lvalues, and are +(typically) reified during compilation. + + +??? (lesson here) + + + +.. keypoints:: + + - Python offers a nice set of basic types as many other programming languages + - Python is strongly typed and dynamically typed diff --git a/branch/rkdarst--strict-warnings-check/_sources/quick-reference.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/quick-reference.rst.txt new file mode 100644 index 00000000..f033c895 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/quick-reference.rst.txt @@ -0,0 +1,2 @@ +Quick reference +=============== diff --git a/branch/rkdarst--strict-warnings-check/_sources/scipy.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/scipy.rst.txt new file mode 100644 index 00000000..db40c632 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/scipy.rst.txt @@ -0,0 +1,123 @@ +SciPy +===== + +.. questions:: + + - When you need more advanced mathematical functions, where do you look? + +.. objectives:: + + - Understand that SciPy exists and what kinds of things it has. + - Non-objective: know details of everything (or anything) in SciPy. + +.. seealso:: + + * Main article: `SciPy documentation `__ + + + +SciPy is a library that builds on top of NumPy. It contains a lot of +interfaces to battle-tested numerical routines written in Fortran or +C, as well as python implementations of many common algorithms. + + + +What's in SciPy? +---------------- + +Briefly, it contains functionality for + +- Special functions (Bessel, Gamma, etc.) +- Numerical integration +- Optimization +- Interpolation +- Fast Fourier Transform (FFT) +- Signal processing +- Linear algebra (more complete than in NumPy) +- Sparse matrices +- Statistics +- More I/O routine, e.g. Matrix Market format for sparse matrices, + MATLAB files (.mat), etc. + +Many (most?) of these are not written specifically for SciPy, but use +the best available open source C or Fortran libraries. Thus, you get +the best of Python and the best of compiled languages. + +Most functions are documented ridiculously well from a scientific +standpoint: you aren't just using some unknown function, but have a +full scientific description and citation to the method and +implementation. + + + +Example: Numerical integration +------------------------------ + +.. challenge:: + + Define a function of one variable and using + `scipy.integrate.quad `__ + calculate the integral of your function in the + interval ``[0.0, 4.0]``. Then vary the interval and also modify the function and check + whether scipy can integrate it. + + +.. solution:: + + :class: toggle-shown + + .. code-block:: python + + from scipy import integrate + + def myfunction(x): + # you need to define result + return result + + integral = integrate.quad(myfunction, 0.0, 4.0) + print(integral) + + `quad + `__ + uses the Fortran library QUADPACK, which one can assume is pretty + good. You can also see a whole lot of scientific information about + the function on the docs page - including the scientific names of + the methods used. + + + +Exercise 3.2 +------------ + +Use the SciPy sparse matrix functionality to create a random sparse +matrix with a probability of non-zero elements of 0.05 and size 10000 +x 10000. The use the SciPy sparse linear algebra support to calculate +the matrix-vector product of the sparse matrix you just created and a +random vector. Use the %timeit macro to measure how long it +takes. Does the optional ``format`` argument when you create the +sparse matrix make a difference? + +Then, compare to how long it takes if you'd instead first convert the +sparse matrix to a normal NumPy dense array, and use the NumPy ``dot`` +method to calculate the matrix-vector product. + +Can you figure out a quick rule of thumb when it's worth using a +sparse matrix representation vs. a dense representation? + + + +See also +-------- + +* `SciPy general introduction `__ +* `SciPy documentation + `__ + + + +.. keypoints:: + + - When you need advance math or scientific functions, let's just + admit it: you do a web search first. + - But when you see something in SciPy come up, you know your + solutions are in good hands. diff --git a/branch/rkdarst--strict-warnings-check/_sources/scripts.rst.txt b/branch/rkdarst--strict-warnings-check/_sources/scripts.rst.txt new file mode 100644 index 00000000..819ef618 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_sources/scripts.rst.txt @@ -0,0 +1,326 @@ +Scripts +======= + +.. questions:: + + - Why moving from Jupyter notebooks to scripts? + - How to create a python script? + - How to generalize a python script? + +.. objectives:: + + - Learn how to streamline your python notebooks by creating repeatable python scripts + - Learn how to import other python files + - Learn to parse command line arguments in python + + +Why scripts? +------------- + +So far we have been learning python using Jupyter notebooks. It is very convenient: it allowed us to experiment and prototype python code so we may think that is more than enough for your day to day work. + +But after several weeks of hard work with python, you may end up: + +- either with 10 different notebooks (so that you can run them concurrently) +- or with a very long notebook which is becoming hardly readable! + +Let's imagine you have created 10 notebooks to run for 10 different input parameters and now you are willing to experiment with 1000 sets of input parameters. +Suppose you find a bug in the original notebook and need to rerun everything: are you willing to re-create manually your 1000 notebooks? + +In this episode, we will learn how to automate your work using python scripts so that + +* you do not need to manually configure your notebooks to be able to run with different parameters +* can easily run you work via other tools, such as on computing clusters. + + +From jupyter notebooks to python scripts +----------------------------------------- + +Save as python script +--------------------- + +Jupyter notebooks can be parameterized for instance using `papermill `_. It can be an attractive approach when you have short notebooks (to generate automatically plots/reports) but as soon as you have more complex tasks to execute, we strongly recommend to generate python scripts. This will also force you to modularize your code. + +Within JupyterLab, you can export any jupyter notebook to a python script: + +.. figure:: https://jupyterlab.readthedocs.io/en/stable/_images/exporting_menu.png + + Select File (top menu bar) → Export Notebook as → **Export notebook to Executable Script**. + +Actually, you could also export your notebook in many other formats. Check `JupyterLab documentation `_ for more information. + + +.. challenge:: Scripts-1 + + + 1. Create a fresh jupyter notebook and rename it **plot_inflammation.ipynb** + + 2. Download the `first dataset `_ and load it in python. Below is an example on how you can proceed:: + + from io import StringIO + + import numpy as np + import requests + url='https://raw.githubusercontent.com/swcarpentry/python-novice-inflammation/gh-pages/data/inflammation-01.csv' + s=requests.get(url).text + + data = np.loadtxt(fname=StringIO(s), delimiter=',') + + *Note that later in the course, you will learn how to use* `pandas `_ *python package where loading such dataset from an url would become much simpler.* + + 3. Plot the dataset (you may simply use ``imshow`` from ``matplotlib.pyplot``) and save the resulting plot in a file called **plot.png**:: + + import matplotlib.pyplot as plt + + plt.imshow(data) + + plt.savefig('plot.png') + + *Feel free to customize your plot as you learned in the preceding episode*. + + 4. Export your notebook as a python script and check that you have a new file called **plot_inflammation.py**. Please note that the file may be located in your **Downloads** folder (in that case, make sure you move it to your working directory). + + 5. Open a Terminal and navigate to the folder where you have exported your notebook to run it:: + + ./plot_inflammation.py + +Run a python script +------------------- + +Let's understand why our python script ran out of the box. Open **plot_inflammation.py** with your favorite editor (from JupyerLab, you can double click on the file to open it). You should have, at the very top of your script:: + + #!/usr/bin/env python + +*Note: you may have* **python3** *rather than python*. + +In the exercise above, a few things can go wrong: + +- if you get an error such as:: + + can't open file 'test_inflammation.py': [Errno 2] No such file or directory + + That's probably because you try to run **plot_inflammation.py** from a different folder. The solution is to check **plot_inflammation.py** is in the current folder. + +- or:: + + bash: python: command not found + +This happens if the python command is not in your **PATH**. You may have to specify the full path to the python command. + + + +Importing other python files +---------------------------- + +We have a very short notebook that loads and plots data but let's imagine we need to process data after loading them. For instance, we can normalize data:: + + data = data / np.linalg.norm(data) + + +In that case, it is good practice to separate processing from plotting. The reason is that you usually need to generate your plot several time while processing data once only (especially when data processing is computational intensive). + +For example, we can create a new python file (**inflammation_functions.py**) containing a function to normalize our dataset:: + + import numpy as np + + def processing(dataset): + return dataset / np.linalg.norm(dataset) + +and a second file calling this function: + +.. code-block:: + :emphasize-lines: 6,16 + + from io import StringIO + + import numpy as np + import requests + + import inflammation_functions + + url='https://raw.githubusercontent.com/swcarpentry/python-novice-inflammation/gh-pages/data/inflammation-01.csv' + s=requests.get(url).text + + data = np.loadtxt(fname=StringIO(s), delimiter=',') + + + # call processing function from inflammation_functions + + data = inflammation_functions.processing(data) + + + +.. challenge:: Scripts-2 (optional) + + 1. Update **inflammation_functions.py** to add a new function for plotting the dataset. + + 2. Update **test_inflammation.py** to call it. + + +Command line arguments with ``sys.argv`` +---------------------------------------- + +We have better organized our code but it still cannot easily process different +input files. For this, rather than copying several time the same code for +different input files, we can update the main code to take the input file from the command +line. + +**Example**: We create a Python script and pass the input file and the output file +name as command line arguments: + +.. code-block:: python + :emphasize-lines: 3-4 + + import sys + + input_file_name = sys.argv[1] + output_file_name = sys.argv[2] + + # to keep things simple we only print them out: + print(f"input file is {input_file_name}") + print(f"output file is {output_file_name}") + + +We can try it out:: + + $ python myscript.py myinput myoutput + + +.. discussion:: + + - Does it work? + + - Why is this better than modifying the script every time I want it to + operate on a different file? + + - What problems do you expect when using this approach (using ``sys.argv``)? + +This approach is brittle and more robust solutions exist that allow to fully +customize your scripts and generate help texts at the same time: + +- `argparse `__: this is the one that we will show +- `doctopt `__: you write the help text and this generates a parser for you +- `click `__: another nice library for command line interfaces + + +Parsing command line arguments with ``argparse`` +------------------------------------------------ + +This example not only gives you descriptive command line +arguments, it also automatically generates a ``--help`` option for you: + +.. code-block:: python + + #!/usr/bin/env python + + import argparse + parser = argparse.ArgumentParser() + parser.add_argument('-o', '--output', type=str, + help="output filename") + args = parser.parse_args() + + if args.output: + print(f"output file is {args.output}") + + +.. challenge:: Scripts-3 + + 1. Take the python script we have written in the preceding exercise and use + ``argparse`` to be able to read any input file and save the resulting image in an output file (filename is specified via command line argument). + + 2. Execute your script for all the **inflammation** files (there are 12 files numbered from 01 to 12). + + +.. solution:: + + .. code-block:: + :emphasize-lines: 5,7-10,12,19 + + from io import StringIO + import numpy as np + import requests + import matplotlib.pyplot as plt + import argparse + + parser = argparse.ArgumentParser() + parser.add_argument("-i", "--input", type=str, help="input data file (URL)") + parser.add_argument("-o", "--output", type=str, help="output plot file") + args = parser.parse_args() + + url = args.input + s = requests.get(url).text + + data = np.loadtxt(fname=StringIO(s), delimiter=",") + + plt.imshow(data) + + plt.savefig(args.output) + + +.. discussion:: + + **What was the point of doing this?** + + Now you can do this:: + + $ python test_inflammation.py --help + $ python test_inflammation.py --input https://raw.githubusercontent.com/swcarpentry/python-novice-inflammation/gh-pages/data/inflammation-01.csv --output 01.png + $ python test_inflammation.py --input https://raw.githubusercontent.com/swcarpentry/python-novice-inflammation/gh-pages/data/inflammation-02.csv --output 02.png + + - We can now process different input files without changing the script. + - This way we can also loop over file patterns (using shell loops or similar) or use + the script in a workflow management system and process many files in parallel. + - By changing from ``sys.argv`` to ``argparse`` we made the script more robust against + user input errors and also got a help text (accessible via ``--help``). + + +Synchronize with Jupytext (optional) +------------------------------------ + +`jupytext `_ is a python package you can use for automatically synchronizing your notebooks into python scripts. + +To install it from the command line (make sure you use JupyterLab 2.x):: + + pip install jupytext --upgrade + +or + +:: + + conda install -c conda-forge jupytext + +Please note that you may also use `Anaconda navigator `_ (if installed) to install ``jupytext``. + +Installing Jupytext will trigger a build of the JupyterLab extension the next time you open it. If you prefer, you can trigger the build manually with + +:: + + jupyter lab build + + +Once installed, you can pair your notebook: + +.. figure:: https://raw.githubusercontent.com/mwouts/jupytext/master/packages/labextension/jupytext_commands.png + + Select "Commands" from left toolbar, search "jupytext", then **Pair notebook with percent script** (**NOT** what you see in the image). + + +After few seconds, **test_inflammation.py** will be created and synchronized with **test_inflammation.ipynb**. + +Double click on the python script to edit it and add (on the top of the script): + +:: + + #!/usr/bin/env python + + +This will make sure you can execute it from the command line. + +*Note that, it can also be added in the jupyter notebook by editing notebook metadata (Property Inspector)*. + + +.. keypoints:: + + - synchronize your jupyter notebooks & python scripts with ``jupytext`` + - ``import`` other python files + - command line arguments in python scripts diff --git a/branch/rkdarst--strict-warnings-check/_static/basic.css b/branch/rkdarst--strict-warnings-check/_static/basic.css new file mode 100644 index 00000000..24bc73e7 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_static/basic.css @@ -0,0 +1,855 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 450px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +dl.footnote > dt, +dl.citation > dt { + float: left; + margin-right: 0.5em; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dt:after { + content: ":"; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0.5em; + content: ":"; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +div.doctest > div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +code.descclassname { + background-color: transparent; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/branch/rkdarst--strict-warnings-check/_static/clipboard.min.js b/branch/rkdarst--strict-warnings-check/_static/clipboard.min.js new file mode 100644 index 00000000..02c549e3 --- /dev/null +++ b/branch/rkdarst--strict-warnings-check/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.4 + * https://zenorocha.github.io/clipboard.js + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return function(n){var o={};function r(t){if(o[t])return o[t].exports;var e=o[t]={i:t,l:!1,exports:{}};return n[t].call(e.exports,e,e.exports,r),e.l=!0,e.exports}return r.m=n,r.c=o,r.d=function(t,e,n){r.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:n})},r.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return r.d(e,"a",e),e},r.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},r.p="",r(r.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function o(t,e){for(var n=0;n