Adding files segmentation project

3_customer_segmentation_update_frequency.ipynb

@@ -0,0 +1,975 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Our goal here is to cluster our customers once again and check how our clusters change weeks after weeks. This will enable us to see when we will need to update our algorithm.\n",
+    "\n",
+    "To do this, we will calculate the Adjusted Rand Index between a cluster made with out original data preprocessing and a cluster made with a new preprocessing taking into account the new data. Then, we will be able to see the evolution of the ARI weeks after weeks and see when an update is necessary."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Importing packages\n",
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "import seaborn as sns\n",
+    "from tqdm import tqdm\n",
+    "\n",
+    "from datetime import date\n",
+    "from datetime import timedelta\n",
+    "\n",
+    "from sklearn.preprocessing import StandardScaler\n",
+    "from sklearn.cluster import KMeans\n",
+    "from sklearn.metrics.cluster import adjusted_rand_score\n",
+    "\n",
+    "from yellowbrick.cluster import KElbowVisualizer\n",
+    "from yellowbrick.cluster import SilhouetteVisualizer"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# To remove some warnings (setting with a copy)\n",
+    "pd.options.mode.chained_assignment = None"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We will be using all our available data (so UK and the other countries)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Loading data\n",
+    "df = pd.read_csv('static/customer_segmentation.csv', encoding='latin1')"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We change our InvoiceDate column into a datetime column."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df['InvoiceDate'] = pd.to_datetime(df['InvoiceDate'])\n",
+    "df['InvoiceDate'] = df['InvoiceDate'].dt.to_period('D')\n",
+    "df['InvoiceDate'] = df['InvoiceDate'].astype('datetime64[ns]')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We remove missing rows and columns we won't use in this analysis\n",
+    "df = df[df['CustomerID'].notnull()]\n",
+    "df = df.reset_index()\n",
+    "df = df.drop(['StockCode', 'Country', 'index'], axis=1)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We remove the order amounts that have a negative value (discounts or returned orders)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "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>CustomerID</th>\n",
+       "      <th>Description</th>\n",
+       "      <th>Quantity</th>\n",
+       "      <th>UnitPrice</th>\n",
+       "      <th>InvoiceNo</th>\n",
+       "      <th>InvoiceDate</th>\n",
+       "      <th>TotalAmount</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>47</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER RED POLKA DOT</td>\n",
+       "      <td>6</td>\n",
+       "      <td>1.85</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>2010-12-01</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>48</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER UNION JACK</td>\n",
+       "      <td>6</td>\n",
+       "      <td>1.85</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>2010-12-01</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>49</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE HANGING HEART T-LIGHT HOLDER</td>\n",
+       "      <td>6</td>\n",
+       "      <td>2.55</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01</td>\n",
+       "      <td>15.30</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>50</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE METAL LANTERN</td>\n",
+       "      <td>6</td>\n",
+       "      <td>3.39</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01</td>\n",
+       "      <td>20.34</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>51</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>CREAM CUPID HEARTS COAT HANGER</td>\n",
+       "      <td>8</td>\n",
+       "      <td>2.75</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01</td>\n",
+       "      <td>22.00</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "    CustomerID                         Description  Quantity  UnitPrice   \n",
+       "47     17850.0           HAND WARMER RED POLKA DOT         6       1.85  \\\n",
+       "48     17850.0              HAND WARMER UNION JACK         6       1.85   \n",
+       "49     17850.0  WHITE HANGING HEART T-LIGHT HOLDER         6       2.55   \n",
+       "50     17850.0                 WHITE METAL LANTERN         6       3.39   \n",
+       "51     17850.0      CREAM CUPID HEARTS COAT HANGER         8       2.75   \n",
+       "\n",
+       "   InvoiceNo InvoiceDate  TotalAmount  \n",
+       "47    536372  2010-12-01        11.10  \n",
+       "48    536372  2010-12-01        11.10  \n",
+       "49    536373  2010-12-01        15.30  \n",
+       "50    536373  2010-12-01        20.34  \n",
+       "51    536373  2010-12-01        22.00  "
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "df['TotalAmount'] = df['Quantity'] * df['UnitPrice']\n",
+    "data_null = df[df['TotalAmount'] < 0]\n",
+    "data_null['Quantity'] = - data_null['Quantity']\n",
+    "data_null['TotalAmount'] = - data_null['TotalAmount']\n",
+    "data_null = data_null[['CustomerID', 'Description', 'Quantity', 'UnitPrice', 'TotalAmount']]\n",
+    "\n",
+    "data_not_null = df[df['TotalAmount'] >= 0]\n",
+    "data_not_null['Quantity'] = - data_not_null['Quantity']\n",
+    "data_not_null['TotalAmount'] = - data_not_null['TotalAmount']\n",
+    "data_not_null = data_not_null[['CustomerID', 'Description', 'Quantity', 'UnitPrice', 'TotalAmount']]\n",
+    "\n",
+    "df_concat = pd.concat([data_null, data_not_null])\n",
+    "df_concat = df_concat.drop_duplicates()\n",
+    "df_concat = df_concat.drop('TotalAmount', axis=1)\n",
+    "\n",
+    "data_concat = pd.concat([df_concat, df])\n",
+    "null_quantity = data_concat[data_concat['Quantity'] < 0]\n",
+    "data_concat = data_concat.drop(null_quantity.index)\n",
+    "data_concat = data_concat.drop_duplicates(subset=['CustomerID', 'Description', 'Quantity', 'UnitPrice', 'TotalAmount'])\n",
+    "data_concat.head()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Functions for RFM"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we will define several functions : a function to subset our dataframe based on dates and then functions to create our RFM features."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Subset dates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def data_subset(data, beginning='2010-12-01', end='2011-12-09'):\n",
+    "    \n",
+    "    beginning = pd.to_datetime(beginning)\n",
+    "    end = pd.to_datetime(end)\n",
+    "    \n",
+    "    # Subsetting\n",
+    "    data = data[(data['InvoiceDate'] >= beginning) & (data['InvoiceDate'] <= end)]\n",
+    "\n",
+    "    return data"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Recency"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def recency(data):\n",
+    "    new_data = data.copy()\n",
+    "    last_day = new_data['InvoiceDate'].max()\n",
+    "\n",
+    "    recency = []\n",
+    "    for value in new_data['InvoiceDate']:\n",
+    "        result = last_day - value\n",
+    "        recency.append(result.days)\n",
+    "    \n",
+    "    new_data['Recency'] = recency\n",
+    "\n",
+    "    return new_data"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Frequency"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def frequency(data):\n",
+    "    new_data = data.copy()\n",
+    "\n",
+    "    frequencies_series = new_data.groupby('CustomerID')['InvoiceNo'].unique()\n",
+    "\n",
+    "    nb_orders = []\n",
+    "    for value in frequencies_series.values:\n",
+    "        nb_orders.append(len(value))\n",
+    "\n",
+    "    indexes = frequencies_series.index\n",
+    "\n",
+    "    df_freq = pd.DataFrame(nb_orders, columns=['NbOrder'])\n",
+    "    df_freq['CustomerID'] = indexes\n",
+    "\n",
+    "    df_merge = new_data.merge(df_freq, on='CustomerID')\n",
+    "\n",
+    "    df_merge['Frequency'] = df_merge['NbOrder']\n",
+    "\n",
+    "    return df_merge"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Monetary"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def monetary(data):\n",
+    "    new_data = data.copy()\n",
+    "    new_data['Monetary'] = new_data['Quantity'] * new_data['UnitPrice']\n",
+    "\n",
+    "    return new_data"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Creating our RFM features"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def rfm(data):\n",
+    "    new_data = data.copy()\n",
+    "\n",
+    "    # We apply our previously define functions\n",
+    "    new_data = recency(new_data)\n",
+    "    new_data = frequency(new_data)\n",
+    "    new_data = monetary(new_data)\n",
+    "\n",
+    "    # We only keep the features we are interested in\n",
+    "    df_rfm = new_data[['CustomerID', 'Recency', 'Frequency', 'Monetary']]\n",
+    "\n",
+    "    # We GroupBy to get the total order value per customer\n",
+    "    monetary_sum = df_rfm.groupby('CustomerID')['Monetary'].sum()\n",
+    "    monetary_sum = pd.DataFrame(monetary_sum)\n",
+    "    monetary_sum = monetary_sum.reset_index()\n",
+    "\n",
+    "    # We remove rows with very small total order value\n",
+    "    # Main issue is that some people returned their order and\n",
+    "    # either have a total of 0 or they gained money on it\n",
+    "    # To be safe, we remove those very few rows\n",
+    "    monetary_sum = monetary_sum[monetary_sum['Monetary'] > 5]\n",
+    "\n",
+    "    df_rfm = df_rfm.drop('Monetary', axis=1)\n",
+    "    df_rfm = df_rfm.merge(monetary_sum, on='CustomerID')\n",
+    "    df_rfm = df_rfm.sort_values(['CustomerID', 'Recency'])\n",
+    "    df_rfm = df_rfm.drop_duplicates(subset='CustomerID')\n",
+    "    df_rfm = df_rfm.reset_index()\n",
+    "    df_rfm = df_rfm.drop(['index', 'CustomerID'], axis=1)\n",
+    "\n",
+    "    return df_rfm"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Score ARI: at which frequency do we need to update our clusters"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Last Day: 2011-12-09 00:00:00\n",
+      "First Day: 2010-12-01 00:00:00\n"
+     ]
+    }
+   ],
+   "source": [
+    "# We check what if the first and last dates available in our original dataframe\n",
+    "last_day = df[f'InvoiceDate'].max()\n",
+    "first_day = df['InvoiceDate'].min()\n",
+    "print('Last Day:', last_day)\n",
+    "print('First Day:', first_day)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We split the dataset into two parts: the first 9 months and then the last 3 months."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "(1602, 3)\n"
+     ]
+    },
+    {
+     "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>Recency</th>\n",
+       "      <th>Frequency</th>\n",
+       "      <th>Monetary</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>30</td>\n",
+       "      <td>3</td>\n",
+       "      <td>463.41</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>149</td>\n",
+       "      <td>1</td>\n",
+       "      <td>40.00</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>163</td>\n",
+       "      <td>2</td>\n",
+       "      <td>160.33</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>146</td>\n",
+       "      <td>1</td>\n",
+       "      <td>43.80</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>90</td>\n",
+       "      <td>3</td>\n",
+       "      <td>310.30</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "   Recency  Frequency  Monetary\n",
+       "0       30          3    463.41\n",
+       "1      149          1     40.00\n",
+       "2      163          2    160.33\n",
+       "3      146          1     43.80\n",
+       "4       90          3    310.30"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "df_rfm = data_subset(data_concat, beginning='2010-12-01', end='2011-09-01')\n",
+    "df_rfm_ini = rfm(df_rfm)\n",
+    "print(df_rfm_ini.shape)\n",
+    "df_rfm_ini.head()"
+   ]
+  },
+  {
+   "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>Recency</th>\n",
+       "      <th>Frequency</th>\n",
+       "      <th>Monetary</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>count</th>\n",
+       "      <td>1602.000000</td>\n",
+       "      <td>1602.000000</td>\n",
+       "      <td>1602.000000</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>mean</th>\n",
+       "      <td>63.584894</td>\n",
+       "      <td>3.579900</td>\n",
+       "      <td>383.292091</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>std</th>\n",
+       "      <td>62.502802</td>\n",
+       "      <td>5.552896</td>\n",
+       "      <td>1438.844267</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>min</th>\n",
+       "      <td>0.000000</td>\n",
+       "      <td>1.000000</td>\n",
+       "      <td>5.040000</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>25%</th>\n",
+       "      <td>16.000000</td>\n",
+       "      <td>1.000000</td>\n",
+       "      <td>35.400000</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>50%</th>\n",
+       "      <td>42.000000</td>\n",
+       "      <td>2.000000</td>\n",
+       "      <td>100.680000</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>75%</th>\n",
+       "      <td>91.000000</td>\n",
+       "      <td>4.000000</td>\n",
+       "      <td>291.115000</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>max</th>\n",
+       "      <td>274.000000</td>\n",
+       "      <td>89.000000</td>\n",
+       "      <td>36688.960000</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "           Recency    Frequency      Monetary\n",
+       "count  1602.000000  1602.000000   1602.000000\n",
+       "mean     63.584894     3.579900    383.292091\n",
+       "std      62.502802     5.552896   1438.844267\n",
+       "min       0.000000     1.000000      5.040000\n",
+       "25%      16.000000     1.000000     35.400000\n",
+       "50%      42.000000     2.000000    100.680000\n",
+       "75%      91.000000     4.000000    291.115000\n",
+       "max     274.000000    89.000000  36688.960000"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We can see that some people like to order a lot\n",
+    "df_rfm_ini.describe()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We do a small preprocessing of our features :\n",
+    "\n",
+    "- We apply a log function to the \"Frequency\" and \"Monetary\" features which are very skewed,\n",
+    "- We scale all our features.\n",
+    "\n",
+    "We need to to it once for our original dataframe (9 months of data) and we'll use this preprocessing later on."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Applying a log function\n",
+    "df_rfm_ini['Frequency'] = np.log(df_rfm_ini['Frequency'])\n",
+    "df_rfm_ini['Monetary'] = np.log(df_rfm_ini['Monetary'])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "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>Recency</th>\n",
+       "      <th>Frequency</th>\n",
+       "      <th>Monetary</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>-0.537502</td>\n",
+       "      <td>0.308927</td>\n",
+       "      <td>0.985611</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>1.367007</td>\n",
+       "      <td>-1.014213</td>\n",
+       "      <td>-0.666035</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>1.591067</td>\n",
+       "      <td>-0.179405</td>\n",
+       "      <td>0.270014</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>1.318994</td>\n",
+       "      <td>-1.014213</td>\n",
+       "      <td>-0.604847</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>0.422755</td>\n",
+       "      <td>0.308927</td>\n",
+       "      <td>0.715202</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "    Recency  Frequency  Monetary\n",
+       "0 -0.537502   0.308927  0.985611\n",
+       "1  1.367007  -1.014213 -0.666035\n",
+       "2  1.591067  -0.179405  0.270014\n",
+       "3  1.318994  -1.014213 -0.604847\n",
+       "4  0.422755   0.308927  0.715202"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Scaling our data\n",
+    "scaler_ini = StandardScaler()\n",
+    "scaler_ini.fit(df_rfm_ini[['Recency', 'Frequency', 'Monetary']])\n",
+    "\n",
+    "df_rfm_ini[['Recency', 'Frequency', 'Monetary']] = scaler_ini.transform(df_rfm_ini[['Recency', 'Frequency', 'Monetary']])\n",
+    "df_rfm_ini = pd.DataFrame(df_rfm_ini, columns=['Recency', 'Frequency', 'Monetary'])\n",
+    "df_rfm_ini.head()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We create a preprocessing function to be able to compare two kinds of preprocessing (one taking into account the new data, the other using our old data)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def preprocessing(data):\n",
+    "    new_data = data.copy()\n",
+    "    new_data['Frequency'] = np.log(new_data['Frequency'])\n",
+    "    new_data['Monetary'] = np.log(new_data['Monetary'])\n",
+    "\n",
+    "    scaler = StandardScaler()\n",
+    "    scaler.fit(new_data[['Recency', 'Frequency', 'Monetary']])\n",
+    "\n",
+    "    new_data[['Recency', 'Frequency', 'Monetary']] = scaler.transform(new_data[['Recency', 'Frequency', 'Monetary']])\n",
+    "    new_data = pd.DataFrame(new_data, columns=['Recency', 'Frequency', 'Monetary'])\n",
+    "\n",
+    "    return new_data"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "From pour previous analysis, we know we can cluster our clients into 4 groups.\n",
+    "\n",
+    "We will use a specific random_state to have smoother results. No matter the random_state, results are fundamentally the same."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(array([0, 1, 2, 3], dtype=int32), array([558, 231, 301, 512]))"
+      ]
+     },
+     "execution_count": 26,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "kmeans = KMeans(n_init='auto', n_clusters=4, random_state=58)\n",
+    "kmeans.fit(df_rfm_ini)\n",
+    "np.unique(kmeans.labels_, return_counts=True)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we want to use our initial preprocessing for the final 3 months of our dataset and then compare with a new preprocessing that would be done each time."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 27,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "100%|██████████| 16/16 [00:01<00:00,  8.63it/s]\n",
+      "100%|██████████| 16/16 [00:01<00:00,  8.66it/s]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# We start by using the old preprocessing\n",
+    "list_df_old = []\n",
+    "\n",
+    "for i in tqdm(range(0, 112, 7)):\n",
+    "    # We create the subset\n",
+    "    new_data = data_subset(data_concat, beginning=date(2010, 12, 1), end=date(2011, 9, 1) + timedelta(days=i))\n",
+    "\n",
+    "    # We get the features\n",
+    "    new_data_rfm = rfm(new_data)\n",
+    "\n",
+    "    # We do the original preprocessing\n",
+    "    new_data_rfm['Frequency'] = np.log(new_data_rfm['Frequency'])\n",
+    "    new_data_rfm['Monetary'] = np.log(new_data_rfm['Monetary'])\n",
+    "\n",
+    "    new_data_rfm[['Recency', 'Frequency', 'Monetary']] = scaler_ini.transform(new_data_rfm[['Recency', 'Frequency', 'Monetary']])\n",
+    "    new_data_rfm = pd.DataFrame(new_data_rfm, columns=['Recency', 'Frequency', 'Monetary'])\n",
+    "\n",
+    "    # We predict the clusters with our kmeans model\n",
+    "    y = kmeans.predict(new_data_rfm)\n",
+    "    new_data_rfm['old_cluster'] = y\n",
+    "    list_df_old.append(new_data_rfm)\n",
+    "\n",
+    "# We continue by using a new preprocessing each time\n",
+    "list_df_new = []\n",
+    "\n",
+    "for i in tqdm(range(0, 112, 7)):\n",
+    "    # We create the subset\n",
+    "    new_data = data_subset(data_concat, beginning=date(2010, 12, 1), end=date(2011, 9, 1) + timedelta(days=i))\n",
+    "\n",
+    "    # We get the features\n",
+    "    new_data_rfm = rfm(new_data)\n",
+    "\n",
+    "    # We aplly a new preprocessing\n",
+    "    new_data_rfm = preprocessing(new_data_rfm)\n",
+    "    \n",
+    "    # We predict the clusters by fitting to the new data\n",
+    "    y = kmeans.fit_predict(new_data_rfm)\n",
+    "    new_data_rfm['new_cluster'] = y\n",
+    "    list_df_new.append(new_data_rfm)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 28,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Update needed every 4 weeks.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# We calcule the ARI between the old and new clustering\n",
+    "list_ari = []\n",
+    "for i in range(len(list_df_new)):\n",
+    "    list_ari.append(round(adjusted_rand_score(list_df_new[i]['new_cluster'], list_df_old[i]['old_cluster']), 4))\n",
+    "\n",
+    "# When the ARI drops below 0.8, an update is necessary\n",
+    "update = 0\n",
+    "for i in range(len(list_ari)):\n",
+    "    if list_ari[i] < 0.85:\n",
+    "        update = i - 1\n",
+    "        break\n",
+    "\n",
+    "# Update frequency:\n",
+    "print(f'Update needed every {update} weeks.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 30,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "image/png": "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",
+      "text/plain": [
+       "<Figure size 800x600 with 1 Axes>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "# Graphically\n",
+    "plt.style.use('seaborn-v0_8-darkgrid')\n",
+    "plt.figure(figsize=(8, 6))\n",
+    "plt.plot(list_ari, marker='o')\n",
+    "plt.axhline(y=0.85, color='r', linestyle='--')\n",
+    "plt.axvline(x=update, color='r', linestyle='--')\n",
+    "\n",
+    "plt.title(\"ARI Score for the last 3 months\", fontsize=18)\n",
+    "plt.xlabel('Weeks', fontsize=14)\n",
+    "plt.ylabel('Adjusted Rand Index Score', fontsize=14)\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "artefact",
+   "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.4"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

4_customer_segmentation_streamlit_preparation.ipynb

@@ -0,0 +1,934 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "\n",
+    "from datetime import date\n",
+    "from datetime import timedelta"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "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>InvoiceNo</th>\n",
+       "      <th>StockCode</th>\n",
+       "      <th>Description</th>\n",
+       "      <th>Quantity</th>\n",
+       "      <th>InvoiceDate</th>\n",
+       "      <th>UnitPrice</th>\n",
+       "      <th>CustomerID</th>\n",
+       "      <th>Country</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>536365</td>\n",
+       "      <td>85123A</td>\n",
+       "      <td>WHITE HANGING HEART T-LIGHT HOLDER</td>\n",
+       "      <td>6</td>\n",
+       "      <td>12/1/2010 8:26</td>\n",
+       "      <td>2.55</td>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>536365</td>\n",
+       "      <td>71053</td>\n",
+       "      <td>WHITE METAL LANTERN</td>\n",
+       "      <td>6</td>\n",
+       "      <td>12/1/2010 8:26</td>\n",
+       "      <td>3.39</td>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>536365</td>\n",
+       "      <td>84406B</td>\n",
+       "      <td>CREAM CUPID HEARTS COAT HANGER</td>\n",
+       "      <td>8</td>\n",
+       "      <td>12/1/2010 8:26</td>\n",
+       "      <td>2.75</td>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>536365</td>\n",
+       "      <td>84029G</td>\n",
+       "      <td>KNITTED UNION FLAG HOT WATER BOTTLE</td>\n",
+       "      <td>6</td>\n",
+       "      <td>12/1/2010 8:26</td>\n",
+       "      <td>3.39</td>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>536365</td>\n",
+       "      <td>84029E</td>\n",
+       "      <td>RED WOOLLY HOTTIE WHITE HEART.</td>\n",
+       "      <td>6</td>\n",
+       "      <td>12/1/2010 8:26</td>\n",
+       "      <td>3.39</td>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "  InvoiceNo StockCode                          Description  Quantity   \n",
+       "0    536365    85123A   WHITE HANGING HEART T-LIGHT HOLDER         6  \\\n",
+       "1    536365     71053                  WHITE METAL LANTERN         6   \n",
+       "2    536365    84406B       CREAM CUPID HEARTS COAT HANGER         8   \n",
+       "3    536365    84029G  KNITTED UNION FLAG HOT WATER BOTTLE         6   \n",
+       "4    536365    84029E       RED WOOLLY HOTTIE WHITE HEART.         6   \n",
+       "\n",
+       "      InvoiceDate  UnitPrice  CustomerID         Country  \n",
+       "0  12/1/2010 8:26       2.55     17850.0  United Kingdom  \n",
+       "1  12/1/2010 8:26       3.39     17850.0  United Kingdom  \n",
+       "2  12/1/2010 8:26       2.75     17850.0  United Kingdom  \n",
+       "3  12/1/2010 8:26       3.39     17850.0  United Kingdom  \n",
+       "4  12/1/2010 8:26       3.39     17850.0  United Kingdom  "
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We load our data\n",
+    "df = pd.read_csv('static/customer_segmentation.csv', encoding='latin1')\n",
+    "df.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We change our dates feature into a datetime type\n",
+    "df['InvoiceDate'] = pd.to_datetime(df['InvoiceDate'])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/var/folders/sm/_8w8tt415w56rr72t8421wj00000gn/T/ipykernel_4478/4209121508.py:3: SettingWithCopyWarning: \n",
+      "A value is trying to be set on a copy of a slice from a DataFrame.\n",
+      "Try using .loc[row_indexer,col_indexer] = value instead\n",
+      "\n",
+      "See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy\n",
+      "  data_null['Quantity'] = - data_null['Quantity']\n",
+      "/var/folders/sm/_8w8tt415w56rr72t8421wj00000gn/T/ipykernel_4478/4209121508.py:4: SettingWithCopyWarning: \n",
+      "A value is trying to be set on a copy of a slice from a DataFrame.\n",
+      "Try using .loc[row_indexer,col_indexer] = value instead\n",
+      "\n",
+      "See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy\n",
+      "  data_null['TotalAmount'] = - data_null['TotalAmount']\n",
+      "/var/folders/sm/_8w8tt415w56rr72t8421wj00000gn/T/ipykernel_4478/4209121508.py:8: SettingWithCopyWarning: \n",
+      "A value is trying to be set on a copy of a slice from a DataFrame.\n",
+      "Try using .loc[row_indexer,col_indexer] = value instead\n",
+      "\n",
+      "See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy\n",
+      "  data_not_null['Quantity'] = - data_not_null['Quantity']\n",
+      "/var/folders/sm/_8w8tt415w56rr72t8421wj00000gn/T/ipykernel_4478/4209121508.py:9: SettingWithCopyWarning: \n",
+      "A value is trying to be set on a copy of a slice from a DataFrame.\n",
+      "Try using .loc[row_indexer,col_indexer] = value instead\n",
+      "\n",
+      "See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy\n",
+      "  data_not_null['TotalAmount'] = - data_not_null['TotalAmount']\n"
+     ]
+    },
+    {
+     "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>CustomerID</th>\n",
+       "      <th>Description</th>\n",
+       "      <th>Quantity</th>\n",
+       "      <th>UnitPrice</th>\n",
+       "      <th>InvoiceNo</th>\n",
+       "      <th>StockCode</th>\n",
+       "      <th>InvoiceDate</th>\n",
+       "      <th>Country</th>\n",
+       "      <th>TotalAmount</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>47</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER RED POLKA DOT</td>\n",
+       "      <td>6</td>\n",
+       "      <td>1.85</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>22632</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>48</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER UNION JACK</td>\n",
+       "      <td>6</td>\n",
+       "      <td>1.85</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>22633</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>49</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE HANGING HEART T-LIGHT HOLDER</td>\n",
+       "      <td>6</td>\n",
+       "      <td>2.55</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>85123A</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>15.30</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>50</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE METAL LANTERN</td>\n",
+       "      <td>6</td>\n",
+       "      <td>3.39</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>71053</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>20.34</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>51</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>CREAM CUPID HEARTS COAT HANGER</td>\n",
+       "      <td>8</td>\n",
+       "      <td>2.75</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>84406B</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>22.00</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "    CustomerID                         Description  Quantity  UnitPrice   \n",
+       "47     17850.0           HAND WARMER RED POLKA DOT         6       1.85  \\\n",
+       "48     17850.0              HAND WARMER UNION JACK         6       1.85   \n",
+       "49     17850.0  WHITE HANGING HEART T-LIGHT HOLDER         6       2.55   \n",
+       "50     17850.0                 WHITE METAL LANTERN         6       3.39   \n",
+       "51     17850.0      CREAM CUPID HEARTS COAT HANGER         8       2.75   \n",
+       "\n",
+       "   InvoiceNo StockCode         InvoiceDate         Country  TotalAmount  \n",
+       "47    536372     22632 2010-12-01 09:01:00  United Kingdom        11.10  \n",
+       "48    536372     22633 2010-12-01 09:01:00  United Kingdom        11.10  \n",
+       "49    536373    85123A 2010-12-01 09:02:00  United Kingdom        15.30  \n",
+       "50    536373     71053 2010-12-01 09:02:00  United Kingdom        20.34  \n",
+       "51    536373    84406B 2010-12-01 09:02:00  United Kingdom        22.00  "
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "df['TotalAmount'] = df['Quantity'] * df['UnitPrice']\n",
+    "data_null = df[df['TotalAmount'] < 0]\n",
+    "data_null['Quantity'] = - data_null['Quantity']\n",
+    "data_null['TotalAmount'] = - data_null['TotalAmount']\n",
+    "data_null = data_null[['CustomerID', 'Description', 'Quantity', 'UnitPrice', 'TotalAmount']]\n",
+    "\n",
+    "data_not_null = df[df['TotalAmount'] >= 0]\n",
+    "data_not_null['Quantity'] = - data_not_null['Quantity']\n",
+    "data_not_null['TotalAmount'] = - data_not_null['TotalAmount']\n",
+    "data_not_null = data_not_null[['CustomerID', 'Description', 'Quantity', 'UnitPrice', 'TotalAmount']]\n",
+    "\n",
+    "df_concat = pd.concat([data_null, data_not_null])\n",
+    "df_concat = df_concat.drop_duplicates()\n",
+    "df_concat = df_concat.drop('TotalAmount', axis=1)\n",
+    "\n",
+    "data_concat = pd.concat([df_concat, df])\n",
+    "null_quantity = data_concat[data_concat['Quantity'] < 0]\n",
+    "data_concat = data_concat.drop(null_quantity.index)\n",
+    "data_concat = data_concat.drop_duplicates(subset=['CustomerID', 'Description', 'Quantity', 'UnitPrice', 'TotalAmount'])\n",
+    "data_concat.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def data_subset(data, beginning='2010-12-01', end='2011-12-09'):\n",
+    "    \n",
+    "    beginning = pd.to_datetime(beginning)\n",
+    "    end = pd.to_datetime(end)\n",
+    "    \n",
+    "    # Subsetting\n",
+    "    data = data[(data['InvoiceDate'] >= beginning) & (data['InvoiceDate'] <= end)]\n",
+    "\n",
+    "    return data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def recency(data):\n",
+    "    new_data = data.copy()\n",
+    "    last_day = new_data['InvoiceDate'].max()\n",
+    "\n",
+    "    recency = []\n",
+    "    for value in new_data['InvoiceDate']:\n",
+    "        result = last_day - value\n",
+    "        recency.append(result.days)\n",
+    "    \n",
+    "    new_data['Recency'] = recency\n",
+    "\n",
+    "    return new_data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def frequency(data):\n",
+    "    new_data = data.copy()\n",
+    "\n",
+    "    frequencies_series = new_data.groupby('CustomerID')['InvoiceNo'].unique()\n",
+    "\n",
+    "    nb_orders = []\n",
+    "    for value in frequencies_series.values:\n",
+    "        nb_orders.append(len(value))\n",
+    "\n",
+    "    indexes = frequencies_series.index\n",
+    "\n",
+    "    df_freq = pd.DataFrame(nb_orders, columns=['NbOrder'])\n",
+    "    df_freq['CustomerID'] = indexes\n",
+    "\n",
+    "    df_merge = new_data.merge(df_freq, on='CustomerID')\n",
+    "\n",
+    "    df_merge['Frequency'] = df_merge['NbOrder']\n",
+    "\n",
+    "    return df_merge"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def monetary(data):\n",
+    "    new_data = data.copy()\n",
+    "    new_data['Monetary'] = new_data['Quantity'] * new_data['UnitPrice']\n",
+    "\n",
+    "    return new_data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def rfm(data):\n",
+    "    new_data = data.copy()\n",
+    "\n",
+    "    new_data = recency(new_data)\n",
+    "    new_data = frequency(new_data)\n",
+    "    new_data = monetary(new_data)\n",
+    "\n",
+    "    df_rfm = new_data[['CustomerID', 'Recency', 'Frequency', 'Monetary']]\n",
+    "\n",
+    "    monetary_sum = df_rfm.groupby('CustomerID')['Monetary'].sum()\n",
+    "    monetary_sum = pd.DataFrame(monetary_sum)\n",
+    "    monetary_sum = monetary_sum.reset_index()\n",
+    "    monetary_sum = monetary_sum[monetary_sum['Monetary'] > 5]\n",
+    "\n",
+    "    df_rfm = df_rfm.drop('Monetary', axis=1)\n",
+    "    df_rfm = df_rfm.merge(monetary_sum, on='CustomerID')\n",
+    "    df_rfm = df_rfm.sort_values(['CustomerID', 'Recency'])\n",
+    "    df_rfm = df_rfm.drop_duplicates(subset='CustomerID')\n",
+    "    df_rfm = df_rfm.reset_index()\n",
+    "    df_rfm = df_rfm.drop(['index'], axis=1)\n",
+    "\n",
+    "    return df_rfm"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "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>CustomerID</th>\n",
+       "      <th>Description</th>\n",
+       "      <th>Quantity</th>\n",
+       "      <th>UnitPrice</th>\n",
+       "      <th>InvoiceNo</th>\n",
+       "      <th>StockCode</th>\n",
+       "      <th>InvoiceDate</th>\n",
+       "      <th>Country</th>\n",
+       "      <th>TotalAmount</th>\n",
+       "      <th>Recency</th>\n",
+       "      <th>NbOrder</th>\n",
+       "      <th>Frequency</th>\n",
+       "      <th>Monetary</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER RED POLKA DOT</td>\n",
+       "      <td>6</td>\n",
+       "      <td>1.85</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>22632</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>11.10</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER UNION JACK</td>\n",
+       "      <td>6</td>\n",
+       "      <td>1.85</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>22633</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>11.10</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE HANGING HEART T-LIGHT HOLDER</td>\n",
+       "      <td>6</td>\n",
+       "      <td>2.55</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>85123A</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>15.30</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>15.30</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE METAL LANTERN</td>\n",
+       "      <td>6</td>\n",
+       "      <td>3.39</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>71053</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>20.34</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>20.34</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>CREAM CUPID HEARTS COAT HANGER</td>\n",
+       "      <td>8</td>\n",
+       "      <td>2.75</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>84406B</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>United Kingdom</td>\n",
+       "      <td>22.00</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>22.00</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "   CustomerID                         Description  Quantity  UnitPrice   \n",
+       "0     17850.0           HAND WARMER RED POLKA DOT         6       1.85  \\\n",
+       "1     17850.0              HAND WARMER UNION JACK         6       1.85   \n",
+       "2     17850.0  WHITE HANGING HEART T-LIGHT HOLDER         6       2.55   \n",
+       "3     17850.0                 WHITE METAL LANTERN         6       3.39   \n",
+       "4     17850.0      CREAM CUPID HEARTS COAT HANGER         8       2.75   \n",
+       "\n",
+       "  InvoiceNo StockCode         InvoiceDate         Country  TotalAmount   \n",
+       "0    536372     22632 2010-12-01 09:01:00  United Kingdom        11.10  \\\n",
+       "1    536372     22633 2010-12-01 09:01:00  United Kingdom        11.10   \n",
+       "2    536373    85123A 2010-12-01 09:02:00  United Kingdom        15.30   \n",
+       "3    536373     71053 2010-12-01 09:02:00  United Kingdom        20.34   \n",
+       "4    536373    84406B 2010-12-01 09:02:00  United Kingdom        22.00   \n",
+       "\n",
+       "   Recency  NbOrder  Frequency  Monetary  \n",
+       "0      373        9          9     11.10  \n",
+       "1      373        9          9     11.10  \n",
+       "2      373        9          9     15.30  \n",
+       "3      373        9          9     20.34  \n",
+       "4      373        9          9     22.00  "
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We apply our functions to get the new features we are interested in\n",
+    "df_info = recency(data_concat)\n",
+    "df_info = frequency(df_info)\n",
+    "df_info = monetary(df_info)\n",
+    "df_info.head()"
+   ]
+  },
+  {
+   "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>CustomerID</th>\n",
+       "      <th>Description</th>\n",
+       "      <th>Quantity</th>\n",
+       "      <th>InvoiceNo</th>\n",
+       "      <th>InvoiceDate</th>\n",
+       "      <th>TotalAmount</th>\n",
+       "      <th>Recency</th>\n",
+       "      <th>NbOrder</th>\n",
+       "      <th>Frequency</th>\n",
+       "      <th>Monetary</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER RED POLKA DOT</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>11.10</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER UNION JACK</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>11.10</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE HANGING HEART T-LIGHT HOLDER</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>15.30</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>15.30</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE METAL LANTERN</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>20.34</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>20.34</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>CREAM CUPID HEARTS COAT HANGER</td>\n",
+       "      <td>8</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>22.00</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>22.00</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "   CustomerID                         Description  Quantity InvoiceNo   \n",
+       "0     17850.0           HAND WARMER RED POLKA DOT         6    536372  \\\n",
+       "1     17850.0              HAND WARMER UNION JACK         6    536372   \n",
+       "2     17850.0  WHITE HANGING HEART T-LIGHT HOLDER         6    536373   \n",
+       "3     17850.0                 WHITE METAL LANTERN         6    536373   \n",
+       "4     17850.0      CREAM CUPID HEARTS COAT HANGER         8    536373   \n",
+       "\n",
+       "          InvoiceDate  TotalAmount  Recency  NbOrder  Frequency  Monetary  \n",
+       "0 2010-12-01 09:01:00        11.10      373        9          9     11.10  \n",
+       "1 2010-12-01 09:01:00        11.10      373        9          9     11.10  \n",
+       "2 2010-12-01 09:02:00        15.30      373        9          9     15.30  \n",
+       "3 2010-12-01 09:02:00        20.34      373        9          9     20.34  \n",
+       "4 2010-12-01 09:02:00        22.00      373        9          9     22.00  "
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We drop features we won't use\n",
+    "df_info = df_info.drop(['StockCode', 'Country', 'UnitPrice'], axis=1)\n",
+    "df_info.head()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We apply our rfm function to have the list of CustomerID values that have a \"Monetary\" feature which is positive."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([12347., 12348., 12349., ..., 18282., 18283., 18287.])"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "df_customers = rfm(df)\n",
+    "customers = df_customers['CustomerID'].unique()\n",
+    "customers"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "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>CustomerID</th>\n",
+       "      <th>Description</th>\n",
+       "      <th>Quantity</th>\n",
+       "      <th>InvoiceNo</th>\n",
+       "      <th>InvoiceDate</th>\n",
+       "      <th>TotalAmount</th>\n",
+       "      <th>Recency</th>\n",
+       "      <th>NbOrder</th>\n",
+       "      <th>Frequency</th>\n",
+       "      <th>Monetary</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER RED POLKA DOT</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>11.10</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>HAND WARMER UNION JACK</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536372</td>\n",
+       "      <td>2010-12-01 09:01:00</td>\n",
+       "      <td>11.10</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>11.10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE HANGING HEART T-LIGHT HOLDER</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>15.30</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>15.30</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>WHITE METAL LANTERN</td>\n",
+       "      <td>6</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>20.34</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>20.34</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>17850.0</td>\n",
+       "      <td>CREAM CUPID HEARTS COAT HANGER</td>\n",
+       "      <td>8</td>\n",
+       "      <td>536373</td>\n",
+       "      <td>2010-12-01 09:02:00</td>\n",
+       "      <td>22.00</td>\n",
+       "      <td>373</td>\n",
+       "      <td>9</td>\n",
+       "      <td>9</td>\n",
+       "      <td>22.00</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "   CustomerID                         Description  Quantity InvoiceNo   \n",
+       "0     17850.0           HAND WARMER RED POLKA DOT         6    536372  \\\n",
+       "1     17850.0              HAND WARMER UNION JACK         6    536372   \n",
+       "2     17850.0  WHITE HANGING HEART T-LIGHT HOLDER         6    536373   \n",
+       "3     17850.0                 WHITE METAL LANTERN         6    536373   \n",
+       "4     17850.0      CREAM CUPID HEARTS COAT HANGER         8    536373   \n",
+       "\n",
+       "          InvoiceDate  TotalAmount  Recency  NbOrder  Frequency  Monetary  \n",
+       "0 2010-12-01 09:01:00        11.10      373        9          9     11.10  \n",
+       "1 2010-12-01 09:01:00        11.10      373        9          9     11.10  \n",
+       "2 2010-12-01 09:02:00        15.30      373        9          9     15.30  \n",
+       "3 2010-12-01 09:02:00        20.34      373        9          9     20.34  \n",
+       "4 2010-12-01 09:02:00        22.00      373        9          9     22.00  "
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We apply to get only the interesting IDs\n",
+    "df_info = df_info[df_info['CustomerID'].isin(customers)]\n",
+    "df_info.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We save as a CSV file\n",
+    "df_info.to_csv('static/customer_info.csv')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "artefact",
+   "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.4"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

5_customer_segmentation_streamlit.py

@@ -0,0 +1,289 @@
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+from PIL import Image
+import datetime
+import streamlit as st
+
+#####################################################################################################################################
+st.set_page_config(layout='wide')
+
+# Sidebar:  Image + main info on dataset
+def data_subset(data, beginning='2010-12-01', end='2011-12-09'):
+    
+    beginning = pd.to_datetime(beginning)
+    end = pd.to_datetime(end)
+    
+    # Subsetting
+    data = data[(data['InvoiceDate'] >= beginning) & (data['InvoiceDate'] <= end)]
+
+    return data
+
+# Loading datasets
+df_info = pd.read_csv('static/customer_info.csv')
+df_info['InvoiceDate'] = pd.to_datetime(df_info['InvoiceDate'])
+
+with st.sidebar:
+    col1, col2, col3 = st.columns(3)
+    with col2:
+        random_image = Image.open('static/logo_random.png')
+        st.image(random_image)
+
+    # Showing top products
+    if st.checkbox('Check to see top products sold in a selected timeframe'):
+        start = st.date_input('Input beginning of the wanted timeframe', datetime.date(2010, 12, 1),
+                              min_value=datetime.date(2010, 12, 1), max_value=datetime.date(2011, 12, 9), key=1)
+        end = st.date_input('Input beginning of the wanted timeframe', datetime.date(2011, 12, 9),
+                            min_value=start, max_value=datetime.date(2011, 12, 9), key=2)
+
+        df_top_products = df_info.copy()
+        df_subset_products = data_subset(df_top_products, start, end)
+
+        df_subset_products = df_top_products.groupby('Description')['Quantity'].sum()
+        number_chosen_products = st.number_input('How many top products sold do you want to see?', value=5)
+        df_subset_products_top = pd.DataFrame(df_top_products.sort_values(by='Quantity', ascending=False)).iloc[:number_chosen_products,:]
+        df_subset_products_top = df_subset_products_top[['Description', 'Quantity']]
+        st.dataframe(df_subset_products_top)
+
+    # Showing most recent clients
+    if st.checkbox('Check to see the most recent customers in a selected timeframe'):
+        start_clts = st.date_input('Input beginning of the wanted timeframe', datetime.date(2010, 12, 1),
+                              min_value=datetime.date(2010, 12, 1), max_value=datetime.date(2011, 12, 9), key=3)
+        end_clts = st.date_input('Input beginning of the wanted timeframe', datetime.date(2011, 12, 9),
+                            min_value=start_clts, max_value=datetime.date(2011, 12, 9), key=4)
+        df_recent_customers = df_info.copy()
+        df_subset_recent_customers = data_subset(df_recent_customers, start_clts, end_clts)
+
+        df_subset_recent_customers = df_subset_recent_customers.groupby('CustomerID')['Recency'].min()
+        number_chosen_recency = st.number_input('How many recent customers do you want to see?', value=5)
+        df_subset_recent_customers_top = pd.DataFrame(df_subset_recent_customers.sort_values()).iloc[:number_chosen_recency,:]
+        st.dataframe(df_subset_recent_customers_top)
+
+    # Showing most prolific customers
+    if st.checkbox('Check to see the top customers in a selected timeframe'):
+        start_top = st.date_input('Input beginning of the wanted timeframe', datetime.date(2010, 12, 1),
+                              min_value=datetime.date(2010, 12, 1), max_value=datetime.date(2011, 12, 9), key=5)
+        end_top = st.date_input('Input beginning of the wanted timeframe', datetime.date(2011, 12, 9),
+                            min_value=start_top, max_value=datetime.date(2011, 12, 9), key=6)
+        df_top_customers = df_info.copy()
+        df_subset_top_customers = data_subset(df_top_customers, start_top, end_top)
+
+        df_subset_top_customers = df_subset_top_customers.groupby('CustomerID')['Monetary'].sum()
+        number_chosen_top_clts = st.number_input('How many top customers do you want to see?', value=5)
+        df_subset_top_customers_top = pd.DataFrame(df_subset_top_customers.sort_values(ascending=False)).iloc[:number_chosen_top_clts,:]
+        st.dataframe(df_subset_top_customers_top)
+
+#####################################################################################################################################
+st.title('E-commerce: client dashboard')
+st.write("---")
+
+# Loading dataset
+df_info_customer = df_info.copy()
+customer_id_default = int(df_info_customer['CustomerID'].min())
+
+# We choose a CustomerID
+st.number_input('CustomerID', min_value=customer_id_default, value=customer_id_default, step=1, format="%d", key='customer_id')
+customer_id = st.session_state.customer_id
+
+if customer_id not in df_info_customer['CustomerID'].values:
+    st.write('This CustomerID is not available right now, please find another.')
+
+else:
+    start_info = st.date_input('Input beginning of the wanted timeframe', datetime.date(2010, 12, 1),
+                                min_value=datetime.date(2010, 12, 1), max_value=datetime.date(2011, 12, 9), key=7)
+    end_info = st.date_input('Input beginning of the wanted timeframe', datetime.date(2011, 12, 9),
+                                min_value=start_info, max_value=datetime.date(2011, 12, 9), key=8)
+    df_subset_info_customer = data_subset(df_info_customer, start_info, end_info)
+
+    # Main info (recency, number of orders, how much the customer spent)
+    df_subset_info_customer = df_subset_info_customer[df_subset_info_customer['CustomerID'] == customer_id]
+    df_main_info = df_subset_info_customer.groupby('CustomerID').agg(Recency=('Recency', 'min'), NbOrder=('NbOrder', 'max'), MonetaryTotal=('Monetary', 'sum'))
+
+    # GroupBy to get the mean value of each order for the customer
+    df_mean_order = df_subset_info_customer.groupby(['InvoiceNo', 'CustomerID']).agg(TotalOrderValue=('Monetary', 'sum'))
+    df_mean_order = df_mean_order.groupby('CustomerID').agg(MeanOrderValue=('TotalOrderValue', 'mean'))
+
+    # GroupBy to get the most bought product and its quantity
+    df_product_clts = pd.DataFrame(df_info.groupby(['CustomerID','Description'])['Quantity'].sum())
+    df_product_clts = df_product_clts.reset_index()
+    df_product_clts = df_product_clts[df_product_clts['CustomerID'] == customer_id]
+    ids, values = df_product_clts.groupby('CustomerID')['Quantity'].max().index, df_product_clts.groupby('CustomerID')['Quantity'].max().values
+    df_product_clts = df_product_clts[(df_product_clts['CustomerID'] == ids[0]) & (df_product_clts['Quantity'] == values[0])]
+
+    # Now we create the columns we want
+    df_main_info['MeanOrderValue'] = df_mean_order['MeanOrderValue'].values[0]
+    df_main_info['MostOrderedProduct'] = df_product_clts['Description'].values[0]
+    df_main_info['MostOrderedProductQuantity'] = df_product_clts['Quantity'].values[0]
+
+    # We can show it now that it's complete
+    st.dataframe(df_main_info)
+
+    st.write("---")
+    #####################################################################################################################################
+    st.subheader('Similarity between customers:')
+    with st.expander('Choose a number of similar customers to compare:'):
+
+        if st.checkbox('Only similar customers:'):
+            options_similar = ['Recency', 'NbOrder', 'MonetaryTotal', 'MeanOrderValue']
+            option_similar = st.selectbox('Choose a feature to plot:', tuple(options_similar))
+
+            df_similar_customer = df_info.copy()
+
+            # Main info (recency, number of orders, how much the customer spent)
+            df_similar_customer_grouped = df_similar_customer.groupby('CustomerID').agg(Recency=('Recency', 'min'), NbOrder=('NbOrder', 'max'), MonetaryTotal=('Monetary', 'sum'))
+
+            # GroupBy to get the mean value of each order for the customer
+            df_mean_order_similar = df_similar_customer.groupby(['InvoiceNo', 'CustomerID']).agg(TotalOrderValue=('Monetary', 'sum'))
+            df_mean_order_similar = df_mean_order_similar.groupby('CustomerID').agg(MeanOrderValue=('TotalOrderValue', 'mean'))
+
+            # Now we create the column we want
+            df_similar_customer_grouped['MeanOrderValue'] = df_mean_order_similar['MeanOrderValue'].values
+
+            # We select the client
+            df_similar_customer_grouped = df_similar_customer_grouped.reset_index()
+            df_selected_clt = df_similar_customer_grouped[df_similar_customer_grouped['CustomerID'] == customer_id]
+
+            # We calculate distances (euclidean)
+            distances = []
+            for i in range(df_similar_customer_grouped.shape[0]):
+                distance = np.linalg.norm(df_similar_customer_grouped.drop('CustomerID', axis=1).values[i] - df_selected_clt.drop('CustomerID', axis=1).values)
+                distances.append(distance)
+
+            n_neighbors = st.slider("Number of similar customers:", min_value=5, max_value=30, value=10)
+            neighbors = sorted(distances)[:n_neighbors]
+
+            # We get the indices of the similar customers
+            indices_neighbors = []
+            for i in range(len(neighbors)):
+                indices_neighbors.append(distances.index(neighbors[i]))
+
+            df_neighbors_selected = df_similar_customer_grouped.iloc[indices_neighbors, :]
+
+            fig2, ax = plt.subplots()
+            ax.set_xlabel('Customers', fontsize=17)
+            ax.set_ylabel(option_similar, fontsize=17)
+            ax.axhline(y=df_selected_clt[option_similar].values, color='r', label='axhline - full height')
+            ax = plt.boxplot(df_neighbors_selected[option_similar], showfliers=False)
+
+            st.pyplot(fig2)
+
+        if st.checkbox('Compare to all customers:'):
+            options_all = ['Recency', 'NbOrder', 'MonetaryTotal', 'MeanOrderValue']
+            option_all = st.selectbox('Choose a feature to plot:', tuple(options_all))
+
+            df_all_customer = df_info.copy()
+
+            # Main info (recency, number of orders, how much the customer spent)
+            df_all_customer_grouped = df_all_customer.groupby('CustomerID').agg(Recency=('Recency', 'min'), NbOrder=('NbOrder', 'max'), MonetaryTotal=('Monetary', 'sum'))
+
+            # GroupBy to get the mean value of each order for the customer
+            df_mean_order_all = df_all_customer.groupby(['InvoiceNo', 'CustomerID']).agg(TotalOrderValue=('Monetary', 'sum'))
+            df_mean_order_all = df_mean_order_all.groupby('CustomerID').agg(MeanOrderValue=('TotalOrderValue', 'mean'))
+
+            # Now we create the column we want
+            df_all_customer_grouped['MeanOrderValue'] = df_mean_order_all['MeanOrderValue'].values
+
+            # We select the client
+            df_selected_clt_all = df_all_customer_grouped.reset_index()
+            df_selected_clt_all = df_selected_clt_all[df_selected_clt_all['CustomerID'] == customer_id]
+
+            # We calculate distances (euclidean)
+            distances = []
+            for i in range(df_all_customer_grouped.shape[0]):
+                distance = np.linalg.norm(df_all_customer_grouped.values[i] - df_selected_clt_all.drop('CustomerID', axis=1).values)
+                distances.append(distance)
+
+            fig2, ax = plt.subplots()
+            ax.set_xlabel('Customers', fontsize=17)
+            ax.set_ylabel(option_all, fontsize=17)
+            ax.axhline(y=df_selected_clt_all[option_all].values, color='r', label='axhline - full height')
+            ax = plt.boxplot(df_all_customer_grouped[option_all], showfliers=False)
+
+            st.pyplot(fig2)
+
+    st.write("---")
+    #####################################################################################################################################
+    st.subheader('Barplot of top selected products in the selected timeframe:')
+    with st.expander('Select to choose how many top products you want to see and in which timeframe'):
+
+        start_product_date = st.date_input('Input beginning of the wanted timeframe', datetime.date(2010, 12, 1),
+                                min_value=datetime.date(2010, 12, 1), max_value=datetime.date(2011, 12, 9), key=9)
+        end_product_date = st.date_input('Input beginning of the wanted timeframe', datetime.date(2011, 12, 9),
+                                min_value=start_product_date, max_value=datetime.date(2011, 12, 9), key=10)
+        df_top_products_plot = df_info.copy()
+        df_subset_products = data_subset(df_top_products_plot, start_product_date, end_product_date)
+        start_product, end_product = st.select_slider('Select a range of top product', options=[x for x in range(1, 21)], value=(1, 10))
+        df_subset_products = df_subset_products.groupby('Description')['Quantity'].sum()
+        df_subset_products = df_subset_products.reset_index()
+        df_slider_products = df_subset_products.sort_values(by='Quantity', ascending=False)
+        df_slider_products = df_slider_products.iloc[start_product-1:end_product, :]
+
+        fig, ax = plt.subplots()
+        bars = plt.barh(y=df_slider_products['Description'], width=df_slider_products['Quantity'], color=['darkmagenta', 'darkblue', 'darkgreen', 'darkred', 'darkgrey', 'darkorange'])
+
+        ax.bar_label(bars)
+        ax = plt.gca().invert_yaxis()
+
+        st.subheader('Selected top products:')
+        st.pyplot(fig)
+
+    st.write("---")
+    #####################################################################################################################################
+
+    st.subheader('Barplot of sales:')
+    with st.expander('Select to choose the periodicity:'):
+        options_similar = ['Months', 'Days', 'Hours']
+        option_similar = st.selectbox('Choose a periodicity:', tuple(options_similar))
+
+        if option_similar == 'Months':
+            df_months = df_info.copy()
+            df_months = df_months.merge(pd.DataFrame(df_months.groupby('CustomerID')['Monetary'].sum()), on='CustomerID')
+            df_months['Periodicity'] = pd.DatetimeIndex(df_months['InvoiceDate']).month
+            df_months = df_months.sort_values('Recency')
+            df_months = df_months.drop_duplicates(subset='CustomerID')
+
+            fig1, ax1 = plt.subplots()
+            ax1 = sns.barplot(x=df_months['Periodicity'], y=df_months['Monetary_y'], errorbar=None)
+            plt.title('Sales per Months')
+            plt.xlabel('Periodicity: Months')
+            plt.ylabel('TotalOrderValue')
+            st.pyplot(fig1)
+
+        elif option_similar == 'Days':
+            df_days = df_info.copy()
+            df_days = df_days.merge(pd.DataFrame(df_days.groupby('CustomerID')['Monetary'].sum()), on='CustomerID')
+            df_days['Periodicity'] = pd.DatetimeIndex(df_days['InvoiceDate']).day
+            df_days = df_days.sort_values('Recency')
+            df_days = df_days.drop_duplicates(subset='CustomerID')
+
+            fig2, ax2 = plt.subplots()
+            ax2 = sns.barplot(x=df_days['Periodicity'], y=df_days['Monetary_y'], errorbar=None)
+            plt.title('Sales per Days')
+            plt.xlabel('Periodicity: Days')
+            plt.xticks(rotation=90)
+            plt.ylabel('TotalOrderValue')
+            st.pyplot(fig2)
+
+        elif option_similar == 'Hours':
+            df_hours = df_info.copy()
+            df_hours = df_hours.merge(pd.DataFrame(df_hours.groupby('CustomerID')['Monetary'].sum()), on='CustomerID')
+            df_hours['Periodicity'] = pd.DatetimeIndex(df_hours['InvoiceDate']).hour
+            df_hours = df_hours.sort_values('Recency')
+            df_hours = df_hours.drop_duplicates(subset='CustomerID')
+
+            fig3, ax3 = plt.subplots()
+            ax3 = sns.barplot(x=df_hours['Periodicity'], y=df_hours['Monetary_y'], errorbar=None)
+            plt.title('Sales per Hours')
+            plt.xlabel('Periodicity: Hours')
+            plt.ylabel('TotalOrderValue')
+            st.pyplot(fig3)
+
+
+    st.write("---")    
+#####################################################################################################################################
+
+col1, col2, col3, col4, col5 = st.columns(5)
+with col5:
+    logo_artefact = Image.open('static/logo_artefact.png')
+    st.image(logo_artefact)

requirements.txt

@@ -0,0 +1,8 @@
+streamlit
+pandas
+numpy
+matplotlib
+seaborn
+datetime
+Pillow
+plotly