Metadata-Version: 2.4
Name: td_ml_mta
Version: 0.0.16
Summary: Multi-Touch Attribution using Shapley and Markov chains 
Project-URL: Homepage, https://github.com/treasure-data-ps/td_ml_libraries/tree/main/td_ml_mta
Project-URL: Bug Tracker, https://github.com/treasure-data-ps/td_ml_libraries/tree/main/td_ml_mta
Author-email: Gurbaksh Sharma <gurumail10@gmail.com>
License: Copyright © 2022 Treasure Data, Inc. (or its affiliates). All rights reserved
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: marketing-attribution-models==2.1.0
Requires-Dist: numpy
Requires-Dist: pandas>=2.0.0
Requires-Dist: polars<2.0,>=1.0
Requires-Dist: pytd
Description-Content-Type: text/markdown

# td-ml-mta

# Treasure Data Multi-Touch Attribution (TD-ML-MTA) Package

Welcome to the TD-ML-MTA package, designed for Multi-Touch Attribution (MTA) within the Treasure Data environment. This Python package uses Shapley and Markov models to help businesses understand the impact of different marketing touchpoints on conversions or other key goals.

## Overview

Multi-Touch Attribution (MTA) is a critical aspect of marketing analytics, enabling companies to analyze how various marketing touchpoints contribute to customer conversions or other desired outcomes. The TD-ML-MTA package integrates Shapley values and the Markov model to provide a comprehensive solution for MTA within Treasure Data.

With TD-ML-MTA, you can determine the individual and collective contributions of different touchpoints, considering the temporal aspect of customer journeys and leveraging the power of Treasure Data for data storage and analysis.

## Installation

You can install the TD-ML-MTA package using pip:

```bash
pip install td-ml-mta
```

## Dependencies

The attribution models come from the DP6 [`marketing_attribution_models`](https://pypi.org/project/marketing-attribution-models/) (MAM) library.
MAM 2.x was a full rewrite (import path moved to `mam`, new constructor, new `run_*` API), so this package **pins the exact MAM release it is written against**:

| td_ml_mta | marketing_attribution_models |
|-----------|------------------------------|
| >= 0.0.16 | `==2.1.0` (import name `mam`) |
| <= 0.0.15 | 1.0.x (unpinned; breaks with 2.x) |

The pin is declared in `pyproject.toml`, so `pip install td-ml-mta` resolves the right version. Polars is additionally capped below 2.0 because MAM 2.1.0 relies on behaviour that Polars 2.0 changes. As a safety net for bare Treasure Data containers, the package also checks the installed MAM version at import time and installs `marketing_attribution_models==2.1.0` if it is missing or different. To move to a newer MAM release, bump `MAM_VERSION` in `td_ml_mta/_mam.py` and the pin in `pyproject.toml`, then re-run `pytest tests` (golden outputs from the previous stack live in `tests/data`).

## Usage

Both entry points are configured through environment variables (unchanged across releases) and read/write fixed tables in the sink database.

```python
from td_ml_mta import run_markov_model, run_shapley_model

run_markov_model()
run_shapley_model()
```

| Environment variable | Description |
|----------------------|-------------|
| `TD_API_KEY`, `TD_API_SERVER` | Treasure Data credentials / endpoint |
| `SINK_DB` | Database holding the input tables and receiving the output tables |
| `user_id_col` | User id column |
| `time_col` | Timestamp column (string, datetime or Unix epoch) |
| `channel_colname` | Channel column (Shapley) / journey string column `"A > B > C"` (Markov) |
| `conversion_col_name` | Conversion flag column (bool, 0/1 or `'true'`/`'false'`) |
| `save_tables_in_td` | `yes` to write the output tables |
| `markov_include_non_converting_journeys` | Optional, default `no`. See *Markov weighting* below |

| Model | Input table | Output tables (columns) |
|-------|-------------|-------------------------|
| Markov | `mta_journey_agg_markov` (one row per journey) | `mta_markov_transition` (one column per channel + `(conversion)`, `channels`)<br>`mta_markov_attribution` (`channels`, `attribution_markov_algorithmic`, `removal_effect`) |
| Shapley | `mta_shapely_input_table` (one row per touchpoint) | `mta_shapley_attribution` (`channels`, `variable`, `value`, `day`) |

The Shapley table contains the ordered Shapley model for coalition sizes 0-3 (`day` 0-3, where size 0 means all unique channels of the journey) and the unordered size-4 model (`day` 4).

The underlying functions are also available for notebooks and testing without Treasure Data I/O: `build_markov_tables(data, channel_colname, conversion_col_name)` and `build_shapley_table(data, user_id_col, time_col, channel_colname, conversion_col_name)`.

### Upgrading deployed workflows

- Workflows that run `pip install td-ml-mta` without a version pick up 0.0.16 automatically. Nothing in the workflow changes: same environment variables, same input tables, same output tables and columns, same entry points (`run_markov_model()` / `run_shapley_model()`, no arguments, return `None`), also importable from `td_ml_mta.markov` / `td_ml_mta.shapley`.
- Workflows pinned to `td-ml-mta==0.0.15` (or older) must move to `>=0.0.16`; those releases install MAM unpinned and no longer work.
- Workflows that also run their own `pip install marketing_attribution_models` can drop that line. If it stays, pip still resolves the pinned 2.1.0 through this package's metadata and the import-time check enforces it.
- Python 3.8 or newer is required (MAM 2.x needs pandas 2 and polars 1); installation and the test-suite are verified on CPython 3.8 through 3.12.

### Markov weighting

MAM 2.x builds the transition matrix from every journey, the standard removal-effect formulation. MAM 1.x (and therefore td_ml_mta <= 0.0.15) used the conversion value (1 or 0) as the transition frequency, so non-converting journeys never entered the chain. To keep existing dashboards stable, the default reproduces the historical numbers exactly. Set `markov_include_non_converting_journeys=yes` (or `count_non_converting_journeys=True` on `build_markov_tables`) to use the full MAM 2.x model; the output schema is the same, the values differ.

## Changelog

### 0.0.16
- Migrated to `marketing_attribution_models` 2.1.0 (`mam` package) and pinned that exact version; previous releases installed MAM unpinned at import time and broke when 2.x was published.
- Configuration, input tables, output tables and output columns are unchanged. Markov and Shapley results are numerically identical to 0.0.15 (verified against MAM 1.0.10).
- Conversion flags, timestamps and journey columns are normalised before modelling (bool / 0-1 / text flags, string / datetime / epoch timestamps, string / array journeys).
- New: `build_markov_tables` and `build_shapley_table` pure functions, `__version__`, optional `markov_include_non_converting_journeys` switch.

Thank you for choosing TD-ML-MTA for your Treasure Data Multi-Touch Attribution needs! 📊🚀

`Copyright © 2022 Treasure Data, Inc. (or its affiliates). All rights reserved`
