monkstools: Advertising Delivery ROI Analysis Framework

monkstools is a Python module crafted for a streamlined analysis and visualization of advertising Return on Investment (ROI) across different platforms. This guide offers a concise and clear walkthrough to help you utilize its features effectively.

Overview

• What is it?
  A template Python framework to analyze and visualize the ROI for product advertising across multiple platforms.

• Who is it for?
  Programmers, data analysts, and professionals aiming to evaluate advertising ROI.

• Usage Context:
  While designed for ideation and collaboration, remember that real-world applications would require extensive model training and real data.

Getting Started

1. Installation

Before using monkstools, ensure you have it installed. If not, you can do so using pip:

pip install monkstools

2. Initialize the Framework

Once installed, initiate the ROICalculator to automatically set up both the ProductPreference and TransmissionCost classes.

from monkstools.roi_calculator import ROICalculator  

preference_file = 'path_to_preference_file.csv'
cost_file = 'path_to_cost_file.csv'
roi_calculator = ROICalculator(preference_file, cost_file)

3. Define Products & Platforms

Specify the products and platforms you wish to analyze:

products = ['Example Product 1', ...]
platforms = ['Example Platform 1', ...]

4. Visualize ROI Matrix

Run the following to compute and showcase the ROI matrix:

ROICalculator.display_roi_matrix(roi_calculator, products, platforms)

5. Debugging

For detailed insights or debugging, enable verbose mode:

# For instance:
roi_calculator.calculate(product_name='Example Product 1', platform_name='Example Platform 1', verbose=True)

Hands-On Example

To provide a clearer understanding, here's a complete example using the framework:

import pkg_resources
import matplotlib.pyplot as plt
from monkstools.roi_calculator import ROICalculator  

def test_display_roi_matrix():

    # Specify the paths to your data files
    preference_file = pkg_resources.resource_filename('monkstools', 'd4_data_map_product_costomerType.csv')
    cost_file = pkg_resources.resource_filename('monkstools', 'd3_data_map_delivery_cost_media.csv')

    # Initialize the calculator with the provided data
    roi_calculator = ROICalculator(preference_file, cost_file)

    # Define the products and platforms for analysis
    products = [
        'Toyota Corolla', 'Toyota RAV4', 'Toyota Camry', 'Toyota Land Cruiser', 'Toyota Hilux', 
        'Toyota Prius', 'Toyota Tacoma', 'Toyota Highlander', 'Toyota Sienna', 'Toyota 4Runner'
    ]
    platforms = [
        'Youtube', 'Facebook', 'WhatsApp', 'Instagram', 'WeChat', 'TikTok', 'QQ', 'Weibo', 'Twitter', 
        'LinkedIn', 'Snapchat', 'Pinterest', 'Reddit', 'Telegram', 'LINE', 'Viber', 'IMO', 'Zalo', 'VK', 'Odnoklassniki'
    ]

    # Display the ROI matrix
    roi_calculator.display_roi_matrix(products, platforms) 

    # Post-execution: Verify the chart manually or check the "ROI_Comparison.png" file
    # Optionally, automate assertions based on expected outcomes

if __name__ == "__main__":
    test_display_roi_matrix()
    print("Test executed. Please verify the output chart.")

Run the above script to visualize the ROI across various platforms for the specified products. Ensure you adjust the paths to your data files accordingly.

Documentation updated and compiled by Xiaowen Kang, 2023.8.24.