WorldCupROI

AI Sports Sponsorship Intelligence Platform

WorldCupROI blends match performance, media attention, fan behavior, sponsor investment, scenario simulation, and uncertainty risk into one sponsor ROI decision platform. The goal is not only to predict football results, but to help answer: which sponsorship strategy should a brand choose, under what risk, and why?

Platform Hero Overview

Core result snapshot

10-Second Overview

WorldCupROI is a reproducible sports sponsorship analytics project with four layers:

Results Showcase

Model Performance Comparison

What it shows: Compares trained baseline and benchmark models on primary evaluation metrics.

Why it matters: It shows whether the current model choice is a stable baseline or only a placeholder.

Business takeaway: Use the benchmark spread to decide which model family deserves production tuning first.

ROI Feature Importance / SHAP

What it shows: Ranks the strongest sponsor ROI drivers using SHAP-style feature contribution scores.

Why it matters: Explainability keeps ROI recommendations auditable and helps detect proxy-label overdependence.

Business takeaway: Improve brand heat, sponsor-team fit, media exposure, and activation quality before scaling spend.

Sponsor ROI Ranking

What it shows: Ranks sponsors by predicted commercial ROI and network influence evidence.

Why it matters: A sponsor can look attractive because expected ROI is high or because relationship influence is broad.

Business takeaway: Prioritize sponsors that combine high ROI with strong team-player-network leverage.

Scenario ROI Lift

What it shows: Shows conservative, balanced, and aggressive strategy lift against the baseline.

Why it matters: Scenario analysis turns the model from prediction into a decision simulator.

Business takeaway: Select aggressive strategies only when lift is positive and risk remains tolerable.

Prediction Interval / Conformal Prediction

What it shows: Displays ROI point estimates with conformal-style prediction intervals.

Why it matters: Prediction intervals show forecast reliability, not just expected value.

Business takeaway: Prefer narrow-interval opportunities when sponsor budgets are constrained.

Monte Carlo Risk Distribution

What it shows: Shows the distribution of Monte Carlo ROI standard deviation and risk scores.

Why it matters: The spread of risk is often more important than average ROI for sponsorship planning.

Business takeaway: Use high-risk tails as triggers for staged spend, insurance clauses, or additional analyst review.

Sponsor-Team-Player Network

What it shows: Visualizes sponsor, team, and player relationships as a weighted commercial graph.

Why it matters: Graph position captures activation leverage that flat tables miss.

Business takeaway: Use central sponsors and teams as anchor partnerships for campaign portfolios.

Future Event ROI Trend Forecast

What it shows: Shows future sponsor ROI forecasts across the 2026, 2030, and 2034 World Cup cycles.

Why it matters: It makes time dependence visible instead of treating every tournament as the same planning context.

Business takeaway: Use the trend as a budget planning prior, then review uncertainty before committing long-cycle spend.

Sentiment Event Impact on ROI

What it shows: Compares ROI deltas for positive sentiment spikes, stage attention shocks, and baseline attention events.

Why it matters: Sentiment can change conversion quality even when media exposure is high.

Business takeaway: Prepare contingency messaging and spend limits around high-attention negative events.

Budget and Media Sensitivity

What it shows: Maps risk-adjusted ROI under different sponsor budgets and media multiplier combinations.

Why it matters: Resource optimization converts model output into a concrete allocation recommendation.

Business takeaway: Scale spend where the sensitivity surface is high and stable, not only where raw ROI is high.

Graph Attention ROI Contribution

What it shows: Ranks sponsor nodes by graph attention-style contribution to ROI.

Why it matters: It explains relationship leverage beyond flat sponsor ranking or tabular SHAP alone.

Business takeaway: Use high-contribution sponsors as anchor nodes in portfolio planning.

Extreme Scenario ROI and Risk Intervals

What it shows: Stress-tests key player injury, sentiment crisis, sponsor policy change, and positive viral upside scenarios.

Why it matters: Extreme cases reveal downside intervals that average ROI hides.

Business takeaway: Pre-approve response playbooks before the tournament starts.

Integrated Commercial Decision Score

What it shows: Combines ROI, media exposure value, fan conversion, social spread, and brand influence.

Why it matters: Sponsor decisions are multi-objective; ROI alone is too narrow for portfolio planning.

Business takeaway: Prioritize high composite score opportunities, then review interval width and graph influence.

Sponsor and Player Influence Network

What it shows: Visualizes sponsor and player influence pathways from the heterogeneous commercial graph.

Why it matters: Player and sponsor influence can amplify or weaken projected ROI under the same match context.

Business takeaway: Pair high-influence sponsors with resilient player/team nodes before selecting activation themes.

Problem

Most football analytics projects stop at predicting who wins. Sponsorship decisions need more: media exposure, fan attention, brand fit, player availability, commercial momentum, downside risk, and an explanation a non-technical stakeholder can trust.

WorldCupROI frames the World Cup as an attention market where sponsor ROI depends on both match context and business activation.

Why It Matters

Tournament sponsorship budgets are committed before all outcomes are known. A high-profile campaign can underperform if the model ignores uncertainty, audience behavior, or sponsor-team fit.

Key Innovations

Research Questions

1. How much do match strength, player availability, and tournament stage change sponsor ROI?
2. Do media narratives and fan behavior improve ROI analysis beyond match results?
3. Which sponsor features create the strongest ROI lift under uncertainty?
4. How stable are ROI predictions under cross-validation and subsample checks?
5. Can graph centrality reveal sponsor-team-player influence patterns?
6. How can a dashboard convert model output into a business recommendation?

Dataset & Data Sources

Detailed documentation:

reports/data_card.md
reports/data_quality_report.md
docs/data_card.md

Deep analysis landing artifacts:

reports/deep_analysis_landing_report.md
reports/deep_analysis_landing_report.pdf
reports/future_roi_forecast.csv
reports/sentiment_event_roi_impact.csv
reports/resource_optimization_recommendations.csv
reports/extreme_scenario_roi_risk.csv
data/commercial_decision_metrics.csv
assets/figures/deep_analysis_figure_notes.md

Model Performance

Validation is generated by src/model_validation.py and saved to reports/cross_validation_summary.csv. It now includes random k-fold validation, sub-sample sensitivity checks, and tournament-era temporal sliding validation.

Model governance:

reports/model_card.md
reports/match_outcome_model_card.md
reports/sponsor_roi_model_card.md

Explainability & SHAP

Explainability artifacts:

reports/roi_feature_importance.csv
reports/roi_driver_explanations.csv
reports/explainability_report.md
assets/figures/roi_feature_importance_shap.png

The ROI explanation layer is designed for business review: it connects model output to sponsor spend, brand heat, media exposure, FanScore, stage premium, player influence, and sponsor-team fit.

Uncertainty & Conformal Prediction

Risk artifacts:

data/roi_uncertainty.csv
reports/conformal_prediction_report.md
reports/uncertainty_summary.md
assets/figures/monte_carlo_risk_distribution.png
assets/figures/prediction_interval_conformal.png

Scenario Simulation

WorldCupROI supports conservative, balanced, and aggressive sponsor strategies. Each scenario includes ROI, lift, risk score, confidence interval, recommendation reason, and rank.

Generated artifacts:

data/scenario_recommendations.csv
reports/scenario_ranking.md
reports/scenario_strategy_summary.csv
assets/figures/scenario_roi_lift.png

Graph Intelligence

The graph layer upgrades a flat sponsor table into a heterogeneous team-player-sponsor-match network.

The current graph baseline uses centrality features, weighted two-hop propagation, and a GraphSAGE-style neighbor aggregation score. It is not a production neural GNN yet, but it gives reviewers a reproducible bridge from relationship structure to sponsor/player influence and SHAP-style ROI drivers.

Architecture

What it shows: The full platform architecture from data sources to features, models, risk controls, reports, and dashboard delivery.

Why it matters: Reviewers can understand how data, modeling, uncertainty, graph intelligence, and product outputs connect.

Business takeaway: Sponsors can trace a recommendation back to evidence rather than treating the dashboard as a black box.

What it shows: The modeling pipeline for match prediction, ROI prediction, explanation, conformal intervals, and scenario outputs.

Why it matters: Separating match outcome modeling from sponsor ROI modeling keeps the business target clear.

Business takeaway: Match probability becomes one commercial input, not the final product.

Dashboard Gallery

The Streamlit app is structured as five decision pages:

Discover -> Explain -> Predict -> Simulate -> Recommend

What it shows: The dashboard pages as a decision workflow, not a loose chart wall.

Why it matters: Each page answers one business question and passes the user to the next step.

Business takeaway: Analysts can move from evidence to recommendation without leaving the platform.

Additional GIF previews:

Preview	GIF
Static dashboard overview
Scenario simulation
Risk analysis
Network analysis

Demo Video

The repository includes generated demo media:

assets/videos/worldcuproi_demo.mp4
assets/gifs/platform_hero_overview.gif
assets/gifs/static_platform_dashboard.gif
assets/gifs/scenario_simulation.gif
assets/gifs/risk_uncertainty.gif
assets/gifs/network_graph.gif

The main README GIF is captured from the polished static HTML dashboard, so the GitHub preview works without a server while still reflecting the five-page World Cup styled decision workflow.

Installation & Reproducibility

Windows PowerShell

git clone https://github.com/2417467487-hub/WorldCupROI.git
cd WorldCupROI
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python src/pipeline.py --demo
streamlit run dashboard/app.py -- --demo

macOS

git clone https://github.com/2417467487-hub/WorldCupROI.git
cd WorldCupROI
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python src/pipeline.py --demo
streamlit run dashboard/app.py -- --demo

Linux

git clone https://github.com/2417467487-hub/WorldCupROI.git
cd WorldCupROI
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python src/pipeline.py --demo
streamlit run dashboard/app.py -- --demo

Make Shortcuts

make pipeline
make dashboard
make assets
make demo

Docker

docker build -t worldcuproi .
docker run --rm -p 8501:8501 worldcuproi

CI/CD

.github/workflows/ci.yml
.github/workflows/streamlit-cloud.yml
docs/deployment.md

The Streamlit Cloud workflow runs the demo pipeline, smoke-tests the Streamlit app, and optionally calls STREAMLIT_DEPLOY_HOOK_URL when configured.

Contributions

Roadmap

License / Contact

This repository is a portfolio and research demonstration project. Commercial sponsor variables are documented as proxy/mock where audited campaign data is unavailable.

Repository: github.com/2417467487-hub/WorldCupROI