openretailscience 0.45.0__py3-none-any.whl

openretailscience/constants.py

@@ -0,0 +1,295 @@
+"""Constants used throughout OpenRetailScience.
+
+This module contains constant values that are shared across the package.
+"""
+
+# Tailwind CSS color palette definitions
+# https://raw.githubusercontent.com/tailwindlabs/tailwindcss/a1e74f055b13a7ef5775bdd72a77a4d397565016/src/public/colors.js
+COLORS = {
+    "slate": {
+        50: "#f8fafc",
+        100: "#f1f5f9",
+        200: "#e2e8f0",
+        300: "#cbd5e1",
+        400: "#94a3b8",
+        500: "#64748b",
+        600: "#475569",
+        700: "#334155",
+        800: "#1e293b",
+        900: "#0f172a",
+        950: "#020617",
+    },
+    "gray": {
+        50: "#f9fafb",
+        100: "#f3f4f6",
+        200: "#e5e7eb",
+        300: "#d1d5db",
+        400: "#9ca3af",
+        500: "#6b7280",
+        600: "#4b5563",
+        700: "#374151",
+        800: "#1f2937",
+        900: "#111827",
+        950: "#030712",
+    },
+    "zinc": {
+        50: "#fafafa",
+        100: "#f4f4f5",
+        200: "#e4e4e7",
+        300: "#d4d4d8",
+        400: "#a1a1aa",
+        500: "#71717a",
+        600: "#52525b",
+        700: "#3f3f46",
+        800: "#27272a",
+        900: "#18181b",
+        950: "#09090b",
+    },
+    "neutral": {
+        50: "#fafafa",
+        100: "#f5f5f5",
+        200: "#e5e5e5",
+        300: "#d4d4d4",
+        400: "#a3a3a3",
+        500: "#737373",
+        600: "#525252",
+        700: "#404040",
+        800: "#262626",
+        900: "#171717",
+        950: "#0a0a0a",
+    },
+    "stone": {
+        50: "#fafaf9",
+        100: "#f5f5f4",
+        200: "#e7e5e4",
+        300: "#d6d3d1",
+        400: "#a8a29e",
+        500: "#78716c",
+        600: "#57534e",
+        700: "#44403c",
+        800: "#292524",
+        900: "#1c1917",
+        950: "#0c0a09",
+    },
+    "red": {
+        50: "#fef2f2",
+        100: "#fee2e2",
+        200: "#fecaca",
+        300: "#fca5a5",
+        400: "#f87171",
+        500: "#ef4444",
+        600: "#dc2626",
+        700: "#b91c1c",
+        800: "#991b1b",
+        900: "#7f1d1d",
+        950: "#450a0a",
+    },
+    "orange": {
+        50: "#fff7ed",
+        100: "#ffedd5",
+        200: "#fed7aa",
+        300: "#fdba74",
+        400: "#fb923c",
+        500: "#f97316",
+        600: "#ea580c",
+        700: "#c2410c",
+        800: "#9a3412",
+        900: "#7c2d12",
+        950: "#431407",
+    },
+    "amber": {
+        50: "#fffbeb",
+        100: "#fef3c7",
+        200: "#fde68a",
+        300: "#fcd34d",
+        400: "#fbbf24",
+        500: "#f59e0b",
+        600: "#d97706",
+        700: "#b45309",
+        800: "#92400e",
+        900: "#78350f",
+        950: "#451a03",
+    },
+    "yellow": {
+        50: "#fefce8",
+        100: "#fef9c3",
+        200: "#fef08a",
+        300: "#fde047",
+        400: "#facc15",
+        500: "#eab308",
+        600: "#ca8a04",
+        700: "#a16207",
+        800: "#854d0e",
+        900: "#713f12",
+        950: "#422006",
+    },
+    "lime": {
+        50: "#f7fee7",
+        100: "#ecfccb",
+        200: "#d9f99d",
+        300: "#bef264",
+        400: "#a3e635",
+        500: "#84cc16",
+        600: "#65a30d",
+        700: "#4d7c0f",
+        800: "#3f6212",
+        900: "#365314",
+        950: "#1a2e05",
+    },
+    "green": {
+        50: "#f0fdf4",
+        100: "#dcfce7",
+        200: "#bbf7d0",
+        300: "#86efac",
+        400: "#4ade80",
+        500: "#22c55e",
+        600: "#16a34a",
+        700: "#15803d",
+        800: "#166534",
+        900: "#14532d",
+        950: "#052e16",
+    },
+    "emerald": {
+        50: "#ecfdf5",
+        100: "#d1fae5",
+        200: "#a7f3d0",
+        300: "#6ee7b7",
+        400: "#34d399",
+        500: "#10b981",
+        600: "#059669",
+        700: "#047857",
+        800: "#065f46",
+        900: "#064e3b",
+        950: "#022c22",
+    },
+    "teal": {
+        50: "#f0fdfa",
+        100: "#ccfbf1",
+        200: "#99f6e4",
+        300: "#5eead4",
+        400: "#2dd4bf",
+        500: "#14b8a6",
+        600: "#0d9488",
+        700: "#0f766e",
+        800: "#115e59",
+        900: "#134e4a",
+        950: "#042f2e",
+    },
+    "cyan": {
+        50: "#ecfeff",
+        100: "#cffafe",
+        200: "#a5f3fc",
+        300: "#67e8f9",
+        400: "#22d3ee",
+        500: "#06b6d4",
+        600: "#0891b2",
+        700: "#0e7490",
+        800: "#155e75",
+        900: "#164e63",
+        950: "#083344",
+    },
+    "sky": {
+        50: "#f0f9ff",
+        100: "#e0f2fe",
+        200: "#bae6fd",
+        300: "#7dd3fc",
+        400: "#38bdf8",
+        500: "#0ea5e9",
+        600: "#0284c7",
+        700: "#0369a1",
+        800: "#075985",
+        900: "#0c4a6e",
+        950: "#082f49",
+    },
+    "blue": {
+        50: "#eff6ff",
+        100: "#dbeafe",
+        200: "#bfdbfe",
+        300: "#93c5fd",
+        400: "#60a5fa",
+        500: "#3b82f6",
+        600: "#2563eb",
+        700: "#1d4ed8",
+        800: "#1e40af",
+        900: "#1e3a8a",
+        950: "#172554",
+    },
+    "indigo": {
+        50: "#eef2ff",
+        100: "#e0e7ff",
+        200: "#c7d2fe",
+        300: "#a5b4fc",
+        400: "#818cf8",
+        500: "#6366f1",
+        600: "#4f46e5",
+        700: "#4338ca",
+        800: "#3730a3",
+        900: "#312e81",
+        950: "#1e1b4b",
+    },
+    "violet": {
+        50: "#f5f3ff",
+        100: "#ede9fe",
+        200: "#ddd6fe",
+        300: "#c4b5fd",
+        400: "#a78bfa",
+        500: "#8b5cf6",
+        600: "#7c3aed",
+        700: "#6d28d9",
+        800: "#5b21b6",
+        900: "#4c1d95",
+        950: "#2e1065",
+    },
+    "purple": {
+        50: "#faf5ff",
+        100: "#f3e8ff",
+        200: "#e9d5ff",
+        300: "#d8b4fe",
+        400: "#c084fc",
+        500: "#a855f7",
+        600: "#9333ea",
+        700: "#7e22ce",
+        800: "#6b21a8",
+        900: "#581c87",
+        950: "#3b0764",
+    },
+    "fuchsia": {
+        50: "#fdf4ff",
+        100: "#fae8ff",
+        200: "#f5d0fe",
+        300: "#f0abfc",
+        400: "#e879f9",
+        500: "#d946ef",
+        600: "#c026d3",
+        700: "#a21caf",
+        800: "#86198f",
+        900: "#701a75",
+        950: "#4a044e",
+    },
+    "pink": {
+        50: "#fdf2f8",
+        100: "#fce7f3",
+        200: "#fbcfe8",
+        300: "#f9a8d4",
+        400: "#f472b6",
+        500: "#ec4899",
+        600: "#db2777",
+        700: "#be185d",
+        800: "#9d174d",
+        900: "#831843",
+        950: "#500724",
+    },
+    "rose": {
+        50: "#fff1f2",
+        100: "#ffe4e6",
+        200: "#fecdd3",
+        300: "#fda4af",
+        400: "#fb7185",
+        500: "#f43f5e",
+        600: "#e11d48",
+        700: "#be123c",
+        800: "#9f1239",
+        900: "#881337",
+        950: "#4c0519",
+    },
+}

openretailscience/metrics/base.py

@@ -0,0 +1,29 @@
+"""Shared ibis expression helpers for metric calculations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import ibis.expr.types as ir
+
+PERCENTAGE_SCALE = 100
+
+
+def ratio_metric(
+    numerator: ir.NumericValue,
+    denominator: ir.NumericValue,
+    scale: float = PERCENTAGE_SCALE,
+) -> ir.FloatingValue:
+    """Computes a scaled ratio, returning NULL on zero denominator.
+
+    Args:
+        numerator (ir.NumericValue): The numerator ibis expression.
+        denominator (ir.NumericValue): The denominator ibis expression.
+        scale (float, optional): Multiplicative scale factor. Defaults to 100 for percentages.
+
+    Returns:
+        ir.FloatingValue: The scaled ratio expression. Evaluates to NULL
+            when the denominator is zero (materializes as NaN in pandas).
+    """
+    return (numerator / denominator.nullif(0)) * scale

openretailscience/metrics/distribution/acv.py

@@ -0,0 +1,81 @@
+"""ACV (All Commodity Volume) metric.
+
+ACV measures total dollar sales across all products in a set of stores,
+expressed in millions ($MM).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import ibis
+from ibis import _
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+from openretailscience.options import get_option
+from openretailscience.utils.validation import ensure_ibis_table, validate_columns
+
+
+class Acv:
+    """Calculates ACV (All Commodity Volume) for a set of stores.
+
+    ACV represents total dollar sales across all products, expressed in millions ($MM).
+    NaN values in the spend column are excluded from the sum.
+
+    Results are accessible via the `table` attribute (ibis Table) or the `df` property
+    (materialized pandas DataFrame).
+
+    Args:
+        df (pd.DataFrame | ibis.Table): Transaction data containing at least a unit_spend column.
+        group_col (str | list[str] | None, optional): Optional column(s) to group the ACV calculation by
+            (e.g., store_id). Defaults to None for total ACV.
+        acv_scale_factor (float, optional): Factor to scale the ACV result (default is 1,000,000 for $MM).
+
+    Raises:
+        TypeError: If df is not a pandas DataFrame or an Ibis Table.
+        ValueError: If required columns are missing from the data or if acv_scale_factor is not positive.
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        *,
+        group_col: str | list[str] | None = None,
+        acv_scale_factor: float = 1_000_000,
+    ) -> None:
+        """Initializes the ACV calculation."""
+        self._df: pd.DataFrame | None = None
+        self.table: ibis.Table
+
+        df = ensure_ibis_table(df)
+
+        if acv_scale_factor <= 0:
+            raise ValueError("acv_scale_factor must be positive.")
+
+        unit_spend_col = get_option("column.unit_spend")
+
+        if isinstance(group_col, str):
+            group_col = [group_col]
+
+        required_cols = [unit_spend_col]
+        if group_col is not None:
+            required_cols.extend(group_col)
+        validate_columns(df, required_cols)
+
+        if group_col is not None:
+            df = df.group_by(group_col)
+
+        self.table = df.aggregate(acv=_[unit_spend_col].sum() / acv_scale_factor)
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Returns the materialized pandas DataFrame of ACV results.
+
+        Returns:
+            pd.DataFrame: DataFrame with ACV values. Cached after first access.
+        """
+        if self._df is None:
+            self._df = self.table.execute()
+        return self._df

openretailscience/metrics/distribution/pct_of_stores.py

@@ -0,0 +1,118 @@
+"""% of Stores (Numeric Distribution) metric.
+
+% of Stores measures the share of total stores in the dataset that sell a given product.
+Every store counts equally regardless of its sales volume.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import ibis
+from ibis import _
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+from openretailscience.metrics.base import ratio_metric
+from openretailscience.options import ColumnHelper, get_option
+from openretailscience.utils.validation import ensure_ibis_table, validate_columns
+
+_TEMP_TOTAL_STORES = "__prs_temp_total_stores__"
+
+
+class PctOfStores:
+    """Calculates the percentage of stores selling each product.
+
+    This is the simplest, unweighted distribution metric (numeric distribution).
+    It answers the question: "What fraction of stores carry this product?"
+
+    Results are accessible via the ``table`` attribute (ibis Table) or the ``df`` property
+    (materialized pandas DataFrame).
+
+    Args:
+        df (pd.DataFrame | ibis.Table): Transaction-level data containing at least
+            store_id and product_id columns.
+        product_col (str | list[str] | None, optional): Column(s) defining product granularity.
+            Defaults to ``get_option("column.product_id")``.
+        group_col (str | list[str] | None, optional): Additional grouping dimensions
+            (e.g., ``"category_0_name"``). Defaults to None.
+        within_group (bool, optional): Controls the denominator when ``group_col`` is specified.
+            When ``False`` (default), the percentage is relative to all stores in the dataset.
+            When ``True``, the percentage is relative to stores within each group independently.
+            Has no effect when ``group_col`` is None. Defaults to False.
+
+    Raises:
+        TypeError: If df is not a pandas DataFrame or an Ibis Table.
+        ValueError: If required columns are missing from the data, or if product_col
+            appears in group_col.
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame | ibis.Table,
+        *,
+        product_col: str | list[str] | None = None,
+        group_col: str | list[str] | None = None,
+        within_group: bool = False,
+    ) -> None:
+        """Initializes the % of Stores calculation."""
+        self._df: pd.DataFrame | None = None
+        self.table: ibis.Table
+
+        df = ensure_ibis_table(df)
+
+        store_id_col = get_option("column.store_id")
+
+        if product_col is None:
+            product_col = [get_option("column.product_id")]
+        elif isinstance(product_col, str):
+            product_col = [product_col]
+
+        if isinstance(group_col, str):
+            group_col = [group_col]
+
+        required_cols = [store_id_col, *product_col]
+        group_cols = list(product_col)
+        if group_col is not None:
+            overlap = set(product_col) & set(group_col)
+            if len(overlap) > 0:
+                msg = f"product_col {overlap} must not also appear in group_col"
+                raise ValueError(msg)
+            required_cols.extend(group_col)
+            group_cols.extend(group_col)
+        validate_columns(df, required_cols)
+
+        store_product = df.select([store_id_col, *group_cols]).distinct()
+
+        agg_stores_col = get_option("column.agg.store_id")
+        per_group = store_product.group_by(group_cols).aggregate(
+            **{agg_stores_col: _[store_id_col].count()},
+        )
+
+        use_within_group = within_group and group_col is not None
+        if use_within_group:
+            total_stores = store_product.group_by(group_col).aggregate(
+                **{_TEMP_TOTAL_STORES: _[store_id_col].nunique()},
+            )
+            per_group = per_group.inner_join(total_stores, group_col)
+            denominator = _[_TEMP_TOTAL_STORES]
+        else:
+            denominator = store_product[store_id_col].nunique()
+
+        pct_stores_col = ColumnHelper.join_options("column.agg.store_id", "column.suffix.percent")
+        final_cols = [*group_cols, agg_stores_col, pct_stores_col]
+        self.table = per_group.mutate(
+            **{pct_stores_col: ratio_metric(_[agg_stores_col], denominator)},
+        ).select(final_cols)
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Returns the materialized pandas DataFrame of % of Stores results.
+
+        Returns:
+            pd.DataFrame: DataFrame with % of stores values. Cached after first access.
+        """
+        if self._df is None:
+            self._df = self.table.execute()
+        return self._df