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:

pip install td-ml-mta

Dependencies

The attribution models come from the DP6 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:

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.

from td_ml_mta import run_markov_model, run_shapley_model

run_markov_model()
run_shapley_model()

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