do-attribution 0.0.1.post1__py3-none-any.whl

do_attribution/__init__.py

@@ -0,0 +1,115 @@
+"""
+do_attribution
+===================
+
+Multi-touch attribution for Python.  Exposes two statistical allocation
+models -- an absorbing-Markov-chain removal-effect model and a
+cooperative-game-theoretic Shapley-value model -- through a single
+:class:`BaseAttribution` interface, so callers can switch models or
+fit both and compare them without changing their call site.
+
+Quick start
+-----------
+
+>>> from do_attribution import MarkovAttribution, ShapleyAttribution, CompareAttribution
+>>> paths = ['A > B > C', 'A > C', 'B > C']
+>>> conversions = [1, 0, 1]
+>>> MarkovAttribution(order=1).fit(paths, conversions)['attribution']      # doctest: +SKIP
+>>> ShapleyAttribution().fit(paths, conversions)['attribution']             # doctest: +SKIP
+>>> CompareAttribution().fit(paths, conversions)                            # doctest: +SKIP
+"""
+
+from .base import BaseAttribution
+from .markov import MarkovAttribution
+from .shapley import ShapleyAttribution
+from .compare import CompareAttribution
+# MODIFIED: export TemporalShapleyAttribution now that the module lives
+# inside the package (previously a workspace-root draft).
+from .temporal_shapley import TemporalShapleyAttribution
+# MODIFIED (temporal v1 punch list): export TemporalMarkovAttribution
+# alongside its Shapley sibling, plus the suggest_freq diagnostic.
+from .temporal_markov import TemporalMarkovAttribution
+from .temporal_diagnostics import suggest_freq
+from .temporal import (
+    BoundaryEvent,
+    DaySummary,
+    DecompositionResult,
+    EpochRecommendation,
+    EpochSufficiencyError,
+    EpochWidthError,
+    MergeAction,
+    NonCalendarBoundaryError,
+    PinAction,
+    PinOverlapError,
+    SegmentFit,
+    SignalContinuityError,
+    SignalShapeError,
+    SignalSufficiencyError,
+    StreamingEpochRecommender,
+    TemporalRecommendationError,
+    WeightedAffineCost,
+    assign_paths_to_epochs,
+    recommend_epochs,
+)
+from .reporting import TemporalReportingSnapshot
+from .utils import (
+    DEFAULT_SEPARATOR,
+    SPECIAL_TOKENS,
+    create_n_order_states,
+    extract_channels,
+    get_powerset,
+    split_path,
+    strip_conversion_labels,  # MODIFIED: P0 export.
+    strip_conversion_labels_array,  # MODIFIED: P0 export.
+    to_int_array,
+    to_string_array,
+    validate_data,
+)
+
+__version__ = "0.0.1.post1"
+
+__all__ = [
+    # Classes
+    "BaseAttribution",
+    "MarkovAttribution",
+    "ShapleyAttribution",
+    "CompareAttribution",
+    # MODIFIED: temporal classes exported alongside their static siblings.
+    "TemporalShapleyAttribution",
+    "TemporalMarkovAttribution",
+    # MODIFIED: temporal diagnostics.
+    "suggest_freq",
+    # Global-signal temporal recommender.
+    "BoundaryEvent",
+    "DaySummary",
+    "DecompositionResult",
+    "EpochRecommendation",
+    "EpochSufficiencyError",
+    "EpochWidthError",
+    "MergeAction",
+    "NonCalendarBoundaryError",
+    "PinAction",
+    "PinOverlapError",
+    "SegmentFit",
+    "SignalContinuityError",
+    "SignalShapeError",
+    "SignalSufficiencyError",
+    "StreamingEpochRecommender",
+    "TemporalRecommendationError",
+    "TemporalReportingSnapshot",
+    "WeightedAffineCost",
+    "assign_paths_to_epochs",
+    "recommend_epochs",
+    # Utils
+    "DEFAULT_SEPARATOR",
+    "SPECIAL_TOKENS",
+    "create_n_order_states",
+    "extract_channels",
+    "get_powerset",
+    "split_path",
+    "strip_conversion_labels",  # MODIFIED: P0 export.
+    "strip_conversion_labels_array",  # MODIFIED: P0 export.
+    "to_int_array",
+    "to_string_array",
+    "validate_data",
+]

do_attribution/base.py

@@ -0,0 +1,147 @@
+"""
+do_attribution.base
+------------------------
+
+Abstract base class shared by every attribution model in the library.
+Guarantees a single, consistent ``fit`` / ``get_attribution`` API so that
+code can switch between Markov-chain and Shapley-value attribution without
+any changes other than the constructor name.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+from .utils import DEFAULT_SEPARATOR, _normalize_conversion_labels  # MODIFIED: P0 imports
+from .reporting import (
+    TemporalReportingSnapshot,
+    build_epoch_metrics,
+    render_temporal_report,
+)
+
+
+class BaseAttribution(ABC):
+    """Common interface for all attribution models.
+
+    Subclasses must implement :meth:`fit`.  They should populate
+    ``self.channels`` and ``self._last_attribution`` so that
+    :meth:`get_attribution` and :meth:`get_channels` work uniformly.
+
+    Parameters
+    ----------
+    separator : str, default=' > '
+        Delimiter used to split path strings into channels.
+    conversion_labels : iterable of str, optional
+        Tokens in the path strings that represent the conversion endpoint
+        (e.g. ``"Purchase"``) rather than a real marketing channel.  When
+        supplied, these tokens are stripped from every path *before* channel
+        extraction, state creation, and attribution math, so they never
+        appear in ``attribution``, ``removal_effects``, the transition
+        matrix, Shapley values, or any downstream viz.  Case-sensitive exact
+        match.  Defaults to ``None`` (every token is treated as a channel,
+        matching the pre-P0 behaviour).  Raises ``ValueError`` if any label
+        collides with :data:`~do_attribution.utils.SPECIAL_TOKENS`.
+    """
+
+    def __init__(
+        self,
+        separator: str = DEFAULT_SEPARATOR,
+        conversion_labels: Optional[Iterable[str]] = None,  # MODIFIED: P0 parameter.
+    ):
+        self.separator: str = separator
+        # MODIFIED: normalise + validate once at construction time so every
+        # downstream operation can rely on a frozenset[str] (possibly empty).
+        self.conversion_labels: "frozenset[str]" = _normalize_conversion_labels(
+            conversion_labels
+        )
+        self.channels: List[str] = []
+        self._last_attribution: Dict[str, float] = {}
+        self._static_reporting_snapshot: TemporalReportingSnapshot | None = None
+
+    # ------------------------------------------------------------------ #
+    # Required API                                                        #
+    # ------------------------------------------------------------------ #
+    @abstractmethod
+    def fit(
+        self,
+        paths: Union[Sequence[str], np.ndarray, pd.Series],
+        conversions: Union[Sequence[int], np.ndarray, pd.Series],
+    ) -> Dict[str, Any]:
+        """Fit the model and return the results dict.
+
+        Every subclass must at minimum include an ``'attribution'`` key
+        whose value is a ``dict[str, float]`` normalised to sum to 1.
+        """
+        raise NotImplementedError
+
+    # ------------------------------------------------------------------ #
+    # Convenience helpers (concrete)                                      #
+    # ------------------------------------------------------------------ #
+    def get_attribution(self) -> Dict[str, float]:
+        """Return the attribution dict from the last :meth:`fit` call."""
+        if not self._last_attribution:
+            raise ValueError("No attribution available. Call fit() first.")
+        return dict(self._last_attribution)
+
+    def get_channels(self) -> List[str]:
+        """Return the sorted channel list learned during the last fit."""
+        return list(self.channels)
+
+    def summary(self, output_format: str = "summary") -> str:
+        """Render a plain-text summary or report for a fitted static model.
+
+        Static fits use the same deterministic renderer as temporal fits with
+        one ``All paths`` cohort and no timestamp boundaries.  Temporal
+        subclasses override this method with their multi-epoch snapshots.
+        """
+
+        if self._static_reporting_snapshot is None:
+            raise RuntimeError("summary() requires a fitted attribution model")
+        return render_temporal_report(self._static_reporting_snapshot, output_format)
+
+    def _store_static_reporting(
+        self,
+        paths: Union[Sequence[str], np.ndarray, pd.Series],
+        conversions: Union[Sequence[int], np.ndarray, pd.Series],
+        model_details: tuple = (),  # MODIFIED: distilled model sections
+    ) -> None:
+        """Store the all-data snapshot after a successful static fit."""
+
+        path_count = len(paths)
+        conversion_count = int(np.asarray(conversions, dtype=int).sum())
+        metrics = build_epoch_metrics(
+            epoch_labels=["All paths"],
+            starts=[pd.NaT],
+            ends=[pd.NaT],
+            path_counts=[path_count],
+            conversion_counts=[conversion_count],
+            sample_floors=0,
+        )
+        self._static_reporting_snapshot = TemporalReportingSnapshot(
+            model_name=self.__class__.__name__,
+            epoch_source="static",
+            epoch_labels=("All paths",),
+            boundaries=None,
+            epoch_metrics=metrics,
+            attribution_matrix=pd.DataFrame([dict(self._last_attribution)]),
+            sample_floor=0,
+            model_details=tuple(model_details),  # MODIFIED
+        )
+
+    # ------------------------------------------------------------------ #
+    # Introspection                                                       #
+    # ------------------------------------------------------------------ #
+    @property
+    def name(self) -> str:
+        """Short human-readable name of the concrete model."""
+        return self.__class__.__name__
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return f"<{self.name} separator={self.separator!r}>"
+
+
+__all__ = ["BaseAttribution"]

do_attribution/compare.py

@@ -0,0 +1,138 @@
+"""
+do_attribution.compare
+---------------------------
+
+Thin wrapper that fits both the :class:`MarkovAttribution` and
+:class:`ShapleyAttribution` models on the same data and returns a
+side-by-side comparison so callers can inspect differences in the
+attribution distributions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+from .base import BaseAttribution
+from .markov import MarkovAttribution
+from .shapley import ShapleyAttribution
+from .utils import DEFAULT_SEPARATOR, extract_channels
+
+
+class CompareAttribution:
+    """Run Markov and Shapley attribution on the same data and compare.
+
+    Parameters
+    ----------
+    markov_order : int, default=1
+        Order of the Markov chain used internally.
+    markov_removal_strategy : {'fail', 'detour'}, default='fail'
+        Removal strategy forwarded to :class:`MarkovAttribution`.
+    separator : str, default=' > '
+        Separator used to split path strings.
+    extra_models : dict[str, BaseAttribution], optional
+        Additional named attribution models to include in the comparison.
+        Each model must implement the :class:`BaseAttribution` API.
+    conversion_labels : iterable of str, optional
+        Tokens that represent the conversion endpoint (e.g. ``"Purchase"``)
+        rather than a real channel.  Forwarded to both sub-models so they
+        strip the endpoint tokens before any attribution math.  See
+        :class:`do_attribution.base.BaseAttribution` for full semantics.
+    """
+
+    def __init__(
+        self,
+        markov_order: int = 1,
+        markov_removal_strategy: str = "fail",
+        separator: str = DEFAULT_SEPARATOR,
+        extra_models: Optional[Dict[str, BaseAttribution]] = None,
+        conversion_labels: Optional[Iterable[str]] = None,  # MODIFIED: P0.
+    ) -> None:
+        self.separator = separator
+        # MODIFIED (P0): store conversion_labels so both extract_channels()
+        # calls and forwarded sub-models exclude the endpoint tokens.  Keep
+        # a list copy (not a frozenset) so we can re-pass it unchanged.
+        self.conversion_labels: Optional[List[str]] = (
+            list(conversion_labels) if conversion_labels is not None else None
+        )
+        self.markov = MarkovAttribution(
+            order=markov_order,
+            separator=separator,
+            removal_strategy=markov_removal_strategy,
+            conversion_labels=conversion_labels,  # MODIFIED: P0 forward.
+        )
+        self.shapley = ShapleyAttribution(
+            separator=separator,
+            conversion_labels=conversion_labels,  # MODIFIED: P0 forward.
+        )
+        self.extra_models: Dict[str, BaseAttribution] = dict(extra_models or {})
+
+        self._results: Dict[str, Dict[str, Any]] = {}
+        self.channels: List[str] = []
+
+    # ------------------------------------------------------------------ #
+    # Public API                                                          #
+    # ------------------------------------------------------------------ #
+    def fit(
+        self,
+        paths: Union[Sequence[str], np.ndarray, pd.Series],
+        conversions: Union[Sequence[int], np.ndarray, pd.Series],
+    ) -> Dict[str, Dict[str, Any]]:
+        """Fit every model and return their individual result dicts.
+
+        Returns
+        -------
+        dict
+            Keys are the model names (``'markov'``, ``'shapley'``, plus any
+            keys from ``extra_models``). Values are the raw result dicts
+            returned by each model's own ``fit``.
+        """
+        # MODIFIED (P0): pass conversion_labels to extract_channels so the
+        # endpoint tokens never show up in self.channels / attribution_frame.
+        self.channels = extract_channels(
+            paths, self.separator, conversion_labels=self.conversion_labels
+        )
+        self._results = {
+            "markov": self.markov.fit(paths, conversions),
+            "shapley": self.shapley.fit(paths, conversions),
+        }
+        for name, model in self.extra_models.items():
+            self._results[name] = model.fit(paths, conversions)
+        return self._results
+
+    def attribution_frame(self) -> pd.DataFrame:
+        """Return a DataFrame with one row per channel and one column per model.
+
+        Columns are the normalised attribution shares (sum to 1 within
+        each column).  Channels are sorted alphabetically.
+        """
+        if not self._results:
+            raise ValueError("No results available. Call fit() first.")
+
+        frame = pd.DataFrame(index=sorted(self.channels))
+        for name, res in self._results.items():
+            frame[name] = pd.Series(res["attribution"])
+        # Channels absent from a particular model fill as 0.
+        return frame.fillna(0.0).sort_index()
+
+    def difference_frame(self, reference: str = "markov") -> pd.DataFrame:
+        """Return per-channel differences vs a reference model's share."""
+        frame = self.attribution_frame()
+        if reference not in frame.columns:
+            raise ValueError(
+                f"reference={reference!r} not in results {list(frame.columns)}"
+            )
+        diff = frame.subtract(frame[reference], axis=0)
+        diff.columns = [f"{c}_minus_{reference}" for c in diff.columns]
+        return diff.drop(columns=[f"{reference}_minus_{reference}"])
+
+    def get_results(self) -> Dict[str, Dict[str, Any]]:
+        """Return the raw results dict from the last :meth:`fit`."""
+        if not self._results:
+            raise ValueError("No results available. Call fit() first.")
+        return self._results
+
+
+__all__ = ["CompareAttribution"]