openretailscience 0.45.0__py3-none-any.whl

openretailscience/__init__.py

@@ -0,0 +1,3 @@
+from openretailscience.plugin import plugin_manager
+
+__all__ = ["plugin_manager"]

openretailscience/analysis/cohort.py

@@ -0,0 +1,185 @@
+"""Cohort Analysis and User Segmentation.
+
+This module implements functionality for performing cohort analysis, a powerful technique used in customer analytics
+and retention strategies.
+
+Cohort analysis helps in understanding customer behavior over time by grouping users based on shared characteristics
+or experiences, such as sign-up date, first purchase, or marketing campaign interaction. This method provides
+valuable insights into user engagement, retention, and lifetime value, which businesses can leverage in various ways:
+
+1. Customer retention analysis: By tracking how different cohorts behave over time, businesses can identify trends
+   in user engagement and develop strategies to improve customer loyalty.
+
+2. Marketing performance evaluation: Understanding how different user groups respond to marketing efforts helps in
+   optimizing campaigns for higher conversions and better ROI.
+
+3. Product lifecycle insights: Analyzing user activity across cohorts can reveal product adoption trends and inform
+   feature development or enhancements.
+
+4. Revenue forecasting: Cohort-based revenue tracking enables more accurate predictions of future earnings and
+   helps in financial planning.
+
+5. Personalization and segmentation: Businesses can tailor their offerings based on cohort behavior to enhance
+   customer experience and increase retention rates.
+
+The module employs key metrics such as retention rate, churn rate, and customer lifetime value (CLV) to measure
+cohort performance and user engagement over time:
+
+- Retention Rate: The percentage of users who continue to engage with a product or service over a given period.
+- Churn Rate: The percentage of users who stop engaging with the product within a specific timeframe.
+- Customer Lifetime Value (CLV): The predicted total revenue a customer will generate throughout their relationship
+  with the business.
+
+By leveraging cohort analysis, businesses can make data-driven decisions to enhance customer experience, improve
+marketing strategies, and drive long-term growth.
+"""
+
+from typing import ClassVar
+
+import ibis
+import numpy as np
+import pandas as pd
+
+from openretailscience.options import ColumnHelper
+
+
+class CohortAnalysis:
+    """Class for performing cohort analysis and visualization."""
+
+    VALID_PERIODS: ClassVar[set[str]] = {"year", "quarter", "month", "week", "day"}
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        aggregation_column: str,
+        agg_func: str = "nunique",
+        period: str = "month",
+        percentage: bool = False,
+    ) -> None:
+        """Initializes the Cohort Analysis object.
+
+        Args:
+            df (pd.DataFrame | ibis.Table): The dataset containing transaction data.
+            aggregation_column (str): The column to apply the aggregation function on (e.g., 'unit_spend').
+            agg_func (str, optional): Aggregation function (e.g., "nunique", "sum", "mean"). Defaults to "nunique".
+            period (str): Period for cohort analysis (must be "year", "quarter", "month", "week", or "day").
+            percentage (bool): If True, converts cohort values into retention percentages relative to the first period.
+
+        Raises:
+            ValueError: If `period` is not one of the allowed values.
+            ValueError: If `df` is missing required columns
+                (`customer_id`, `transaction_date`, or `aggregation_column`).
+        """
+        cols = ColumnHelper()
+
+        if period not in self.VALID_PERIODS:
+            error_message = f"Invalid period '{period}'. Allowed values: {self.VALID_PERIODS}."
+            raise ValueError(error_message)
+
+        required_cols = [
+            cols.customer_id,
+            cols.transaction_date,
+            aggregation_column,
+        ]
+        missing_cols = [col for col in required_cols if col not in df.columns]
+
+        if missing_cols:
+            error_message = f"Missing required columns: {missing_cols}"
+            raise ValueError(error_message)
+
+        self.df = self._calculate_cohorts(
+            df=df,
+            agg_func=agg_func,
+            period=period,
+            aggregation_column=aggregation_column,
+            percentage=percentage,
+        )
+
+    def _fill_cohort_gaps(
+        self,
+        cohort_analysis_table: pd.DataFrame,
+        period: str,
+    ) -> pd.DataFrame:
+        """Fills gaps in the cohort analysis table for missing periods.
+
+        Args:
+            cohort_analysis_table (pd.DataFrame): The cohort analysis table to fill gaps in.
+            period (str): The period of analysis (year, quarter, month, week, or day).
+
+        Returns:
+            pd.DataFrame: Cohort table with missing periods filled.
+        """
+        cohort_analysis_table.index = pd.to_datetime(cohort_analysis_table.index)
+
+        min_period = cohort_analysis_table.index.min()
+        max_period = cohort_analysis_table.index.max()
+
+        period_lookup = {"year": "YS", "quarter": "QS", "month": "MS", "week": "W", "day": "D"}
+        full_range = pd.date_range(start=min_period, end=max_period, freq=period_lookup[period])
+        cohort_analysis_table = cohort_analysis_table.reindex(full_range, fill_value=0)
+        if cohort_analysis_table.shape[1] > 0:
+            max_period_since = cohort_analysis_table.columns.max()
+            all_periods = range(max_period_since + 1)
+            cohort_analysis_table = cohort_analysis_table.reindex(columns=all_periods, fill_value=0)
+        return cohort_analysis_table
+
+    def _calculate_cohorts(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        aggregation_column: str,
+        agg_func: str = "nunique",
+        period: str = "month",
+        percentage: bool = False,
+    ) -> pd.DataFrame:
+        """Computes a cohort analysis table based on transaction data.
+
+        Args:
+            df (pd.DataFrame | ibis.Table): The dataset containing transaction data.
+            aggregation_column (str): The column to apply the aggregation function on (e.g., 'unit_spend').
+            agg_func (str, optional): Aggregation function (e.g., "nunique", "sum", "mean"). Defaults to "nunique".
+            period (str): Period for cohort analysis (must be "year", "quarter", "month", "week", or "day").
+            percentage (bool): If True, converts cohort values into retention percentages relative to the first period.
+
+        Returns:
+            pd.DataFrame: Cohort analysis table with user retention values.
+        """
+        cols = ColumnHelper()
+
+        ibis_table = ibis.memtable(df) if isinstance(df, pd.DataFrame) else df
+
+        filtered_table = ibis_table.mutate(
+            period_shopped=ibis_table[cols.transaction_date].truncate(period),
+            period_value=ibis_table[aggregation_column],
+        )
+
+        customer_cohort = filtered_table.group_by(cols.customer_id).aggregate(
+            min_period_shopped=filtered_table.period_shopped.min(),
+        )
+
+        cohort_table = (
+            filtered_table.join(customer_cohort, [cols.customer_id])
+            .group_by("min_period_shopped", "period_shopped")
+            .aggregate(period_value=getattr(filtered_table.period_value, agg_func)())
+        )
+
+        cohort_table = cohort_table.mutate(
+            period_since=cohort_table.period_shopped.delta(cohort_table.min_period_shopped, unit=period),
+        )
+
+        cohort_df = cohort_table.execute().drop_duplicates(subset=["min_period_shopped", "period_since"])
+
+        cohort_analysis_table = cohort_df.pivot(
+            index="min_period_shopped",
+            columns="period_since",
+            values="period_value",
+        )
+
+        if percentage:
+            first_period = cohort_analysis_table[0].replace(0, np.nan)
+            cohort_analysis_table = cohort_analysis_table.div(first_period, axis=0).round(2)
+
+        cohort_analysis_table = cohort_analysis_table.fillna(0)
+        cohort_analysis_table = self._fill_cohort_gaps(cohort_analysis_table, period)
+        cohort_analysis_table.index.name = "min_period_shopped"
+
+        return cohort_analysis_table

openretailscience/analysis/composite_rank.py

@@ -0,0 +1,372 @@
+"""Composite Rank Analysis Module for Multi-Factor Retail Decision Making.
+
+## Business Context
+
+In retail, critical decisions like product ranging, supplier selection, and store
+performance evaluation require balancing multiple competing factors. A product might
+have high sales but low margin, or a supplier might offer great prices but poor
+delivery reliability. Composite ranking enables data-driven decisions by combining
+multiple performance metrics into a single, actionable score.
+
+## Real-World Applications
+
+1. **Product Range Optimization**: Rank products for listing/delisting decisions based on:
+   - Sales velocity (units per week)
+   - Gross margin percentage
+   - Stock turn rate
+   - Customer satisfaction scores
+   - Return rates
+
+2. **Supplier Performance Management**: Evaluate suppliers using:
+   - On-time delivery percentage
+   - Price competitiveness
+   - Quality scores (defect rates)
+   - Payment terms flexibility
+   - Order fill rates
+
+3. **Store Performance Assessment**: Rank stores for investment decisions based on:
+   - Sales per square foot
+   - Conversion rates
+   - Labor productivity
+   - Customer satisfaction (NPS)
+   - Shrinkage rates
+
+4. **Category Management**: Prioritize categories for space allocation using:
+   - Category growth rates
+   - Market share
+   - Profitability
+   - Cross-category purchase influence
+   - Seasonal consistency
+
+## How It Works
+
+The module creates individual rankings for each metric, then combines these rankings
+using aggregation functions (mean, sum, min, max) to produce a final composite score.
+This approach normalizes metrics with different scales and ensures each factor contributes
+appropriately to the final decision.
+
+## Business Value
+
+- **Objective Decision Making**: Removes bias by systematically weighing all factors
+- **Scalability**: Can evaluate thousands of products/stores/suppliers simultaneously
+- **Transparency**: Clear methodology that stakeholders can understand and trust
+- **Flexibility**: Different aggregation methods suit different business strategies
+- **Actionable Output**: Direct ranking enables clear cut-off decisions
+
+Key Features:
+- Creates individual ranks for multiple columns with business metrics
+- Supports both ascending and descending sort orders for each metric
+- Combines individual ranks using business-appropriate aggregation functions
+- Handles tie values for fair comparison
+- Utilizes Ibis for efficient query execution on large retail datasets
+"""
+
+from typing import Any
+
+import ibis
+import ibis.expr.types as ir
+import pandas as pd
+
+
+class CompositeRank:
+    """Creates multi-factor composite rankings for retail decision-making.
+
+    The CompositeRank class enables retailers to make data-driven decisions by combining
+    multiple performance metrics into a single, actionable ranking. This is essential for
+    scenarios where no single metric tells the complete story.
+
+    ## Business Problem Solved
+
+    Retailers face complex trade-offs daily: Should we keep the high-volume product with
+    low margins or the high-margin product with slow sales? Which supplier offers the best
+    overall value when considering price, quality, and reliability? This class provides a
+    systematic approach to these multi-dimensional decisions.
+
+    ## Example Use Case: Product Range Review
+
+    When conducting quarterly range reviews, a retailer might rank products by:
+    - Sales performance (higher is better → descending order)
+    - Days of inventory (lower is better → ascending order)
+    - Customer rating (higher is better → descending order)
+    - Return rate (lower is better → ascending order)
+
+    The composite rank identifies products that perform well across ALL metrics, not just
+    excel in one area. Products with the best composite scores are clear "keep" decisions,
+    while those with the worst scores are candidates for delisting.
+
+    ## Aggregation Strategies
+
+    Different business contexts require different aggregation approaches:
+    - **Mean**: Balanced scorecard approach, all factors equally important
+    - **Min**: Conservative approach, focus on worst-performing metric
+    - **Max**: Optimistic approach, highlight strength in any area
+    - **Sum**: Cumulative performance across all dimensions
+
+    ## Actionable Outcomes
+
+    The composite rank directly supports decisions like:
+    - Top 20% composite rank → Increase inventory investment
+    - Bottom 20% composite rank → Consider delisting or markdown
+    - Middle 60% → Maintain current strategy, monitor for changes
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        rank_cols: list[tuple[str, str] | str],
+        agg_func: str,
+        ignore_ties: bool = False,
+        group_col: str | list[str] | None = None,
+    ) -> None:
+        """Initialize the CompositeRank class for multi-criteria retail analysis.
+
+        Args:
+            df (pd.DataFrame | ibis.Table): Product, store, or supplier performance data.
+            rank_cols (List[Union[Tuple[str, str], str]]): Metrics to rank with their optimization direction.
+                Examples for product ranging:
+                - ("sales_units", "desc") - Higher sales are better
+                - ("days_inventory", "asc") - Lower inventory days are better
+                - ("margin_pct", "desc") - Higher margins are better
+                - ("return_rate", "asc") - Lower returns are better
+                If just a string is provided, ascending order is assumed.
+            agg_func (str): How to combine individual rankings:
+                - "mean": Balanced scorecard (most common for range reviews)
+                - "sum": Total performance score (for bonus calculations)
+                - "min": Worst-case performance (for risk assessment)
+                - "max": Best-case performance (for opportunity identification)
+            ignore_ties (bool, optional): How to handle identical values:
+                - False (default): Products with same sales get same rank (fair comparison)
+                - True: Force unique ranks even for ties (strict ordering needed)
+            group_col (str | list[str], optional): Column(s) to partition rankings by group.
+                - None (default): Rank across entire dataset (current behavior)
+                - If specified: Calculate ranks independently within each group
+                Examples for group-based ranking:
+                - "product_category": Rank products within each category
+                - "store_region": Rank stores within their regions
+                - "supplier_type": Rank suppliers within their specialization
+
+        Raises:
+            ValueError: If specified metrics are not in the data or sort order is invalid.
+            ValueError: If aggregation function is not supported.
+            ValueError: If group_col is specified but doesn't exist in the data.
+
+        Examples:
+            >>> # Global ranking: Rank all products together (current behavior)
+            >>> ranker = CompositeRank(
+            ...     df=product_data,
+            ...     rank_cols=[
+            ...         ("weekly_sales", "desc"),
+            ...         ("margin_percentage", "desc"),
+            ...         ("stock_cover_days", "asc"),
+            ...         ("customer_rating", "desc")
+            ...     ],
+            ...     agg_func="mean"
+            ... )
+            >>> # Products with lowest composite_rank should be reviewed for delisting
+
+            >>> # Group-based ranking: Rank products within each category
+            >>> ranker = CompositeRank(
+            ...     df=product_data,
+            ...     rank_cols=[
+            ...         ("weekly_sales", "desc"),
+            ...         ("margin_percentage", "desc"),
+            ...         ("stock_cover_days", "asc")
+            ...     ],
+            ...     agg_func="mean",
+            ...     group_col="product_category"
+            ... )
+            >>> # Electronics products ranked against other electronics
+            >>> # Apparel products ranked against other apparel
+        """
+        self._df: pd.DataFrame | None = None
+        if isinstance(df, pd.DataFrame):
+            df = ibis.memtable(df)
+
+        self._validate_group_col(group_col, df)
+        rank_mutates = self._process_rank_columns(rank_cols, df, group_col, ignore_ties)
+        df = df.mutate(**rank_mutates)
+        self.table = self._create_composite_ranking(df, rank_mutates, agg_func)
+
+    def _validate_group_col(self, group_col: str | list[str] | None, df: ibis.Table) -> None:
+        """Validate group_col parameter against the DataFrame columns.
+
+        Args:
+            group_col (str | list[str] | None): Column name or list of column names to partition rankings by.
+                None skips validation entirely.
+            df (ibis.Table): The table whose columns are validated against.
+
+        Raises:
+            TypeError: If group_col is not a string, list, or None.
+            ValueError: If group_col is an empty list.
+            ValueError: If any specified group columns are not found in the DataFrame.
+        """
+        if group_col is None:
+            return
+
+        if isinstance(group_col, str):
+            group_col = [group_col]
+        elif not isinstance(group_col, list):
+            msg = f"group_col must be a string or list of strings. Got {type(group_col).__name__}."
+            raise TypeError(msg)
+
+        if len(group_col) == 0:
+            msg = "group_col must not be an empty list. Use None for global ranking."
+            raise ValueError(msg)
+
+        missing_cols = sorted(set(group_col) - set(df.columns))
+        if len(missing_cols) > 0:
+            msg = f"Group column(s) {missing_cols} not found in the DataFrame"
+            raise ValueError(msg)
+
+    def _process_rank_columns(
+        self,
+        rank_cols: list[tuple[str, str] | str],
+        df: ibis.Table,
+        group_col: str | list[str] | None,
+        ignore_ties: bool,
+    ) -> dict[str, ir.IntegerColumn]:
+        """Process rank columns and create ranking expressions.
+
+        Validates each column specification, then builds an ibis ranking expression
+        for each metric using the appropriate window function and tie-handling strategy.
+
+        Args:
+            rank_cols (list[tuple[str, str] | str]): Column specifications to rank. Each element is
+                either a string (column name, defaults to ascending) or a tuple of (column_name, sort_order).
+            df (ibis.Table): The table containing the columns to rank.
+            group_col (str | list[str] | None): Column(s) to partition the ranking window by,
+                or None for global ranking.
+            ignore_ties (bool): If True, uses row_number for unique ranks. If False, uses rank
+                which assigns the same rank to tied values.
+
+        Returns:
+            dict[str, ir.IntegerColumn]: Mapping of rank column names (e.g., "sales_rank") to ibis ranking expressions.
+
+        Raises:
+            ValueError: If a specified column is not found in the DataFrame.
+            ValueError: If a sort order is not one of "asc", "ascending", "desc", or "descending".
+        """
+        if len(rank_cols) == 0:
+            msg = "rank_cols must contain at least one column specification"
+            raise ValueError(msg)
+
+        valid_sort_orders = ["asc", "ascending", "desc", "descending"]
+        rank_mutates = {}
+
+        for col_spec in rank_cols:
+            col_name, sort_order = self._parse_column_spec(col_spec)
+
+            # Validate column exists and sort order is valid
+            if col_name not in df.columns:
+                msg = f"Column '{col_name}' not found in the DataFrame"
+                raise ValueError(msg)
+            if sort_order.lower() not in valid_sort_orders:
+                msg = f"Sort order must be one of {valid_sort_orders}. Got '{sort_order}'"
+                raise ValueError(msg)
+
+            order_by = ibis.asc(df[col_name]) if sort_order in ["asc", "ascending"] else ibis.desc(df[col_name])
+            window = self._create_window(group_col, df, order_by)
+
+            # Calculate rank based on ignore_ties parameter (using 1-based ranks)
+            rank_col = ibis.row_number().over(window) + 1 if ignore_ties else ibis.rank().over(window) + 1
+            rank_mutates[f"{col_name}_rank"] = rank_col
+
+        return rank_mutates
+
+    def _parse_column_spec(self, col_spec: tuple[str, str] | str) -> tuple[str, str]:
+        """Parse a column specification into a column name and sort order.
+
+        Args:
+            col_spec (tuple[str, str] | str): Either a column name string (defaults to "asc")
+                or a tuple of (column_name, sort_order).
+
+        Returns:
+            tuple[str, str]: A tuple of (column_name, sort_order).
+
+        Raises:
+            ValueError: If a tuple is provided but does not contain exactly two elements.
+        """
+        if isinstance(col_spec, str):
+            return col_spec, "asc"
+        if len(col_spec) != 2:  # noqa: PLR2004 - Error message below explains the value
+            msg = f"Column specification must be a string or a tuple of (column_name, sort_order). Got {col_spec}"
+            raise ValueError(msg)
+        return col_spec
+
+    def _create_window(
+        self,
+        group_col: str | list[str] | None,
+        df: ibis.Table,
+        order_by: ir.Column,
+    ) -> Any:  # noqa: ANN401 - WindowedExpr is an internal ibis type; Any is safest here
+        """Create an ibis window specification for ranking.
+
+        Builds the appropriate window function based on whether rankings should be
+        global or partitioned by group column(s).
+
+        Args:
+            group_col (str | list[str] | None): Column(s) to partition the window by.
+                None creates a global window, a string or list creates a grouped window.
+            df (ibis.Table): The table containing the group columns.
+            order_by (ir.Column): An ibis ordering expression (e.g., ibis.asc or ibis.desc) for the window.
+
+        Returns:
+            Any: An ibis window specification for use with ranking functions.
+        """
+        if group_col is None:
+            return ibis.window(order_by=order_by)
+        if isinstance(group_col, str):
+            return ibis.window(group_by=df[group_col], order_by=order_by)
+        return ibis.window(group_by=[df[col] for col in group_col], order_by=order_by)
+
+    def _create_composite_ranking(
+        self,
+        df: ibis.Table,
+        rank_mutates: dict[str, ir.IntegerColumn],
+        agg_func: str,
+    ) -> ibis.Table:
+        """Create the final composite ranking by aggregating individual rank columns.
+
+        Combines the individual ranking columns into a single composite_rank column
+        using the specified aggregation function.
+
+        Args:
+            df (ibis.Table): The table with individual rank columns already added.
+            rank_mutates (dict[str, ir.IntegerColumn]): Mapping of rank column names to their expressions,
+                used to identify which columns to aggregate.
+            agg_func (str): Aggregation function to combine ranks. Must be one of
+                "mean", "sum", "min", or "max".
+
+        Returns:
+            ibis.Table: The input table with an additional composite_rank column.
+
+        Raises:
+            ValueError: If agg_func is not one of the supported aggregation functions.
+        """
+        column_refs = [df[col] for col in rank_mutates]
+        agg_expr = {
+            "mean": sum(column_refs) / len(column_refs),
+            "sum": sum(column_refs),
+            "min": ibis.least(*column_refs),
+            "max": ibis.greatest(*column_refs),
+        }
+
+        if agg_func.lower() not in agg_expr:
+            msg = f"Aggregation function must be one of {list(agg_expr.keys())}. Got '{agg_func}'"
+            raise ValueError(msg)
+
+        return df.mutate(composite_rank=agg_expr[agg_func])
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Returns ranked data ready for business decision-making.
+
+        Returns:
+            pd.DataFrame: Performance data with ranking columns added:
+                - Original metrics (sales, margin, etc.)
+                - Individual rank columns (e.g., sales_rank, margin_rank)
+                - composite_rank: Final combined ranking for decisions
+        """
+        if self._df is None:
+            self._df = self.table.execute()
+        return self._df