How mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction works
1. Repository shape
This is a self-contained Python machine-learning project with two main execution surfaces: a Jupyter notebook for analysis/training (world-cup.ipynb) and a Streamlit app for interactive prediction (app.py). There is no separate backend service or database.
2. Primary data source
The core input is a single preprocessed CSV: data/teams_match_features.csv. It contains historical international match records plus engineered features such as recent form, FIFA player ratings, and ELO values. This dataset is the foundation for both model training and tournament simulation.
3. Offline analytics / model development boundary
world-cup.ipynb is the offline workbench where the ML pipeline is explored, benchmarked, and validated. Based on the README, it handles EDA, preprocessing, model comparison, and selection of the final classifier. This is where the project’s predictive logic is established before being used in the app.
4. Modeling pipeline
All candidate models are wrapped in a consistent scikit-learn pipeline with StandardScaler before classification. The project benchmarks multiple classifiers, then selects XGBoost as the best-performing model using weighted F1-score. That model becomes the decision engine for match outcome prediction.
5. Prediction logic
The system predicts win / draw / loss probabilities for a match using team-level features from the CSV. A notable architectural choice is symmetric prediction: the same match is evaluated twice with home/away swapped, and the probabilities are averaged to reduce positional bias.
6. Tournament simulation engine
The app is not just a single-match predictor; it simulates the full FIFA World Cup 2026 structure. That includes:
- 12 groups of 4 teams
- group standings and points calculation
- qualification of top 2 plus best 8 third-placed teams
- Round of 32 through Final
- third-place play-off
Knockout draws are resolved by higher predicted win probability rather than penalty-shootout modeling.
7. Streamlit application boundary
app.py is the user-facing runtime. It presents a two-page Streamlit dashboard:
- Group Prediction: interactive head-to-head match prediction for chosen teams
- Knockout Bracket: full tournament progression, stage filters, and podium summary
This is the presentation layer that consumes the trained prediction/simulation logic.
8. Visualization layer
The app uses Plotly for interactive probability charts and stage-by-stage match displays. This visualization layer is part of the Streamlit UI, not a separate service. In the notebook, exploratory charts likely use matplotlib and seaborn, which are for offline analysis rather than the live app.
9. Static assets and presentation config
pictures/ stores images used in the UI header and branding. .streamlit/config.toml defines the app’s theme and Streamlit presentation settings. These files affect look-and-feel, not model behavior.
10. Runtime and environment
The project is pure Python and depends on pandas, numpy, scikit-learn, xgboost, lightgbm, plotly, and streamlit. The .devcontainer/ folder indicates the repo is set up for reproducible development in a containerized environment.
11. End-to-end data flow
The conceptual flow is:
historical match dataset → feature engineering / model training in notebook → selected XGBoost classifier → match probability inference → group-stage and knockout simulation → Streamlit charts and tables.
The app is the final consumer of this pipeline and exposes the tournament results interactively.
12. Key architectural takeaway
This repository is best understood as a single-project ML pipeline with an interactive front end, not a multi-service system. The important boundaries are between:
- data preparation and model selection (world-cup.ipynb)
- live prediction and simulation (app.py)
- static resources and UI configuration (data/, pictures/, .streamlit/)
Main entry points: app.py Streamlit app · world-cup.ipynb Notebook · devcontainer.json Dev container · requirements.txt Dependencies
Components 16
Offline ML
Notebook-driven exploration, preprocessing, benchmarking, and model selection.
- Match features · Preprocessed historical match records with engineered team features used for training and simulation.
data/teams_match_features.csv - Notebook · Offline workbench for EDA, preprocessing, model comparison, and validation.
world-cup.ipynb - Feature prep · Transforms match history into model-ready team-level features and target labels.
- Model bench · Compares candidate scikit-learn pipelines and selects the best classifier by weighted F1.
- XGBoost · Selected decision model for win/draw/loss probability prediction.
Runtime UI
Streamlit application that performs prediction, tournament simulation, and visualization.
- Symmetric predict · Runs the same match twice with swapped sides and averages probabilities to reduce positional bias.
- Group stage · Simulates group standings, points, and qualification for the tournament opening round.
- Knockout run · Advances the bracket from Round of 32 to the Final and third-place play-off using predicted win probability.
- Streamlit app · Interactive front end for match prediction and full tournament simulation.
app.py - Group prediction · Interactive head-to-head predictor for selected teams with probability output.
- Knockout bracket · Tournament progression view with stage filters, bracket results, and podium summary.
- Plotly charts · Interactive probability charts and stage-by-stage match displays used in the app.
Support
Static assets, environment, and presentation configuration.
- Streamlit theme · Streamlit styling and app presentation settings.
.streamlit/config.toml - Brand images · Images used for headers and visual branding in the UI.
pictures - Dev container · Containerized development setup for reproducible local execution.
.devcontainer/devcontainer.json - Dependencies · Python package requirements for data processing, modeling, visualization, and Streamlit runtime.
requirements.txt
Connections 19
- Match features → Feature prep: training data · Historical match features feed preprocessing and label construction.
- Feature prep → Notebook: explored in · Notebook drives offline preparation and analysis.
- Notebook → Model bench: benchmarks · Notebook compares candidate pipelines and metrics.
- Model bench → XGBoost: selects · Best weighted F1 classifier becomes the final decision engine.
- XGBoost → Symmetric predict: predicts with · Classifier powers win/draw/loss probability estimation.
- Symmetric predict → Group stage: scores matches · Symmetric probabilities are reused for group-stage head-to-heads.
- Symmetric predict → Knockout run: resolves ties · Predicted win probability determines knockout advancement.
- Group stage → Streamlit app: feeds · Group standings and qualifiers are surfaced in the app.
- Knockout run → Streamlit app: feeds · Bracket progression and podium results are surfaced in the app.
- Streamlit app → Group prediction: renders · Interactive single-match prediction surface.
- Streamlit app → Knockout bracket: renders · Full tournament simulation and bracket surface.
- Group prediction → Plotly charts: charts · Probability outputs are visualized interactively.
- Knockout bracket → Plotly charts: charts · Stage results and match displays are visualized interactively.
- Streamlit theme → Streamlit app: styles · Streamlit configuration controls appearance and layout.
- Brand images → Streamlit app: decorates · Images provide UI branding and header presentation.
- Dependencies → Notebook: supports · Notebook analysis depends on the project Python stack.
- Dependencies → Streamlit app: supports · Streamlit runtime and prediction stack rely on shared packages.
- Dev container → Notebook: supports · Container setup enables reproducible offline development.
- Dev container → Streamlit app: supports · Container setup enables reproducible app execution.