openretailscience 0.45.0__py3-none-any.whl

openretailscience/segmentation/nlr.py

@@ -0,0 +1,218 @@
+"""New-Lapsed-Repeating (NLR) Segmentation for Customer Lifecycle Classification.
+
+## Business Context
+
+Understanding customer lifecycle stages is fundamental to retail strategy. Customers naturally
+move between periods of activity and inactivity, and identifying these transitions enables
+targeted interventions at each stage.
+
+## The Business Problem
+
+Retailers need to understand which customers are growing the base (new), which are loyal
+(repeating), and which have stopped purchasing (lapsed). Without this classification,
+marketing budgets are misallocated — spending acquisition dollars on existing customers
+or ignoring at-risk customers who are about to churn.
+
+## Segment Definitions
+
+Given two time periods (P1 and P2), customers are classified based on where they have
+a positive aggregated value:
+
+- **New**: Positive value in P2 only — these customers were acquired in the later period
+- **Repeating**: Positive value in both P1 and P2 — these customers are retained
+- **Lapsed**: Positive value in P1 only — these customers have stopped purchasing
+
+A customer must have a positive aggregated value (> 0) in a period to be considered as
+having "bought" in that period. Zero or negative values do not count. Customers with
+no positive value in either period are excluded from the results entirely, as they do
+not meet the criteria for any segment. When using non-spend aggregation functions like
+``count`` or ``nunique``, the threshold still applies but measures transaction presence
+rather than spend.
+
+## Real-World Applications
+
+### New Customers
+- Measure acquisition effectiveness period-over-period
+- Design onboarding journeys to convert first-time buyers to repeat customers
+- Track new customer quality (spend levels, category breadth)
+
+### Repeating Customers
+- Core loyal base driving consistent revenue
+- Cross-sell and upsell opportunities
+- Loyalty program engagement and reward optimization
+
+### Lapsed Customers
+- Win-back campaigns with targeted incentives
+- Churn root cause analysis (price sensitivity, assortment gaps)
+- Customer lifetime value recalculation and reactivation ROI modeling
+"""
+
+from __future__ import annotations
+
+import ibis
+import pandas as pd
+
+from openretailscience.options import ColumnHelper
+
+SEGMENT_NEW = "New"
+SEGMENT_REPEATING = "Repeating"
+SEGMENT_LAPSED = "Lapsed"
+
+_VALID_AGG_FUNCS = {"sum", "mean", "max", "count", "nunique"}
+
+
+class NLRSegmentation:
+    """Segments customers into New, Repeating, and Lapsed based on presence across two periods.
+
+    NLRSegmentation compares customer purchasing activity across two defined time periods (P1 and P2) to classify
+    each customer's lifecycle stage. A customer is considered active in a period only if their aggregated value is
+    strictly positive (> 0). This enables retailers to measure acquisition, retention, and churn rates in a single
+    view, and to size the revenue impact of each lifecycle segment.
+
+    The segmentation is commonly used in period-over-period reporting (e.g., year-over-year, quarter-over-quarter)
+    to answer questions such as how many customers were retained, how many were lost, and how many are newly acquired.
+    When combined with spend data, it reveals whether revenue growth is driven by new customer acquisition or by
+    increasing spend from repeating customers.
+
+    Attributes:
+        table (ibis.Table): The underlying ibis Table expression containing the segmentation results.
+            Can be used for further ibis operations before materializing to a DataFrame.
+        df (pd.DataFrame): The materialized segmentation results as a pandas DataFrame, indexed by
+            customer_id (and group_col if specified). Cached after first access.
+
+    Example:
+        >>> import pandas as pd
+        >>> from openretailscience.segmentation.nlr import NLRSegmentation
+        >>> df = pd.DataFrame({
+        ...     "customer_id": [1, 2, 3, 1, 3, 4],
+        ...     "unit_spend": [50.0, 100.0, 80.0, 75.0, 60.0, 150.0],
+        ...     "year": [2023, 2023, 2023, 2024, 2024, 2024],
+        ... })
+        >>> seg = NLRSegmentation(df=df, period_col="year", p1_value=2023, p2_value=2024)
+        >>> seg.df[["segment_name"]]
+                     segment_name
+        customer_id
+        1               Repeating
+        2                  Lapsed
+        3               Repeating
+        4                     New
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        period_col: str,
+        p1_value: str | float | ibis.Scalar,
+        p2_value: str | float | ibis.Scalar,
+        value_col: str | None = None,
+        agg_func: str = "sum",
+        group_col: str | list[str] | None = None,
+    ) -> None:
+        """Segments customers into New, Repeating, and Lapsed based on positive aggregated value across two periods.
+
+        A customer is considered to have "bought" in a period only if their aggregated value_col
+        is strictly positive (> 0). Customers are then classified as:
+        - New: positive value in P2 only
+        - Repeating: positive value in both P1 and P2
+        - Lapsed: positive value in P1 only
+
+        Args:
+            df (pd.DataFrame | ibis.Table): Transaction data. Must contain customer_id, period_col,
+                and value_col columns.
+            period_col (str): Column containing period identifiers.
+            p1_value (str | float | ibis.Scalar): Value in period_col identifying period 1.
+            p2_value (str | float | ibis.Scalar): Value in period_col identifying period 2.
+            value_col (str | None, optional): Column to aggregate for determining customer activity.
+                Defaults to ColumnHelper().unit_spend.
+            agg_func (str, optional): Aggregation function to use when grouping by customer_id.
+                Defaults to "sum".
+            group_col (str | list[str] | None, optional): Column(s) to group by when calculating segments.
+                When specified, segments are calculated within each group independently.
+                Defaults to None.
+
+        Raises:
+            ValueError: If required columns are missing from the DataFrame, or if agg_func is not
+                a supported aggregation function.
+        """
+        self._df: pd.DataFrame | None = None
+
+        cols = ColumnHelper()
+        value_col = cols.unit_spend if value_col is None else value_col
+
+        self._group_col: list[str] | None = [group_col] if isinstance(group_col, str) else group_col
+
+        if isinstance(df, pd.DataFrame):
+            df = ibis.memtable(df)
+
+        # Validate required columns
+        required_cols = [cols.customer_id, value_col, period_col]
+        if self._group_col is not None:
+            required_cols.extend(self._group_col)
+
+        missing_cols = set(required_cols) - set(df.columns)
+        if len(missing_cols) > 0:
+            msg = f"The following columns are required but missing: {missing_cols}"
+            raise ValueError(msg)
+
+        p1_expr = p1_value if isinstance(p1_value, ibis.Expr) else ibis.literal(p1_value)
+        p2_expr = p2_value if isinstance(p2_value, ibis.Expr) else ibis.literal(p2_value)
+        if p1_expr.equals(p2_expr):
+            msg = f"p1_value and p2_value must be different, got '{p1_value}' for both"
+            raise ValueError(msg)
+
+        if agg_func not in _VALID_AGG_FUNCS:
+            msg = f"agg_func must be one of {sorted(_VALID_AGG_FUNCS)}, got '{agg_func}'"
+            raise ValueError(msg)
+
+        # Filter to only P1 and P2 rows
+        df = df.filter((df[period_col] == p1_value) | (df[period_col] == p2_value))
+
+        # Determine which periods each customer has positive spend in
+        group_cols = [cols.customer_id]
+        if self._group_col is not None:
+            group_cols.extend(self._group_col)
+
+        p1_col = f"{value_col}_p1"
+        p2_col = f"{value_col}_p2"
+
+        agg_method = getattr(df[value_col], agg_func)
+        p1_agg = agg_method(where=df[period_col] == p1_value)
+        p2_agg = agg_method(where=df[period_col] == p2_value)
+        customer = df.group_by(*group_cols).aggregate(
+            **{
+                p1_col: p1_agg.fill_null(0),
+                p2_col: p2_agg.fill_null(0),
+            },
+        )
+
+        # Exclude customers with no positive value in either period
+        customer = customer.filter((customer[p1_col] > 0) | (customer[p2_col] > 0))
+
+        # Classify: both periods -> Repeating, P1 only -> Lapsed, P2 only -> New
+        # Use of ifelse ensures compatibility with some ibis backends that do not support boolean expressions in cases
+        # statements
+        in_p1 = (customer[p1_col] > 0).ifelse(1, 0)
+        in_p2 = (customer[p2_col] > 0).ifelse(1, 0)
+        segment_expr = ibis.cases(
+            ((in_p1 == 1) & (in_p2 == 1), SEGMENT_REPEATING),
+            (in_p1 == 1, SEGMENT_LAPSED),
+            (in_p2 == 1, SEGMENT_NEW),
+        )
+
+        self.table: ibis.Table = customer.mutate(segment_name=segment_expr).select(
+            *group_cols,
+            "segment_name",
+            p1_col,
+            p2_col,
+        )
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Returns the DataFrame with segment names, indexed by customer_id (and group_col if specified)."""
+        if self._df is None:
+            cols = ColumnHelper()
+            index_cols = [cols.customer_id]
+            if self._group_col is not None:
+                index_cols.extend(self._group_col)
+            self._df = self.table.execute().set_index(index_cols)
+        return self._df

openretailscience/segmentation/rfm.py

@@ -0,0 +1,307 @@
+"""Customer Segmentation Using RFM Analysis.
+
+This module implements RFM (Recency, Frequency, Monetary) segmentation, a widely used technique in customer analytics
+to categorize customers based on their purchasing behavior.
+
+RFM segmentation assigns scores to customers based on:
+1. Recency (R): How recently a customer made a purchase.
+2. Frequency (F): How often a customer makes purchases.
+3. Monetary (M): The total amount spent by a customer.
+
+### Benefits of RFM Segmentation:
+- **Customer Value Analysis**: Identifies high-value customers who contribute the most revenue.
+- **Personalized Marketing**: Enables targeted campaigns based on customer purchasing behavior.
+- **Customer Retention Strategies**: Helps recognize at-risk customers and develop engagement strategies.
+- **Sales Forecasting**: Provides insights into future revenue trends based on past spending behavior.
+
+### Scoring Methodology:
+- Each metric (R, F, M) is divided into 10 bins (0-9) using the NTILE(10) function.
+- A higher score indicates a better customer (e.g., lower recency, higher frequency, and monetary value).
+- The final RFM segment is computed as `R*100 + F*10 + M`, providing a unique customer classification.
+
+This module leverages `pandas` and `ibis` for efficient data processing and integrates with retail analytics workflows
+to enhance customer insights and business decision-making.
+"""
+
+import datetime
+
+import ibis
+import pandas as pd
+
+from openretailscience.options import ColumnHelper, get_option
+from openretailscience.utils.validation import ensure_ibis_table
+
+
+class RFMSegmentation:
+    """Segments customers using the RFM (Recency, Frequency, Monetary) methodology.
+
+    Customers are scored on three dimensions:
+    - Recency (R): Days since the last transaction (lower is better).
+    - Frequency (F): Number of unique transactions (higher is better).
+    - Monetary (M): Total amount spent (higher is better).
+
+    Each metric is ranked into bins using either NTILE or custom cut points where,
+    - The highest score represents the best score (top percentile of customers).
+    - The lowest score represents the lowest score (bottom percentile of customers).
+    The RFM segment is a 3-digit number (R*100 + F*10 + M), representing customer value.
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        current_date: str | datetime.date | None = None,
+        r_segments: int | list[float] = 10,
+        f_segments: int | list[float] = 10,
+        m_segments: int | list[float] = 10,
+        min_monetary: float | None = None,
+        max_monetary: float | None = None,
+        min_frequency: int | None = None,
+        max_frequency: int | None = None,
+    ) -> None:
+        """Initializes the RFM segmentation process.
+
+        Args:
+            df (pd.DataFrame | ibis.Table): A DataFrame or Ibis table containing transaction data.
+                Must include the following columns:
+                - customer_id
+                - transaction_date
+                - unit_spend
+                - transaction_id
+            current_date (Optional[Union[str, datetime.date]]): The reference date for calculating recency.
+                Can be a string (format: "YYYY-MM-DD"), a date object, or None (defaults to the current system date).
+            r_segments (Union[int, list[float]], optional): Number of bins (1-10) or custom percentile
+                cut points (max 9 cut points). Defaults to 10 bins.
+            f_segments (Union[int, list[float]], optional): Number of bins (1-10) or custom percentile
+                cut points (max 9 cut points). Defaults to 10 bins.
+            m_segments (Union[int, list[float]], optional): Number of bins (1-10) or custom percentile
+                cut points (max 9 cut points). Defaults to 10 bins.
+            min_monetary (Optional[float]): Minimum monetary value to include in segmentation.
+                Customers with total spend below this value will be excluded from the analysis.
+            max_monetary (Optional[float]): Maximum monetary value to include in segmentation.
+                Customers with total spend above this value will be excluded from the analysis.
+            min_frequency (Optional[int]): Minimum purchase frequency to include in segmentation.
+                Customers with fewer transactions will be excluded from the analysis.
+            max_frequency (Optional[int]): Maximum purchase frequency to include in segmentation.
+                Customers with more transactions will be excluded from the analysis.
+
+        Raises:
+            ValueError: If the dataframe is missing required columns, invalid segment parameters,
+                       or invalid filter parameters.
+            TypeError: If the input data is not a pandas DataFrame or an Ibis Table.
+        """
+        self._df: pd.DataFrame | None = None
+        cols = ColumnHelper()
+        required_cols = [
+            cols.customer_id,
+            cols.transaction_date,
+            cols.unit_spend,
+            cols.transaction_id,
+        ]
+        df = ensure_ibis_table(df)
+
+        missing_cols = set(required_cols) - set(df.columns)
+        if missing_cols:
+            error_message = f"Missing required columns: {missing_cols}"
+            raise ValueError(error_message)
+
+        if isinstance(current_date, str):
+            current_date = datetime.date.fromisoformat(current_date)
+        elif current_date is None:
+            current_date = datetime.datetime.now(datetime.timezone.utc).date()
+        elif not isinstance(current_date, datetime.date):
+            raise TypeError("current_date must be a string in 'YYYY-MM-DD' format, a datetime.date object, or None")
+
+        self._validate_segments(r_segments, "r_segments")
+        self._validate_segments(f_segments, "f_segments")
+        self._validate_segments(m_segments, "m_segments")
+        self._validate_monetary_filters(min_monetary, max_monetary)
+        self._validate_frequency_filters(min_frequency, max_frequency)
+
+        self.r_segments = r_segments
+        self.f_segments = f_segments
+        self.m_segments = m_segments
+        self.min_monetary = min_monetary
+        self.max_monetary = max_monetary
+        self.min_frequency = min_frequency
+        self.max_frequency = max_frequency
+
+        self.table = self._compute_rfm(df, current_date)
+
+    def _validate_segments(self, segments: int | list[float], param_name: str) -> None:
+        """Validates segment parameters.
+
+        Args:
+            segments: The segment parameter to validate
+            param_name: Name of the parameter for error messages
+
+        Raises:
+            ValueError: If segment parameters are invalid
+        """
+        max_segments_int = 10
+        max_segments_list = 9
+        max_segments = 1
+
+        if isinstance(segments, int):
+            if segments < max_segments or segments > max_segments_int:
+                msg = f"{param_name} must be between {max_segments} and {max_segments_int} when specified as an integer"
+                raise ValueError(msg)
+        elif isinstance(segments, list):
+            if len(segments) == 0 or len(segments) > max_segments_list:
+                msg = (
+                    f"{param_name} must contain between {max_segments} and"
+                    f" {max_segments_list} cut points when specified as a list"
+                )
+                raise ValueError(msg)
+            if not all(isinstance(x, int | float) for x in segments):  # UP038
+                msg = f"All cut points in {param_name} must be numeric"
+                raise ValueError(msg)
+            if not all(0 <= x <= 1 for x in segments):
+                msg = f"All cut points in {param_name} must be between 0 and 1"
+                raise ValueError(msg)
+            if len(segments) != len(set(segments)):
+                msg = f"Cut points in {param_name} must be unique"
+                raise ValueError(msg)
+            if segments != sorted(segments):
+                msg = f"Cut points in {param_name} must be in ascending order"
+                raise ValueError(msg)
+        else:
+            msg = f"{param_name} must be an integer or a list of floats"
+            raise TypeError(msg)
+
+    def _validate_monetary_filters(self, min_monetary: float | None, max_monetary: float | None) -> None:
+        if min_monetary is not None:
+            if not isinstance(min_monetary, int | float):
+                raise TypeError("min_monetary must be a numeric value")
+            if min_monetary < 0:
+                raise ValueError("min_monetary must be non-negative")
+
+        if max_monetary is not None:
+            if not isinstance(max_monetary, int | float):
+                raise TypeError("max_monetary must be a numeric value")
+            if max_monetary < 0:
+                raise ValueError("max_monetary must be non-negative")
+
+        if min_monetary is not None and max_monetary is not None and min_monetary >= max_monetary:
+            raise ValueError("min_monetary must be less than max_monetary")
+
+    def _validate_frequency_filters(self, min_frequency: float | None, max_frequency: float | None) -> None:
+        if min_frequency is not None:
+            if not isinstance(min_frequency, int):
+                raise TypeError("min_frequency must be an integer")
+            if min_frequency < 1:
+                raise ValueError("min_frequency must be at least 1")
+
+        if max_frequency is not None:
+            if not isinstance(max_frequency, int):
+                raise TypeError("max_frequency must be an integer")
+            if max_frequency < 1:
+                raise ValueError("max_frequency must be at least 1")
+
+        if min_frequency is not None and max_frequency is not None and min_frequency > max_frequency:
+            raise ValueError("min_frequency must be less than or equal to max_frequency")
+
+    def _compute_rfm(self, df: ibis.Table, current_date: datetime.date) -> ibis.Table:
+        """Computes the RFM metrics and segments customers accordingly.
+
+        Args:
+            df (ibis.Table): The transaction data table.
+            current_date (datetime.date): The reference date for calculating recency.
+
+        Returns:
+            ibis.Table: A table with RFM scores and segment values.
+        """
+        cols = ColumnHelper()
+        current_date_expr = ibis.literal(current_date)
+
+        customer_metrics = df.group_by(cols.customer_id).aggregate(
+            recency_days=current_date_expr.delta(df[cols.transaction_date].max().cast("date"), unit="day").cast(
+                "int32",
+            ),
+            frequency=df[cols.transaction_id].nunique(),
+            monetary=df[cols.unit_spend].sum(),
+        )
+
+        filtered_metrics = self._apply_filters(customer_metrics)
+
+        rfm_scores = filtered_metrics.mutate(
+            r_score=self._compute_score(filtered_metrics, "recency_days", self.r_segments, ascending=False),
+            f_score=self._compute_score(filtered_metrics, "frequency", self.f_segments, ascending=True),
+            m_score=self._compute_score(filtered_metrics, "monetary", self.m_segments, ascending=True),
+        )
+
+        return rfm_scores.mutate(
+            rfm_segment=(rfm_scores.r_score * 100 + rfm_scores.f_score * 10 + rfm_scores.m_score),
+            fm_segment=(rfm_scores.f_score * 10 + rfm_scores.m_score),
+        )
+
+    def _apply_filters(self, customer_metrics: ibis.Table) -> ibis.Table:
+        """Applies the specified filters to the customer metrics.
+
+        Args:
+            customer_metrics: Table with customer metrics (recency_days, frequency, monetary)
+
+        Returns:
+            Filtered table containing only customers meeting all filter criteria
+        """
+        filter_configs = [
+            ("monetary", self.min_monetary, self.max_monetary),
+            ("frequency", self.min_frequency, self.max_frequency),
+        ]
+
+        filtered_table = customer_metrics
+
+        for column_name, min_val, max_val in filter_configs:
+            if min_val is not None:
+                filtered_table = filtered_table.filter(filtered_table[column_name] >= min_val)
+
+            if max_val is not None:
+                filtered_table = filtered_table.filter(filtered_table[column_name] <= max_val)
+
+        return filtered_table
+
+    def _compute_score(
+        self,
+        table: ibis.Table,
+        column: str,
+        segments: int | list[float],
+        ascending: bool = True,
+    ) -> ibis.expr.types.IntegerColumn:
+        """Computes score for a given column using either NTILE or custom cut points.
+
+        Args:
+            table: The table containing the data
+            column: The column name to compute scores for
+            segments: Either number of bins or list of cut points
+            ascending: Whether lower values should get higher scores (for recency=False, for frequency/monetary=True)
+
+        Returns:
+            An Ibis expression representing the computed scores
+        """
+        order_fn = ibis.asc if ascending else ibis.desc
+        window = ibis.window(
+            order_by=[order_fn(table[column]), ibis.asc(table[ColumnHelper().customer_id])],
+        )
+
+        if isinstance(segments, int):
+            return ibis.ntile(segments).over(window)
+
+        percentile = table[column].percent_rank().over(window)
+
+        sorted_segments = sorted(segments)
+        case_expr = ibis.literal(0).cast("int32")
+
+        for i, cutpoint in enumerate(sorted_segments):
+            condition = percentile > ibis.literal(cutpoint)
+            case_expr = condition.ifelse(
+                ibis.literal(i + 1).cast("int32"),
+                case_expr,
+            )
+
+        return case_expr
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Returns the dataframe with the segment names."""
+        if self._df is None:
+            self._df = self.table.execute().set_index(get_option("column.customer_id"))
+        return self._df