Google Ads ROAS & Income Predictor

DH Marketing Consultants — Machine Learning Decision Support System for Digital Advertising

Executive Summary

Google Ads ROAS & Income Predictor is a complete, production-ready Decision Support System (DSS) developed as a Master's Thesis in Data Science with AI (BIG School, 2025).

The system predicts ROAS and future revenue at segment level (Country × Channel × Device) and transforms these predictions into actionable budget allocation recommendations with risk quantification and business-friendly explainability.

Value for technical profiles:
End-to-end rigorous pipeline with strict temporal validation, no data leakage, multi-model comparison (LightGBM selected over XGBoost, Random Forest and Linear Regression), post-prediction calibration, and drift detection per segment and date as a reliability indicator.

Value for business / marketing profiles:
An intuitive, fully dynamic Streamlit interface that allows uploading historical and forecast data, viewing realistic predictions, receiving automatic SHAP insights in plain business language, optimizing budgets automatically or manually, and downloading executive reports in PDF and Excel. The drift detection system warns users when predictions should be treated with caution due to market volatility.

Current status: Fully functional, includes test datasets, Advanced Settings with one-click reset, and is production-ready.

Key achievement: On the 8-month test period (Apr–Dec 2024), the system predicted €1,012,516 in revenue against €1,010,303 actual — a deviation of just 0.22%, equivalent to 99.78% revenue precision. Weekly segment-level predictions are noisier by nature, but at the aggregate level the system is highly reliable for monthly and quarterly budget planning.

Quick Start

pip install -r requirements.txt
streamlit run app.py

Open: http://localhost:8501

Test datasets included in data/test/ so anyone can try the system immediately.

Business & Presentation Materials

The docs/ folder includes ready-to-use presentation decks for stakeholder communication:

Document	Description
`DH_Income_predictor_business_deck_pptx.pdf`	Business-oriented deck — value proposition, use cases, and ROI framing for clients and decision-makers
`DH_Income_predictor_enablement_deck_pptx.pdf`	Enablement deck — onboarding guide and feature walkthrough for end users and internal teams
`DH_brand_style_guide.pdf`	DH Marketing Consultants brand guidelines

Both decks are in PDF format and can be shared directly with non-technical stakeholders without requiring access to the codebase.

Project Context

Academic Framework

Field	Details
Program	Master's in Data Science with AI (2nd Edition)
Institution	BIG School
Duration	May - November 2025
Website	https://thebigschool.com/master-data-science-con-ia/
Discipline	Applied Machine Learning, Time Series Forecasting, Business Analytics
License	Academic Use Only

Business Context

Digital advertising represents a significant investment for modern businesses, yet budget allocation decisions often rely on intuition rather than data-driven insights. This project addresses the critical need for:

Predictive accuracy: Forecasting ROAS before spending occurs
Explainability: Understanding which factors drive performance
Actionability: Converting predictions into concrete budget recommendations
Accessibility: Making ML insights available to non-technical business users

Research Problem

Challenge Statement

ROAS at the weekly segment level is inherently noisy and difficult to predict due to:

High variance in small segments
Multiple interacting factors (seasonality, competition, market conditions)
Non-linear relationships between investment and return
Risk of temporal leakage and overfitting in model development

Research Questions

Can we predict segment-level ROAS with sufficient accuracy for strategic planning?
Which features genuinely drive advertising performance without introducing data leakage?
How can we quantify prediction uncertainty and incorporate it into recommendations?
Can we make ML insights accessible to business users without technical expertise?

Success Criteria

Technical Metrics:

MAE (ROAS prediction) < 0.3
Aggregate revenue prediction error < 1%
Train/test generalization gap < 0.15
No temporal leakage in feature engineering

Business Metrics:

Actionable recommendations per segment
Risk-adjusted ROI optimization
User adoption by non-technical stakeholders
Reduction in suboptimal budget allocation

Methodology

The project follows a rigorous, iterative data science methodology designed to address the challenges of time series forecasting in advertising:

1. Data Leakage Prevention

Critical Design Decision: Eliminate all variables that cannot be known before making investment decisions.

Variables Removed:

Clicks, impressions, views (only known after spending)
Direct conversions and conversion metrics
CTR, CPC calculated from current period
Any revenue-derived metrics from the same period

Variables Retained:

Historical lags (1-3 periods)
Moving averages (3-6 months)
Year-over-year comparisons
Investment amount (the decision variable)
Segment identifiers (country, channel, device)
Calendar and seasonality features

Validation: Temporal split with strict train/test boundaries (train ≤2023, test 2024).

2. Temporal Feature Engineering

Temporal Features:

Lags: ROAS, revenue, and investment from previous 1-3 periods
Moving Averages: 3-month and 6-month rolling windows for stability detection
Year-over-Year: Same period previous year for annual patterns

Calendar Features:

Commercial Events: Black Friday, Cyber Monday, Christmas, Hot Sale, Valentine's Day
National Holidays: Country-specific using holidays library
Seasonal Periods: Summer sales, back-to-school, end-of-year
Religious Events: Easter/Semana Santa with variable dates

Temporal Validation:

TimeSeriesSplit for cross-validation
Chronological train/test split (no random shuffling)
Walk-forward validation for production deployment

3. Segmentation Strategy

Granularity: Weekly aggregation by segment (Country × Channel × Device)

Benefits:

Reduces daily noise while maintaining strategic relevance
Aligns with typical marketing planning cycles
Sufficient data points per segment for stable predictions
Matches business decision-making timeframes

Segment Encoding:

One-hot encoding for country, channel, device
Enables model to learn segment-specific patterns
Captures structural differences in performance

4. Modeling Approach

Primary Algorithm: LightGBM (Gradient Boosting, selected model)

Selection Rationale (from four-model comparison):

Best Test MAE: 0.655 vs XGBoost 0.756, Random Forest 0.758, Linear Regression 0.803
Best Test R²: 0.530 — explains 53% of weekly ROAS variance
Strong 5-fold CV performance: MAE 0.765 ± 0.059
Efficient training on tabular time series data

Hyperparameter Optimisation:

RandomizedSearchCV with TimeSeriesSplit (50 candidates, 3 folds)
Best CV MAE: 0.855
Parameters: max_depth=6, learning_rate=0.01, n_estimators=100, min_child_weight=10
Regularisation (reg_alpha=5, reg_lambda=0.1) to control overfitting

Model Validation:

Training Set:  2021-01-25 → 2024-09-09  (1,628 observations, 90.6%)
Test Set:      2024-09-16 → 2024-09-23  (28 observations, 1.6%)
Holdout Set:   2024-09-30 → 2024-12-30  (140 observations, 7.8%)
Validation:    5-fold TimeSeriesSplit

5. Interpretability & Explainability

SHAP (SHapley Additive exPlanations):

Global feature importance across all predictions
Per-instance explanations for each segment forecast
Identification of performance drivers (positive and negative)

Business Translation:

Automatic generation of bullet-point insights
"Top 3 positive drivers: high investment, Black Friday, Search channel"
"Top 3 negative drivers: high CPC lag, Display in Mexico, local holidays"

Value: Builds trust with business users and enables strategic learning.

6. Risk-Adjusted Recommendations

Beyond Point Predictions: The system quantifies uncertainty and incorporates it into recommendations.

Risk Metrics:

Prediction variance across validation folds
Historical ROAS volatility by segment
Investment concentration risk

Actionable Labels:

"Scale Up": High predicted ROAS, low risk
"Monitor": Medium ROAS or high uncertainty
"Pause": Low predicted ROAS or excessive risk
"Reallocate": Better opportunities exist elsewhere

Project Evolution

This section documents the iterative development process, demonstrating the methodological rigor applied throughout the thesis.

Phase 1: Initial Prototype (v1.x)

Language: Spanish
Target: Gross revenue prediction
Status: Proof of concept

Challenges Identified:

Severe Overfitting: R² train ~0.95, R² test ~0.45
Volume variables (clicks, impressions) dominated predictions
Model memorized training data rather than learning generalizable patterns
Temporal Leakage: Random train/test split violated temporal order
Untreated Collinearity: Highly correlated features caused instability
Daily Granularity: Excessive noise in target variable
Poor Metrics: MAPE ~30-40%, unusable for business planning

Lessons Learned:

Need for stricter feature selection
Importance of temporal validation
Target variable must align with business decisions

Phase 2: Technical Refinement (v2.x - v3.x)

Major Changes:

Feature Elimination: Removed clicks, impressions, views, unique_revenue
Target Change: From total_revenue → ROAS (Revenue / Investment)
- More actionable metric
- Less biased by absolute scale
- Better aligned with strategic decision-making
Granularity Evolution: Daily → weekly/monthly by segment
Temporal Features: Added lags, moving averages, YoY comparisons
Calendar Variables: Commercial events and national holidays
Strict Validation: TimeSeriesSplit + chronological train/test split

Improvements:

R² test improved to ~0.60-0.70
MAE (ROAS) reduced to ~0.3-0.4
Train/test gap reduced from 0.50 to ~0.20
No evidence of temporal leakage

Remaining Challenges:

Model selection (XGBoost vs alternatives)
Fine-tuning hyperparameters
Explainability integration

Phase 3: Functional Maturity (v4.x)

Achieved Performance:

MAE (ROAS): ~0.20-0.30
Relative Revenue Error: ~10-15%
Aggregate Revenue Error: <0.5%
Train/Test Gap: <0.15
R²: ~0.13 (appropriate for noisy weekly ROAS)

Note on R²: Weekly ROAS is inherently volatile. An R² of 0.13 means the model explains 13% of weekly variance—sufficient for identifying structural patterns and estimating aggregates accurately.

New Capabilities:

Scenario Simulation: Compare investment strategies
- Example: Reallocate €10,000/week → +€36,000/year estimated gain
Sensitivity Analysis: "What if CPC increases 10%?"
Marginal Analysis: "What if I shift budget from Display to Search?"
Actionable Recommendations: Scale/Pause/Monitor labels per segment
Risk Quantification: Volatility scores and uncertainty intervals
Financial Projections: Expected revenue in euros, not just ROAS ratios

Production Readiness:

Serialized models with versioning (xgboost_v4_YYYYMMDD.pkl)
Reusable feature engineering pipeline
Automated input validation
Error handling and logging

Phase 4: Internationalization & Standardization

Translation to English:

All notebooks, comments, and documentation translated
Professional terminology standardized
Improved international evaluation potential

Documentation Enhancements:

Consistent Markdown tables across notebooks
Checklists per development phase
Executive ASCII summaries for quick scanning
File traceability with date suffixes
Comprehensive README files for each module

Code Quality:

Function decomposition and modularization
Type hints and docstrings
Pytest unit tests for critical functions
Git commit discipline with semantic versioning

Phase 5: Web Application - Production Deployment & Final Refinements (v4.x → vFinal)

The Transformation: From static Jupyter notebooks to a fully interactive, production-ready business tool.

Critical improvements delivered in the final iterations (February 2026):

Complete replacement of all hardcoded data with real, dynamic calculations and drift detection (R²) in both notebooks and the interface.
Definitive fix of the ROAS and investment gap caused by an overly short drop_duplicates key.
Fine-tuning of the model directly in the interface (prediction_engine.py) to produce realistic forecasts instead of overly conservative/low ROAS values (see "Documentación Técnica Calibración final ROAS en prediction_engine.py.txt").
Fully dynamic and functional Streamlit interface featuring:
- Real-time updating of model evaluation metrics and forecasts when uploading new historical or forecast data.
- Advanced Settings with one-click buttons to delete uploaded forecast data, delete uploaded historical data, and reset the model to its initial trained state.
- Heavy use of drift detection per segment and date as a key reliability indicator — especially important since the model was trained on stable periods.
- Budget optimizer with manual editing and Auto Optimize mode (redistributes 60% of budget from the 5 worst-performing segments to the 5 best-performing ones).
- Downloadable comprehensive PDF reports with insights and action points.
- Inclusion of ready-to-use test datasets in data/test/ for immediate testing and demonstrations.

Final status: Production-ready tool usable by both technical and non-technical stakeholders, with built-in safeguards (drift detection) that make predictions trustworthy in real-world conditions.

Phase 6: Final Refinements & vFinal Release (February 2026)


Last Updated	February 25, 2026
Version	vFinal
Status	Production Ready

Recent Updates (v4.2)

Critical Fixes:

Feature Engineering Completeness: Implemented all missing features expected by the model:
- investment_log: Logarithmic transformation of investment
- roas_lag_weighted: Weighted average of last 4 ROAS values
- investment_x_*: Complete interaction features (events, lags, segments)
Forecast Lag Correction: Improved lag selection logic for forecast predictions:
- Prioritizes most recent available data (e.g., December 2024 for January 2025 predictions)
- Falls back to equivalent period lags (year-1) when recent data unavailable
- Eliminates lag desynchronization issues in forecast scenarios

Previous Updates (v4.1)

Forced Proportional Mode: Option to disable economic adjustments when forecast data matches historical data
Enhanced Forecast Visualization: Improved revenue and ROAS display in forecast charts
Model Diagnostics: Comprehensive explanation of prediction differences from historical data
Improved Data Handling: Better preservation of prediction columns (expected_revenue, predicted_roas) throughout the data pipeline

Bug Fixes:

Fixed revenue calculation in forecast charts (Budget vs Revenue, Revenue vs ROAS)
Corrected forecast metrics display in Data Evolution and Performance by Segment tables
Improved color consistency for Forecast ROAS visualization
Resolved missing feature warnings that were causing default values (0) to be used

Model Improvement Plan

A comprehensive analysis has identified opportunities for model enhancement. See Plan_Mejora_Modelo_ROAS_REALISTA.md for detailed analysis and implementation roadmap.

Key Areas for Improvement:

Model overfitting reduction through constrained hyperparameters
Automated validation system with 7 comprehensive tests
Enhanced prediction engine with soft fallback mechanisms
Improved dashboard indicators for model quality assessment

Results & Performance

Model Selection

Four algorithms were evaluated under identical temporal validation conditions. LightGBM was selected as the production model based on the best balance of test performance and generalization:

Model	Test MAE	Test RMSE	Test R²	CV MAE (5-fold)	Overfitting Gap
Linear Regression (baseline)	0.803	1.030	0.157	—	~0
Random Forest	0.758	0.902	0.354	—	0.27
LightGBM ✓ Selected	0.655	0.769	0.530	0.765 ± 0.059	0.24
XGBoost (constrained v5)	0.756	0.951	0.282	0.795 ± 0.075	0.08

Selection rationale: LightGBM achieved the best Test MAE (0.655) and highest R² (0.530), explaining 53% of weekly ROAS variance. The XGBoost constrained model shows lower overfitting but at the cost of significantly worse predictive performance.

Model Performance Metrics (Selected Model: LightGBM)

Segment-Level Weekly ROAS Predictions

Metric	Train	Test	CV Mean (5-fold)	Interpretation
MAE	0.417	0.655	0.765 ± 0.059	Average ROAS error per segment-week
RMSE	0.507	0.769	0.940 ± 0.086	Penalises larger errors more heavily
R²	0.771	0.530	0.200 ± 0.142	CV R² reflects real-world variance
Overfitting Gap (R²)	—	0.241	—	Acceptable for this data size

Note on CV vs Test R²: The 5-fold temporal cross-validation (R² = 0.20) is the most honest estimate of real-world generalization, as it tests across multiple time windows. The test set R² (0.53) reflects a single holdout period which may be more favourable.

Aggregate Performance (Business Impact)

Metric	Value	Context
Revenue precision (aggregate)	99.78%	100% − 0.22% deviation — Apr–Dec 2024 test period
Revenue deviation (test period)	0.22%	Actual €1,010,303 vs predicted €1,012,516
Monthly ROAS MAE (investment-weighted)	0.107	Average monthly ROAS error
Monthly R² (Pearson)	0.311	Correlation between predicted and actual monthly ROAS
MAPE on revenue	19.1%	At segment level; aggregation eliminates most of this error
KS drift test (global)	p = 0.88	No distribution drift detected on test set
Segments with drift	22 of 48 (45.8%)	Segment-level — triggers dashboard warnings

Important methodological note: Monthly, quarterly, and yearly accuracy figures are based on a single aggregation period in the test set (R² = NaN, insufficient data points for reliable calculation). The 0.22% revenue deviation is the most reliable aggregate metric and the one with strongest business validity.

Performance by Timeframe

Timeframe	Reliability	Primary Metric	Use Case
Weekly (segment)	Volatile	CV MAE ≈ 0.77	Directional guidance, drift monitoring
Monthly (aggregate)	Solid	Revenue deviation ≈ 0.22%	Budget allocation planning
Quarterly (aggregate)	Solid	Revenue deviation ≈ 0.22%	Board-level reporting
Yearly (aggregate)	Solid	Revenue deviation ≈ 0.22%	Annual strategy

Key Finding: Noise vs Signal

Weekly segment-level ROAS is inherently noisy, but the model successfully:

Identifies which segments structurally outperform others
Estimates aggregate revenue outcomes with very high precision (0.22% deviation)
Detects investment saturation and diminishing returns via SHAP
Quantifies segment-level volatility for risk-adjusted recommendations

Business Translation: The model is not designed for precise weekly segment forecasting — it is designed for strategic resource allocation decisions, where aggregate accuracy is what matters.

Understanding Prediction Differences

Why predictions may differ from historical data:

The model applies realistic economic adjustments that may cause forecast predictions to differ from historical data, even when using identical input values:

Diminishing Returns: When investment exceeds historical median, ROAS is adjusted downward to reflect efficiency loss
Dynamic CPC/CPM: Higher investment → increased competition → higher costs per click/impression
Historical Lags: Uses most recent available historical data (e.g., December 2024 for January 2025 predictions) with fallback to equivalent period (year-1) when recent data unavailable
Calendar Events: Event detection may vary between years

Solution: Use "Forced Proportional Mode" in Forecast page when you want to replicate historical data exactly (disables economic adjustments).

Note: As of v4.2, the lag selection logic has been improved to prioritize recent data while maintaining consistency with historical patterns. This reduces prediction discrepancies when forecasting future periods.

Model Limitations & Considerations

Known Limitations

1. Weekly Granularity Variance

Issue: Weekly ROAS predictions show high variance at segment level (CV MAE ≈ 0.77) due to short-term market noise
Impact: Individual weekly forecasts may deviate significantly from actuals
Mitigation: Use monthly/quarterly aggregate revenue forecasts for planning decisions
Recommendation: Treat weekly predictions as directional signals, not precise targets

2. Test Set Size

Issue: The holdout test set contains 28 observations and a single monthly period — insufficient to calculate stable R² or multi-period aggregate accuracy
Impact: Aggregate accuracy metrics (monthly, quarterly, yearly) are based on limited data and should be interpreted cautiously
Recommendation: Validate against fresh data as it accumulates; retrain periodically

3. Data Requirements

Minimum Historical Data: Requires at least 12 months of historical data for reliable predictions
Segment Coverage: Predictions are less reliable for segments with <50 historical observations
Missing Segments: New country-channel-device combinations without historical data cannot be predicted
Solution: Uses median ROAS from similar segments as fallback

4. Temporal Scope

Training Period: Model trained on data from 2021 to early 2024
Test Period: Validated on Sep–Dec 2024 holdout data
Future Validity: Model performance may degrade if market conditions change significantly
Recommendation: Retrain model annually or when major market shifts occur

5. Feature Dependencies

Required Columns: Data must include specific columns (date, country, channel, device, investment)
Column Mapping: Excel files must use Spanish column names or match COLUMN_MAPPING in config.py
Missing Values: Cannot handle missing investment values (required for predictions)
Data Quality: Predictions degrade with incomplete or inconsistent historical data

6. Model Assumptions

Stationarity: Assumes historical patterns continue into the future
Non-linearity: LightGBM captures complex relationships but may miss extreme out-of-distribution scenarios
Independence: Assumes segments are relatively independent (no strong cross-segment effects)
Diminishing Returns: Model captures saturation effects via SHAP-informed calibration

7. Geographic Limitations

Supported Countries: Spain, México, Argentina, Colombia (hardcoded in VALID_VALUES)
Holiday Detection: Calendar events optimised for these specific markets
Adding New Countries: Requires code modification and retraining

8. Channel & Device Constraints

Supported Channels: Búsqueda (Search), Display, Video, Social
Supported Devices: Móvil (Mobile), Ordenador (Desktop), Tablet
New Channels/Devices: Cannot predict for channels/devices not present in training data

9. Computational Limitations

File Size: Large Excel files (>100MB) may cause slow processing
Memory Usage: Requires sufficient RAM for feature engineering (8GB minimum)
Processing Time: Initial data upload and feature engineering may take 1-5 minutes
Concurrent Users: Streamlit app designed for single-user sessions

9. Prediction Uncertainty

No Confidence Intervals: Model provides point predictions without uncertainty quantification
Risk Assessment: Risk labels are based on historical volatility, not prediction intervals
Extreme Events: Model may not capture black swan events or sudden market changes

10. Business Context Limitations

External Factors: Does not account for: competitor actions, economic recessions, product launches/discontinuations, brand reputation changes, regulatory changes
Creative Quality: Does not consider ad creative performance variations
Attribution: Assumes last-click attribution (Google Ads default)

When NOT to Use This Model

❌ Do NOT use for:

Real-time bidding decisions (requires sub-second predictions)
Very small budgets (<€100/week per segment)
New products/services without historical data
Crisis management (pandemics, natural disasters)
Regulatory compliance decisions
Legal or financial auditing

✅ DO use for:

Monthly/quarterly budget planning
Strategic resource allocation
Identifying high/low performing segments
Long-term investment strategy
Portfolio-level optimization

Model Maintenance Requirements

Regular Updates Needed:

Monthly: Upload new historical data to maintain prediction accuracy
Quarterly: Review model metrics and compare predictions vs actuals
Annually: Retrain model with updated data and validate performance
As Needed: Update when adding new countries, channels, or devices

Performance Monitoring:

Track aggregate revenue deviation over time (target: <5%)
Monitor CV MAE stability across retraining cycles
Alert if segment-level drift (KS test) exceeds 60% of segments
Review SHAP insights periodically for feature importance shifts

SHAP Explainability Results

Global Feature Importance (Top 10)

Investment Amount: Higher investment → higher revenue (with diminishing returns)
ROAS Lag (1 period): Recent performance predicts near-term future
Black Friday Indicator: Strong positive impact across segments
Search Channel: Structurally higher ROAS than Display/Video
CPC Lag (1 period): Higher costs reduce profitability
Country (Spain): Home market advantage
Desktop Device: Higher conversion rates than mobile
Moving Average ROAS (3 months): Stability indicator
Christmas Period: Seasonal uplift
Year-over-Year ROAS: Captures annual growth trends

Segment-Specific Insights

Example: Spain, Search, Desktop in Black Friday week

Predicted ROAS: 4.2
Top Positive Drivers: Black Friday (+1.1), Search channel (+0.8), High investment (+0.6)
Top Negative Drivers: High CPC lag (-0.3), Holiday overlap (-0.2)
Recommendation: Scale Up (High predicted ROAS, low risk)

Scenario Analysis Results

Example Optimization:

Current Strategy:

Spain: €20,000/week
Mexico: €15,000/week
USA: €15,000/week
Total: €50,000/week
Expected Revenue: €180,000
Expected ROAS: 3.6

Optimized Strategy:

Spain: €25,000/week (+€5,000)
Mexico: €10,000/week (-€5,000)
USA: €15,000/week (unchanged)
Total: €50,000/week
Expected Revenue: €195,000
Expected ROAS: 3.9
Estimated Uplift: +€15,000/week = +€780,000/year

Risk Assessment:

Spain reallocation: Low risk (stable high performer)
Mexico reduction: Medium risk (volatile segment)
Recommendation: Implement gradually over 4 weeks

System Architecture

Data Pipeline

Raw Google Ads Data (Excel)
           ↓
    Data Cleaning
    - Remove invalid rows
    - Standardize formats
    - Handle missing values
           ↓
Feature Engineering
    - Temporal features (lags, rolling averages)
    - Calendar variables (holidays, commercial events)
    - Segment encoding (one-hot: country, channel, device)
           ↓
    Feature Matrix
    (features_v4_YYYYMMDD.xlsx)
           ↓
    Model Training
    (LightGBM — selected model)
           ↓
    Trained Model
    (xgboost_vFinal_TFM_YYYYMMDD.pkl)
           ↓
    Prediction + Calibration
    (diminishing returns, drift detection)
           ↓
Forecast Output
(forecast_YYYYMMDD.xlsx)
           ↓
Streamlit Dashboard
(Interactive UI)

Model Persistence

Versioning Strategy:

Date-based suffixes (YYYYMMDD)
Automatic loading of most recent files
Backward compatibility checks

Serialization:

Model: xgboost_vFinal_TFM_YYYYMMDD.pkl
Feature columns: feature_list_weekly.json / feature_list_monthly.json
Baselines: segment_baselines_weekly.json / segment_baselines_monthly.json
Metrics: metrics_v4_YYYYMMDD.json

Web Application Architecture

Technology: Streamlit (Python web framework)

Structure:

app.py (main entry point)
├── pages/
│   ├── 1_data_status.py     (Data upload & model metrics)
│   ├── 2_forecast.py        (Dashboard & visualizations)
│   └── 3_budget.py          (Optimization engine)
├── utils/
│   ├── data_loader.py        (File handling)
│   ├── feature_engineering.py (Pipeline functions)
│   ├── model_utils.py        (Prediction & SHAP)
│   └── optimization.py       (Budget allocation)
└── config.py                 (Constants & settings)

State Management:

Streamlit session state for cross-page data
Cached data loading for performance
Persistent model in memory

Web Application Features

The dashboard is built with Streamlit and organised into three pages plus a global sidebar. All data flows dynamically — uploading new data immediately recalculates all metrics and charts without restarting the app.

Sidebar — Global Navigation & Model Health

Navigation between the three pages
Current Model Health panel: Real-time MAE, R² (Pearson), and drift indicator badges (green / orange / red) computed dynamically from loaded data
Advanced Settings (collapsible):
- 🗑️ Delete uploaded forecast data
- 🗑️ Delete uploaded historical data
- 🔄 Reset model to initial trained state (one-click)

Page 1: Data Status & Update

Purpose: Overview of what data is currently loaded and the model's current accuracy against it.

Section	What it shows
Data availability	Loaded files (historical, forecast), date ranges, record counts
Model evaluation metrics	MAE, RMSE, R² displayed with colour-coded labels (Good / Acceptable / Poor)
Drift detection summary	KS-test result per segment, global drift status, % segments with detected drift
Upload panel	Drag-and-drop upload for new historical data (`.xlsx`); auto-validates columns and formats

Key behaviour: Uploading new historical data triggers full re-processing — feature engineering, lag recalculation, baseline update — and immediately refreshes all metrics on the page.

Page 2: Forecast Dashboard & Explainability

Purpose: Explore ROAS and revenue predictions, filter by dimensions, and download AI-generated insights.

Filters available: Month, Country, Channel, Device (combinable)

KPI cards: Total predicted investment, total predicted revenue, weighted average ROAS, active segments

Visualisations:

Chart	Description
Budget vs Revenue	Bar chart comparing investment and predicted revenue by segment
ROAS by Segment	Colour-coded with Scale Up / Monitor / Pause labels
Revenue vs ROAS scatter	Identifies high-value, high-efficiency segments
Data Evolution	Time-series comparing historical actuals vs forecast trajectory
Performance by Segment table	Predicted ROAS, investment, revenue, drift status, and recommendation per segment

SHAP Explainability panel: Top 3 positive and top 3 negative drivers per segment, auto-generated in plain business language. Example: "Black Friday event (+1.1), Search channel (+0.8), high investment (+0.6) boosting ROAS; high CPC lag (−0.3) limiting performance."

Drift warning system: Segments with detected distribution drift display an ⚠️ badge.

Reports: One-click download of a complete PDF report containing all KPIs, SHAP explanations, and action points for the selected filter combination.

Page 3: Budget Optimizer

Purpose: Allocate a total budget across segments to maximise predicted ROAS.

Mode	Description
Auto Optimize	Redistributes 60% of budget from the 5 worst-performing segments to the 5 best-performing ones. One click.
Manual editing	Editable table — adjust investment per segment, see predicted revenue update in real time

Outputs per segment: Suggested investment, predicted ROAS, predicted revenue, recommendation label (Scale Up / Monitor / Pause / Reallocate), risk indicator

Risk indicators: Historical volatility score, investment concentration warning (>40% budget to a single segment)

Downloads: Budget plan as .xlsx with all metrics per segment

Installation & Usage

System Requirements

Minimum:

Python 3.9 or higher (verify with python --version)
8 GB RAM
2 GB free disk space
Windows 10+, macOS 10.14+, or Linux (Ubuntu 18.04+)
Modern web browser (Chrome, Firefox, Edge, Safari)

Recommended:

Python 3.10 or 3.11 (best compatibility)
16 GB RAM (for large datasets)
SSD for faster data loading
Dedicated GPU (optional, not required for XGBoost)

Software Dependencies:

All dependencies listed in requirements.txt
Excel reader (for .xlsx files): openpyxl included
No additional database or server software required

Installation Steps

1. Clone or Download the Repository

# If using Git
git clone https://github.com/yourusername/google-ads-roas-predictor.git
cd google-ads-roas-predictor

# Or download and extract the ZIP file

2. Create Virtual Environment (Recommended)

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Mac/Linux)
source venv/bin/activate

3. Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

Key Dependencies:

streamlit==1.28+ - Web application framework
xgboost==2.0+ - Machine learning model
pandas==2.0+ - Data manipulation
plotly==5.18+ - Interactive visualizations
shap==0.42+ - Model explainability
openpyxl==3.1+ - Excel file handling
holidays==0.35+ - Calendar features

4. Prepare Data Files

Required Directory Structure:

data/
├── raw/
│   └── google_ads_data_YYYYMMDD.xlsx    # Historical Google Ads data
├── processed/
│   └── features_v4_YYYYMMDD.xlsx        # Engineered features
└── forecast/
    └── forecast_YYYYMMDD.xlsx           # Model predictions

models/
└── xgboost_v4_YYYYMMDD.pkl              # Trained XGBoost model

results/
└── metrics_v4_YYYYMMDD.json             # Model evaluation metrics

File Naming Convention:

All files include date suffix: YYYYMMDD
Example: features_v4_20260115.xlsx, forecast_20260117.xlsx
System automatically loads the most recent file for each type

5. Run the Application

Option A — Double-Click Launch (Windows):

Double-click run_dashboard.bat. Browser opens automatically at http://localhost:8501.

Option B — Command Line:

# If streamlit is in PATH
streamlit run app.py

# If streamlit is not in PATH
python -m streamlit run app.py

Option C — Custom Port:

streamlit run app.py --server.port 8502

6. Access the Dashboard

After running the application:

Automatic Browser Opening: Streamlit will automatically open your default browser
Manual Access: If browser doesn't open automatically, navigate to: http://localhost:8501
Network Access (for remote access):

# Run with network access enabled
streamlit run app.py --server.address 0.0.0.0
# Then access from other devices: http://YOUR_IP:8501

First Launch Checklist:

✅ Verify all dependencies installed correctly
✅ Check that model files exist in models/ directory
✅ Ensure data files are in correct data/ subdirectories
✅ Browser should display the dashboard sidebar with navigation options

Usage Workflow

Typical Session:

Launch Application: Double-click or run from command line
Review Data Status (Page 1):
- Check current data availability
- Review model accuracy metrics
- Upload new Google Ads data if needed
Analyze Forecasts (Page 2):
- Apply filters (month, country, channel)
- Review KPIs and performance tables
- Read AI-generated insights
- Identify top/bottom performers
Optimize Budget (Page 3):
- Input total budget amount
- Run automatic optimization
- Make manual adjustments
- Download budget plan

Updating with New Data

Step-by-Step:

Export Google Ads Data:
- Include required columns (date, country, channel, device, investment, revenue, conversions)
- Save as Excel (.xlsx) format
- Follow naming convention: google_ads_data_YYYYMMDD.xlsx
Upload via Dashboard:
- Navigate to Page 1 (Data Status & Update)
- Drag and drop file or click upload button
- System automatically validates data
Automatic Processing:
- Data cleaning and standardization
- Feature engineering pipeline
- Model prediction generation
- New forecast file created
Review Updated Forecasts:
- Navigate to Page 2 (Forecast)
- New predictions displayed immediately
- Updated insights generated

Troubleshooting

Installation Issues

Issue: Streamlit command not found

# Solution: Use full module path
python -m streamlit run app.py

# Or verify installation
pip show streamlit
pip install --upgrade streamlit

Issue: ModuleNotFoundError (missing dependencies)

# Solution: Reinstall all dependencies
pip install --upgrade -r requirements.txt

# Verify key packages
python -c "import streamlit, pandas, xgboost, plotly; print('All OK')"

Issue: Permission denied errors (Windows)

# Solution: Run PowerShell/CMD as Administrator
# Or use: python -m streamlit run app.py

Runtime Issues

Issue: Port already in use (8501)

# Solution 1: Use different port
streamlit run app.py --server.port 8502
# Then access: http://localhost:8502

# Solution 2: Find and kill process using port 8501
# Windows:
netstat -ano | findstr :8501
taskkill /PID <PID> /F
# Mac/Linux:
lsof -ti:8501 | xargs kill

Issue: Browser doesn't open automatically

# Solution: Manually navigate to http://localhost:8501
# Or check Streamlit config:
# .streamlit/config.toml -> browser.gatherUsageStats = false

Issue: Application runs but shows "No data loaded"

# Solution: Check file paths and naming
# 1. Verify model files exist: models/xgboost_v4_*.pkl
# 2. Verify data files: data/processed/features_v4_*.xlsx
# 3. Check file naming convention (YYYYMMDD suffix)
# 4. Ensure files are in correct subdirectories

Data & Model Issues

Issue: File not found errors

# Solution: Check file naming and location
# Ensure YYYYMMDD suffix is correct (e.g., 20260115)
# Verify files are in correct subdirectories:
#   - models/xgboost_v4_YYYYMMDD.pkl
#   - data/processed/features_v4_YYYYMMDD.xlsx
#   - results/metrics_v4_YYYYMMDD.json

Issue: Model predictions fail

# Solution 1: Check feature compatibility
# Ensure new data has same structure as training data
# Verify all required columns are present

# Solution 2: Check model file integrity
python -c "import pickle; pickle.load(open('models/xgboost_v4_*.pkl', 'rb'))"

# Solution 3: Verify feature columns match
# Compare columns in new data vs features_v4_*.xlsx

Issue: Uploaded file validation fails

# Common causes:
# 1. Missing required columns (date, country, channel, device, investment)
# 2. Incorrect column names (must match COLUMN_MAPPING in config.py)
# 3. Invalid date format (must be Excel date format)
# 4. Invalid country/channel/device values (must be in VALID_VALUES)

# Solution: Check validation error messages in dashboard
# Review config.py for valid values and column mappings

Issue: Predictions seem incorrect or unrealistic

# Solution 1: Verify data quality
# - Check for outliers in investment values
# - Verify date ranges are reasonable
# - Ensure revenue values are positive

# Solution 2: Check model version
# - Ensure using latest model (check date suffix)
# - Verify model was trained on similar data

# Solution 3: Review model limitations (see section above)
# - Weekly predictions have ±20% variance
# - Use monthly/quarterly aggregates for planning

Performance Issues

Issue: Application runs slowly

# Solution 1: Check file sizes
# Large Excel files (>100MB) may cause delays
# Consider splitting data into smaller files

# Solution 2: Increase available RAM
# Minimum 8GB required, 16GB recommended

# Solution 3: Use SSD instead of HDD
# Faster data loading and processing

Issue: Memory errors during processing

# Solution: Reduce data size or increase RAM
# - Process data in smaller batches
# - Close other applications
# - Use 64-bit Python (not 32-bit)

Getting Help

If issues persist:

Check error messages in Streamlit console/terminal
Review model limitations section above
Verify all files follow naming conventions
Check that Python version is 3.9+ (python --version)
Ensure all dependencies are installed correctly

Test Datasets

The project includes ready-to-use test datasets in data/test/ so anyone can test the system immediately without creating data:

Forecast examples:

forecast_month_04-2025.xlsx
forecast_month_07-2025.xlsx
forecast_agg3months_01+03-2025.xlsx

Historical examples:

historical_agg2months_01+02-25_InaccuratePredictions.xlsx (ideal for testing drift)
historical_agg3months_01+03-2025.xlsx
historical_agg6months_01+06-2025.xlsx

File Structure

.
├── .gitignore                          # Specifies intentionally untracked files to ignore in Git
├── data_processor.py                   # Handles data cleaning, validation, and processing pipelines
├── optimizer.py                        # Implements budget optimization algorithms (auto and manual modes)
├── pipeline.py                         # Orchestrates the full ML pipeline: from data ingestion to prediction
├── prediction_engine.py                # Core prediction logic using XGBoost models, with hybrid weekly/monthly blending and drift detection
├── README.md                           # Main project documentation file
├── requirements.txt                    # Lists all Python dependencies for the project
├── train_monthly_model.py              # Script to train and save the monthly XGBoost model
├── shap_insights.py                    # Generates SHAP-based explanations and business-friendly insights
├── run_streamlit_with_logs.bat         # Batch script to run Streamlit app with logging (Windows)
├── run_streamlit_with_logs.ps1         # PowerShell script to run Streamlit app with logging (Windows)
├── config.py                           # Central configuration file for constants, paths, and settings
├── model_validator.py                  # Validates model integrity, features, and performance metrics
├── feature_engineering.py              # Implements weekly and monthly feature engineering functions
├── .gitattributes                      # Git attributes for handling file-specific behaviors (e.g., line endings)
├── app.py                              # Main Streamlit application entry point
├── private                            # Private directory for internal notes and deprecated files
│   ├── + Pasos activar piloto.txt      # Internal notes on activating pilot mode
│   ├── Documentación Técnica Calibración fianl ROAS en prediction_engine.py .txt  # Technical documentation on ROAS calibration in prediction_engine.py
│   ├── PLAN_ACCION_R2_REAL_NO_HARDCOREADO V2.md  # Action plan for real R² without hardcoding
│   ├── README - OLD.md                 # Old version of README
│   ├── Plan Acción Bug ROAS e Ingresos Datos Históricos.docx  # Action plan for ROAS and revenue bugs in historical data
│   └── test_old                        # Subdirectory for old test files
│       └── datatest_generator.xlsx     # Excel file for generating test data
├── components                          # Streamlit UI components
│   ├── charts.py                       # Functions for creating Plotly charts and visualizations
│   ├── model_accuracy.py               # Component for displaying model accuracy metrics
│   ├── model_health.py                 # Component for model health monitoring and drift alerts
│   ├── sidebar.py                      # Sidebar navigation and UI elements
│   ├── tables.py                       # Functions for rendering tables and data displays
│   ├── upload_section.py               # Component for data upload sections
│   └── __init__.py                  # Initializes the components package
├── models                              # Directory for trained models and related files
│   ├── feature_list_monthly.json       # JSON list of features for the monthly model
│   ├── feature_list_weekly.json        # JSON list of features for the weekly model
│   ├── segment_baselines_monthly.json  # JSON baselines for monthly drift detection per segment
│   ├── segment_baselines_weekly.json   # JSON baselines for weekly drift detection per segment
│   └── xgboost_vFinal_TFM_20260218.pkl # Final trained XGBoost model pickle file
├── results                             # Directory for model outputs and metrics
│   ├── metrics_v4_20260224.json        # JSON file with model evaluation metrics
│   ├── comparison_models_v4_20260224.xlsx  # Excel comparison of different models
│   ├── metrics_aggregated_v4_20260224.json  # JSON aggregated metrics
│   ├── predictions_v4_20260224.xlsx    # Excel file with model predictions
│   └── segment_baselines.json          # JSON baselines for segments
├── .streamlit                          # Streamlit configuration directory
│   └── config.toml                     # Streamlit app configuration file
├── assets                              # Directory for static assets like images and PDFs
│   ├── images                          # Subdirectory for images and GIFs
│   │   ├── DH_logo_dark.svg            # DH logo — dark variant (SVG)
│   │   ├── DH_logo_light.svg           # DH logo — light variant (SVG)
│   │   ├── dh logo.gif                # Animated logo GIF
│   │   ├── dh_ logo.png                # Static logo PNG
│   │   ├── dh_favicon.ico              # Favicon for the app
│   │   ├── 1_forecast.gif              # GIF demo of forecast upload
│   │   ├── gif_ilustrativo_ejemplo.gif # Illustrative example GIF
│   │   ├── 2_historical.gif            # GIF demo of historical data upload
│   │   └── 3_predictor.gif             # GIF demo of budget optimizer
│   └── pdf                             # Subdirectory for PDF files
│       └── forecast_report_example.pdf # Example forecast report PDF
├── data                                # Main data directory
│   ├── forecast                        # Subdirectory for forecast data files
│   │   └── forecast_20260224_174125.xlsx  # Example forecast Excel file
│   ├── interim                         # Subdirectory for intermediate data
│   │   └── google_ads_clean_20260207.xlsx  # Cleaned Google Ads data
│   ├── processed                       # Subdirectory for processed features
│   │   ├── features_weekly_v4_20260218.xlsx  # Weekly engineered features
│   │   └── monthly_features_20260218.xlsx  # Monthly engineered features
│   ├── raw                             # Subdirectory for raw data
│   │   ├── google_ads_data.xlsx        # Raw Google Ads data
│   │   └── google_ads_data_202101_202412.xlsx  # Raw data from 2021-2024
│   └── test                            # Subdirectory for test datasets
│       ├── forecast                    # Test forecast files
│       │   ├── forecast_month_04-2025.xlsx  # Test forecast for April 2025
│       │   ├── forecast_month_07-2025.xlsx  # Test forecast for July 2025
│       │   └── forecast_agg3months_01+03-2025.xlsx  # Aggregated 3-month forecast test
│       └── historical                  # Test historical files
│           ├── historical_agg2months_01+02-25_InaccuratePredictions.xlsx  # 2-month historical test with inaccuracies
│           ├── historical_agg3months_01+03-2025.xlsx  # 3-month historical test
│           └── historical_agg6months_01+06-2025.xlsx  # 6-month historical test
├── docs                                # Directory for additional documentation
│   ├── DH_brand_style_guide.pdf        # DH Marketing Consultants brand style guide
│   ├── DH_Income_predictor_business_deck_pptx.pdf   # Business deck for stakeholders and clients
│   ├── DH_Income_predictor_enablement_deck_pptx.pdf # Enablement deck for end users and onboarding
│   └── tabla_opciones_avanzadas.md     # Markdown table of advanced options
├── notebooks                           # Directory for Jupyter notebooks
│   ├── 01_data_cleaning_en.ipynb       # Notebook for data cleaning
│   ├── 02_eda_en.ipynb                 # Notebook for exploratory data analysis
│   ├── 03a_weekly_feature_engineering_en.ipynb  # Weekly feature engineering
│   ├── 03b_monthly_feature_engineering_en.ipynb  # Monthly feature engineering
│   ├── 04_modeling_en.ipynb            # Model training and selection
│   ├── 05_evaluation_en.ipynb          # Model evaluation and analysis
│   ├── 06_predict_en.py                # Prediction engine script
│   └── _deprecated                     # Subdirectory for deprecated notebooks
│       ├── 01_data_cleaning_en - v8 Datos Hardcoreados.ipynb  # Deprecated cleaning with hardcoded data
│       ├── 02_eda_en - v8 Datos Hardcoreados.ipynb  # Deprecated EDA with hardcoded data
│       ├── 03a_weekly_feature_engineering_en - v8 Datos Hardcoreados.ipynb  # Deprecated weekly features
│       ├── 03b_monthly_feature_engineering_en - v8 Datos Hardcoreados.ipynb  # Deprecated monthly features
│       ├── 04_modeling_en - v8 Datos Hardcoreados.ipynb  # Deprecated modeling
│       ├── 05_evaluation_en - v8 Datos Hardcoreados.ipynb  # Deprecated evaluation
│       ├── 06_predict_en - v8 Datos Hardcoreados.py  # Deprecated prediction script
        └── 06_predict_en_vFINAL_prev_py.ipynb  # Previous final prediction notebook

Technical Stack

Core Technologies

Technology	Version	Purpose
Python	3.9+	Primary programming language
Streamlit	1.28+	Web application framework
LightGBM	3.3+	Selected production model
XGBoost	2.0+	Challenger model (evaluated, available)
Pandas	2.0+	Data manipulation
NumPy	1.24+	Numerical computing
Scikit-learn	1.3+	ML utilities, metrics, TimeSeriesSplit
SHAP	0.42+	Model explainability
SciPy	1.10+	KS-test for drift detection
Plotly	5.18+	Interactive visualisations
OpenPyXL	3.1+	Excel file handling
Holidays	0.35+	Calendar features (national holidays)

Development Tools

Tool	Purpose
Jupyter	Notebook development
Git	Version control
Pytest	Unit testing
Black	Code formatting
Pylint	Code linting
Poetry	Dependency management (optional)

Data Sources

Google Ads API/Export:

Date, country, channel, device
Investment amount
Revenue
Conversions
Impressions, clicks, views (for historical features only)

External Data:

holidays library for national holidays
Manual commercial event calendar
Historical exchange rates (if multi-currency)

Academic Contributions

Methodological Innovations

Temporal Leakage Prevention Framework: Systematic elimination of post-decision variables, strict temporal validation protocol, ensures real-world applicability.

Multi-Granularity Performance Analysis: Recognition that weekly segment-level ROAS is noisy (CV MAE ≈ 0.77) but aggregate revenue is highly predictable (0.22% deviation), development of reliability labels by timeframe, business-aligned interpretation of model outputs.

Risk-Adjusted Recommendation System: Integration of prediction uncertainty into decision-making, quantification of segment-level volatility, portfolio-style risk management for advertising.

Explainability-First Deployment: SHAP integration as core feature (not afterthought), automated generation of business-language insights, bridges ML predictions and strategic understanding.

Academic Rigor

Data Science Best Practices:

Comprehensive EDA with statistical tests
Four-model comparison (Linear Regression, Random Forest, XGBoost, LightGBM) with identical temporal validation conditions
LightGBM selected based on best Test MAE (0.655) and Test R² (0.530)
Hyperparameter optimisation with RandomizedSearchCV and TimeSeriesSplit
Temporal cross-validation (5-fold TimeSeriesSplit) as primary generalization estimate
Train/test/holdout split with chronological order
Drift detection via KS-test on feature distributions per segment
Residual analysis, investment elasticity quantification, SHAP-based feature importance

Reproducibility:

Versioned data files with date stamps
Serialized models with metadata
Documented random seeds
Requirements.txt for environment replication
Modular code with clear separation of concerns

Documentation:

Inline code comments
Docstrings for all functions
README files at each directory level
Jupyter notebooks with markdown explanations
Methodology document with statistical justifications

Thesis Evaluation Criteria

Criterion	Evidence
Problem Definition	Clear research questions, success metrics defined
Literature Review	Referenced in methodology (ROAS prediction, time series)
Methodology	Rigorous data science pipeline with justifications
Technical Depth	Advanced ML techniques, SHAP explainability, optimization
Results	Comprehensive evaluation with multiple metrics
Validation	Temporal cross-validation, train/test split, scenario analysis
Reproducibility	Complete code, data versioning, requirements documented
Innovation	Risk-adjusted recommendations, multi-granularity precision
Business Value	Deployed web application, real-world usability
Communication	Clear visualizations, executive summaries, user guide

Future Work

Note on current capabilities: Several items that might seem "future" are already implemented. Budget auto-reallocation, prescriptive segment labels (Scale Up / Monitor / Pause / Reallocate), and SHAP-driven insights are live in the current system. The items below are genuine extensions that require new data sources, model retraining, or significant architectural changes.

Short-Term Enhancements

Additional Segmentation Dimensions: The current model operates at Country × Channel × Device level. Extending to ad group or campaign type (brand vs. generic) would require retraining with new historical data structured at that granularity — the COLUMN_MAPPING in config.py already maps ad_group but it is not used as a model feature yet.

Model Retraining Pipeline: Automate the full pipeline from data upload to model retraining and deployment without manual notebook execution. Currently retraining requires running 04_modeling_en.ipynb manually.

Confidence Intervals: The model currently provides point predictions. Adding prediction intervals (e.g., via quantile regression or bootstrapped residuals) would improve the risk quantification system.

UI Enhancements: Dark mode option, customisable dashboards, scheduled email reports, REST API endpoint for programmatic access.

Medium-Term Goals

Exogenous Signal Integration: Incorporating macroeconomic indicators (CPI, consumer confidence) or category-level search trends as additional features could improve forward-looking predictions, particularly for planning periods far from the training distribution. This is a legitimate research direction but requires careful validation to avoid introducing spurious correlations — weather or social sentiment data would only be useful for specific verticals (retail, events).

Multi-Platform Integration: Extending the model to Facebook/Meta Ads, LinkedIn Ads, or TikTok requires platform-specific feature engineering and separate models or a unified cross-platform feature space. The architecture is designed for this extension.

Attribution Modeling: The current system assumes last-click attribution (Google Ads default). Multi-touch attribution or data-driven attribution would make the revenue predictions more accurate for accounts with long conversion paths.

A/B Testing Framework: Automated experiment design with statistical significance testing and treatment effect estimation to validate budget allocation recommendations before full deployment.

Long-Term Vision

Real-Time Bidding Integration: Connecting directly to the Google Ads API for real-time bid adjustments based on live ROAS predictions. This requires sub-second inference latency and a fundamentally different deployment architecture from the current batch-prediction approach.

Multi-Objective Optimisation: The current budget optimizer maximises predicted ROAS subject to a total budget constraint. Extending to multi-objective optimisation (e.g., ROAS + brand awareness metrics simultaneously) with Pareto front exploration would enable more nuanced strategic decisions.

Enterprise Features: Multi-user access with role-based permissions, audit trails, compliance reporting, integration with BI tools (Tableau, Power BI), and a full REST API for programmatic access.

License

Academic Use Only

This project is part of a Master's Thesis (TFM) in Data Science and is licensed for academic purposes only.

Permitted Uses:

Academic research and study
Educational purposes in university settings
Evaluation by thesis committees
Non-commercial personal learning

Prohibited Uses:

Commercial deployment without permission
Redistribution for profit
Modification and resale
Use in production systems without license

Citation: If you use this work in academic research, please cite:

Sánchez, Alberto. (2025). Google Ads ROAS & Income Predictor: A Machine Learning
Decision Support System for Digital Advertising. Master's Thesis in Data Science
with AI, 2nd Edition. BIG School.
Available at: https://thebigschool.com/master-data-science-con-ia/

Contact for Commercial Licensing: DH Marketing Consultants — [Contact Email]

Contact & Support

Project Author:

Name: Alberto Sánchez
Email: alberto.sanchez@gmail.com
LinkedIn: https://www.linkedin.com/in/albertosvallejo/
GitHub: https://github.com/albertosvallejo/

Academic Supervisor:

BIG School — Master's in Data Science with AI, 2nd Edition (May–Nov 2025)
URL: https://thebigschool.com/master-data-science-con-ia/
Open source community — Python, XGBoost, Streamlit, SHAP

Conclusion

This Master's Thesis demonstrates the complete journey from academic research to production-ready business application. The Google Ads ROAS & Income Predictor successfully:

Solves a Real Business Problem: Provides actionable budget allocation recommendations backed by a model that achieves 0.22% aggregate revenue deviation on the test period
Applies Rigorous Data Science: Four-model comparison under identical temporal validation, no data leakage, KS-based drift detection, SHAP explainability
Delivers Business Value: Interactive Streamlit tool accessible to non-technical users, with PDF reports, Auto Optimize, and segment-level risk warnings
Maintains Academic Standards: Comprehensive documentation, reproducible results, honest reporting of both strengths and limitations

The system transforms machine learning predictions into strategic decisions, bridging the gap between technical capability and business utility. Weekly ROAS prediction at segment level remains challenging (CV MAE ≈ 0.77) — this is an honest and expected result for a noisy metric with limited historical data per segment. The system's value lies in aggregate accuracy and the decision support layer built on top of it.

Key Takeaway: With proper temporal validation, leakage prevention, and a multi-model evaluation framework, machine learning can provide reliable guidance for advertising budget allocation — not by predicting the future perfectly, but by structuring decisions with quantified uncertainty.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.streamlit		.streamlit
assets		assets
components		components
data/test		data/test
docs		docs
models		models
notebooks		notebooks
results		results
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
app.py		app.py
config.py		config.py
data_processor.py		data_processor.py
docker-compose.yml		docker-compose.yml
feature_engineering.py		feature_engineering.py
model_validator.py		model_validator.py
optimizer.py		optimizer.py
pipeline.py		pipeline.py
prediction_engine.py		prediction_engine.py
requirements.txt		requirements.txt
run_streamlit_with_logs.bat		run_streamlit_with_logs.bat
run_streamlit_with_logs.ps1		run_streamlit_with_logs.ps1
shap_insights.py		shap_insights.py
train_monthly_model.py		train_monthly_model.py

Folders and files

Latest commit

History

Repository files navigation

Google Ads ROAS & Income Predictor

Executive Summary

Quick Start

Business & Presentation Materials

Table of Contents

Project Context

Academic Framework

Business Context

Research Problem

Challenge Statement

Challenge Statement

Research Questions

Success Criteria

Methodology

1. Data Leakage Prevention

2. Temporal Feature Engineering

3. Segmentation Strategy

4. Modeling Approach

5. Interpretability & Explainability

6. Risk-Adjusted Recommendations

Project Evolution

Phase 1: Initial Prototype (v1.x)

Phase 2: Technical Refinement (v2.x - v3.x)

Phase 3: Functional Maturity (v4.x)

Phase 4: Internationalization & Standardization

Phase 5: Web Application - Production Deployment & Final Refinements (v4.x → vFinal)

Phase 6: Final Refinements & vFinal Release (February 2026)

Recent Updates (v4.2)

Previous Updates (v4.1)

Model Improvement Plan

Results & Performance

Model Selection

Model Performance Metrics (Selected Model: LightGBM)

Segment-Level Weekly ROAS Predictions

Aggregate Performance (Business Impact)

Performance by Timeframe

Key Finding: Noise vs Signal

Understanding Prediction Differences

Model Limitations & Considerations

Known Limitations

1. Weekly Granularity Variance

2. Test Set Size

3. Data Requirements

4. Temporal Scope

5. Feature Dependencies

6. Model Assumptions

7. Geographic Limitations

8. Channel & Device Constraints

9. Computational Limitations

9. Prediction Uncertainty

10. Business Context Limitations

When NOT to Use This Model

Model Maintenance Requirements

SHAP Explainability Results

Global Feature Importance (Top 10)

Segment-Specific Insights

Scenario Analysis Results

System Architecture

Data Pipeline

Model Persistence

Web Application Architecture

Web Application Features

Sidebar — Global Navigation & Model Health

Page 1: Data Status & Update

Page 2: Forecast Dashboard & Explainability

Page 3: Budget Optimizer

Installation & Usage

System Requirements

Installation Steps

1. Clone or Download the Repository

2. Create Virtual Environment (Recommended)

3. Install Dependencies

4. Prepare Data Files

5. Run the Application

6. Access the Dashboard

Usage Workflow