openretailscience 0.45.0__py3-none-any.whl

openretailscience/plots/venn.py

@@ -0,0 +1,127 @@
+"""This module provides functionality for creating Venn and Euler diagrams from pandas DataFrames.
+
+It is designed to visualize relationships between sets, highlighting intersections and differences between them.
+
+### Core Features
+
+- **Supports 2-set and 3-set Diagrams**: Allows visualization of up to three overlapping sets.
+- **Venn and Euler Diagrams**: Uses Venn diagrams by default; switches to Euler diagrams when `vary_size=True`.
+- **Customizable Colors and Labels**: Automatically assigns colors and labels for subset representation.
+- **Dynamic Sizing**: Adjusts circle sizes for Euler diagrams to reflect proportions.
+- **Title and Source Attribution**: Optionally adds a title and source text.
+
+### Use Cases
+
+- **Set Comparisons**: Identify shared and unique elements across two or three sets.
+- **Proportional Representation**: Euler diagrams ensure area-accurate representation.
+- **Data Overlap Visualization**: Helps in understanding relationships within categorical data.
+
+### Limitations and Warnings
+
+- **Only Supports 2 or 3 Sets**: Does not extend to Venn diagrams with more than three sets.
+- **Pre-Aggregated Data Required**: The module does not perform data aggregation; input data
+should already be structured correctly.
+
+"""
+
+from collections.abc import Callable
+
+import pandas as pd
+from matplotlib import pyplot as plt
+from matplotlib.axes import Axes, SubplotBase
+from matplotlib_set_diagrams import EulerDiagram, VennDiagram
+
+from openretailscience.options import PlotStyleHelper
+from openretailscience.plots.styles import graph_utils as gu
+from openretailscience.plots.styles.colors import get_plot_colors
+from openretailscience.plots.styles.font_utils import get_font_properties
+from openretailscience.plots.styles.styling_helpers import PlotStyler
+
+MAX_SUPPORTED_SETS = 3
+MIN_SUPPORTED_SETS = 2
+
+
+def plot(
+    df: pd.DataFrame,
+    labels: list[str],
+    title: str | None = None,
+    source_text: str | None = None,
+    vary_size: bool = False,
+    figsize: tuple[int, int] | None = None,
+    ax: Axes | None = None,
+    subset_label_formatter: Callable | None = None,
+    **kwargs: dict[str, any],
+) -> SubplotBase:
+    """Plots a Venn or Euler diagram using subset sizes extracted from a DataFrame.
+
+    Args:
+        df (pd.DataFrame): DataFrame with 'groups' and 'percent' columns.
+        labels (list[str]): Labels for the sets in the diagram.
+        title (str, optional): Title of the plot. Defaults to None.
+        source_text (str, optional): Source text for attribution. Defaults to None.
+        vary_size (bool, optional): Whether to vary circle size based on subset sizes. Defaults to False.
+        figsize (tuple[int, int], optional): Size of the plot. Defaults to None.
+        ax (Axes, optional): Matplotlib axes object to plot on. Defaults to None.
+        subset_label_formatter (callable, optional): Function to format subset labels. Defaults to None.
+        **kwargs: Additional keyword arguments.
+
+    Returns:
+        SubplotBase: The matplotlib axes object with the plotted diagram.
+
+    Raises:
+        ValueError: If the number of sets is not 2 or 3.
+    """
+    num_sets = len(labels)
+    if num_sets not in {MIN_SUPPORTED_SETS, MAX_SUPPORTED_SETS}:
+        raise ValueError("Only 2-set or 3-set Venn diagrams are supported")
+
+    default_colors = get_plot_colors(num_sets)
+    colors = kwargs.pop("color", default_colors)
+
+    zero_group = (0, 0) if num_sets == MIN_SUPPORTED_SETS else (0, 0, 0)
+    percent_s = df.loc[df["groups"] != zero_group, ["groups", "percent"]].set_index("groups")["percent"]
+    subset_sizes = percent_s.to_dict()
+
+    subset_labels = {
+        k: subset_label_formatter(v) if subset_label_formatter else str(v) for k, v in subset_sizes.items()
+    }
+
+    if ax is None:
+        _, ax = plt.subplots(figsize=figsize)
+
+    diagram_class = EulerDiagram if vary_size else VennDiagram
+    diagram = diagram_class(
+        set_labels=labels,
+        subset_sizes=subset_sizes,
+        subset_labels=subset_labels,
+        set_colors=colors,
+        ax=ax,
+        **kwargs,
+    )
+
+    center_x, center_y, displacement = 0.5, 0.5, 0.1
+    styler = PlotStyler()
+    style = PlotStyleHelper()
+    for text in diagram.set_label_artists:
+        text.set_fontproperties(get_font_properties(style.label_font))
+        text.set_fontsize(style.label_size)
+        if num_sets == MAX_SUPPORTED_SETS and not vary_size:
+            x, y = text.get_position()
+            direction_x, direction_y = x - center_x, y - center_y
+            scale = displacement / (direction_x**2 + direction_y**2) ** 0.5
+            text.set_position((x + scale * direction_x, y + scale * direction_y))
+
+    for subset_id in subset_sizes:
+        if subset_id not in diagram.subset_label_artists:
+            continue
+        text = diagram.subset_label_artists[subset_id]
+        text.set_fontproperties(get_font_properties(style.label_font))
+
+    if title:
+        styler.apply_title(ax, title, pad=style.title_size + 20)
+
+    if source_text is not None:
+        ax.set_xticklabels([], visible=False)
+        gu.add_source_text(ax=ax, source_text=source_text, is_venn_diagram=True)
+
+    return ax

openretailscience/plots/waterfall.py

@@ -0,0 +1,217 @@
+"""This module provides functionality to generate a waterfall chart.
+
+A visualization commonly used to illustrate how
+different positive and negative values contribute to a cumulative total.Waterfall charts are effective in showing
+the incremental impact of individual components, making them particularly useful for financial analysis,
+performance tracking, and visualizing changes over time.
+
+### Features
+
+- **Waterfall Chart Creation**: Displays how different positive and negative values affect a starting total.
+- **Data Label Formatting**: Supports custom formatting for data labels, including absolute
+  values, percentages, or both.
+- **Net Line and Bar Display**: Optionally includes a net line and net bar to show the overall
+  cumulative result.
+- **Customizable Plot Style**: Options to customize chart titles, axis labels, and remove zero
+  amounts for better clarity.
+- **Handling of Zero Amounts**: Allows removal of zero amounts from the plot to avoid cluttering the chart.
+- **Interactive Elements**: Supports custom annotations for the chart with source text.
+
+### Use Cases
+
+- **Financial Analysis**: Show the breakdown of profits and losses over multiple periods, or how
+  different cost categories affect overall margin.
+- **Revenue Tracking**: Track how revenue or other key metrics change over time, and visualize
+  the impact of individual contributing factors.
+- **Performance Visualization**: Highlight how various business or product categories affect
+  overall performance, such as sales, expenses, or growth metrics.
+- **Budget Breakdown**: Visualize how different spending categories contribute to a total budget over a period.
+
+### Functionality Details
+
+- **plot()**: Generates a waterfall chart from a list of amounts and labels. It supports
+  additional customization for display settings, labels, and source text.
+- **format_data_labels()**: A helper function used to format the data labels according to the
+  specified format (absolute, percentage, both).
+"""
+
+import warnings
+from typing import Literal
+
+import pandas as pd
+from matplotlib.axes import Axes
+
+import openretailscience.plots.styles.graph_utils as gu
+from openretailscience.options import PlotStyleHelper
+from openretailscience.plots.styles.colors import get_named_color
+from openretailscience.plots.styles.font_utils import get_font_properties
+
+
+def plot(
+    amounts: list[float],
+    labels: list[str],
+    title: str | None = None,
+    y_label: str | None = None,
+    x_label: str = "",
+    source_text: str | None = None,
+    data_label_format: Literal["absolute", "percentage", "both"] | None = None,
+    display_net_bar: bool = False,
+    display_net_line: bool = False,
+    remove_zero_amounts: bool = True,
+    ax: Axes | None = None,
+    **kwargs: dict[str, any],
+) -> Axes:
+    """Generates a waterfall chart.
+
+    Waterfall plots are particularly good for showing how different things add or subtract from a starting number. For
+    instance:
+    - Changes in sales figures from one period to another
+    - Breakdown of profit margins
+    - Impact of different product categories on overall revenue
+
+    They are often used to identify key drivers of financial performance, highlight areas for
+    improvement, and communicate complex data stories to stakeholders in an intuitive manner.
+
+    Args:
+        amounts (list[float]): The amounts to plot.
+        labels (list[str]): The labels for the amounts.
+        title (str, optional): The title of the chart. Defaults to None.
+        y_label (str, optional): The y-axis label. Defaults to None.
+        x_label (str, optional): The x-axis label. Defaults to None.
+        source_text (str, optional): The source text to add to the plot. Defaults to None.
+        data_label_format (Literal["absolute", "percentage", "both", "none"], optional): The format of the data labels.
+            Defaults to "absolute".
+        display_net_bar (bool, optional): Whether to display a net bar. Defaults to False.
+        display_net_line (bool, optional): Whether to display a net line. Defaults to False.
+        remove_zero_amounts (bool, optional): Whether to remove zero amounts from the plot. Defaults to True
+        ax (Axes, optional): The matplotlib axes object to plot on. Defaults to None.
+        **kwargs: Additional keyword arguments to pass to the Pandas plot function.
+
+    Returns:
+        Axes: The matplotlib axes object.
+    """
+    if len(amounts) != len(labels):
+        raise ValueError("The lengths of amounts and labels must be the same")
+
+    data_label_format = data_label_format.lower() if data_label_format else None
+    if data_label_format is not None and data_label_format not in [
+        "absolute",
+        "percentage",
+        "both",
+    ]:
+        raise ValueError(
+            "data_label_format must be either 'absolute', 'percentage', 'both', or None.",
+        )
+
+    df = pd.DataFrame({"labels": labels, "amounts": amounts})
+
+    if remove_zero_amounts:
+        df = df[df["amounts"] != 0]
+
+    amount_total = df["amounts"].sum()
+
+    positive_color = get_named_color("positive")
+    negative_color = get_named_color("negative")
+
+    default_colors = (df["amounts"] > 0).map({True: positive_color, False: negative_color}).to_list()
+    bottom = df["amounts"].cumsum().shift(1).fillna(0).to_list()
+
+    if display_net_bar:
+        # Append a row for the net amount
+        df.loc[len(df)] = ["Net", amount_total]
+        default_colors.append(get_named_color("difference"))
+        bottom.append(0)
+
+    # Create the plot
+    width = kwargs.pop("width", 0.8)
+    color = kwargs.pop("color", default_colors)
+    ax = df.plot.bar(
+        x="labels",
+        y="amounts",
+        legend=None,
+        bottom=bottom,
+        color=color,
+        width=width,
+        ax=ax,
+        **kwargs,
+    )
+
+    extra_title_pad = 25 if data_label_format != "none" else 0
+    ax = gu.standard_graph_styles(
+        ax,
+        title=title,
+        y_label=gu.not_none(y_label, "Amounts"),
+        x_label=x_label,
+        title_pad=10 + extra_title_pad,
+    )
+
+    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),
+    )
+
+    # Add a black line at the y=0 position
+    ax.axhline(y=0, color="black", linewidth=1, zorder=-1)
+    if data_label_format is not None:
+        labels = format_data_labels(
+            df["amounts"],
+            amount_total,
+            data_label_format,
+            decimals,
+        )
+
+        style = PlotStyleHelper()
+        ax.bar_label(
+            ax.containers[0],
+            label_type="edge",
+            labels=labels,
+            padding=5,
+            fontsize=style.label_size - 1,
+            fontproperties=get_font_properties(style.label_font),
+        )
+
+    if display_net_line:
+        ax.axhline(y=amount_total, color="black", linewidth=1, linestyle="--")
+
+    if source_text is not None:
+        gu.add_source_text(ax=ax, source_text=source_text)
+
+    gu.standard_tick_styles(ax)
+
+    return ax
+
+
+def format_data_labels(
+    amounts: pd.Series,
+    total_change: float,
+    label_format: str,
+    decimals: int,
+) -> list[str]:
+    """Format the data labels based on the specified format.
+
+    Args:
+        amounts (pd.Series): The amounts to format.
+        total_change (float): The total change (sum of amounts) used for percentage calculations.
+        label_format (str): The format of the data labels ("absolute", "percentage", or "both").
+        decimals (int): The number of decimal places for formatting.
+
+    Returns:
+        list[str]: A list of formatted data label strings.
+    """
+    if label_format == "absolute":
+        return amounts.apply(lambda x: gu.human_format(x, decimals=decimals + 1)).tolist()
+
+    if total_change == 0:
+        warnings.warn(
+            "Total change is zero, cannot calculate percentages. Percentage labels will be omitted.",
+            UserWarning,
+            stacklevel=2,
+        )
+        if label_format == "percentage":
+            return [""] * len(amounts)
+        return [gu.human_format(x, decimals=decimals + 1) for x in amounts]
+
+    if label_format == "percentage":
+        return amounts.apply(lambda x: f"{x / total_change:.0%}").tolist()
+
+    return [f"{gu.human_format(x, decimals=decimals + 1)} ({x / total_change:.0%})" for x in amounts]

openretailscience/plugin.py

@@ -0,0 +1,238 @@
+"""Plugin management module for openretailscience."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import traceback
+import types
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+    from typing import Self
+
+
+class PluginManager:
+    """Manages plugins for openretailscience package."""
+
+    _instance: PluginManager | None = None
+
+    def __new__(cls: type[PluginManager]) -> Self:
+        """Singleton pattern for plugin manager."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._classes = {}
+            cls._instance._functions = {}
+            cls._instance._registered_classes = set()
+            cls._instance._registered_functions = set()
+            cls._instance._plugin_loaded = False
+        return cls._instance
+
+    def register_method(self, target_class: type, name: str, method: Callable) -> None:
+        """Register a method with the plugin manager for a specific class.
+
+        Args:
+            target_class: Class to extend
+            name: Method name
+            method: Method to register
+        """
+        class_name = target_class.__name__
+        self._classes.setdefault(class_name, {})[name] = method
+
+    def register_function_extension(self, target_function: Callable, name: str, method: Callable) -> None:
+        """Register an extension method for a standalone function.
+
+        Args:
+            target_function: Function to extend
+            name: Extension method name
+            method: Method to register
+        """
+        function_name = target_function.__name__
+        self._functions.setdefault(function_name, {})[name] = method
+
+    def extensible(self, cls_or_func: type | Callable) -> type | Callable:
+        """Decorator to make a class or function extensible via plugins."""
+        if inspect.isclass(cls_or_func):
+            return self._make_class_extensible(cls_or_func)
+        return self._make_function_extensible(cls_or_func)
+
+    def _make_class_extensible(self, cls: type) -> type:
+        """Make a class extensible via plugins."""
+        original_init = cls.__init__
+
+        @functools.wraps(original_init)
+        def wrapped_init(self, *args, **kwargs):  # noqa: ANN001, ANN002, ANN003, ANN202
+            original_init(self, *args, **kwargs)
+            plugin_mgr = plugin_manager
+            if not plugin_mgr._plugin_loaded:
+                plugin_mgr._load_all_plugins()
+            plugin_mgr.apply_methods_to_instance(self)
+
+        cls.__init__ = wrapped_init
+        self._registered_classes.add(cls.__name__)
+        return cls
+
+    def _make_function_extensible(self, func: Callable) -> Callable:
+        """Make a function extensible via plugins."""
+
+        @functools.wraps(func)
+        def wrapped_func(*args, **kwargs):  # noqa: ANN002, ANN003, ANN202
+            if not plugin_manager._plugin_loaded:
+                plugin_manager._load_all_plugins()
+
+            result = func(*args, **kwargs)
+
+            function_name = func.__name__
+            if function_name in self._functions:
+                return ExtensibleFunctionResult(result, function_name)
+            return result
+
+        self._registered_functions.add(func.__name__)
+        return wrapped_func
+
+    def _load_all_plugins(self) -> None:
+        """Load all plugins from entry points once."""
+        failed_plugins = []
+        try:
+            for entry_point in entry_points(group="openretailscience.plugins"):
+                try:
+                    plugin_register_fn = entry_point.load()
+                    plugin_register_fn(self)
+                except Exception as plugin_error:  # noqa: BLE001, PERF203
+                    failed_plugins.append((entry_point.name, str(plugin_error)))
+                    traceback.print_exc()
+            self._plugin_loaded = True
+            if failed_plugins:
+                print(f"Warning: {len(failed_plugins)} plugins failed to load: {failed_plugins}")  # noqa: T201
+        except Exception as e:  # noqa: BLE001
+            print(f"Error loading plugins: {e}")  # noqa: T201
+            traceback.print_exc()
+
+    def apply_methods_to_instance(self, instance: object) -> None:
+        """Apply all registered methods to an instance."""
+        class_name = instance.__class__.__name__
+        methods = self._classes.get(class_name, {})
+        for name, method in methods.items():
+            bound = types.MethodType(method, instance)
+            setattr(instance, name, bound)
+
+    def apply_extensions_to_function_result(self, wrapper: object, function_name: str) -> None:
+        """Apply registered extensions to a function result wrapper."""
+        for name, method in self._functions.get(function_name, {}).items():
+
+            def create_extension(wrap: object, extension_method: Callable[..., None], method_name: str) -> None:
+                def extension_wrapper(*args: tuple, **kwargs: dict) -> object:
+                    return extension_method(wrap._result, *args, **kwargs)
+
+                extension_wrapper.__name__ = method_name
+                return extension_wrapper
+
+            extension = create_extension(wrapper, method, name)
+            setattr(wrapper, name, extension)
+
+
+class ExtensibleFunctionResult:
+    """Wrapper for function results that can have extension methods."""
+
+    def __init__(self, result: object, function_name: str) -> None:
+        """Initialize a FunctionResultWrapper."""
+        self._result = result
+        self._function_name = function_name
+        plugin_manager.apply_extensions_to_function_result(self, function_name)
+
+    def __getattr__(self, name: str) -> object:
+        """Delegate attribute access to the wrapped result."""
+        if hasattr(self._result, name):
+            return getattr(self._result, name)
+        type_name = type(self._result).__name__
+        message = f"'{type_name}' object has no attribute '{name}'"
+        raise AttributeError(message)
+
+    def __repr__(self) -> str:
+        """Represent the wrapper as the wrapped result."""
+        return repr(self._result)
+
+    def __str__(self) -> str:
+        """Convert the wrapper to string as the wrapped result."""
+        return str(self._result)
+
+    def __iter__(self) -> None | Iterator:
+        """Return an iterator if the result supports iteration."""
+        if hasattr(self._result, "__iter__"):
+            return iter(self._result)
+        type_name = type(self._result).__name__
+        message = f"'{type_name}' object is not iterable"
+        raise TypeError(message)
+
+    def __getitem__(self, key: object) -> object:
+        """Support indexing if the wrapped result supports it."""
+        if not hasattr(self._result, "__getitem__"):
+            type_name = type(self._result).__name__
+            message = f"'{type_name}' object does not support indexing"
+            raise TypeError(message)
+        return self._result[key]
+
+    def __len__(self) -> int:
+        """Return the length of the wrapped result if it has one."""
+        if not hasattr(self._result, "__len__"):
+            type_name = type(self._result).__name__
+            message = f"'{type_name}' object has no len()"
+            raise TypeError(message)
+        return len(self._result)
+
+    def __add__(self, other: object) -> object:
+        """Support addition if the wrapped result supports it."""
+        if isinstance(other, ExtensibleFunctionResult):
+            return self._result + other._result
+        return self._result + other
+
+    def __radd__(self, other: object) -> object:
+        """Support right addition if the wrapped result supports it."""
+        return other + self._result
+
+    def __mul__(self, other: object) -> object:
+        """Support multiplication if the wrapped result supports it."""
+        return self._result * other
+
+    def __rmul__(self, other: object) -> object:
+        """Support right multiplication if the wrapped result supports it."""
+        return other * self._result
+
+    def __eq__(self, other: object) -> bool:
+        """Support equality comparison."""
+        if isinstance(other, ExtensibleFunctionResult):
+            return self._result == other._result
+        return self._result == other
+
+    def __hash__(self) -> int:
+        """Support hashing by delegating to the wrapped result."""
+        return hash(self._result)
+
+    def __lt__(self, other: object) -> bool:
+        """Support less than comparison."""
+        if isinstance(other, ExtensibleFunctionResult):
+            return self._result < other._result
+        return self._result < other
+
+    def __gt__(self, other: object) -> bool:
+        """Support greater than comparison."""
+        if isinstance(other, ExtensibleFunctionResult):
+            return self._result > other._result
+        return self._result > other
+
+    def __le__(self, other: object) -> bool:
+        """Support less than or equal comparison."""
+        if isinstance(other, ExtensibleFunctionResult):
+            return self._result <= other._result
+        return self._result <= other
+
+    def __ge__(self, other: object) -> bool:
+        """Support greater than or equal comparison."""
+        if isinstance(other, ExtensibleFunctionResult):
+            return self._result >= other._result
+        return self._result >= other
+
+
+plugin_manager = PluginManager()

openretailscience/segmentation/hml.py

@@ -0,0 +1,97 @@
+"""Heavy-Medium-Light (HML) Segmentation for Customer Value Classification.
+
+## Business Context
+
+The 80/20 rule dominates retail customer behavior: typically 20% of customers generate 80%
+of revenue. HML segmentation formalizes this insight by classifying customers into Heavy,
+Medium, Light, and Zero spenders, enabling targeted strategies for each value tier.
+
+## The Business Problem
+
+All customers are not equal, but many retailers treat them the same way. Marketing budgets
+are wasted on low-value customers while high-value customers don't receive appropriate
+attention. Without clear customer value classification, businesses struggle to:
+- Allocate marketing spend effectively
+- Design appropriate service levels
+- Create relevant offers for different customer types
+- Identify at-risk high-value customers
+
+## Real-World Applications
+
+### Heavy Spenders (Top ~20%)
+- VIP programs with exclusive access and premium support
+- Personalized shopping experiences and dedicated account management
+- Early access to new products and sales
+- Higher-value promotional offers and loyalty rewards
+
+### Medium Spenders (Middle ~30%)
+- Growth-focused marketing to move them toward Heavy tier
+- Category expansion offers to increase wallet share
+- Loyalty programs designed to increase purchase frequency
+- Targeted promotions based on purchase history
+
+### Light Spenders (Lower ~50%)
+- Cost-effective digital marketing channels
+- Basic loyalty programs and promotional offers
+- Automated email campaigns for reactivation
+- Focus on retention rather than acquisition costs
+
+### Zero Spenders
+- Win-back campaigns for previously active customers
+- Low-cost reactivation offers
+- Analysis for churn prevention insights
+- Potential customer file purging for database hygiene
+
+This module extends ThresholdSegmentation to implement the standard HML classification
+using Pareto-based percentile thresholds for consistent, business-relevant segments.
+"""
+
+from typing import Literal
+
+import ibis
+import pandas as pd
+
+from openretailscience.segmentation.threshold import ThresholdSegmentation
+
+
+class HMLSegmentation(ThresholdSegmentation):
+    """Segments customers into Heavy, Medium, Light and Zero spenders based on the total spend."""
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        value_col: str | None = None,
+        agg_func: str = "sum",
+        zero_value_customers: Literal["separate_segment", "exclude", "include_with_light"] = "separate_segment",
+        group_col: str | list[str] | None = None,
+    ) -> None:
+        """Segments customers into Heavy, Medium, Light and Zero spenders based on the total spend.
+
+        HMLSegmentation is a subclass of ThresholdSegmentation and based around an industry standard definition. The
+        thresholds for Heavy (top 20%), Medium (next 30%) and Light (bottom 50%) are chosen based on the pareto
+        distribution, commonly know as the 80/20 rule. It is typically used in retail to segment customers based on
+        their spend, transaction volume or quantities purchased.
+
+        Args:
+            df (pd.DataFrame | ibis.Table): A dataframe with the transaction data.
+                The dataframe must contain a customer_id column.
+            value_col (str, optional): The column to use for the segmentation.
+                Defaults to get_option("column.unit_spend").
+            agg_func (str, optional): The aggregation function to use when grouping by customer_id. Defaults to "sum".
+            zero_value_customers (Literal["separate_segment", "exclude", "include_with_light"], optional): How to handle
+                customers with zero spend. Defaults to "separate_segment".
+            group_col (str | list[str] | None, optional): Column(s) to group by when calculating segments. When
+                specified, segments are calculated within each group independently. For example, setting
+                group_col="store_id" calculates Heavy/Medium/Light segments within each store. Defaults to None.
+        """
+        thresholds = [0.500, 0.800, 1]
+        segments = ["Light", "Medium", "Heavy"]
+        super().__init__(
+            df=df,
+            value_col=value_col,
+            agg_func=agg_func,
+            thresholds=thresholds,
+            segments=segments,
+            zero_value_customers=zero_value_customers,
+            group_col=group_col,
+        )