Download README.md from AdryanAzul/Football-Match-Prediction: direct link, hf CLI and curl.
- Browser
- Download file 10.3 kB
-
https://huggingface.co/AdryanAzul/Football-Match-Prediction/resolve/main/README.md
- Command line
-
hf download hf://AdryanAzul/Football-Match-Prediction/README.md
-
curl -L -o README.md https://huggingface.co/AdryanAzul/Football-Match-Prediction/resolve/main/README.md
language:
- pt
library_name: scikit-learn
tags:
- tabular-classification
- random-forest
- football
- sports-analytics
- monte-carlo
Football Match Prediction & Monte Carlo Simulation
Modelo de classificação baseado em Random Forest (scikit-learn) para prever o resultado de partidas de futebol (vitória do mandante, empate ou vitória do visitante) e estimar probabilidades de título de uma liga nacional por meio de Simulação de Monte Carlo.
Objetivo da Previsão
Estimar as probabilidades $P(\text{Mandante}), P(\text{Empate}), P(\text{Visitante})$ para partidas de futebol a partir da força média dos elencos titulares e do histórico de confronto direto, utilizando essas probabilidades para simular as rodadas finais de um campeonato e calcular a probabilidade de título de cada clube.
Origem dos Dados
- Fonte original: European Soccer Database (publicado originalmente no Kaggle por Hugo Mathien), contendo dados históricos de partidas, ligas, clubes e atributos de jogadores (baseados em avaliações do EA Sports FIFA).
- Recorte no repositório: O arquivo
data/dados_preparados.csv(~2,32 MiB) contém apenas os metadados das partidas e as 3 features agregadas extraídas do banco SQLite original (database.sqlite, não incluído neste repositório devido ao tamanho de ~298,6 MB).
Descrição do Dataset
- Total de partidas extraídas:
25.979 - Partidas válidas após remoção de nulos (
dropna):25.221(758 partidas sem rating completo de jogadores foram removidas) - Período:
2008-07-18a2016-05-25(8temporadas:2008/2009a2015/2016) - Cobertura:
11ligas europeias (Belgium Jupiler League, England Premier League, France Ligue 1, Germany 1. Bundesliga, Italy Serie A, Netherlands Eredivisie, Poland Ekstraklasa, Portugal Liga ZON Sagres, Scotland Premier League, Spain LIGA BBVA, Switzerland Super League) - Distribuição da variável-alvo (após limpeza):
- Classe
0(Vitória do Mandante):11.550(45,79%) - Classe
1(Empate):6.404(25,39%) - Classe
2(Vitória do Visitante):7.267(28,81%)
- Classe
Variáveis Utilizadas
As features devem ser fornecidas exatamente na seguinte ordem e formato numérico (float):
home_overall_rating: média dooverall_ratingdos 11 jogadores titulares do time mandante.away_overall_rating: média dooverall_ratingdos 11 jogadores titulares do time visitante.hist_goal_diff: saldo de gols acumulado em confrontos diretos anteriores entre os dois times, sempre na perspectiva do mandante atual (0quando é o primeiro confronto registrado).
Variável-alvo (target):
0: Vitória do mandante (home_team_goal > away_team_goal)1: Empate (home_team_goal == away_team_goal)2: Vitória do visitante (home_team_goal < away_team_goal)
Engenharia de Atributos
- Rating da equipe: Para cada partida, os 11 titulares de cada equipe (
home_player_1..11eaway_player_1..11) são desempilhados e cruzados com a média deoverall_ratingdo jogador na tabelaPlayer_Attributes, gerando a média da equipe. - Saldo histórico do confronto (
hist_goal_diff): Calculado em ordem cronológica dentro de cada par de times (matchup), acumulando o saldo de gols apenas das partidas anteriores à partida atual e ajustando o sinal conforme o mando de campo.
Pré-processamento
- Remoção de linhas com valores nulos em
home_overall_ratingouaway_overall_rating. - Ordenação cronológica por
date. - Divisão temporal estrita:
- Treino: temporadas anteriores a
2015/2016(21.895partidas). - Teste: temporada
2015/2016(3.326partidas).
- Treino: temporadas anteriores a
- Padronização:
StandardScalerajustado exclusivamente no conjunto de treino (mean_ = [70.5358, 70.4748, -0.2023],scale_ = [5.3208, 5.3084, 5.7843]) e encapsulado emPipelinedurante a validação cruzada.
Arquitetura e Parâmetros do Modelo
- Algoritmo:
RandomForestClassifier(scikit-learn) - Hiperparâmetros:
n_estimators=100,max_depth=5,random_state=42 - Importância das features (
feature_importances_):home_overall_rating:0.3965away_overall_rating:0.3630hist_goal_diff:0.2405
Estratégia de Treinamento e Avaliação
- Validação cruzada
5-foldcomPipeline([('scaler', StandardScaler()), ('clf', RandomForestClassifier(...))])no conjunto de treino (< 2015/2016). - Avaliação final fora da amostra (out-of-time) na temporada
2015/2016(3.326partidas), preservando a separação temporal em relação à simulação de Monte Carlo. - O script
src/preProcess.pytambém treina e reporta um modelo de gradient boosting (XGBClassifierquandoxgboostestá instalado, ouHistGradientBoostingClassifiercomo fallback) apenas para comparação; o artefato salvo para inferência e simulação é omodelo_rf.pkl.
Métricas Reais Obtidas
- Validação Cruzada (5-fold, Random Forest - Treino): Acurácia
0.5211 (+/- 0.0064) - Conjunto de Teste (
>= 2015/2016,3.326partidas):- Random Forest (artefato publicado
modelo_rf.pkl):- Acurácia global:
0.49 - Classe
0(Mandante,1.459jogos):precision=0.48,recall=0.88,f1-score=0.63 - Classe
1(Empate,855jogos):precision=0.00,recall=0.00,f1-score=0.00 - Classe
2(Visitante,1.012jogos):precision=0.50,recall=0.33,f1-score=0.39
- Acurácia global:
- XGBoost (comparação em treino/teste, não serializado):
- Acurácia global:
0.47(macro avg f1=0.38, conseguindo recall0.08na classe de empates).
- Acurácia global:
- Random Forest (artefato publicado
Explicação da Simulação de Monte Carlo
O script src/simulation.py avalia a temporada 2015/2016 da England Premier League (380 partidas):
- Calcula a pontuação real acumulada nas primeiras
280partidas (28 rodadas: 3 pontos por vitória, 1 por empate). - Para as últimas
100partidas (10 rodadas finais), obtém as probabilidades $[P(0), P(1), P(2)]$ viamodelo_rf.predict_proba(scaler.transform(X_restantes)). - Executa
1.000simulações independentes (np.random.default_rng(42)), sorteando o resultado de cada jogo restante de acordo com suas probabilidades previstas. - Ao final de cada iteração, contabiliza o time com maior pontuação como campeão daquela simulação.
Resultados de Probabilidade de Título
Resultados registrados em reports/resultado_simulacao_titulo.csv (soma total = 100.0%):
| Time | Probabilidade de Campeão (%) |
|---|---|
| Leicester City | 45.0% |
| Manchester City | 26.5% |
| Tottenham Hotspur | 17.4% |
| Arsenal | 8.7% |
| Manchester United | 2.4% |
| Demais 15 clubes da liga | 0.0% |
Limitações Metodológicas
- Média global de rating dos jogadores: Em
src/extract.py,PlayerLatestRatingcalculaAVG(overall_rating)sobre toda a tabelaPlayer_Attributespor jogador, sem filtrar apenas registros anteriores à data de cada partida. - Previsão de empates no Random Forest: Com
max_depth=5e desbalanceamento natural da classe1(empates), o classificador não prevê a classe1como classe majoritária (predict), embora atribua probabilidades não nulas viapredict_proba(usadas na simulação de Monte Carlo). - Critério de desempate na simulação: Como o modelo não prevê placar exato de gols, o desempate em cada universo simulado considera apenas a pontuação total (
max), sem saldo de gols. - Dependência do SQLite para metadados na simulação:
src/simulation.pylê os nomes de ligas e times diretamente dedatabase.sqlite(oudatabase.zip). Para reproduzirsimulation.pydo zero, é necessário obter o European Soccer Database (database.sqlite).
Instruções para Carregar o Modelo e Realizar Previsões
import joblib
import pandas as pd
modelo = joblib.load("modelo_rf.pkl")
scaler = joblib.load("scaler.pkl")
# Ordem obrigatória das features:
# ['home_overall_rating', 'away_overall_rating', 'hist_goal_diff']
amostra = pd.DataFrame(
[[70.67, 68.83, 0.0]],
columns=["home_overall_rating", "away_overall_rating", "hist_goal_diff"],
)
amostra_escalada = scaler.transform(amostra)
classe_prevista = modelo.predict(amostra_escalada)[0]
probabilidades = modelo.predict_proba(amostra_escalada)[0]
print("Classe prevista (0=Mandante, 1=Empate, 2=Visitante):", classe_prevista)
print("Probabilidades [Mandante, Empate, Visitante]:", probabilidades.round(4))
Instruções para Reproduzir o Treinamento e a Simulação
- Instale as dependências:
pip install -r requirements.txt - Para reproduzir o treinamento a partir de
data/dados_preparados.csv, executesrc/preProcess.pya partir da raiz ondedados_preparados.csvestiver acessível. - Para reproduzir a extração (
src/extract.py) e a simulação completa (src/simulation.py), é necessário possuir o arquivodatabase.sqlite(European Soccer Database) na pasta de execução.
Dependências e Versões
Versões testadas no ambiente de validação:
- Python
3.12 scikit-learn==1.8.0pandas==2.3.1numpy==2.3.2joblib==1.5.3xgboost==3.4.1
Atenção: Artefatos
.pklserializados comscikit-learn==1.8.0devem ser carregados preferencialmente na mesma versão doscikit-learnpara evitar avisos ou incompatibilidades de desserialização.
Licença e Atribuições
- Dados: Os dados em
data/dados_preparados.csvsão derivados do European Soccer Database (Hugo Mathien, Kaggle — originalmente disponibilizado sob licença CC0: Public Domain). - Código e artefatos do modelo: Não há arquivo
LICENSEespecífico definido no repositório original; recomenda-se definir explicitamente a licença do código antes de uso comercial.
Uso de Ferramentas de IA
Ferramentas de assistência por IA (Antigravity / Gemini) foram utilizadas exclusivamente para:
- Auditoria técnica e metodológica do pipeline original;
- Correção do cálculo de
hist_goal_diffe da divisão temporal/escalonamento sem vazamento entre treino e teste; - Execução dos testes de carregamento, inferência e reprodução da simulação;
- Preparação da estrutura de publicação (
huggingface_release/) e redação deste Model Card.