mta 0.0.8__py3-none-any.whl

mta/__init__.py

@@ -0,0 +1 @@
+from .mta import MTA

mta/mta.py

@@ -0,0 +1,956 @@
+import pandas as pd
+from itertools import chain, tee, combinations
+from functools import reduce, wraps
+from operator import mul
+from collections import defaultdict, Counter
+import random
+import time
+import numpy as np
+import copy
+import os
+import sys
+import math
+from collections.abc import Callable
+from typing import List, Any, Dict, Tuple, DefaultDict, Optional, Union
+from dataclasses import dataclass
+import arrow
+
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import train_test_split
+
+
+@dataclass
+class MTAConfig:
+    """Configuration for MTA model"""
+
+    allow_loops: bool = False
+    add_timepoints: bool = True
+    sep: str = " > "
+    normalize_by_default: bool = True
+
+
+def show_time(func: Callable[..., Any]):
+    """Timer decorator"""
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        t0 = time.time()
+        print(f"running {func.__name__}.. ", end="")
+        sys.stdout.flush()
+
+        v = func(*args, **kwargs)
+
+        minutes, seconds = divmod(time.time() - t0, 60)
+        st = "elapsed time:"
+        if minutes:
+            st += f" {minutes:.0f} min"
+        if seconds:
+            st += f" {seconds:.3f} sec"
+        print(st)
+
+        return v
+
+    return wrapper
+
+
+class MTA:
+    """Multi-Touch Attribution model implementation"""
+
+    def __init__(
+        self,
+        data: Union[str, pd.DataFrame] = "data.csv.gz",
+        config: Optional[MTAConfig] = None,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize MTA model
+
+        Args:
+            data: Path to CSV file or DataFrame
+            config: MTAConfig object or use kwargs for individual settings
+        """
+        # Setup configuration
+        if config is None:
+            config = MTAConfig(
+                **{
+                    k: v
+                    for k, v in kwargs.items()
+                    if k in MTAConfig.__dataclass_fields__
+                }
+            )
+        self.config = config
+
+        # Constants
+        self.NULL = "(null)"
+        self.START = "(start)"
+        self.CONV = "(conversion)"
+
+        # Load and validate data
+        self._load_data(data)
+        self._validate_data()
+
+        # Process data
+        if config.add_timepoints:
+            self.add_exposure_times()
+        if not config.allow_loops:
+            self.remove_loops()
+
+        self._prepare_data()
+        self._setup_channels()
+
+        # Initialize results storage
+        self.attribution: Dict[str, Dict[str, float]] = defaultdict(
+            lambda: defaultdict(float)
+        )
+
+    def _load_data(self, data: Union[str, pd.DataFrame]) -> None:
+        """Load data from file or DataFrame"""
+        if isinstance(data, str):
+            data_path = os.path.join(os.path.dirname(__file__), "data", data)
+            self.data = pd.read_csv(data_path)
+        elif isinstance(data, pd.DataFrame):
+            self.data = data.copy()
+        else:
+            raise TypeError("data must be a file path or pandas DataFrame")
+
+    def _validate_data(self) -> None:
+        """Validate required columns exist"""
+        required_cols = {"path", "total_conversions", "total_null"}
+        if not required_cols.issubset(self.data.columns):
+            raise ValueError(
+                f"Data must contain columns: {required_cols}. "
+                f"Found: {set(self.data.columns)}"
+            )
+
+    def _prepare_data(self) -> None:
+        """Convert path and exposure_times to lists"""
+        self.data[["path", "exposure_times"]] = self.data[
+            ["path", "exposure_times"]
+        ].map(lambda x: [ch.strip() for ch in str(x).split(self.config.sep.strip())])
+
+    def _setup_channels(self) -> None:
+        """Setup channel mappings and indices"""
+        self.channels = sorted({ch for ch in chain.from_iterable(self.data["path"])})
+        self.channels_ext = [self.START] + self.channels + [self.CONV, self.NULL]
+        self.channel_name_to_index = {c: i for i, c in enumerate(self.channels_ext)}
+        self.index_to_channel_name = {
+            i: c for c, i in self.channel_name_to_index.items()
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(channels={len(self.channels)}, "
+            f"journeys={len(self.data)})"
+        )
+
+    def add_exposure_times(self, exposure_every_second: bool = True) -> "MTA":
+        """Generate synthetic exposure times"""
+        if "exposure_times" in self.data.columns:
+            return self
+
+        ts = []
+        _t0 = arrow.utcnow()
+
+        if exposure_every_second:
+            for path_str in self.data["path"]:
+                path_list = [ch.strip() for ch in path_str.split(">")]
+                time_range = arrow.Arrow.range(
+                    "second", _t0, _t0.shift(seconds=len(path_list) - 1)
+                )
+                ts.append(
+                    self.config.sep.join(
+                        [t.format("YYYY-MM-DD HH:mm:ss") for t in time_range]
+                    )
+                )
+
+        self.data["exposure_times"] = ts
+        return self
+
+    @show_time
+    def remove_loops(self) -> "MTA":
+        """Remove consecutive duplicate channels"""
+        cleaned_data = []
+
+        for _, row in self.data.iterrows():
+            path = [ch.strip() for ch in str(row["path"]).split(">")]
+            exposure = [ch.strip() for ch in str(row["exposure_times"]).split(">")]
+
+            clean_path, clean_exposure = [], []
+            prev_channel = None
+
+            for ch, exp in zip(path, exposure):
+                if ch != prev_channel:
+                    clean_path.append(ch)
+                    clean_exposure.append(exp)
+                    prev_channel = ch
+
+            cleaned_data.append(
+                {
+                    "path": self.config.sep.join(clean_path),
+                    "exposure_times": self.config.sep.join(clean_exposure),
+                    **{
+                        col: row[col]
+                        for col in self.data.columns
+                        if col not in ["path", "exposure_times"]
+                    },
+                }
+            )
+
+        self.data = pd.DataFrame(cleaned_data)
+
+        # Aggregate duplicate paths
+        agg_dict = {
+            col: "sum"
+            for col in self.data.columns
+            if col not in ["path", "exposure_times"]
+        }
+        agg_dict["exposure_times"] = "first"
+
+        self.data = self.data.groupby("path", as_index=False).agg(agg_dict)
+        return self
+
+    @staticmethod
+    def normalize_dict(
+        dict_: Dict[Any, float], decimal_digits: int = 6
+    ) -> Dict[Any, float]:
+        """Normalize dictionary values to sum to 1"""
+        total = sum(dict_.values())
+        return (
+            {k: round(v / total, decimal_digits) for k, v in dict_.items()}
+            if total
+            else dict_
+        )
+
+    def _apply_normalization(
+        self, result: Dict[str, float], normalize: bool
+    ) -> Dict[str, float]:
+        """Apply normalization if requested"""
+        return self.normalize_dict(result) if normalize else result
+
+    @show_time
+    def linear(self, share: str = "same", normalize: bool = True) -> "MTA":
+        """
+        Linear attribution model
+
+        Args:
+            share: 'same' for equal distribution or 'proportional' for weighted
+            normalize: Whether to normalize results
+        """
+        if share not in ["same", "proportional"]:
+            raise ValueError("share must be 'same' or 'proportional'")
+
+        linear = defaultdict(float)
+
+        for row in self.data.itertuples():
+            if not row.total_conversions:
+                continue
+
+            if share == "same":
+                unique_channels = set(row.path)
+                credit_per_channel = row.total_conversions / len(unique_channels)
+                for c in unique_channels:
+                    linear[c] += credit_per_channel
+            else:  # proportional
+                channel_counts = Counter(row.path)
+                total_touches = sum(channel_counts.values())
+                for c, count in channel_counts.items():
+                    linear[c] += row.total_conversions * (count / total_touches)
+
+        linear = self._apply_normalization(dict(linear), normalize)
+        self.attribution["linear"] = linear
+        return self
+
+    @show_time
+    def position_based(
+        self, first_weight: float = 40, last_weight: float = 40, normalize: bool = True
+    ) -> "MTA":
+        """
+        Position-based attribution
+
+        Args:
+            first_weight: Percentage credit for first touch (0-100)
+            last_weight: Percentage credit for last touch (0-100)
+            normalize: Whether to normalize results
+        """
+        if first_weight + last_weight > 100:
+            raise ValueError("Sum of first and last weights cannot exceed 100")
+
+        position_based = defaultdict(float)
+
+        for row in self.data.itertuples():
+            if not row.total_conversions:
+                continue
+
+            path_len = len(row.path)
+
+            if path_len == 1:
+                position_based[row.path[0]] += row.total_conversions
+            elif path_len == 2:
+                credit = row.total_conversions / 2
+                position_based[row.path[0]] += credit
+                position_based[row.path[-1]] += credit
+            else:
+                position_based[row.path[0]] += (
+                    first_weight * row.total_conversions / 100
+                )
+                position_based[row.path[-1]] += (
+                    last_weight * row.total_conversions / 100
+                )
+
+                middle_credit = (
+                    (100 - first_weight - last_weight) * row.total_conversions / 100
+                )
+                middle_channels = row.path[1:-1]
+                credit_per_middle = middle_credit / len(middle_channels)
+
+                for c in middle_channels:
+                    position_based[c] += credit_per_middle
+
+        position_based = self._apply_normalization(dict(position_based), normalize)
+        self.attribution["pos_based"] = position_based
+        return self
+
+    @show_time
+    def time_decay(
+        self, count_direction: str = "left", normalize: bool = True
+    ) -> "MTA":
+        """
+        Time decay attribution - channels closer to conversion get more credit
+
+        Args:
+            count_direction: 'left' (oldest first) or 'right' (newest first)
+            normalize: Whether to normalize results
+        """
+        if count_direction not in ["left", "right"]:
+            raise ValueError("count_direction must be 'left' or 'right'")
+
+        time_decay = defaultdict(float)
+
+        for row in self.data.itertuples():
+            if not row.total_conversions:
+                continue
+
+            # Get unique channels in order of appearance
+            seen = []
+            path_to_iterate = (
+                row.path if count_direction == "left" else reversed(row.path)
+            )
+
+            for c in path_to_iterate:
+                if c not in seen:
+                    seen.append(c)
+
+            if count_direction == "right":
+                seen.reverse()
+
+            # Assign weights: 1, 2, 3, ... (linear growth)
+            total_weight = sum(range(1, len(seen) + 1))
+
+            for i, c in enumerate(seen, 1):
+                time_decay[c] += (i / total_weight) * row.total_conversions
+
+        time_decay = self._apply_normalization(dict(time_decay), normalize)
+        self.attribution["time_decay"] = time_decay
+        return self
+
+    @show_time
+    def first_touch(self, normalize: bool = True) -> "MTA":
+        """First-touch attribution model"""
+        first_touch = (
+            self.data[self.data["total_conversions"] > 0]
+            .groupby(self.data["path"].apply(lambda x: x[0]))["total_conversions"]
+            .sum()
+            .to_dict()
+        )
+
+        first_touch = self._apply_normalization(first_touch, normalize)
+        self.attribution["first_touch"] = first_touch
+        return self
+
+    @show_time
+    def last_touch(self, normalize: bool = True) -> "MTA":
+        """Last-touch attribution model"""
+        last_touch = (
+            self.data[self.data["total_conversions"] > 0]
+            .groupby(self.data["path"].apply(lambda x: x[-1]))["total_conversions"]
+            .sum()
+            .to_dict()
+        )
+
+        last_touch = self._apply_normalization(last_touch, normalize)
+        self.attribution["last_touch"] = last_touch
+        return self
+
+    @staticmethod
+    def pairs(lst: List[Any]) -> zip:
+        """Generate consecutive pairs from list"""
+        it1, it2 = tee(lst)
+        next(it2, None)
+        return zip(it1, it2)
+
+    def count_pairs(self) -> DefaultDict[Tuple[str, str], int]:
+        """Count channel pair transitions"""
+        pair_counts = defaultdict(int)
+
+        for row in self.data.itertuples():
+            # Count transitions along the path
+            for pair in self.pairs([self.START] + row.path):
+                pair_counts[pair] += row.total_conversions + row.total_null
+
+            # Add terminal transitions
+            pair_counts[(row.path[-1], self.NULL)] += row.total_null
+            pair_counts[(row.path[-1], self.CONV)] += row.total_conversions
+
+        return pair_counts
+
+    def ordered_tuple(self, t: Tuple[Any, ...]) -> Tuple[Any, ...]:
+        """
+        Return tuple t ordered
+        Special case: if tuple starts with START, keep it first and sort the rest
+        """
+        if len(t) > 1 and t[0] == self.START:
+            return (t[0],) + tuple(sorted(t[1:]))
+        return tuple(sorted(t))
+
+    def transition_matrix(self) -> Dict[Tuple[str, str], float]:
+        """Calculate Markov transition probabilities"""
+        pair_counts = self.count_pairs()
+
+        # Calculate outgoing transition totals
+        outgoing = defaultdict(int)
+        for (from_ch, _), count in pair_counts.items():
+            outgoing[from_ch] += count
+
+        # Calculate probabilities
+        return {pair: count / outgoing[pair[0]] for pair, count in pair_counts.items()}
+
+    @show_time
+    def simulate_path(
+        self,
+        trans_mat: Dict[Tuple[str, str], float],
+        drop_channel: Optional[str] = None,
+        n: int = int(1e6),
+    ) -> Dict[str, int]:
+        """Simulate random user journeys using Markov chain"""
+        outcome_counts = defaultdict(int)
+
+        idx_start = self.channel_name_to_index[self.START]
+        idx_null = self.channel_name_to_index[self.NULL]
+        idx_conv = self.channel_name_to_index[self.CONV]
+        idx_drop = self.channel_name_to_index.get(drop_channel, idx_null)
+
+        for _ in range(n):
+            current_idx = idx_start
+
+            while True:
+                # Get transition probabilities from current state
+                probs = [
+                    trans_mat.get(
+                        (
+                            self.index_to_channel_name[current_idx],
+                            self.index_to_channel_name[i],
+                        ),
+                        0,
+                    )
+                    for i in range(len(self.channels_ext))
+                ]
+
+                # Choose next state
+                next_idx = np.random.choice(len(self.channels_ext), p=probs)
+
+                if next_idx == idx_conv:
+                    outcome_counts[self.CONV] += 1
+                    break
+                elif next_idx in {idx_null, idx_drop}:
+                    outcome_counts[self.NULL] += 1
+                    break
+                else:
+                    current_idx = next_idx
+
+        return dict(outcome_counts)
+
+    def _calculate_path_probability(
+        self, path: List[str], trans_mat: Dict[Tuple[str, str], float]
+    ) -> float:
+        """Calculate probability of a specific path"""
+        full_path = [self.START] + path + [self.CONV]
+        probs = [trans_mat.get(pair, 0) for pair in self.pairs(full_path)]
+        return reduce(mul, probs) if probs else 0
+
+    def prob_convert(
+        self, trans_mat: Dict[Tuple[str, str], float], drop: Optional[str] = None
+    ) -> float:
+        """Calculate total conversion probability"""
+        # Filter data
+        if drop:
+            mask = ~self.data["path"].apply(lambda x: drop in x) & (
+                self.data["total_conversions"] > 0
+            )
+        else:
+            mask = self.data["total_conversions"] > 0
+
+        filtered_data = self.data[mask]
+
+        # Sum probabilities across all converting paths
+        total_prob = sum(
+            self._calculate_path_probability(row.path, trans_mat)
+            for row in filtered_data.itertuples()
+        )
+
+        return total_prob
+
+    @show_time
+    def markov(self, sim: bool = False, normalize: bool = True) -> "MTA":
+        """
+        Markov chain attribution model
+
+        Args:
+            sim: Use simulation (True) or analytical calculation (False)
+            normalize: Whether to normalize results
+        """
+        markov = defaultdict(float)
+        trans_mat = self.transition_matrix()
+
+        if sim:
+            # Simulation-based approach
+            outcomes_full = self.simulate_path(trans_mat, drop_channel=None)
+
+            for channel in self.channels:
+                outcomes_drop = self.simulate_path(trans_mat, drop_channel=channel)
+                markov[channel] = (
+                    outcomes_full[self.CONV] - outcomes_drop[self.CONV]
+                ) / outcomes_full[self.CONV]
+        else:
+            # Analytical approach
+            p_base = self.prob_convert(trans_mat)
+
+            for channel in self.channels:
+                p_without = self.prob_convert(trans_mat, drop=channel)
+                markov[channel] = (p_base - p_without) / p_base if p_base else 0
+
+        markov = self._apply_normalization(dict(markov), normalize)
+        self.attribution["markov"] = markov
+        return self
+
+    @show_time
+    def shao(self, normalize: bool = True) -> "MTA":
+        """
+        probabilistic model by Shao and Li (supposed to be equivalent to Shapley); explanation in the original paper may seem rather unclear but
+        this https://stats.stackexchange.com/questions/255312/multi-channel-attribution-modelling-using-a-simple-probabilistic-model
+        is definitely helpful
+        """
+
+        r = defaultdict(lambda: defaultdict(float))
+
+        # count user conversions and nulls for each visited channel and channel pair
+
+        for row in self.data.itertuples():
+
+            for n in range(1, 3):
+
+                # # combinations('ABCD', 2) --> AB AC AD BC BD CD
+
+                for ch in combinations(set(row.path), n):
+
+                    t = self.ordered_tuple(ch)
+
+                    r[t][self.CONV] += row.total_conversions
+                    r[t][self.NULL] += row.total_null
+
+        for _ in r:
+            r[_]["conv_prob"] = r[_][self.CONV] / (r[_][self.CONV] + r[_][self.NULL])
+
+        # calculate channel contributions
+
+        self.C = defaultdict(float)
+
+        for row in self.data.itertuples():
+
+            for ch_i in set(row.path):
+
+                if row.total_conversions:
+
+                    pc = 0  # contribution for current path
+
+                    other_channels = set(row.path) - {ch_i}
+
+                    k = 2 * len(other_channels) if other_channels else 1
+
+                    for ch_j in other_channels:
+
+                        pc += (
+                            r[self.ordered_tuple((ch_i, ch_j))]["conv_prob"]
+                            - r[(ch_i,)]["conv_prob"]
+                            - r[(ch_j,)]["conv_prob"]
+                        )
+
+                    pc = r[(ch_i,)]["conv_prob"] + pc / k
+
+                    self.C[ch_i] += row.total_conversions * pc
+
+        if normalize:
+            self.C = self.normalize_dict(self.C)
+
+        self.attribution["shao"] = self.C
+
+        return self
+
+    def get_generated_conversions(self, max_subset_size: int = 3) -> "MTA":  # FIXED
+
+        self.cc = defaultdict(lambda: defaultdict(float))
+
+        for ch_list, convs, nulls in zip(
+            self.data["path"], self.data["total_conversions"], self.data["total_null"]
+        ):
+
+            # only look at journeys with conversions
+            for n in range(1, max_subset_size + 1):
+
+                for tup in combinations(set(ch_list), n):
+
+                    tup_ = self.ordered_tuple(tup)
+
+                    self.cc[tup_][self.CONV] += convs
+                    self.cc[tup_][self.NULL] += nulls
+
+        return self
+
+    def v(self, coalition: Tuple[Any, Any]) -> float:
+        """
+        total number of conversions generated by all subsets of the coalition;
+        coalition is a tuple of channels
+        """
+
+        s = len(coalition)
+
+        total_convs = 0
+
+        for n in range(1, s + 1):
+            for tup in combinations(coalition, n):
+                tup_ = self.ordered_tuple(tup)
+                total_convs += self.cc[tup_][self.CONV]
+
+        return total_convs
+
+    def w(self, s, n):
+
+        # FIXED: Handle edge cases properly
+        # Formula: s! * (n - s - 1)! / n!
+        if s >= n or s < 0:
+            return 0
+        return math.factorial(s) * math.factorial(n - s - 1) / math.factorial(n)
+
+    @show_time
+    def shapley(self, max_coalition_size: int = 2, normalize: bool = True) -> "MTA":
+        """
+        Shapley value attribution
+
+        Args:
+            max_coalition_size: Maximum size of coalitions to consider
+            normalize: Whether to normalize results
+        """
+        self.get_generated_conversions(max_subset_size=3)
+
+        shapley = defaultdict(float)
+        n_channels = len(self.channels)
+
+        for channel in self.channels:
+            other_channels = set(self.channels) - {channel}
+
+            # Consider all subset sizes up to max_coalition_size
+            for subset_size in range(
+                1, min(max_coalition_size + 1, len(other_channels) + 1)
+            ):
+                for coalition in combinations(other_channels, subset_size):
+                    marginal_contribution = self.v(coalition + (channel,)) - self.v(
+                        coalition
+                    )
+                    weight = self.w(len(coalition), n_channels)
+                    shapley[channel] += marginal_contribution * weight
+
+        shapley = self._apply_normalization(dict(shapley), normalize)
+        self.attribution["shapley"] = shapley
+        return self
+
+    @show_time
+    def logistic_regression(
+        self,
+        test_size: float = 0.25,
+        sample_rows: float = 0.5,
+        sample_features: float = 0.5,
+        normalize: bool = True,
+        n_iterations: int = 2000,
+    ) -> "MTA":
+        """
+        Logistic regression attribution using ensemble approach
+
+        Args:
+            test_size: Proportion for test set
+            sample_rows: Proportion of rows to sample each iteration
+            sample_features: Proportion of features to sample each iteration
+            normalize: Whether to normalize results
+            n_iterations: Number of bootstrap iterations
+        """
+        # Build feature matrix
+        records = []
+        for row in self.data.itertuples():
+            channel_set = {c: 1 for c in row.path}
+
+            for _ in range(row.total_conversions):
+                records.append({**channel_set, "conv": 1})
+
+            for _ in range(row.total_null):
+                records.append({**channel_set, "conv": 0})
+
+        df = pd.DataFrame(records).fillna(0).sample(frac=1.0, random_state=42)
+
+        # Ensemble learning
+        coef_sum = defaultdict(float)
+
+        for i in range(n_iterations):
+            # Balanced sampling
+            df_conv = df[df["conv"] == 1].sample(frac=0.5, random_state=i)
+            df_null = df[df["conv"] == 0].sample(frac=0.5, random_state=i)
+            df_sample = pd.concat([df_conv, df_null]).sample(
+                frac=sample_rows, random_state=i
+            )
+
+            # Feature sampling
+            feature_cols = (
+                df_sample.drop("conv", axis=1)
+                .sample(frac=sample_features, axis=1, random_state=i)
+                .columns
+            )
+
+            X = df_sample[feature_cols]
+            y = df_sample["conv"]
+
+            # Train model
+            X_train, X_test, y_train, y_test = train_test_split(
+                X, y, test_size=test_size, random_state=i, stratify=y
+            )
+
+            clf = LogisticRegression(
+                random_state=i, solver="lbfgs", fit_intercept=False, max_iter=1000
+            ).fit(X_train, y_train)
+
+            # Accumulate coefficients
+            for channel, coef in zip(X_train.columns, clf.coef_[0]):
+                coef_sum[channel] += abs(coef)
+
+        # Average coefficients
+        lr_attribution = {ch: coef / n_iterations for ch, coef in coef_sum.items()}
+
+        lr_attribution = self._apply_normalization(lr_attribution, normalize)
+        self.attribution["linreg"] = lr_attribution
+        return self
+
+    def show(self, channels: Optional[List[str]] = None) -> pd.DataFrame:
+        """
+        Display attribution results
+
+        Args:
+            channels: Specific channels to show (None for all)
+
+        Returns:
+            DataFrame with attribution results
+        """
+        df = pd.DataFrame.from_dict(self.attribution)
+
+        if channels:
+            df = df.loc[df.index.isin(channels)]
+
+        # Sort by index (channel name)
+        df = df.sort_index()
+
+        print("\nAttribution Results:")
+        print("=" * 80)
+        print(df.to_string())
+        print("=" * 80)
+
+        return df
+
+    def compare_models(self) -> pd.DataFrame:
+        """Compare all attribution models side by side"""
+        df = self.show()
+
+        # Add summary statistics
+        print("\nModel Statistics:")
+        print(df.describe())
+
+        return df
+
+    def export_results(self, filepath: str, format: str = "csv") -> None:
+        """
+        Export attribution results
+
+        Args:
+            filepath: Output file path
+            format: 'csv', 'json', or 'excel'
+        """
+        df = pd.DataFrame.from_dict(self.attribution)
+
+        if format == "csv":
+            df.to_csv(filepath)
+        elif format == "json":
+            df.to_json(filepath, orient="index", indent=2)
+        elif format == "excel":
+            df.to_excel(filepath)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+
+        print(f"Results exported to {filepath}")
+
+    def pi(
+        self, path, exposure_times, conv_flag, beta_by_channel, omega_by_channel
+    ) -> Dict[str, float]:
+        """
+
+        calculate contribution of channel i to conversion of journey (user) u - (p_i^u) in the paper
+
+         - path is a list of states that includes (start) but EXCLUDES (null) or (conversion)
+         - exposure_times is list of exposure times
+
+        """
+
+        p = {c: 0 for c in path}  # contributions by channel
+
+        # all contributions are zero if no conversion
+        if not conv_flag:
+            return p
+
+        dts = [
+            (arrow.get(exposure_times[-1]) - arrow.get(t)).seconds
+            for t in exposure_times
+        ]
+
+        _ = defaultdict(float)
+
+        for c, dt in zip(path, dts):
+            _[c] += (
+                beta_by_channel[c]
+                * omega_by_channel[c]
+                * np.exp(-omega_by_channel[c] * dt)
+            )
+
+        for c in _:
+            p[c] = _[c] / sum(_.values())
+
+        return p
+
+    def update_coefs(self, beta: float, omega: float) -> Tuple[float, float, float]:
+        """
+        return updated beta and omega
+        """
+
+        delta = 1e-3
+
+        beta_num = defaultdict(float)
+        beta_den = defaultdict(float)
+        omega_den = defaultdict(float)
+
+        for u, row in enumerate(self.data.itertuples()):
+
+            p = self.pi(
+                row.path, row.exposure_times, row.total_conversions, beta, omega
+            )
+
+            r = copy.deepcopy(row.path)
+
+            dts = [
+                (arrow.get(row.exposure_times[-1]) - arrow.get(t)).seconds
+                for t in row.exposure_times
+            ]
+
+            while r:
+
+                # pick channels starting from the last one
+                c = r.pop()
+                dt = dts.pop()
+
+                beta_den[c] += 1.0 - np.exp(-omega[c] * dt)
+                omega_den[c] += p[c] * dt + beta[c] * dt * np.exp(-omega[c] * dt)
+
+                beta_num[c] += p[c]
+
+        # now that we gone through every user, update coefficients for every channel
+
+        beta0 = copy.deepcopy(beta)
+        omega0 = copy.deepcopy(omega)
+
+        df = []
+
+        for c in self.channels:
+
+            beta_num[c] = (beta_num[c] > 1e-6) * beta_num[c]
+            beta_den[c] = (beta_den[c] > 1e-6) * beta_den[c]
+            omega_den[c] = max(omega_den[c], 1e-6)
+
+            if beta_den[c]:
+                beta[c] = beta_num[c] / beta_den[c]
+
+            omega[c] = beta_num[c] / omega_den[c]
+
+            df.append(abs(beta[c] - beta0[c]) < delta)
+            df.append(abs(omega[c] - omega0[c]) < delta)
+
+        return (beta, omega, sum(df))
+
+    @show_time
+    def additive_hazard(
+        self, epochs: int = 20, normalize: bool = True
+    ) -> "MTA":  # FIXED
+        """
+        additive hazard model as in Multi-Touch Attribution in On-line Advertising with Survival Theory
+        """
+
+        beta = {c: random.uniform(0.001, 1) for c in self.channels}
+        omega = {c: random.uniform(0.001, 1) for c in self.channels}
+
+        for _ in range(epochs):
+
+            beta, omega, h = self.update_coefs(beta, omega)
+
+            if h == 2 * len(self.channels):
+                print(f"converged after {_ + 1} iterations")
+                break
+
+        # time window: take the max time instant across all journeys that converged
+
+        additive_hazard = defaultdict(float)
+
+        for u, row in enumerate(self.data.itertuples()):
+
+            p = self.pi(
+                row.path, row.exposure_times, row.total_conversions, beta, omega
+            )
+
+            for c in p:
+                # FIXED: Weight by actual conversions
+                additive_hazard[c] += p[c] * row.total_conversions
+
+        if normalize:
+            additive_hazard = self.normalize_dict(additive_hazard)
+
+        self.attribution["add_haz"] = additive_hazard
+
+        return self
+
+
+if __name__ == "__main__":
+
+    mta = MTA(data="data.csv.gz", allow_loops=False)
+
+    (
+        mta.linear(share="proportional")
+        .time_decay(count_direction="right")
+        .shapley()
+        .shao()
+        .first_touch()
+        .position_based()
+        .last_touch()
+        .markov(sim=False)
+        .logistic_regression()
+        .additive_hazard()
+        .show()
+    )

mta-0.0.8.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: mta
+Version: 0.0.8
+Summary: Multi-Touch Attribution Models for Marketing Analytics
+Home-page: https://github.com/eeghor/mta
+Author: Igor Korostil
+Author-email: Igor Korostil <eeghor@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/eeghor/mta
+Project-URL: Issues, https://github.com/eeghor/mta/issues
+Keywords: attribution,marketing,multi-touch,analytics,markov,shapley
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scikit-learn>=0.24.0
+Requires-Dist: arrow>=1.0.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Multi-Touch Attribution (MTA)
+
+A comprehensive Python library for multi-touch attribution modeling in marketing analytics. This library implements various attribution models to help marketers understand the contribution of different touchpoints in the customer journey.
+
+## 🎯 Features
+
+### Attribution Models Implemented
+
+- **First Touch**: 100% credit to the first interaction
+- **Last Touch**: 100% credit to the last interaction before conversion
+- **Linear**: Equal credit distribution across all touchpoints
+- **Position-Based (U-Shaped)**: Customizable weights for first/last touch with remaining credit distributed to middle touches
+- **Time Decay**: Higher credit to more recent touchpoints
+- **Markov Chain**: Probabilistic model using transition matrices
+- **Shapley Value**: Game-theoretic fair allocation based on marginal contributions
+- **Shao's Model**: Probabilistic Shapley-equivalent approach
+- **Logistic Regression**: Machine learning-based ensemble attribution
+- **Additive Hazard**: Survival analysis-based attribution
+
+## 📦 Installation
+
+```bash
+pip install mta
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/eeghor/mta.git
+cd mta
+pip install -e .
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```python
+from mta import MTA
+
+# Initialize with your data
+mta = MTA(data="your_data.csv", allow_loops=False, add_timepoints=True)
+
+# Run a single attribution model
+mta.linear(share="proportional", normalize=True)
+mta.show()
+
+# Chain multiple models
+(mta.linear(share="proportional")
+    .time_decay(count_direction="right")
+    .markov(sim=False)
+    .shapley()
+    .show())
+```
+
+### Using Configuration
+
+```python
+from mta import MTA, MTAConfig
+
+# Create custom configuration
+config = MTAConfig(
+    allow_loops=False,
+    add_timepoints=True,
+    sep=" > ",
+    normalize_by_default=True
+)
+
+mta = MTA(data="data.csv", config=config)
+```
+
+### Working with DataFrames
+
+```python
+import pandas as pd
+from mta import MTA
+
+# Load your data
+df = pd.read_csv("customer_journeys.csv")
+
+# Initialize MTA with DataFrame
+mta = MTA(data=df, allow_loops=False)
+
+# Run attribution models
+mta.first_touch().last_touch().linear().show()
+```
+
+## 📊 Data Format
+
+Your input data should be a CSV file or pandas DataFrame with the following columns:
+
+```
+path,total_conversions,total_null,exposure_times
+alpha > beta > gamma,10,5,2023-01-01 10:00:00 > 2023-01-01 11:00:00 > 2023-01-01 12:00:00
+beta > gamma,5,3,2023-01-02 09:00:00 > 2023-01-02 10:00:00
+```
+
+**Required Columns:**
+
+- `path`: Customer journey as channel names separated by `>` (or custom separator)
+- `total_conversions`: Number of conversions for this path
+- `total_null`: Number of non-conversions for this path
+- `exposure_times`: Timestamps of channel exposures (optional, can be auto-generated)
+
+## 🎨 Advanced Usage
+
+### Position-Based Attribution with Custom Weights
+
+```python
+# Give 30% to first touch, 30% to last touch, 40% distributed to middle
+mta.position_based(first_weight=30, last_weight=30, normalize=True)
+```
+
+### Time Decay with Direction Control
+
+```python
+# Count from left (earliest gets lowest credit)
+mta.time_decay(count_direction="left")
+
+# Count from right (latest gets highest credit - more common)
+mta.time_decay(count_direction="right")
+```
+
+### Markov Chain Attribution
+
+```python
+# Analytical calculation (faster)
+mta.markov(sim=False, normalize=True)
+
+# Simulation-based (more flexible, handles complex scenarios)
+mta.markov(sim=True, normalize=True)
+```
+
+### Shapley Value Attribution
+
+```python
+# With custom coalition size
+mta.shapley(max_coalition_size=3, normalize=True)
+```
+
+### Logistic Regression Ensemble
+
+```python
+# Custom sampling and iteration parameters
+mta.logistic_regression(
+    test_size=0.25,
+    sample_rows=0.5,
+    sample_features=0.5,
+    n_iterations=1000,
+    normalize=True
+)
+```
+
+### Export Results
+
+```python
+# Compare all models
+results_df = mta.compare_models()
+
+# Export to various formats
+mta.export_results("attribution_results.csv", format="csv")
+mta.export_results("attribution_results.json", format="json")
+mta.export_results("attribution_results.xlsx", format="excel")
+```
+
+## 📈 Example: Complete Analysis Pipeline
+
+```python
+from mta import MTA
+import pandas as pd
+
+# Load data
+mta = MTA(
+    data="customer_journeys.csv",
+    allow_loops=False,  # Remove consecutive duplicate channels
+    add_timepoints=True  # Auto-generate timestamps if missing
+)
+
+# Run all heuristic models
+(mta
+    .first_touch()
+    .last_touch()
+    .linear(share="proportional")
+    .position_based(first_weight=40, last_weight=40)
+    .time_decay(count_direction="right"))
+
+# Run algorithmic models
+(mta
+    .markov(sim=False)
+    .shapley(max_coalition_size=2)
+    .shao()
+    .logistic_regression(n_iterations=2000)
+    .additive_hazard(epochs=20))
+
+# Display and export results
+results = mta.compare_models()
+mta.export_results("full_attribution_analysis.csv")
+
+# Access specific model results
+print(f"Markov Attribution: {mta.attribution['markov']}")
+print(f"Shapley Attribution: {mta.attribution['shapley']}")
+```
+
+## 🔬 Model Comparison
+
+| Model               | Type             | Strengths                | Use Case                     |
+| ------------------- | ---------------- | ------------------------ | ---------------------------- |
+| First/Last Touch    | Heuristic        | Simple, fast             | Quick baseline               |
+| Linear              | Heuristic        | Fair, interpretable      | Equal value assumption       |
+| Position-Based      | Heuristic        | Balances first/last      | Awareness + conversion focus |
+| Time Decay          | Heuristic        | Recency-weighted         | When recent matters more     |
+| Markov Chain        | Algorithmic      | Considers path structure | Sequential dependency        |
+| Shapley Value       | Algorithmic      | Game-theoretic fairness  | Complex interactions         |
+| Logistic Regression | Machine Learning | Data-driven              | Large datasets               |
+| Additive Hazard     | Statistical      | Time-to-event modeling   | Survival analysis fans       |
+
+## 🛠️ Requirements
+
+- Python >= 3.8
+- pandas >= 1.3.0
+- numpy >= 1.20.0
+- scikit-learn >= 0.24.0
+- arrow >= 1.0.0
+
+## 📝 Citation
+
+If you use this library in your research, please cite:
+
+```bibtex
+@software{mta2024,
+  author = {Igor Korostil},
+  title = {MTA: Multi-Touch Attribution Library},
+  year = {2024},
+  url = {https://github.com/eeghor/mta}
+}
+```
+
+## 📚 References
+
+This library implements models and techniques from the following research papers:
+
+1. **Nisar, T. M., & Yeung, M. (2015)**  
+   _Purchase Conversions and Attribution Modeling in Online Advertising: An Empirical Investigation_  
+   [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2612997)
+
+2. **Shao, X., & Li, L. (2011)**  
+   _Data-driven Multi-touch Attribution Models_  
+   Proceedings of the 17th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining  
+   [PDF](https://dl.acm.org/doi/10.1145/2020408.2020453)
+
+3. **Dalessandro, B., Perlich, C., Stitelman, O., & Provost, F. (2012)**  
+   _Causally Motivated Attribution for Online Advertising_  
+   Proceedings of the Sixth International Workshop on Data Mining for Online Advertising  
+   [PDF](https://dl.acm.org/doi/10.1145/2351356.2351363)
+
+4. **Cano-Berlanga, S., Giménez-Gómez, J. M., & Vilella, C. (2017)**  
+   _Attribution Models and the Cooperative Game Theory_  
+   Expert Systems with Applications, 87, 277-286  
+   [PDF](https://www.sciencedirect.com/science/article/abs/pii/S0957417417304505)
+
+5. **Ren, K., Fang, Y., Zhang, W., Liu, S., Li, J., Zhang, Y., Yu, Y., & Wang, J. (2018)**  
+   _Learning Multi-touch Conversion Attribution with Dual-attention Mechanisms for Online Advertising_  
+   Proceedings of the 27th ACM International Conference on Information and Knowledge Management  
+   [PDF](https://dl.acm.org/doi/10.1145/3269206.3271676)
+
+6. **Zhang, Y., Wei, Y., & Ren, J. (2014)**  
+   _Multi-Touch Attribution in Online Advertising with Survival Theory_  
+   2014 IEEE International Conference on Data Mining  
+   [PDF](https://ieeexplore.ieee.org/document/7023387)
+
+7. **Geyik, S. C., Saxena, A., & Dasdan, A. (2014)**  
+   _Multi-Touch Attribution Based Budget Allocation in Online Advertising_  
+   Proceedings of the 8th International Workshop on Data Mining for Online Advertising  
+   [PDF](https://dl.acm.org/doi/10.1145/2648584.2648586)
+
+### Model-to-Paper Mapping
+
+- **Linear & Position-Based**: Baseline models referenced across multiple papers
+- **Time Decay**: Nisar & Yeung (2015), Zhang et al. (2014)
+- **Markov Chain**: Shao & Li (2011), Dalessandro et al. (2012)
+- **Shapley Value**: Cano-Berlanga et al. (2017)
+- **Logistic Regression**: Dalessandro et al. (2012), Ren et al. (2018)
+- **Additive Hazard**: Zhang et al. (2014)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by various academic papers on marketing attribution
+- Built with pandas, numpy, and scikit-learn
+- Special thanks to the open-source community
+
+## 📧 Contact
+
+Igor Korostil - eeghor@gmail.com
+
+Project Link: [https://github.com/eeghor/mta](https://github.com/eeghor/mta)
+
+## 🐛 Known Issues
+
+- Shapley value computation can be slow for large numbers of channels
+- Additive hazard model requires evenly-spaced time points for best results

mta-0.0.8.dist-info/RECORD

@@ -0,0 +1,7 @@
+mta/__init__.py,sha256=KuXyr5J0rZ1snuaB2kxabi7JIUBcwVeTYCN_d_JomVw,20
+mta/mta.py,sha256=dIfwLBiJbxQ4CfdZod99C1MUsuzsflNJ2JYrrNTAzK0,30740
+mta/data/data.csv.gz,sha256=zN9K0IRC4NAyNMbFAlxoKCgBG_1qtynxG7g3um_ctKg,82453
+mta-0.0.8.dist-info/METADATA,sha256=7shXR-jjNI4MTvui9YvZV8zLNQYOMpnr5sdKj2kWxV4,10962
+mta-0.0.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mta-0.0.8.dist-info/top_level.txt,sha256=yGDzRyCpTtg9Np96GTL1VIgYL8Oya3v2G07vFR8SxAk,4
+mta-0.0.8.dist-info/RECORD,,

mta-0.0.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mta-0.0.8.dist-info/top_level.txt

@@ -0,0 +1 @@
+mta