openretailscience 0.45.0__py3-none-any.whl

openretailscience/segmentation/threshold.py

@@ -0,0 +1,165 @@
+"""Threshold-Based Segmentation for Flexible Business Classification.
+
+## Business Context
+
+Many retail segmentation needs don't fit standard models like RFM. Businesses often need
+custom segments based on specific metrics and thresholds - whether segmenting customers
+by spend percentiles, stores by performance quintiles, or products by sales velocity.
+This module provides flexible threshold-based segmentation for any business dimension.
+
+## The Business Problem
+
+Retailers need custom segmentation rules for different business scenarios:
+- Create spend-based customer tiers (Bronze, Silver, Gold, Platinum)
+- Classify stores into performance bands (A, B, C, D stores)
+- Segment products by velocity (Fast, Medium, Slow movers)
+- Define custom categories based on business-specific thresholds
+
+Standard segmentation approaches are too rigid, while manual classification is inconsistent
+and doesn't scale across large datasets.
+
+## Real-World Applications
+
+### Customer Classification
+- Create VIP tiers based on total spend percentiles
+- Segment by transaction frequency for different service levels
+- Classify customers by recency for retention campaigns
+
+### Store Performance Tiers
+- Classify stores by sales per square foot into performance bands
+- Segment locations by customer conversion rates
+- Create store tiers for investment prioritization
+
+### Product Categorization
+- Segment SKUs by sales velocity for inventory management
+- Classify products by margin contribution for pricing strategies
+- Create ABC analysis categories for supply chain optimization
+
+## Technical Features
+
+- Flexible percentile-based thresholds for consistent segment sizing
+- Custom aggregation functions for different business metrics
+- Configurable handling of zero-value entities
+- Efficient execution using Ibis for large datasets
+"""
+
+from typing import Literal
+
+import ibis
+import pandas as pd
+
+from openretailscience.options import ColumnHelper
+
+
+class ThresholdSegmentation:
+    """Segments customers based on user-defined thresholds and segments."""
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        thresholds: list[float],
+        segments: list[str],
+        value_col: str | None = None,
+        agg_func: str = "sum",
+        zero_segment_name: str = "Zero",
+        zero_value_customers: Literal["separate_segment", "exclude", "include_with_light"] = "separate_segment",
+        group_col: str | list[str] | None = None,
+    ) -> None:
+        """Segments customers based on user-defined thresholds and segments.
+
+        Args:
+            df (pd.DataFrame | ibis.Table): A dataframe with the transaction data. The dataframe must contain a
+                customer_id column.
+            thresholds (List[float]): The percentile thresholds for segmentation.
+            segments (List[str]): A list of segment names for each threshold.
+            value_col (str, optional): The column to use for the segmentation. Defaults to
+                ColumnHelper().unit_spend.
+            agg_func (str, optional): The aggregation function to use when grouping by customer_id. Defaults to "sum".
+            zero_segment_name (str, optional): The name of the segment for customers with zero spend.
+                Defaults to "Zero".
+            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.
+
+        Raises:
+            ValueError: If the dataframe is missing the columns option column.customer_id or `value_col`, or these
+                columns contain null values.
+        """
+        self._df: pd.DataFrame | None = None
+        self._group_col: list[str] | None = None
+        if len(thresholds) != len(set(thresholds)):
+            raise ValueError("The thresholds must be unique")
+
+        if len(thresholds) != len(segments):
+            raise ValueError("The number of thresholds must match the number of segments")
+
+        # Initialize column helper
+        cols = ColumnHelper()
+
+        # Normalize group_col to a list
+        self._group_col = [group_col] if isinstance(group_col, str) else group_col
+
+        if isinstance(df, pd.DataFrame):
+            df: ibis.Table = ibis.memtable(df)
+
+        value_col = cols.unit_spend if value_col is None else value_col
+
+        required_cols = [cols.customer_id, value_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)
+
+        # Build group_by columns: customer_id + optional group columns
+        group_by_cols = [cols.customer_id]
+        if self._group_col is not None:
+            group_by_cols.extend(self._group_col)
+
+        df = df.group_by(*group_by_cols).aggregate(
+            **{value_col: getattr(df[value_col], agg_func)()},
+        )
+
+        # Separate customers with zero spend
+        zero_df = None
+        if zero_value_customers == "exclude":
+            df = df.filter(df[value_col] != 0)
+        elif zero_value_customers == "separate_segment":
+            zero_df = df.filter(df[value_col] == 0).mutate(segment_name=ibis.literal(zero_segment_name))
+            df = df.filter(df[value_col] != 0)
+
+        # Create window function, partitioned by group columns if specified
+        # Order by value_col first, then customer_id to ensure deterministic ordering when values are tied
+        window = (
+            ibis.window(order_by=[ibis.asc(df[value_col]), ibis.asc(df[cols.customer_id])])
+            if self._group_col is None
+            else ibis.window(
+                order_by=[ibis.asc(df[value_col]), ibis.asc(df[cols.customer_id])],
+                group_by=self._group_col,
+            )
+        )
+        df = df.mutate(ptile=ibis.percent_rank().over(window))
+
+        case_args = [(df["ptile"] <= quantile, segment) for quantile, segment in zip(thresholds, segments, strict=True)]
+
+        df = df.mutate(segment_name=ibis.cases(*case_args)).drop(["ptile"])
+
+        if zero_value_customers == "separate_segment":
+            df = ibis.union(df, zero_df)
+
+        self.table = df
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Returns the dataframe with the segment names."""
+        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/utils/date.py

@@ -0,0 +1,226 @@
+"""Utility functions for time-related operations in retail analysis."""
+
+from collections.abc import Mapping
+from datetime import datetime, timezone
+
+import ibis
+
+from openretailscience.options import get_option
+
+
+def _normalize_datetime(date_val: datetime | str) -> datetime:
+    """Convert a string or datetime to a timezone-aware datetime object.
+
+    Strings are parsed as ``%Y-%m-%d`` and localized to UTC.  Naive datetimes
+    are made aware by attaching UTC.  Already-aware datetimes are returned
+    unchanged.
+
+    Args:
+        date_val (datetime | str): A date string (``YYYY-MM-DD``) or datetime to normalize.
+
+    Returns:
+        datetime: A timezone-aware datetime in UTC.
+
+    Raises:
+        TypeError: If *date_val* is neither a ``str`` nor a ``datetime``.
+    """
+    if isinstance(date_val, str):
+        # Convert string to timezone-aware datetime
+        return datetime.strptime(date_val, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+    if isinstance(date_val, datetime):
+        # If datetime is timezone-naive, make it timezone-aware (UTC)
+        if date_val.tzinfo is None:
+            return date_val.replace(tzinfo=timezone.utc)
+        return date_val
+    error_msg = f"Expected str or datetime, got {type(date_val)}"
+    raise TypeError(error_msg)
+
+
+def _is_naive(d: datetime | str) -> bool:
+    """Check whether a datetime-like input is timezone-naive.
+
+    Args:
+        d (datetime | str): A datetime object or date string to check.
+
+    Returns:
+        bool: True if the input is a string or a naive datetime, False if tz-aware.
+
+    Raises:
+        TypeError: If d is not a str or datetime instance.
+    """
+    if isinstance(d, str):
+        return True
+    if isinstance(d, datetime):
+        return d.tzinfo is None
+    msg = f"Expected str or datetime, got {type(d)}"
+    raise TypeError(msg)
+
+
+def _validate_and_normalize_periods(
+    period_ranges: Mapping[str, tuple[datetime | str, datetime | str]],
+) -> dict[str, tuple[datetime, datetime]]:
+    """Validates and normalizes period ranges, returning timezone-aware datetime tuples."""
+    normalized = {}
+
+    for period_name, date_range in period_ranges.items():
+        date_range_length = 2
+        if not (isinstance(date_range, tuple) and len(date_range) == date_range_length):
+            msg = f"Period '{period_name}' must have a (start_date, end_date) tuple"
+            raise ValueError(msg)
+
+        start_date, end_date = date_range
+
+        start_dt = _normalize_datetime(start_date)
+        end_dt = _normalize_datetime(end_date)
+
+        if start_dt > end_dt:
+            msg = f"Period '{period_name}': start date ({start_date}) must be <= end date ({end_date})"
+            raise ValueError(msg)
+
+        normalized[period_name] = (start_dt, end_dt)
+
+    # Check for overlapping periods
+    period_list = list(normalized.items())
+    for i, (name1, (start1, end1)) in enumerate(period_list):
+        for name2, (start2, end2) in period_list[i + 1 :]:
+            if start1 <= end2 and start2 <= end1:
+                overlap_msg = (
+                    f"Periods '{name1}' ({start1.date()}-{end1.date()}) and"
+                    f" '{name2}' ({start2.date()}-{end2.date()}) overlap"
+                )
+                raise ValueError(overlap_msg)
+
+    return normalized
+
+
+def filter_and_label_by_periods(
+    transactions: ibis.Table,
+    period_ranges: dict[str, tuple[datetime, datetime] | tuple[str, str]],
+    period_col: str = "period_name",
+) -> ibis.Table:
+    """Filters transactions to specified time periods and adds period labels.
+
+    This function filters transactions based on specified time periods and adds a new column indicating the period name.
+    It is useful for analyzing transactions within specific date ranges and comparing KPIs between them.
+
+    Example:
+        transactions = ibis.table("transactions")
+        period_ranges = {
+            "Q1": ("2023-01-01", "2023-03-31"),
+            "Q2": ("2023-04-01", "2023-06-30"),
+        }
+        filtered_transactions = filter_and_label_by_periods(transactions, period_ranges)
+        # filtered_transactions will only contain transactions from the date ranges specified in Q1 and Q2 and a new
+        # column 'period_name' will be in the table defining the period for each transaction.
+
+    Args:
+        transactions (ibis.Table): An ibis table with a transaction_date column.
+        period_ranges (dict[str, tuple[datetime, datetime] | tuple[str, str]]): Dict where keys are period names and
+            values are(start_date, end_date) tuples.
+        period_col (str, optional): Name of the column to create for period labels. Defaults to "period_name".
+
+    Returns:
+        An ibis table with filtered transactions and added period label column.
+
+    Raises:
+        ValueError: If any value in period_ranges is not a tuple of length 2.
+        ValueError: If first date > second date for any period.
+        ValueError: If periods overlap with each other.
+    """
+    # Validate periods first
+    _validate_and_normalize_periods(period_ranges)
+
+    branches = []
+    date_column = transactions[get_option("column.transaction_date")]
+
+    date_col_dtype = date_column.type()
+
+    for period_name, date_range in period_ranges.items():
+        start_date, end_date = date_range
+
+        period_condition = date_column.between(
+            ibis.literal(start_date, type=date_col_dtype),
+            ibis.literal(end_date, type=date_col_dtype),
+        )
+        branches.append((period_condition, ibis.literal(period_name)))
+
+    conditions = ibis.or_(*[condition[0] for condition in branches])
+    return transactions.filter(conditions).mutate(**{period_col: ibis.cases(*branches)})
+
+
+def find_overlapping_periods(
+    start_date: datetime | str,
+    end_date: datetime | str,
+    return_str: bool = True,
+) -> list[tuple[str | datetime, str | datetime]]:
+    """Find overlapping time periods within the given date range, split by year.
+
+    This function generates overlapping periods between a given start date and end date.
+    The first period will start from the given start date, and each subsequent period will start on
+    the same month and day for the following years, ending each period on the same month and day
+    of the end date but in the subsequent year,
+    except for the last period, which ends at the provided end date.
+
+    Note:
+        This function does not adjust for leap years. If the start or end date is February 29,
+        it may cause an issue in non-leap years.
+
+    Args:
+        start_date (datetime | str): The starting date of the range, either as a
+            datetime object or 'YYYY-MM-DD' string.
+        end_date (datetime | str): The ending date of the range, either as a
+            datetime object or 'YYYY-MM-DD' string.
+        return_str (bool, optional): If True, returns dates as ISO-formatted strings ('YYYY-MM-DD').
+                                     If False, returns datetime objects. Defaults to True.
+
+    Returns:
+        list[tuple[str | datetime, str | datetime]]:
+        A list of tuples where each tuple contains the start and end dates of an overlapping period,
+        either as strings (ISO format) or datetime objects. Returned datetimes preserve the
+        timezone-awareness of the input (naive in → naive out, aware in → aware out).
+        String inputs produce naive datetime outputs.
+
+    Raises:
+        TypeError: If start_date and end_date have mismatched timezone awareness
+            (one naive or string and one timezone-aware, or vice versa).
+        ValueError: If the start date is after the end date.
+    """
+    # Track whether outputs should be tz-naive to preserve backward compatibility.
+    # String inputs and naive datetime inputs both produced naive outputs before.
+    start_is_naive = _is_naive(start_date)
+    end_is_naive = _is_naive(end_date)
+
+    if start_is_naive != end_is_naive:
+        msg = "start_date and end_date must have matching timezone awareness. Got naive and aware (or vice versa)."
+        raise TypeError(msg)
+
+    start_date = _normalize_datetime(start_date)
+    end_date = _normalize_datetime(end_date)
+
+    if start_date > end_date:
+        raise ValueError("Start date must be before end date")
+
+    if start_date.year == end_date.year:
+        return []
+
+    if start_is_naive:
+        output_tz = None
+        start_date = start_date.replace(tzinfo=None)
+    else:
+        output_tz = start_date.tzinfo
+
+    period_starts = [
+        start_date if year == start_date.year else datetime(year, start_date.month, start_date.day, tzinfo=output_tz)
+        for year in range(start_date.year, end_date.year)
+    ]
+    period_ends = [
+        datetime(year + 1, end_date.month, end_date.day, tzinfo=output_tz)
+        for year in range(start_date.year, end_date.year)
+    ]
+
+    if return_str:
+        return [
+            (s.strftime("%Y-%m-%d"), e.strftime("%Y-%m-%d")) for s, e in zip(period_starts, period_ends, strict=True)
+        ]
+
+    return list(zip(period_starts, period_ends, strict=True))

openretailscience/utils/filter_and_label.py

@@ -0,0 +1,52 @@
+"""filter_and_label Utilities - Filtering and Labeling by Condition.
+
+This module provides utilities to filter an Ibis table based on arbitrary logical conditions
+and attach descriptive labels to matched rows. It is useful for segmenting and analyzing data
+according to business-defined rules, such as category classification, customer segmentation,
+or pricing tiers.
+
+Example use cases:
+- Tagging product records based on category.
+- Classifying transactions into business segments.
+- Preparing labeled datasets for analysis or machine learning.
+"""
+
+import ibis
+
+
+def filter_and_label_by_condition(
+    table: ibis.Table,
+    conditions: dict[str, ibis.expr.types.BooleanColumn],
+    label_col: str = "label",
+) -> ibis.Table:
+    """Filters a table based on specified conditions and adds labels.
+
+    This function filters rows in a table based on specified conditions and adds a new column
+    indicating the label associated with each condition. It's useful for categorizing data
+    based on different criteria.
+
+    Example:
+        data = ibis.memtable(df)
+        labeled_data = filter_and_label_by_condition(
+            data,
+            conditions={
+                "toys": data["category"] == "toys",
+                "shoes": data["category"] == "shoes"
+            }
+        )
+        # labeled_data will only contain rows where category is either "toys" or "shoes",
+        # and a new column 'label' will be added indicating which category it belongs to.
+
+    Args:
+        table (ibis.Table): An ibis table to filter.
+        conditions (dict[str, ibis.expr.types.BooleanColumn]): Dict where keys are labels and
+            values are ibis boolean expressions representing filter conditions.
+        label_col (str, optional): Name of the label column to add. Defaults to "label".
+
+    Returns:
+        ibis.Table: An ibis table with filtered rows and an added label column.
+    """
+    branches = [(condition, ibis.literal(label)) for label, condition in conditions.items()]
+    combined_condition = ibis.or_(*[condition for condition, _ in branches])
+
+    return table.filter(combined_condition).mutate(**{label_col: ibis.cases(*branches)})

openretailscience/utils/label.py

@@ -0,0 +1,79 @@
+"""Label Utilities - Labeling by Condition.
+
+This module provides utilities to label groups in an Ibis table based on whether
+any items in the group meet a specified condition. It supports both binary labeling
+(contains/not_contains) and extended labeling (contains/mixed/not_contains).
+
+Example use cases:
+- Tag transactions as containing a product, product category, or promotion
+- Tag customers as containing a product, product category, or promotion, or store_id
+- Tag a transaction as containing promo items, no promo items, or both on/off promo items
+"""
+
+from typing import Literal
+
+import ibis
+from ibis import _
+
+from openretailscience.options import get_option
+
+
+def label_by_condition(
+    table: ibis.Table,
+    condition: ibis.expr.types.BooleanColumn,
+    label_col: str | None = None,
+    return_col: str = "label_name",
+    labeling_strategy: Literal["binary", "extended"] = "binary",
+    contains_label: str | ibis.Value = "contains",
+    not_contains_label: str | ibis.Value = "not_contains",
+    mixed_label: str | ibis.Value = "mixed",
+) -> ibis.Table:
+    """Labels groups in a table based on whether items in the group meet a condition.
+
+    This function groups a table by the specified label column and determines whether
+    any items in each group meet the given condition. It supports two labeling strategies:
+    - "binary": Labels groups as either "contains" or "not_contains" based on whether
+      any item in the group meets the condition
+    - "extended": Labels groups as "contains" (all items meet condition), "mixed"
+      (some items meet condition), or "not_contains" (no items meet condition)
+
+    Args:
+        table (ibis.Table): An ibis table to process.
+        condition (ibis.expr.types.BooleanColumn): Boolean expression representing
+            the condition to evaluate.
+        label_col (str | None, optional): Column name to group by for labeling. If None, defaults to the setting
+            column.customer_id.
+        return_col (str, optional): Name of the column to add with the labels. Defaults to "label_name".
+        labeling_strategy (Literal["binary", "extended"], optional): Strategy for labeling groups.
+            Defaults to "binary".
+        contains_label (str | ibis.Value, optional): Label for groups that contain
+            items meeting the condition. Defaults to "contains".
+        not_contains_label (str | ibis.Value, optional): Label for groups that do not
+            contain items meeting the condition. Defaults to "not_contains".
+        mixed_label (str | ibis.Value, optional): Label for groups with mixed results
+            (only used with "extended" strategy). Defaults to "mixed".
+
+    Returns:
+        ibis.Table: An ibis table grouped by label_col with an added label column.
+    """
+    if label_col is None:
+        label_col = get_option("column.customer_id")
+
+    table = table.mutate(label_condition=condition.ifelse(1, 0)).group_by(label_col)
+
+    if labeling_strategy == "binary":
+        return table.aggregate(
+            {
+                return_col: (_.label_condition.max() == 1).ifelse(contains_label, not_contains_label),
+            },
+        )
+
+    return table.aggregate(
+        {
+            return_col: ibis.cases(
+                ((_.label_condition.max() == 1) & (_.label_condition.min() == 1), contains_label),
+                ((_.label_condition.max() == 1) & (_.label_condition.min() == 0), mixed_label),
+                else_=not_contains_label,
+            ),
+        },
+    )

openretailscience/utils/validation.py

@@ -0,0 +1,45 @@
+"""Shared validation utilities for OpenRetailScience."""
+
+from __future__ import annotations
+
+import ibis
+import pandas as pd
+
+
+def ensure_ibis_table(df: pd.DataFrame | ibis.Table) -> ibis.Table:
+    """Convert pandas DataFrame to ibis Table, or validate input is an ibis Table.
+
+    Args:
+        df (pd.DataFrame | ibis.Table): Input data to convert or validate.
+
+    Returns:
+        ibis.Table: An ibis Table representation of the input data.
+
+    Raises:
+        TypeError: If df is neither a pandas DataFrame nor an ibis Table.
+    """
+    if isinstance(df, pd.DataFrame):
+        return ibis.memtable(df)
+    if isinstance(df, ibis.Table):
+        return df
+    raise TypeError("df must be either a pandas DataFrame or an Ibis Table.")
+
+
+def validate_columns(df: pd.DataFrame | ibis.Table, required_cols: list[str]) -> None:
+    """Validates that a DataFrame or Ibis Table contains all required columns.
+
+    Args:
+        df (pd.DataFrame | ibis.Table): The data to validate.
+        required_cols (list[str]): Column names that must be present.
+
+    Raises:
+        TypeError: If required_cols is not a list.
+        ValueError: If any required columns are missing from the data.
+    """
+    if not isinstance(required_cols, list):
+        msg = "required_cols must be a list of column names."
+        raise TypeError(msg)
+    missing_cols = sorted(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)