pyretailscience 0.2.0__tar.gz → 0.3.0__tar.gz

{pyretailscience-0.2.0 → pyretailscience-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyretailscience
-Version: 0.2.0
+Version: 0.3.0
 Summary: Retail Data Science Tools
 License: Elastic-2.0
 Author: Murray Vanwyk
@@ -18,6 +18,8 @@ Requires-Dist: numpy (>=1.26.3,<2.0.0)
 Requires-Dist: pandas (>=2.1.4,<3.0.0)
 Requires-Dist: pre-commit (>=3.6.2,<4.0.0)
 Requires-Dist: pyarrow (>=14.0.2,<15.0.0)
+Requires-Dist: scikit-learn (>=1.4.2,<2.0.0)
+Requires-Dist: scipy (>=1.13.0,<2.0.0)
 Requires-Dist: seaborn (>=0.13.1,<0.14.0)
 Requires-Dist: strictyaml (>=1.7.3,<2.0.0)
 Requires-Dist: tqdm (>=4.66.1,<5.0.0)
@@ -48,25 +50,28 @@ pip install pyretailscience
 The `pyretailscience` package provides a command-line interface for generating simulated transaction data.
 
 #### Usage
+
 ```bash
 pyretailscience --config_file=<config_file_path> [--verbose=<True|False>] [--seed=<seed_number>] [output]
 ```
 
 #### Options and Arguments
+
 - `--config_file=<config_file_path>`: The path to the configuration file for the simulation. This is a required argument.
 - `--verbose=<True|False>`: Optional. Set to `True` to see debug messages. Default is `False`.
 - `--seed=<seed_number>`: Optional. Seed for the random number generator used in the simulation. If not provided, a random seed will be used.
 - `[output]`: Optional. The path where the generated transactions will be saved in parquet format. If not provided, the transactions will be saved in the current directory.
 
 #### Examples
+
 ```bash
 # Get the default transaction config file
-wget https://raw.githubusercontent.com/Data-Simply/pyretailscience/0.1.1/data/default_data_config.yaml
+wget https://raw.githubusercontent.com/Data-Simply/pyretailscience/0.3.0/data/default_data_config.yaml
 # Generate the data file
 pyretailscience --config_file=default_data_config.yaml --seed=123 transactions.parquet
 ```
-This command will generate a file named `transactions.parquet` with the simulated transaction data, using the configuration file at default data configuration file, and a seed of `123` for the random number generator.
 
+This command will generate a file named `transactions.parquet` with the simulated transaction data, using the configuration file at default data configuration file, and a seed of `123` for the random number generator.
 
 # Contributing
 

{pyretailscience-0.2.0 → pyretailscience-0.3.0}/README.md

@@ -23,25 +23,28 @@ pip install pyretailscience
 The `pyretailscience` package provides a command-line interface for generating simulated transaction data.
 
 #### Usage
+
 ```bash
 pyretailscience --config_file=<config_file_path> [--verbose=<True|False>] [--seed=<seed_number>] [output]
 ```
 
 #### Options and Arguments
+
 - `--config_file=<config_file_path>`: The path to the configuration file for the simulation. This is a required argument.
 - `--verbose=<True|False>`: Optional. Set to `True` to see debug messages. Default is `False`.
 - `--seed=<seed_number>`: Optional. Seed for the random number generator used in the simulation. If not provided, a random seed will be used.
 - `[output]`: Optional. The path where the generated transactions will be saved in parquet format. If not provided, the transactions will be saved in the current directory.
 
 #### Examples
+
 ```bash
 # Get the default transaction config file
-wget https://raw.githubusercontent.com/Data-Simply/pyretailscience/0.1.1/data/default_data_config.yaml
+wget https://raw.githubusercontent.com/Data-Simply/pyretailscience/0.3.0/data/default_data_config.yaml
 # Generate the data file
 pyretailscience --config_file=default_data_config.yaml --seed=123 transactions.parquet
 ```
-This command will generate a file named `transactions.parquet` with the simulated transaction data, using the configuration file at default data configuration file, and a seed of `123` for the random number generator.
 
+This command will generate a file named `transactions.parquet` with the simulated transaction data, using the configuration file at default data configuration file, and a seed of `123` for the random number generator.
 
 # Contributing
 

{pyretailscience-0.2.0 → pyretailscience-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pyretailscience"
-version = "0.2.0"
+version = "0.3.0"
 description = "Retail Data Science Tools"
 authors = ["Murray Vanwyk <2493311+mvanwyk@users.noreply.github.com>"]
 readme = "README.md"
@@ -19,6 +19,8 @@ loguru = "^0.7.2"
 tqdm = "^4.66.1"
 great-expectations = "^0.18.8"
 pre-commit ="^3.6.2"
+scipy = "^1.13.0"
+scikit-learn = "^1.4.2"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"

{pyretailscience-0.2.0 → pyretailscience-0.3.0}/pyretailscience/customer.py

@@ -1,12 +1,13 @@
-import matplotlib.pyplot as plt
+import operator
+
 import matplotlib.ticker as mtick
 import pandas as pd
 from matplotlib.axes import Axes, SubplotBase
 
 from pyretailscience.data.contracts import TransactionItemLevelContract
+from pyretailscience.style.graph_utils import GraphStyles as gs
 from pyretailscience.style.graph_utils import human_format, standard_graph_styles
 from pyretailscience.style.tailwind import COLORS
-import operator
 
 
 class PurchasesPerCustomer:
@@ -33,7 +34,10 @@ class PurchasesPerCustomer:
         ax: Axes | None = None,
         draw_percentile_line: bool = False,
         percentile_line: float = 0.5,
-        source_text: str = None,
+        source_text: str | None = None,
+        title: str | None = None,
+        xlabel: str | None = None,
+        ylabel: str | None = None,
         **kwargs: dict[str, any],
     ) -> SubplotBase:
         """Plot the distribution of the number of purchases per customer.
@@ -54,6 +58,9 @@ class PurchasesPerCustomer:
         if cumlative:
             density = True
 
+        if xlabel is None:
+            xlabel = "Number of purchases"
+
         ax = self.cust_purchases_s.hist(
             bins=bins,
             cumulative=cumlative,
@@ -62,21 +69,29 @@ class PurchasesPerCustomer:
             color=COLORS["green"][500],
             **kwargs,
         )
-        ax.set_xlabel("Number of purchases")
+
+        ax.set_xlabel(xlabel, fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE, labelpad=10)
         ax.xaxis.set_major_formatter(lambda x, pos: human_format(x, pos, decimals=0))
 
         ax = standard_graph_styles(ax)
 
         if cumlative:
-            plt.title("Number of Purchases Cumulative Distribution")
-            plt.ylabel("Percentage of customers")
+            if title is None:
+                title = "Number of Purchases Cumulative Distribution"
+            if ylabel is None:
+                ylabel = "Percentage of customers"
             ax.yaxis.set_major_formatter(mtick.PercentFormatter(xmax=1, decimals=0))
 
         else:
-            plt.title("Number of Purchases Distribution")
-            plt.ylabel("Number of customers")
+            if title is None:
+                title = "Number of Purchases Distribution"
+            if ylabel is None:
+                ylabel = "Number of customers"
             ax.yaxis.set_major_formatter(lambda x, pos: human_format(x, pos, decimals=0))
 
+        ax.set_title(title, fontsize=gs.DEFAULT_TITLE_FONT_SIZE, pad=15)
+        ax.set_ylabel(ylabel, fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE, labelpad=10)
+
         if draw_percentile_line:
             if percentile_line > 1 or percentile_line < 0:
                 raise ValueError("Percentile line must be between 0 and 1")
@@ -96,7 +111,7 @@ class PurchasesPerCustomer:
                 xycoords="axes fraction",
                 ha="left",
                 va="center",
-                fontsize=10,
+                fontsize=gs.DEFAULT_SOURCE_FONT_SIZE,
             )
 
         return ax
@@ -176,6 +191,9 @@ class DaysBetweenPurchases:
         ax: Axes | None = None,
         draw_percentile_line: bool = False,
         percentile_line: float = 0.5,
+        title: str | None = None,
+        xlabel: str | None = None,
+        ylabel: str | None = None,
         source_text: str = None,
         **kwargs: dict[str, any],
     ) -> SubplotBase:
@@ -204,21 +222,31 @@ class DaysBetweenPurchases:
             color=COLORS["green"][500],
             **kwargs,
         )
-        plt.xlabel("Average Number of Days Between Purchases")
+
+        if xlabel is None:
+            xlabel = "Average Number of Days Between Purchases"
+        ax.set_xlabel(xlabel, fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE, labelpad=10)
         ax.xaxis.set_major_formatter(lambda x, pos: human_format(x, pos, decimals=0))
 
         ax = standard_graph_styles(ax)
 
         if cumlative:
-            plt.title("Average Days Between Purchases Cumulative Distribution")
-            plt.ylabel("Percentage of Customers")
+            if title is None:
+                title = "Average Days Between Purchases Cumulative Distribution"
+            if ylabel is None:
+                ylabel = "Percentage of Customers"
             ax.yaxis.set_major_formatter(mtick.PercentFormatter(xmax=1, decimals=0))
 
         else:
-            plt.title("Average Days Between Purchases Distribution")
-            plt.ylabel("Number of Customers")
+            if title is None:
+                title = "Average Days Between Purchases Distribution"
+            if ylabel is None:
+                ylabel = "Number of Customers"
             ax.yaxis.set_major_formatter(lambda x, pos: human_format(x, pos, decimals=0))
 
+        ax.set_title(title, fontsize=gs.DEFAULT_TITLE_FONT_SIZE, pad=15)
+        ax.set_ylabel(ylabel, fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE, labelpad=10)
+
         if draw_percentile_line:
             if percentile_line > 1 or percentile_line < 0:
                 raise ValueError("Percentile line must be between 0 and 1")
@@ -239,7 +267,7 @@ class DaysBetweenPurchases:
                 xycoords="axes fraction",
                 ha="left",
                 va="center",
-                fontsize=10,
+                fontsize=gs.DEFAULT_SOURCE_FONT_SIZE,
             )
 
         return ax
@@ -306,6 +334,9 @@ class TransactionChurn:
         self,
         cumlative: bool = False,
         ax: Axes | None = None,
+        title: str | None = None,
+        xlabel: str | None = None,
+        ylabel: str | None = None,
         source_text: str = None,
         **kwargs: dict[str, any],
     ) -> SubplotBase:
@@ -320,7 +351,10 @@ class TransactionChurn:
         """
         if cumlative:
             cumulative_churn_rate_s = self.purchase_dist_df["churned"].cumsum().div(self.n_unique_customers)
-            ax = cumulative_churn_rate_s.plot.area(color=COLORS["green"][500])
+            ax = cumulative_churn_rate_s.plot.area(
+                color=COLORS["green"][500],
+                **kwargs,
+            )
             ax.set_xlim(self.purchase_dist_df.index.min(), self.purchase_dist_df.index.max())
         else:
             ax = self.purchase_dist_df["churned_pct"].plot.bar(
@@ -332,11 +366,17 @@ class TransactionChurn:
 
         standard_graph_styles(ax)
 
-        # Format y axis as a percent
+        if title is None:
+            title = "Churn Rate by Number of Purchases"
+        if xlabel is None:
+            xlabel = "Number of Purchases"
+        if ylabel is None:
+            ylabel = "% Churned"
+
         ax.yaxis.set_major_formatter(mtick.PercentFormatter(xmax=1.0))
-        ax.set_xlabel("Number of Purchases")
-        ax.set_ylabel("% Churned")
-        ax.set_title("Churn Rate by Number of Purchases")
+        ax.set_xlabel(xlabel, fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE, labelpad=10)
+        ax.set_ylabel(ylabel, fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE, labelpad=10)
+        ax.set_title(title, fontsize=gs.DEFAULT_TITLE_FONT_SIZE, pad=15)
 
         if source_text:
             ax.annotate(
@@ -345,7 +385,7 @@ class TransactionChurn:
                 xycoords="axes fraction",
                 ha="left",
                 va="center",
-                fontsize=10,
+                fontsize=gs.DEFAULT_SOURCE_FONT_SIZE,
             )
 
         return ax

{pyretailscience-0.2.0 → pyretailscience-0.3.0}/pyretailscience/data/simulation.py

@@ -349,10 +349,12 @@ class Simulation:
         """
         num_new_customers = self.rnd_generator.poisson(self.config["customers"]["average_new_customers_per_day"])
         logger.debug(f"Adding {num_new_customers} new customers")
+        last_customer_id = len(self.customers)
+        last_new_customer_id = last_customer_id + num_new_customers
         self.customers.extend(
             [
                 self._create_customer(customer_id=new_customer_id)
-                for new_customer_id in range(len(self.customers) + 1, num_new_customers + 1)
+                for new_customer_id in range(last_customer_id + 1, last_new_customer_id + 1)
             ]
         )
         # Simulate each customer

pyretailscience-0.3.0/pyretailscience/range_planning.py

@@ -0,0 +1,310 @@
+from typing import Literal
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes, SubplotBase
+from scipy.cluster.hierarchy import dendrogram, linkage
+
+import pyretailscience.style.graph_utils as gu
+from pyretailscience.data.contracts import TransactionItemLevelContract
+from pyretailscience.style.graph_utils import GraphStyles as gs
+
+
+class CustomerDecisionHierarchy:
+    def __init__(
+        self,
+        df: pd.DataFrame,
+        exclude_same_transaction_products: bool = True,
+        method: Literal["truncated_svd", "yules_q"] = "truncated_svd",
+        min_var_explained: float = 0.8,
+        random_state: int = 42,
+    ):
+        """
+        Initializes the RangePlanning object.
+
+        Args:
+            df (pd.DataFrame): The input dataframe containing transaction data. The dataframe must comply with the
+                TransactionItemLevelContract or the TransactionLevelContract.
+            exclude_same_transaction_products (bool, optional): Flag indicating whether to exclude products found in
+                the same transaction from a customer's distinct list of products bought. The idea is that if a
+                customer bought two products in the same transaction they can't be substitutes for that customer.
+                Thus they should be excluded from the analysis. Defaults to True.
+            method (Literal["truncated_svd", "yules_q"], optional): The method to use for calculating distances.
+                Defaults to "truncated_svd".
+            min_var_explained (float, optional): The minimum variance explained required for truncated SVD method.
+                Only applicable if method is "truncated_svd". Defaults to 0.8.
+            random_state (int, optional): Random seed for reproducibility. Defaults to 42.
+
+        Raises:
+            ValueError: If the dataframe does not comply with the TransactionItemLevelContract.
+
+        """
+        if TransactionItemLevelContract(df).validate() is False:
+            raise ValueError("The dataframe does not comply with the TransactionItemLevelContract")
+
+        self.random_state = random_state
+        self.pairs_df = self._get_pairs(df, exclude_same_transaction_products)
+        self.distances = self._calculate_distances(method=method, min_var_explained=min_var_explained)
+
+    @staticmethod
+    def _get_pairs(df: pd.DataFrame, exclude_same_transaction_products: bool) -> pd.DataFrame:
+        if exclude_same_transaction_products:
+            pairs_df = df[["customer_id", "transaction_id", "product_name"]].drop_duplicates()
+            pairs_to_exclude_df = (
+                pairs_df.groupby("transaction_id")
+                .filter(lambda x: len(x) > 1)[["customer_id", "product_name"]]
+                .drop_duplicates()
+            )
+            # Drop all rows from pairs_df where customer_id and product_name are in pairs_to_exclude_df
+            pairs_df = pairs_df.merge(
+                pairs_to_exclude_df, on=["customer_id", "product_name"], how="left", indicator=True
+            )
+            pairs_df = pairs_df[pairs_df["_merge"] == "left_only"][["customer_id", "product_name"]].drop_duplicates()
+        else:
+            pairs_df = df[["customer_id", "product_name"]].drop_duplicates()
+
+        pairs_df = pairs_df.reset_index(drop=True).astype("category")
+
+        return pairs_df
+
+    def _get_truncated_svd_distances(self, min_var_explained: float = 0.8) -> np.array:
+        """
+        Calculate the truncated SVD distances for the given pairs dataframe.
+
+        Args:
+            min_var_explained (float): The minimum variance explained required.
+
+        Returns:
+            np.array: The normalized matrix of truncated SVD distances.
+        """
+        from scipy.sparse import csr_matrix
+        from sklearn.decomposition import TruncatedSVD
+
+        sparse_matrix = csr_matrix(
+            (
+                [1] * len(self.pairs_df),
+                (
+                    self.pairs_df["product_name"].cat.codes,
+                    self.pairs_df["customer_id"].cat.codes,
+                ),
+            )
+        )
+
+        n_products = sparse_matrix.shape[0]
+        svd = TruncatedSVD(n_components=n_products, random_state=self.random_state)
+        svd.fit(sparse_matrix)
+        cuml_var = np.cumsum(svd.explained_variance_ratio_)
+
+        req_n_components = np.argmax(cuml_var >= min_var_explained) + 1
+
+        reduced_matrix = TruncatedSVD(n_components=req_n_components, random_state=self.random_state).fit_transform(
+            sparse_matrix
+        )
+        norm_matrix = reduced_matrix / np.linalg.norm(reduced_matrix, axis=1, keepdims=True)
+
+        return norm_matrix
+
+    @staticmethod
+    def _calculate_yules_q(bought_product_1: np.array, bought_product_2: np.array):
+        """
+        Calculates the Yule's Q coefficient between two binary arrays.
+
+        Args:
+            bought_product_1 (np.array): Binary array representing the first bought product. Each element is 1 if the
+                customer bought the product and 0 if they didn't.
+            bought_product_2 (np.array): Binary array representing the second bought product. Each element is 1 if the
+                customer bought the product and 0 if they didn't.
+
+        Returns:
+            float: The Yule's Q coefficient.
+
+        Raises:
+            ValueError: If the lengths of `bought_product_1` and `bought_product_2` are not the same.
+            ValueError: If `bought_product_1` or `bought_product_2` is not a boolean array.
+
+        """
+        if len(bought_product_1) != len(bought_product_2):
+            raise ValueError("The bought_product_1 and bought_product_2 must be the same length")
+        if len(bought_product_1) == 0:
+            return 0.0
+        if bought_product_1.dtype != bool or bought_product_2.dtype != bool:
+            raise ValueError("The bought_product_1 and bought_product_2 must be boolean arrays")
+
+        a = np.count_nonzero(bought_product_1 & bought_product_2)
+        b = np.count_nonzero(bought_product_1 & ~bought_product_2)
+        c = np.count_nonzero(~bought_product_1 & bought_product_2)
+        d = np.count_nonzero(~bought_product_1 & ~bought_product_2)
+
+        q = (a * d - b * c) / (a * d + b * c)
+
+        return q
+
+    def _get_yules_q_distances(self) -> float:
+        """
+        Calculate the Yules Q distances between pairs of products.
+
+        Returns:
+            float: The Yules Q distances between pairs of products.
+        """
+        from scipy.sparse import csr_matrix
+
+        # Create a sparse matrix where the rows are the customers and the columns are the products
+        # The values are True if the customer bought the product and False if they didn't
+        product_matrix = csr_matrix(
+            (
+                [True] * len(self.pairs_df),
+                (
+                    self.pairs_df["product_name"].cat.codes,
+                    self.pairs_df["customer_id"].cat.codes,
+                ),
+            ),
+            dtype=bool,
+        )
+
+        # Calculate the number of customers and products
+        n_products = product_matrix.shape[0]
+
+        # Create an empty matrix to store the yules q values
+        yules_q_matrix = np.zeros((n_products, n_products), dtype=float)
+
+        # Loop through each pair of products
+        for i in range(n_products):
+            arr_i = product_matrix[i].toarray()
+            for j in range(i + 1, n_products):
+                # Calculate the yules q value for the pair of products
+                arr_j = product_matrix[j].toarray()
+                yules_q_dist = 1 - self._calculate_yules_q(arr_i, arr_j)
+
+                # Store the yules q value in the matrix
+                yules_q_matrix[i, j] = yules_q_dist
+                yules_q_matrix[j, i] = yules_q_dist
+
+        # Normalize the yules q values to be between 0 and 1
+        yules_q_matrix = (yules_q_matrix + 1) / 2
+
+        return yules_q_matrix
+
+    def _calculate_distances(
+        self,
+        method: Literal["truncated_svd", "yules_q"],
+        min_var_explained: float,
+    ) -> None:
+        """Calculates distances between items using the specified method.
+
+        Args:
+            method (Literal["truncated_svd", "yules_q"], optional): The method to use for calculating distances.
+            min_var_explained (float, optional): The minimum variance explained required for truncated SVD method.
+                Only applicable if method is "truncated_svd".
+
+        Raises:
+            ValueError: If the method is not valid.
+
+        Returns:
+            None
+        """
+        # Check method is valid
+        if method == "truncated_svd":
+            distances = self._get_truncated_svd_distances(min_var_explained=min_var_explained)
+        elif method == "yules_q":
+            distances = self._get_yules_q_distances()
+        else:
+            raise ValueError("Method must be 'truncated_svd' or 'yules_q'")
+
+        return distances
+
+    def plot(
+        self,
+        title: str = "Customer Decision Hierarchy",
+        x_label: str | None = None,
+        y_label: str | None = None,
+        ax: Axes | None = None,
+        figsize: tuple[int, int] | None = None,
+        source_text: str | None = None,
+        **kwargs: dict[str, any],
+    ) -> SubplotBase:
+        """
+        Plots the range planning dendrogram.
+
+        Args:
+            title (str, optional): The title of the plot. Defaults to None.
+            x_label (str, optional): The label for the x-axis. Defaults to None.
+            y_label (str, optional): The label for the y-axis. Defaults to None.
+            ax (Axes, optional): The matplotlib Axes object to plot on. Defaults to None.
+            figsize (tuple[int, int], optional): The figure size. Defaults to None.
+            source_text (str, optional): The source text to annotate on the plot. Defaults to None.
+            **kwargs (dict[str, any]): Additional keyword arguments to pass to the dendrogram function.
+
+        Returns:
+            SubplotBase: The matplotlib SubplotBase object.
+        """
+        linkage_matrix = linkage(self.distances, method="ward")
+        labels = self.pairs_df["product_name"].cat.categories
+
+        if ax is None:
+            _, ax = plt.subplots(figsize=figsize)
+
+        orientation = kwargs.get("orientation", "top")
+        if orientation in ["top", "bottom"]:
+            default_x_label = "Products"
+            default_y_label = "Distance"
+        else:
+            default_x_label = "Distance"
+            default_y_label = "Products"
+
+        ax.set_title(
+            title,
+            fontsize=gs.DEFAULT_TITLE_FONT_SIZE,
+            pad=15,
+        )
+        ax.set_xlabel(
+            gu.not_none(y_label, default_x_label),
+            fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE,
+            labelpad=10,
+        )
+        ax.set_ylabel(
+            gu.not_none(x_label, default_y_label),
+            fontsize=gs.DEFAULT_AXIS_LABEL_FONT_SIZE,
+            labelpad=10,
+        )
+
+        # Set the y label to be on the right side of the plot
+        if orientation == "left":
+            ax.yaxis.tick_right()
+            ax.yaxis.set_label_position("right")
+        if orientation == "bottom":
+            ax.xaxis.tick_top()
+            ax.xaxis.set_label_position("top")
+
+        dendrogram(linkage_matrix, labels=labels, ax=ax, **kwargs)
+
+        if source_text is not None:
+            plt.draw()
+
+            y_axis_offset = -0.1
+            if orientation != "bottom":
+                bbox_height = ax.get_xaxis().get_tightbbox().height
+                axis_height = bbox_height / ax.figure.dpi / ax.figure.get_figheight()
+                y_axis_offset = min(-axis_height * 1.5, -0.1)
+
+            x_axis_offset = -0.1
+            if orientation == "right":
+                bbox_width = ax.get_yaxis().get_tightbbox().width
+                axis_width = bbox_width / ax.figure.dpi / ax.figure.get_figwidth()
+                x_axis_offset = min(-axis_width * 1.25, -0.1)
+
+            ax.annotate(
+                source_text,
+                xy=(x_axis_offset, y_axis_offset),
+                xycoords="axes fraction",
+                ha="left",
+                va="center",
+                fontsize=gs.DEFAULT_SOURCE_FONT_SIZE,
+            )
+
+        if orientation in ["top", "bottom"]:
+            ax.xaxis.set_tick_params(labelsize=gs.DEFAULT_TICK_LABEL_FONT_SIZE)
+        else:
+            ax.yaxis.set_tick_params(labelsize=gs.DEFAULT_TICK_LABEL_FONT_SIZE)
+
+        return ax

pyretailscience-0.3.0/pyretailscience/segmentation.py

@@ -0,0 +1,212 @@
+from typing import Literal
+
+import pandas as pd
+from matplotlib.axes import Axes, SubplotBase
+
+import pyretailscience.style.graph_utils as gu
+from pyretailscience.data.contracts import TransactionItemLevelContract, TransactionLevelContract
+from pyretailscience.style.tailwind import COLORS
+
+
+class HMLSegmentation:
+    def __init__(self, df: pd.DataFrame, value_col: str = "total_price") -> None:
+        """
+        Segments customers into Heavy, Medium, Light and Zero spenders based on the total spend.
+
+        Args:
+            df (pd.DataFrame): A dataframe with the transaction data. The dataframe must comply with the
+                TransactionItemLevelContract or the TransactionLevelContract.
+            value_col (str, optional): The column to use for the segmentation. Defaults to "total_price".
+
+        Raises:
+            ValueError: If the dataframe does not comply with the TransactionItemLevelContract or
+                TransactionLevelContract.
+        """
+
+        if TransactionItemLevelContract(df).validate() is False and TransactionLevelContract(df).validate() is False:
+            raise ValueError("The dataframe does not comply with the TransactionItemLevelContract")
+
+        # Group by customer_id and calculate total_spend
+        grouped_df = df.groupby("customer_id")[value_col].sum().to_frame(value_col)
+
+        # Separate customers with zero spend
+        zero_idx = grouped_df[value_col] == 0
+        zero_cust_df = grouped_df[zero_idx]
+        zero_cust_df["segment_name"] = "Zero"
+
+        hml_df = grouped_df[~zero_idx]
+
+        # Create a new column 'segment' based on the total_spend
+        hml_df["segment_name"] = pd.qcut(
+            hml_df[value_col],
+            q=[0, 0.500, 0.800, 1],
+            labels=["Light", "Medium", "Heavy"],
+        )
+
+        hml_df = pd.concat([hml_df, zero_cust_df])
+
+        segment_code_map = {"Light": "L", "Medium": "M", "Heavy": "H", "Zero": "Z"}
+
+        hml_df["segment_id"] = hml_df["segment_name"].map(segment_code_map)
+
+        self.df = grouped_df
+
+    def add_segment(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Adds the segment to the dataframe based on the customer_id column.
+
+        Args:
+            df (pd.DataFrame): The dataframe to add the segment to. The dataframe must have a customer_id column.
+
+        Returns:
+            pd.DataFrame: The dataframe with the segment added.
+
+        Raises:
+            ValueError: If the number of rows before and after the merge do not match.
+        """
+
+        # TODO: Add a contract that ensures there's a customer ID column or matches one or more of a set of contracts
+        # efficently - Eg checks all the quick validations and then tries the extended validations
+
+        rows_before = len(df)
+        df = df.merge(self.df[["segment_name", "segment_id"]], how="left", left_on="customer_id", right_index=True)
+        rows_after = len(df)
+        if rows_before != rows_after:
+            raise ValueError("The number of rows before and after the merge do not match. This should not happen.")
+
+        return df
+
+
+class SegTransactionStats:
+    def __init__(self, df: pd.DataFrame, segment_col: str = "segment_id") -> None:
+        """
+        Calculates transaction statistics by segment.
+
+        Args:
+            df (pd.DataFrame): A dataframe with the transaction data. The dataframe must comply with the
+                TransactionItemLevelContract or the TransactionLevelContract.
+            segment_col (str, optional): The column to use for the segmentation. Defaults to "segment_id".
+
+        Raises:
+            NotImplementedError: If the dataframe does not comply with the TransactionItemLevelContract or
+                TransactionLevelContract.
+
+        """
+        self.segment_col = segment_col
+        if TransactionItemLevelContract(df).validate() is True:
+            stats_df = df.groupby(segment_col).agg(
+                revenue=("total_price", "sum"),
+                transactions=("transaction_id", "nunique"),
+                customers=("customer_id", "nunique"),
+                total_quantity=("quantity", "sum"),
+            )
+            stats_df["price_per_unit"] = stats_df["revenue"] / stats_df["total_quantity"]
+            stats_df["quantity_per_transaction"] = stats_df["total_quantity"] / stats_df["transactions"]
+        elif TransactionLevelContract(df).validate() is True:
+            stats_df = df.groupby(segment_col).agg(
+                revenue=("total_price", "sum"),
+                transactions=("transaction_id", "nunique"),
+                customers=("customer_id", "nunique"),
+            )
+        else:
+            raise NotImplementedError(
+                "The dataframe does not comply with the TransactionItemLevelContract or TransactionLevelContract. "
+                "These are the only two contracts supported at this time."
+            )
+        total_num_customers = df["customer_id"].nunique()
+        stats_df["spend_per_cust"] = stats_df["revenue"] / stats_df["customers"]
+        stats_df["spend_per_transaction"] = stats_df["revenue"] / stats_df["transactions"]
+        stats_df["transactions_per_customer"] = stats_df["transactions"] / stats_df["customers"]
+        stats_df["customers_pct"] = stats_df["customers"] / total_num_customers
+
+        self.df = stats_df
+
+    def plot(
+        self,
+        value_col: str,
+        title: str | None = None,
+        x_label: str | None = None,
+        y_label: str | None = None,
+        ax: Axes | None = None,
+        orientation: Literal["vertical", "horizontal"] = "vertical",
+        sort_order: Literal["ascending", "descending", None] = None,
+        source_text: str = None,
+        **kwargs: dict[str, any],
+    ) -> SubplotBase:
+        """
+        Plots the value_col by segment.
+
+        Args:
+            value_col (str): The column to plot.
+            title (str, optional): The title of the plot. Defaults to None.
+            x_label (str, optional): The x-axis label. Defaults to None. When None the x-axis label is blank when the
+                orientation is horizontal. When the orientation is vertical it is set to the `value_col` in title case.
+            y_label (str, optional): The y-axis label. Defaults to None. When None the y-axis label is set to the
+                `value_col` in title case when the orientation is horizontal. Then the orientation is vertical it is
+                set to blank
+            ax (Axes, optional): The matplotlib axes object to plot on. Defaults to None.
+            orientation (Literal["vertical", "horizontal"], optional): The orientation of the plot. Defaults to
+                "vertical".
+            sort_order (Literal["ascending", "descending", None], optional): The sort order of the segments.
+                Defaults to None. If None, the segments are plotted in the order they appear in the dataframe.
+            source_text (str, optional): The source text to add to the plot. Defaults to None.
+            **kwargs: Additional keyword arguments to pass to the Pandas plot function.
+
+        Returns:
+            SubplotBase: The matplotlib axes object.
+
+        Raises:
+            ValueError: If the sort_order is not "ascending", "descending" or None.
+            ValueError: If the orientation is not "vertical" or "horizontal".
+        """
+
+        if sort_order not in ["ascending", "descending", None]:
+            raise ValueError("sort_order must be either 'ascending' or 'descending' or None")
+        if orientation not in ["vertical", "horizontal"]:
+            raise ValueError("orientation must be either 'vertical' or 'horizontal'")
+
+        default_title = f"{value_col.title()} by Segment"
+        kind = "bar"
+        if orientation == "horizontal":
+            kind = "barh"
+
+        val_s = self.df[value_col]
+        if sort_order is not None:
+            ascending = sort_order == "ascending"
+            val_s = val_s.sort_values(ascending=ascending)
+
+        ax = val_s.plot(
+            kind=kind,
+            color=COLORS["green"][500],
+            legend=False,
+            ax=ax,
+            **kwargs,
+        )
+        ax = gu.standard_graph_styles(ax)
+
+        if orientation == "vertical":
+            plot_y_label = gu.not_none(y_label, value_col.title())
+            plot_x_label = gu.not_none(x_label, "")
+            decimals = gu.get_decimals(ax.get_ylim(), ax.get_yticks())
+            ax.yaxis.set_major_formatter(lambda x, pos: gu.human_format(x, pos, decimals=decimals))
+        else:
+            plot_y_label = gu.not_none(y_label, "")
+            plot_x_label = gu.not_none(x_label, value_col.title())
+            decimals = gu.get_decimals(ax.get_xlim(), ax.get_xticks())
+            ax.xaxis.set_major_formatter(lambda x, pos: gu.human_format(x, pos, decimals=decimals))
+
+        ax.set_title(gu.not_none(title, default_title))
+        ax.set_ylabel(plot_y_label)
+        ax.set_xlabel(plot_x_label)
+
+        if source_text is not None:
+            ax.annotate(
+                source_text,
+                xy=(-0.1, -0.2),
+                xycoords="axes fraction",
+                ha="left",
+                va="center",
+                fontsize=10,
+            )
+
+        return ax

pyretailscience-0.3.0/pyretailscience/standard_graphs.py

@@ -0,0 +1,96 @@
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes, SubplotBase
+from pandas.tseries.offsets import BaseOffset
+
+import pyretailscience.style.graph_utils as gu
+from pyretailscience.style.tailwind import COLORS, get_linear_cmap
+
+# TODO: Consider simplifying this by reducing the color range in the get_linear_cmap function.
+COLORMAP_MIN = 0.25
+COLORMAP_MAX = 0.75
+
+
+def time_plot(
+    df: pd.DataFrame,
+    value_col: str,
+    period: str | BaseOffset = "D",
+    agg_func: str = "sum",
+    group_col: str | None = None,
+    title: str | None = None,
+    x_label: str | None = None,
+    y_label: str | None = None,
+    ax: Axes | None = None,
+    source_text: str = None,
+    **kwargs: dict[str, any],
+) -> SubplotBase:
+    """
+    Plots the value_col over time.
+
+    Args:
+        df (pd.DataFrame): The dataframe to plot.
+        value_col (str): The column to plot.
+        period (str | BaseOffset): The period to group the data by.
+        agg_func (str, optional): The aggregation function to apply to the value_col. Defaults to "sum".
+        group_col (str, optional): The column to group the data by. Defaults to None.
+        title (str, optional): The title of the plot. Defaults to None. When None the title is set to
+            `f"{value_col.title()} by {group_col.title()}"`
+        x_label (str, optional): The x-axis label. Defaults to None. When None the x-axis label is set to blank
+        y_label (str, optional): The y-axis label. Defaults to None. When None the y-axis label is set to the title
+            case of `value_col`
+        ax (Axes, optional): The matplotlib axes object to plot on. Defaults to None.
+        source_text (str, optional): The source text to add to the plot. Defaults to None.
+        **kwargs: Additional keyword arguments to pass to the Pandas plot function.
+
+    Returns:
+        SubplotBase: The matplotlib axes object.
+    """
+    df["transaction_period"] = df["transaction_datetime"].dt.to_period(period)
+
+    if group_col is None:
+        colors = COLORS["green"][500]
+        df = df.groupby("transaction_period")[value_col].agg(agg_func)
+        default_title = "Total Sales"
+        show_legend = False
+    else:
+        colors = get_linear_cmap("green")(np.linspace(COLORMAP_MIN, COLORMAP_MAX, df[group_col].nunique()))
+        df = (
+            df.groupby([group_col, "transaction_period"])[value_col]
+            .agg(agg_func)
+            .reset_index()
+            .pivot(index="transaction_period", columns=group_col, values=value_col)
+        )
+        default_title = f"{value_col.title()} by {group_col.title()}"
+        show_legend = True
+
+    ax = df.plot(
+        linewidth=3,
+        color=colors,
+        legend=show_legend,
+        ax=ax,
+        **kwargs,
+    )
+    ax = gu.standard_graph_styles(ax)
+    ax.set_ylabel(gu.not_none(y_label, value_col.title()))
+    ax.set_title(gu.not_none(title, default_title))
+    ax.set_xlabel(gu.not_none(x_label, ""))
+
+    decimals = gu.get_decimals(ax.get_ylim(), ax.get_yticks())
+    ax.yaxis.set_major_formatter(lambda x, pos: gu.human_format(x, pos, decimals=decimals))
+
+    if show_legend:
+        legend = ax.legend(title="Segment", frameon=True)
+        legend.get_frame().set_facecolor("white")
+        legend.get_frame().set_edgecolor("white")
+
+    if source_text is not None:
+        ax.annotate(
+            source_text,
+            xy=(-0.1, -0.2),
+            xycoords="axes fraction",
+            ha="left",
+            va="center",
+            fontsize=10,
+        )
+
+    return ax

pyretailscience-0.3.0/pyretailscience/style/graph_utils.py

@@ -0,0 +1,83 @@
+from matplotlib.axes import Axes
+
+
+class GraphStyles:
+    """A class to hold the styles for a graph."""
+
+    DEFAULT_TITLE_FONT_SIZE = 16
+    DEFAULT_SOURCE_FONT_SIZE = 10
+    DEFAULT_AXIS_LABEL_FONT_SIZE = 12
+    DEFAULT_TICK_LABEL_FONT_SIZE = 10
+
+
+def human_format(num, pos=None, decimals=0, prefix="") -> str:
+    """Format a number in a human readable format for Matplotlib.
+
+    Args:
+        num (float): The number to format.
+        pos (int, optional): The position. Defaults to None. Only used for Matplotlib compatibility.
+        decimals (int, optional): The number of decimals. Defaults to 0.
+        prefix (str, optional): The prefix of the returned string, eg '$'. Defaults to "".
+
+    Returns:
+        str: The formatted number.
+    """
+    magnitude = 0
+    while abs(num) >= 1000:
+        magnitude += 1
+        num /= 1000.0
+
+    # Add more suffixes if you need them
+    return f"{prefix}%.{decimals}f%s" % (num, ["", "K", "M", "G", "T", "P"][magnitude])
+
+
+def standard_graph_styles(ax: Axes) -> Axes:
+    """Apply standard styles to a Matplotlib graph.
+
+    Args:
+        ax (Axes): The graph to apply the styles to.
+
+    Returns:
+        Axes: The graph with the styles applied.
+    """
+    ax.spines[["top", "right"]].set_visible(False)
+    ax.grid(which="major", axis="x", color="#DAD8D7", alpha=0.5, zorder=1)
+    ax.grid(which="major", axis="y", color="#DAD8D7", alpha=0.5, zorder=1)
+    return ax
+
+
+def not_none(value1, value2):
+    """
+    Helper funciont that returns the first value that is not None.
+
+    Args:
+        value1: The first value.
+        value2: The second value.
+
+    Returns:
+        The first value that is not None.
+    """
+    if value1 is None:
+        return value2
+    return value1
+
+
+def get_decimals(ylim: tuple[float, float], tick_values: list[float], max_decimals: int = 100) -> int:
+    """
+    Helper function for the `human_format` function that determines the number of decimals to use for the y-axis.
+
+    Args:
+        ylim: The y-axis limits.
+        tick_values: The y-axis tick values.
+        max_decimals: The maximum number of decimals to use. Defaults to 100.
+
+    Returns:
+        int: The number of decimals to use.
+    """
+    decimals = 0
+    while True:
+        tick_labels = [human_format(t, 0, decimals=decimals) for t in tick_values if t >= ylim[0] and t <= ylim[1]]
+        if len(tick_labels) == len(set(tick_labels)) or decimals == max_decimals:
+            break
+        decimals += 1
+    return decimals

pyretailscience-0.2.0/pyretailscience/style/graph_utils.py

@@ -1,37 +0,0 @@
-from matplotlib.axes import Axes
-
-
-def human_format(num, pos=None, decimals=0, prefix="") -> str:
-    """Format a number in a human readable format for Matplotlib.
-
-    Args:
-        num (float): The number to format.
-        pos (int, optional): The position. Defaults to None. Only used for Matplotlib compatibility.
-        decimals (int, optional): The number of decimals. Defaults to 0.
-        prefix (str, optional): The prefix of the returned string, eg '$'. Defaults to "".
-
-    Returns:
-        str: The formatted number.
-    """
-    magnitude = 0
-    while abs(num) >= 1000:
-        magnitude += 1
-        num /= 1000.0
-
-    # Add more suffixes if you need them
-    return f"{prefix}%.{decimals}f%s" % (num, ["", "K", "M", "G", "T", "P"][magnitude])
-
-
-def standard_graph_styles(ax: Axes) -> Axes:
-    """Apply standard styles to a Matplotlib graph.
-
-    Args:
-        ax (Axes): The graph to apply the styles to.
-
-    Returns:
-        Axes: The graph with the styles applied.
-    """
-    ax.spines[["top", "right"]].set_visible(False)
-    ax.grid(which="major", axis="x", color="#DAD8D7", alpha=0.5, zorder=1)
-    ax.grid(which="major", axis="y", color="#DAD8D7", alpha=0.5, zorder=1)
-    return ax