Comprehensive Guide to ConversionFlow

This tutorial provides a comprehensive, step-by-step guide to using the ConversionFlow library. We will walk through the entire process, from setting up your environment to running the analysis and interpreting the results.

1. Introduction

What is ConversionFlow?

ConversionFlow is a powerful library for analyzing and optimizing customer conversion journeys. It uses Bayesian Networks to model the probabilities of users moving from one touchpoint to another, allowing you to identify the key drivers of conversion and make data-driven decisions to improve your marketing and sales funnels.

What You Will Learn

By the end of this tutorial, you will be able to:

Set up your environment to use ConversionFlow.
Run the two-stage pipeline (Estimation and Optimization).
Understand the structure of the Bayesian Network model.
Interpret the results of the analysis.
Customize the model for your own use cases.

2. Setup

Prerequisites

Before you begin, make sure you have the following:

Python 3.9 or higher.
Access to the project’s private GitHub repository.
A GitHub Personal Access Token (PAT) with repository access rights.

Installation

Clone the Repository:

Open your terminal and clone the repository using your GitHub PAT:

git clone https://YOUR_USERNAME:YOUR_PAT@github.com/tandpds/ConversionFlow.git
cd ConversionFlow

Create a Virtual Environment:

It is highly recommended to use a virtual environment to manage your dependencies.
```
python -m venv .venv
source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate
```
Install Dependencies:

Install the required Python packages using the requirements.txt file:
```
pip install -r requirements.txt
```
Install the Package:

Install the ConversionFlow package in editable mode. This allows you to make changes to the source code and have them immediately reflected in your environment.
```
pip install -e .
```

3. Running the Pipeline

Now that you have set up your environment, let’s run the ConversionFlow pipeline. The pipeline is divided into two main stages:

Stage 1: Estimation: In this stage, we use Bayesian inference to estimate the parameters of our conversion model.
Stage 2: Optimization: In this stage, we use the estimated parameters to optimize the allocation of a marketing budget.

Stage 1: Running the Estimation

We will start by running the estimation stage with the sample data. This will give us a feel for how the model works and what the output looks like.

Run the Pipeline:

Execute the following command in your terminal from the root of the project directory:
```
python src/orchestration/run_pipeline.py --config assets/config.yml --data input_data/conversion_flow_sample.db --output output_tutorial
```
This command tells the script to:
- --config: Use the configuration file at assets/config.yml.
- --data: Use the sample database at input_data/conversion_flow_sample.db.
- --output: Save the output to a new directory named output_tutorial.
Review the Output:

After the script finishes running, you will find a new directory named output_tutorial with the following contents:
- daily_conversion_rates.csv: A CSV file with daily conversion rates.
- model_analysis.txt: A text file with a detailed analysis of the model results.
- optimization_analysis.txt: A text file with an analysis of the optimization results.
- ..._parameter_summary.csv: A CSV file with a summary of the model parameters.
- Various plots and diagrams (.png files).

Understanding the Estimation Output

The output of the estimation stage provides a wealth of information about your conversion funnel. Here are some of the key things to look at:

Parameter Summary: The ..._parameter_summary.csv file contains the estimated values for the model’s parameters (the alpha and beta coefficients). These values tell you how much each touchpoint influences the others.
Posterior Effects Plot: The posterior_effects.png plot visualizes the strength and uncertainty of the relationships between the different touchpoints.
Conversion Funnel Plot: The conversion_funnel.png plot shows the conversion rates at each stage of the funnel.

4. Interpreting the Results

The estimation stage generates a rich set of outputs that provide deep insights into your customer journey. Let’s break down how to interpret the most important pieces.

The Parameter Summary (`..._parameter_summary.csv`)

This file is the heart of the model’s findings. It contains the posterior distributions for each parameter in the model.

Parameter	Mean	SD	HDI 3%	HDI 97%	…
`alpha_download`	-1.5	0.1	-1.7	-1.3	…
`beta_session_start_to_download`	2.5	0.2	2.1	2.9	…

alpha_... (Intercepts): The alpha parameters represent the baseline probability of a node being True (i.e., an event occurring) when all parent nodes are False. The value is in log-odds space. A more negative value means a lower baseline probability.
beta_... (Coefficients): The beta parameters represent the influence of a parent node on a child node. A positive beta means that if the parent event occurs, the probability of the child event also occurring increases. The magnitude of the beta indicates the strength of this influence.

Key Visualizations

Posterior Effects Plot (posterior_effects.png): This plot provides a visual summary of the beta coefficients. It shows the distribution of each effect, allowing you to see both the magnitude of the effect and the uncertainty around it. Effects whose distributions are far from zero are considered statistically significant.
Conversion Funnel Plot (conversion_funnel.png): This plot provides a high-level overview of the conversion rates at each stage of the customer journey. It’s a great way to quickly identify the biggest drop-off points in your funnel.

5. Stage 2: Running the Optimization

The second stage of the pipeline uses the insights from the estimation stage to recommend an optimal budget allocation across different marketing touchpoints.

How It Works

The optimizer takes the learned beta coefficients from the estimation stage (which represent the influence of each touchpoint) and uses a genetic algorithm to find the budget allocation that maximizes the total expected conversion value, subject to a total budget constraint.

Running the Optimization

Run the Pipeline with a Budget:

To run the optimization stage, you simply need to add the --budget argument to the command line.
```
python src/orchestration/run_pipeline.py --config assets/config.yml --data input_data/conversion_flow_sample.db --output output_tutorial --budget 100000
```
This command will first run the estimation stage (if the results are not already present in the output directory) and then use those results to run the optimization with a total budget of 100,000.
Review the Optimization Output:

The optimization stage adds a key file to the output directory:
- optimal_budget_allocation.csv: This file contains the recommended budget allocation for each marketing touchpoint.

Understanding the Optimization Output

The optimal_budget_allocation.csv file provides a clear, actionable recommendation for your marketing spend.

Node	Allocation
`download`	15000.0
`dealer_search`	25000.0
`car_configuration`	60000.0

This output suggests how to distribute your budget to maximize conversions, based on the model’s understanding of the customer journey.

6. Conclusion

Congratulations! You have now run the entire ConversionFlow pipeline. You have estimated a Bayesian Network model of your customer journey and used it to generate an optimized marketing budget allocation.

From here, you can explore the other sections of the documentation to learn how to customize the model, interpret the results in more detail, and extend the library for your own needs.