monkstools 0.16
Tools for the Monks advertising platform

---

# 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:

```bash
pip install monkstools
```

### 2. **Initialize the Framework**

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

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

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

### 4. **Visualize ROI Matrix**

Run the following to compute and showcase the ROI matrix:

```python
ROICalculator.display_roi_matrix(roi_calculator, products, platforms)
```

### 5. **Debugging**

For detailed insights or debugging, enable verbose mode:

```python
# 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:

```python
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.*