chen_pandas_cut_medium.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### All Pandas cut() you should know for transforming numerical data into categorical data\n",
    "All examples are taken from the following article\n",
    "\n",
    "https://towardsdatascience.com/all-pandas-cut-you-should-know-for-transforming-numerical-data-into-categorical-data-1370cf7f4c4f\n",
    "\n",
    "Numerical data is common in data analysis. Often you have numerical data that is continuous, or very large scales, or is highly skewed. Sometimes, it can be easier to bin values into discrete intervals. This is helpful to perform descriptive statistics when values are divided into meaningful categories. For example, we can divide the age into Toddler, Child, Adult, and Elder.\n",
    "\n",
    "Pandas’ built-in [cut()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.cut.html) function is a great way to transform numerical data into categorical data. In this article, you’ll learn how to use it to deal with the following common tasks.\n",
    "\n",
    "1. [Discretizing into equal-sized bins](#equal)\n",
    "2. [Adding custom bins](#custom)\n",
    "3. [Adding labels to bins](#labels)\n",
    "4. [Configuring leftmost edge with `right=False`](#edge)\n",
    "5. [Include the lowest value with `include_lowest=True`](#lowest)\n",
    "6. [Passing an `IntervalIndex` to `bins`](#interval)\n",
    "7. [Returning bins with `retbins=True`](#retbins)\n",
    "8. [Creating unordered categories](#unordered)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Discretizing into equal-sized bins\n",
    "<a id='equal'></a>\n",
    "\n",
    "The simplest usage of cut() must has a column and an integer as input. It is discretizing values into equal-sized bins."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://miro.medium.com/max/700/1*j_ZpX8hK__RVMMDotr9HVA.png\">"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>(1.903, 34.333]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>(66.667, 99.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>(34.333, 66.667]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>(1.903, 34.333]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>(1.903, 34.333]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>(1.903, 34.333]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>(66.667, 99.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>(66.667, 99.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>(1.903, 34.333]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>(1.903, 34.333]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age         age_group\n",
       "0    2   (1.903, 34.333]\n",
       "1   67    (66.667, 99.0]\n",
       "2   40  (34.333, 66.667]\n",
       "3   32   (1.903, 34.333]\n",
       "4    4   (1.903, 34.333]\n",
       "5   15   (1.903, 34.333]\n",
       "6   82    (66.667, 99.0]\n",
       "7   99    (66.667, 99.0]\n",
       "8   26   (1.903, 34.333]\n",
       "9   30   (1.903, 34.333]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = pd.DataFrame({'age': [2, 67, 40, 32, 4, 15, 82, 99, 26, 30]})\n",
    "df['age_group'] = pd.cut(df['age'], 3) # add a new column\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Observe intervals in the age_group column. Those interval values are having a round bracket at the start and a square bracket at the end, for example (1.903, 34.333]. It basically means any value on the side of the round bracket is not included in the interval and any value on the side of the square bracket is included (It is known as open and closed intervals in Math).\n",
    "\n",
    "Now, let's take a look at the new column age_group."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0     (1.903, 34.333]\n",
       "1      (66.667, 99.0]\n",
       "2    (34.333, 66.667]\n",
       "3     (1.903, 34.333]\n",
       "4     (1.903, 34.333]\n",
       "5     (1.903, 34.333]\n",
       "6      (66.667, 99.0]\n",
       "7      (66.667, 99.0]\n",
       "8     (1.903, 34.333]\n",
       "9     (1.903, 34.333]\n",
       "Name: age_group, dtype: category\n",
       "Categories (3, interval[float64]): [(1.903, 34.333] < (34.333, 66.667] < (66.667, 99.0]]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://miro.medium.com/max/1000/1*5uT5BzEFG7-JW3E6qBbPrA.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It shows dtype: category with 3 label values:\n",
    "- (1.903, 34.333] , \n",
    "- (34.333, 66.667] , and \n",
    "- (66.667, 99.0]. \n",
    "\n",
    "Those label values are ordered as indicated with the symbol <. \n",
    "\n",
    "Behind the theme, an interval is calculated as follows in order to generate the equal-sized bins:\n",
    "\n",
    "$interval$ = (max_value — min_value) / num_of_bins = (99 - 2 / $3 = 32.33333\n",
    "         \n",
    "        (<--32.3333-->] < (<--32.3333-->] < (<--32.3333-->]\n",
    "        (1.903, 34.333] < (34.333, 66.667] < (66.667, 99.0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Adding custom bins\n",
    "<a id='custom'></a>\n",
    "\n",
    "Let’s divide the above age values into 4 custom groups i.e. 0–12, 12–19, 19–60, 61–100. To do that, we can simply pass those values in a list (`[0, 12, 19, 61, 100]`) to the argument `bins`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>(0, 12]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>(61, 100]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>(0, 12]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>(12, 19]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>(61, 100]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>(61, 100]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age  age_group\n",
       "0    2    (0, 12]\n",
       "1   67  (61, 100]\n",
       "2   40   (19, 61]\n",
       "3   32   (19, 61]\n",
       "4    4    (0, 12]\n",
       "5   15   (12, 19]\n",
       "6   82  (61, 100]\n",
       "7   99  (61, 100]\n",
       "8   26   (19, 61]\n",
       "9   30   (19, 61]"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group'] = pd.cut(df['age'], bins=[0, 12, 19, 61, 100])\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src = https://miro.medium.com/max/700/1*P4cgZsvCM5o4LqaJ5-MgYg.png>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see dtype: category with 4 ordered label values: (0, 12] < (12, 19] < (19, 61] < (61, 100]."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let’s sort the DataFrame by the column age_group:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>(0, 12]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>(0, 12]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>(12, 19]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>(19, 61]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>(61, 100]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>(61, 100]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>(61, 100]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age  age_group\n",
       "0    2    (0, 12]\n",
       "4    4    (0, 12]\n",
       "5   15   (12, 19]\n",
       "2   40   (19, 61]\n",
       "3   32   (19, 61]\n",
       "8   26   (19, 61]\n",
       "9   30   (19, 61]\n",
       "1   67  (61, 100]\n",
       "6   82  (61, 100]\n",
       "7   99  (61, 100]"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df.sort_values('age_group')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src = https://miro.medium.com/max/1000/1*0LP51LTjIZfXhXPphOUuXQ.png>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let’s count that how many values fall into each bin."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 12]      2\n",
       "(12, 19]     1\n",
       "(19, 61]     4\n",
       "(61, 100]    3\n",
       "Name: age_group, dtype: int64"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group'].value_counts().sort_index()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Adding labels to bins\n",
    "<a id='labels'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is more descriptive to label these age_group values as `<12`, `Teen`, `Adult`, `Older`.\n",
    "To do that, we can simply pass those values in a list to the argument labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>&lt;12</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>Older</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>Adult</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>Adult</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>&lt;12</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>Teen</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>Older</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>Older</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>Adult</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>Adult</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age age_group\n",
       "0    2       <12\n",
       "1   67     Older\n",
       "2   40     Adult\n",
       "3   32     Adult\n",
       "4    4       <12\n",
       "5   15      Teen\n",
       "6   82     Older\n",
       "7   99     Older\n",
       "8   26     Adult\n",
       "9   30     Adult"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bins = [0, 12, 19, 61, 100]\n",
    "labels = ['<12', 'Teen', 'Adult', 'Older']\n",
    "df['age_group'] = pd.cut(df['age'], bins, labels=labels)\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src = 'https://miro.medium.com/max/700/1*hD7KJ5aNHW9_4FYpFIriTg.png'>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, it is showing label when sorting and counting"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<12      2\n",
       "Teen     1\n",
       "Adult    4\n",
       "Older    3\n",
       "Name: age_group, dtype: int64"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group'].value_counts().sort_index()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Configuring leftmost edge with `right=False`\n",
    "<a id='edge'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is an argument right in Pandas `cut()` to configure whether `bins` include the rightmost edge or not. `right` defaults to True, which mean bins like `[0, 12, 19, 61, 100]` indicate `(0,12], (12,19], (19,61],(61,100]` . To include the leftmost edge, we can set `right=False`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0      [0, 12)\n",
       "1    [61, 100)\n",
       "2     [19, 61)\n",
       "3     [19, 61)\n",
       "4      [0, 12)\n",
       "5     [12, 19)\n",
       "6    [61, 100)\n",
       "7    [61, 100)\n",
       "8     [19, 61)\n",
       "9     [19, 61)\n",
       "Name: age, dtype: category\n",
       "Categories (4, interval[int64]): [[0, 12) < [12, 19) < [19, 61) < [61, 100)]"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pd.cut(df['age'], bins=[0, 12, 19, 61, 100], right=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Include the lowest value with `include_lowest=True`\n",
    "<a id='lowest'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose you would like to divide the above age values into `2–12`, `12–19`, `19–60`, `61–100` instead. You will get a result contains `NaN` when setting the bins to `[2, 12, 19, 61, 100]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>(2.0, 12.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>(12.0, 19.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age      age_group\n",
       "0    2            NaN\n",
       "1   67  (61.0, 100.0]\n",
       "2   40   (19.0, 61.0]\n",
       "3   32   (19.0, 61.0]\n",
       "4    4    (2.0, 12.0]\n",
       "5   15   (12.0, 19.0]\n",
       "6   82  (61.0, 100.0]\n",
       "7   99  (61.0, 100.0]\n",
       "8   26   (19.0, 61.0]\n",
       "9   30   (19.0, 61.0]"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group'] = pd.cut(df['age'], bins=[2, 12, 19, 61, 100])\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We get a `NaN` because the value 2 is the leftmost edge of the first bin `(2.0, 19.0]` and is not included. To include the lowest value, we can set `include_lowest=True`. Alternatively, you can set the `right` to `False` to include the leftmost edge."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>(1.999, 12.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>(1.999, 12.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>(12.0, 19.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age      age_group\n",
       "0    2  (1.999, 12.0]\n",
       "1   67  (61.0, 100.0]\n",
       "2   40   (19.0, 61.0]\n",
       "3   32   (19.0, 61.0]\n",
       "4    4  (1.999, 12.0]\n",
       "5   15   (12.0, 19.0]\n",
       "6   82  (61.0, 100.0]\n",
       "7   99  (61.0, 100.0]\n",
       "8   26   (19.0, 61.0]\n",
       "9   30   (19.0, 61.0]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group'] = pd.cut(\n",
    "    df['age'], \n",
    "    bins=[2, 12, 19, 61, 100], \n",
    "    include_lowest=True)\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Passing an `IntervalIndex` to `bins`\n",
    "<a id='interval'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far we have been passing an array to `bins`. Instead of an array, we can also pass an `IntervalIndex`.\n",
    "Let’s create an IntervalIndex with 3 bins `(0, 12], (19, 61], (61, 100]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "bins = pd.IntervalIndex.from_tuples([(0, 12), (19, 61), (61, 100)])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "IntervalIndex([(0, 12], (19, 61], (61, 100]],\n",
    "              closed='right',\n",
    "              dtype='interval[int64]')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, let’s pass it to the argument `bins`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "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>age</th>\n",
       "      <th>age_group</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "      <td>(0.0, 12.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>67</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>40</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>32</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>(0.0, 12.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>15</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>82</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>99</td>\n",
       "      <td>(61.0, 100.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>26</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>30</td>\n",
       "      <td>(19.0, 61.0]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age      age_group\n",
       "0    2    (0.0, 12.0]\n",
       "1   67  (61.0, 100.0]\n",
       "2   40   (19.0, 61.0]\n",
       "3   32   (19.0, 61.0]\n",
       "4    4    (0.0, 12.0]\n",
       "5   15            NaN\n",
       "6   82  (61.0, 100.0]\n",
       "7   99  (61.0, 100.0]\n",
       "8   26   (19.0, 61.0]\n",
       "9   30   (19.0, 61.0]"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df['age_group'] = pd.cut(df['age'], bins)\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Returning bins with `retbins=True`\n",
    "<a id='retbins'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is an argument called `retbin` to return the `bins`. If it is set to `True`, the result will return the `bins` and it is useful when bins is passed as a single number value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "result, bins = pd.cut(\n",
    "    df['age'], \n",
    "    bins=4,            # A single number value\n",
    "    retbins=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0    (1.903, 26.25]\n",
       "1     (50.5, 74.75]\n",
       "2     (26.25, 50.5]\n",
       "3     (26.25, 50.5]\n",
       "4    (1.903, 26.25]\n",
       "5    (1.903, 26.25]\n",
       "6     (74.75, 99.0]\n",
       "7     (74.75, 99.0]\n",
       "8    (1.903, 26.25]\n",
       "9     (26.25, 50.5]\n",
       "Name: age, dtype: category\n",
       "Categories (4, interval[float64]): [(1.903, 26.25] < (26.25, 50.5] < (50.5, 74.75] < (74.75, 99.0]]"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Print out result\n",
    "result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1.903, 26.25 , 50.5  , 74.75 , 99.   ])"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Print out bins value\n",
    "bins "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. Creating unordered categories\n",
    "<a id='unordered'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`ordered=False` will result in unordered categories when labels are passed. This parameter can be used to allow non-unique labels:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0      <12\n",
       "1    Older\n",
       "2    Adult\n",
       "3    Adult\n",
       "4      <12\n",
       "5     Teen\n",
       "6    Older\n",
       "7    Older\n",
       "8    Adult\n",
       "9    Adult\n",
       "Name: age, dtype: category\n",
       "Categories (4, object): ['<12', 'Teen', 'Adult', 'Older']"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pd.cut(\n",
    "    df['age'], \n",
    "    bins=[0, 12, 19, 61, 100], \n",
    "    labels=['<12', 'Teen', 'Adult', 'Older'], \n",
    "    ordered=False)"
   ]
  },
  {
   "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}