docstring_error_interactive.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE** This notebook is work under progress"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactive exploration of current errors in pandas docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*DISCLAIMER: This notebook is based on the one uploaded by @dujm [here](https://github.com/python-sprints/pandas-mentoring/blob/master/notebooks/docstring_error_interactive.ipynb)*\n",
    "\n",
    "\n",
    "This notebook will help you detect which errors are still present on some of the docstrings of pandas, so that you can select one of them, fix it, and submit a PR to the [pandas repository](https://github.com/pandas-dev/pandas). \n",
    "\n",
    "**IMPORTANT!** Before starting to work on fixing an error, check that nobody is already working on it by searching the issues and PRs in the pandas repository. If you nobody is doing so, open an issue and let others know you will be fixing that docstring.\n",
    "\n",
    "This script currently supports pandas version >= 0.25.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start by importing the necessary packages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "import pandas as pd\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "import json\n",
    "\n",
    "import ipywidgets as widgets\n",
    "from IPython.display import display, clear_output, Markdown\n",
    "import qgrid\n",
    "\n",
    "from error_descriptions import error_descriptions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## *Static exploration*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Generate a .json containing all current errors"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This step was automatically done if you are running this notebook from Binder. Keep in mind that the .json file is updated every 15 minutes, so it might be outdated. When you select an error to work on, double check that nobody has submitted an issue to work on it already.\n",
    "\n",
    "If you want to generate the .json file locally, simply run the following command from your pandas clone:\n",
    "\n",
    "`./scripts/validate_docstrings.py --format=json > /path/to/json/pandas_docstring_errors.json`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Plot a table describing the errors"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will plot a table that indicates which pandas functions still have an error in their docstrings. The specific error code and description will be also described."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>function</th>\n",
       "      <th>file</th>\n",
       "      <th>file_line</th>\n",
       "      <th>error_code</th>\n",
       "      <th>error_description</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>pandas.BooleanDtype</td>\n",
       "      <td>/core/arrays/boolean.py</td>\n",
       "      <td>40</td>\n",
       "      <td>SA01</td>\n",
       "      <td>See Also section not found</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>pandas.Categorical</td>\n",
       "      <td>/core/arrays/categorical.py</td>\n",
       "      <td>213</td>\n",
       "      <td>PR01</td>\n",
       "      <td>Parameters {'fastpath'} not documented</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>pandas.Categorical.__array__</td>\n",
       "      <td>/core/arrays/categorical.py</td>\n",
       "      <td>1268</td>\n",
       "      <td>ES01</td>\n",
       "      <td>No extended summary found</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>pandas.Categorical.__array__</td>\n",
       "      <td>/core/arrays/categorical.py</td>\n",
       "      <td>1268</td>\n",
       "      <td>PR01</td>\n",
       "      <td>Parameters {'dtype'} not documented</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>pandas.Categorical.__array__</td>\n",
       "      <td>/core/arrays/categorical.py</td>\n",
       "      <td>1268</td>\n",
       "      <td>SA01</td>\n",
       "      <td>See Also section not found</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>pandas.Categorical.__array__</td>\n",
       "      <td>/core/arrays/categorical.py</td>\n",
       "      <td>1268</td>\n",
       "      <td>EX01</td>\n",
       "      <td>No examples section found</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>pandas.Categorical.from_codes</td>\n",
       "      <td>/core/arrays/categorical.py</td>\n",
       "      <td>589</td>\n",
       "      <td>SA01</td>\n",
       "      <td>See Also section not found</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>pandas.CategoricalDtype</td>\n",
       "      <td>/core/dtypes/dtypes.py</td>\n",
       "      <td>168</td>\n",
       "      <td>SA04</td>\n",
       "      <td>Missing description for See Also \"Categorical\"...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>pandas.CategoricalIndex</td>\n",
       "      <td>/core/indexes/category.py</td>\n",
       "      <td>69</td>\n",
       "      <td>EX02</td>\n",
       "      <td>Examples do not pass tests:\\n*****************...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>pandas.CategoricalIndex</td>\n",
       "      <td>/core/indexes/category.py</td>\n",
       "      <td>69</td>\n",
       "      <td>EX03</td>\n",
       "      <td>flake8 error: E231 missing whitespace after ',...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                        function                         file file_line  \\\n",
       "0            pandas.BooleanDtype      /core/arrays/boolean.py        40   \n",
       "1             pandas.Categorical  /core/arrays/categorical.py       213   \n",
       "2   pandas.Categorical.__array__  /core/arrays/categorical.py      1268   \n",
       "3   pandas.Categorical.__array__  /core/arrays/categorical.py      1268   \n",
       "4   pandas.Categorical.__array__  /core/arrays/categorical.py      1268   \n",
       "5   pandas.Categorical.__array__  /core/arrays/categorical.py      1268   \n",
       "6  pandas.Categorical.from_codes  /core/arrays/categorical.py       589   \n",
       "7        pandas.CategoricalDtype       /core/dtypes/dtypes.py       168   \n",
       "8        pandas.CategoricalIndex    /core/indexes/category.py        69   \n",
       "9        pandas.CategoricalIndex    /core/indexes/category.py        69   \n",
       "\n",
       "  error_code                                  error_description  \n",
       "0       SA01                         See Also section not found  \n",
       "1       PR01             Parameters {'fastpath'} not documented  \n",
       "2       ES01                          No extended summary found  \n",
       "3       PR01                Parameters {'dtype'} not documented  \n",
       "4       SA01                         See Also section not found  \n",
       "5       EX01                          No examples section found  \n",
       "6       SA01                         See Also section not found  \n",
       "7       SA04  Missing description for See Also \"Categorical\"...  \n",
       "8       EX02  Examples do not pass tests:\\n*****************...  \n",
       "9       EX03  flake8 error: E231 missing whitespace after ',...  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Import JSON as df\n",
    "file = 'pandas_docstring_errors.json'\n",
    "df = (pd.read_json(file)\n",
    "            .transpose()\n",
    "            .filter(items=['errors', 'file', 'file_line'])\n",
    "            .explode('errors')\n",
    "            .dropna()\n",
    "            .reset_index()\n",
    "            .rename(columns={\"index\": \"function\"})\n",
    "     )\n",
    "\n",
    "# Divide errors in their code and description\n",
    "df[['error_code','error_description']] = pd.DataFrame(df.errors.tolist())\n",
    "df = df.drop([\"errors\"], axis=1)\n",
    "\n",
    "# Print file name relative to pandas repository path\n",
    "df['file'] = df['file'].str.split('/pandas').str[1]\n",
    "\n",
    "# Show the ten first examples\n",
    "df.head(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Count number of functions with errors per error type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>error_code</th>\n",
       "      <th>counts</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>SA01</td>\n",
       "      <td>372</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>EX01</td>\n",
       "      <td>362</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>ES01</td>\n",
       "      <td>354</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>RT03</td>\n",
       "      <td>288</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>GL08</td>\n",
       "      <td>242</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>SA04</td>\n",
       "      <td>227</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>PR07</td>\n",
       "      <td>212</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>PR01</td>\n",
       "      <td>212</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>EX03</td>\n",
       "      <td>145</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>RT02</td>\n",
       "      <td>121</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>EX02</td>\n",
       "      <td>98</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>11</th>\n",
       "      <td>PR02</td>\n",
       "      <td>90</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>SS06</td>\n",
       "      <td>81</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>PR08</td>\n",
       "      <td>10</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>PR06</td>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>15</th>\n",
       "      <td>YD01</td>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>PR09</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   error_code  counts\n",
       "0        SA01     372\n",
       "1        EX01     362\n",
       "2        ES01     354\n",
       "3        RT03     288\n",
       "4        GL08     242\n",
       "5        SA04     227\n",
       "6        PR07     212\n",
       "7        PR01     212\n",
       "8        EX03     145\n",
       "9        RT02     121\n",
       "10       EX02      98\n",
       "11       PR02      90\n",
       "12       SS06      81\n",
       "13       PR08      10\n",
       "14       PR06       4\n",
       "15       YD01       4\n",
       "16       PR09       1"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_code = df['error_code'].value_counts().reset_index()\n",
    "df_code.columns = ['error_code','counts']\n",
    "\n",
    "df_code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Count number of errors per function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>function</th>\n",
       "      <th>counts</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>pandas.core.groupby.DataFrameGroupBy.boxplot</td>\n",
       "      <td>14</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>pandas.HDFStore.append</td>\n",
       "      <td>13</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>pandas.PeriodIndex</td>\n",
       "      <td>12</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>pandas.CategoricalIndex.remove_unused_categories</td>\n",
       "      <td>11</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>pandas.Series.cat.remove_unused_categories</td>\n",
       "      <td>11</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1013</th>\n",
       "      <td>pandas.tseries.offsets.BusinessDay.is_on_offset</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1014</th>\n",
       "      <td>pandas.DataFrame.max</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1015</th>\n",
       "      <td>pandas.Series.str.get_dummies</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1016</th>\n",
       "      <td>pandas.Series.max</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1017</th>\n",
       "      <td>pandas.Series.str.contains</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>1018 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                                              function  counts\n",
       "0         pandas.core.groupby.DataFrameGroupBy.boxplot      14\n",
       "1                               pandas.HDFStore.append      13\n",
       "2                                   pandas.PeriodIndex      12\n",
       "3     pandas.CategoricalIndex.remove_unused_categories      11\n",
       "4           pandas.Series.cat.remove_unused_categories      11\n",
       "...                                                ...     ...\n",
       "1013   pandas.tseries.offsets.BusinessDay.is_on_offset       1\n",
       "1014                              pandas.DataFrame.max       1\n",
       "1015                     pandas.Series.str.get_dummies       1\n",
       "1016                                 pandas.Series.max       1\n",
       "1017                        pandas.Series.str.contains       1\n",
       "\n",
       "[1018 rows x 2 columns]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_function = df['function'].value_counts().reset_index()\n",
    "df_function.columns = ['function','counts']\n",
    "\n",
    "df_function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## *Interactive exploration* "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Select an error from the following dropdown menu to see a complete description and example of it, and the number of that type of errors in pandas:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "05075057af9442368f2e62f6be6fb098",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Dropdown(description='Task:', options=('ES01', 'EX01', 'EX02', 'EX03', 'GL08', 'PR01', 'PR02', 'PR06', 'PR07',…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "86a27ad7a6f2400fb9432ccdce7594e1",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Output()"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "def unique_sorted_values(array):\n",
    "    unique = array.unique().tolist()\n",
    "    unique.sort()\n",
    "    return unique\n",
    "\n",
    "w = widgets.Dropdown(\n",
    "    options=unique_sorted_values(df_code.error_code),\n",
    "    value='ES01',\n",
    "    description='Task:',\n",
    ")\n",
    "display(w)\n",
    "\n",
    "out = widgets.Output()\n",
    "display(out)\n",
    "\n",
    "def on_change(change):\n",
    "    with out:\n",
    "        if change['type'] == 'change' and change['name'] == 'value':\n",
    "            error_code = change['new']\n",
    "            error_cnt = df_code.loc[df_code['error_code'] == error_code]['counts'].values[0]\n",
    "            description = error_descriptions[error_code][\"description\"]\n",
    "            bad_example = error_descriptions[error_code][\"bad_example\"]\n",
    "            good_example = error_descriptions[error_code][\"good_example\"]\n",
    "            references = error_descriptions[error_code][\"references\"]\n",
    "\n",
    "            clear_output()\n",
    "            \n",
    "            # Display text\n",
    "            display(Markdown(\"## {} ({} errors)\".format(error_code, error_cnt)))\n",
    "            display(Markdown(description))\n",
    "            display(Markdown(\"### Bad Example\"))\n",
    "            display(Markdown(bad_example))\n",
    "            display(Markdown(\"### Good Example\"))\n",
    "            display(Markdown(good_example))\n",
    "            display(Markdown(\"### References\"))\n",
    "            display(Markdown(references))\n",
    "\n",
    "w.observe(on_change)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can filter the following table by the error code you want to work on, or its function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Create qgrid widget\n",
    "qgrid_widget = qgrid.show_grid(df, grid_options={'forceFitColumns': True})\n",
    "qgrid_widget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}