# 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

1.  **Clone the Repository**:

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

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

2.  **Create a Virtual Environment**:

    It is highly recommended to use a virtual environment to manage your dependencies.

    ```bash
    python -m venv .venv
    source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate
    ```

3.  **Install Dependencies**:

    Install the required Python packages using the `requirements.txt` file:

    ```bash
    pip install -r requirements.txt
    ```

4.  **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.

    ```bash
    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:

1.  **Stage 1: Estimation**: In this stage, we use Bayesian inference to estimate the parameters of our conversion model.
2.  **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.

1.  **Run the Pipeline**:

    Execute the following command in your terminal from the root of the project directory:

    ```bash
    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`.

2.  **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

1.  **Run the Pipeline with a Budget**:

    To run the optimization stage, you simply need to add the `--budget` argument to the command line.

    ```bash
    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.

2.  **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.