|
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
10.3 kB
| 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-18` a `2016-05-25` (`8` temporadas: `2008/2009` a `2015/2016`) | |
| * **Cobertura:** `11` ligas 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%`) | |
| ## Variáveis Utilizadas | |
| As features devem ser fornecidas exatamente na seguinte ordem e formato numérico (`float`): | |
| 1. `home_overall_rating`: média do `overall_rating` dos 11 jogadores titulares do time mandante. | |
| 2. `away_overall_rating`: média do `overall_rating` dos 11 jogadores titulares do time visitante. | |
| 3. `hist_goal_diff`: saldo de gols acumulado em confrontos diretos anteriores entre os dois times, sempre na perspectiva do mandante atual (`0` quando é 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..11` e `away_player_1..11`) são desempilhados e cruzados com a média de `overall_rating` do jogador na tabela `Player_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_rating` ou `away_overall_rating`. | |
| * Ordenação cronológica por `date`. | |
| * **Divisão temporal estrita:** | |
| * **Treino:** temporadas anteriores a `2015/2016` (`21.895` partidas). | |
| * **Teste:** temporada `2015/2016` (`3.326` partidas). | |
| * **Padronização:** `StandardScaler` ajustado **exclusivamente** no conjunto de treino (`mean_ = [70.5358, 70.4748, -0.2023]`, `scale_ = [5.3208, 5.3084, 5.7843]`) e encapsulado em `Pipeline` durante 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.3965` | |
| * `away_overall_rating`: `0.3630` | |
| * `hist_goal_diff`: `0.2405` | |
| ## Estratégia de Treinamento e Avaliação | |
| * Validação cruzada `5-fold` com `Pipeline([('scaler', StandardScaler()), ('clf', RandomForestClassifier(...))])` no conjunto de treino (`< 2015/2016`). | |
| * Avaliação final fora da amostra (*out-of-time*) na temporada `2015/2016` (`3.326` partidas), preservando a separação temporal em relação à simulação de Monte Carlo. | |
| * O script `src/preProcess.py` também treina e reporta um modelo de *gradient boosting* (`XGBClassifier` quando `xgboost` está instalado, ou `HistGradientBoostingClassifier` como fallback) apenas para comparação; o artefato salvo para inferência e simulação é o `modelo_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.326` partidas):** | |
| * **Random Forest (artefato publicado `modelo_rf.pkl`):** | |
| * Acurácia global: `0.49` | |
| * Classe `0` (Mandante, `1.459` jogos): `precision=0.48`, `recall=0.88`, `f1-score=0.63` | |
| * Classe `1` (Empate, `855` jogos): `precision=0.00`, `recall=0.00`, `f1-score=0.00` | |
| * Classe `2` (Visitante, `1.012` jogos): `precision=0.50`, `recall=0.33`, `f1-score=0.39` | |
| * **XGBoost (comparação em treino/teste, não serializado):** | |
| * Acurácia global: `0.47` (`macro avg f1=0.38`, conseguindo recall `0.08` na classe de empates). | |
| ## Explicação da Simulação de Monte Carlo | |
| O script `src/simulation.py` avalia a temporada `2015/2016` da **England Premier League** (`380` partidas): | |
| 1. Calcula a pontuação real acumulada nas primeiras `280` partidas (28 rodadas: 3 pontos por vitória, 1 por empate). | |
| 2. Para as últimas `100` partidas (10 rodadas finais), obtém as probabilidades $[P(0), P(1), P(2)]$ via `modelo_rf.predict_proba(scaler.transform(X_restantes))`. | |
| 3. Executa `1.000` simulações independentes (`np.random.default_rng(42)`), sorteando o resultado de cada jogo restante de acordo com suas probabilidades previstas. | |
| 4. 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 | |
| 1. **Média global de rating dos jogadores:** Em `src/extract.py`, `PlayerLatestRating` calcula `AVG(overall_rating)` sobre toda a tabela `Player_Attributes` por jogador, sem filtrar apenas registros anteriores à data de cada partida. | |
| 2. **Previsão de empates no Random Forest:** Com `max_depth=5` e desbalanceamento natural da classe `1` (empates), o classificador não prevê a classe `1` como classe majoritária (`predict`), embora atribua probabilidades não nulas via `predict_proba` (usadas na simulação de Monte Carlo). | |
| 3. **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. | |
| 4. **Dependência do SQLite para metadados na simulação:** `src/simulation.py` lê os nomes de ligas e times diretamente de `database.sqlite` (ou `database.zip`). Para reproduzir `simulation.py` do zero, é necessário obter o *European Soccer Database* (`database.sqlite`). | |
| ## Instruções para Carregar o Modelo e Realizar Previsões | |
| ```python | |
| 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 | |
| 1. Instale as dependências: | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 2. Para reproduzir o treinamento a partir de `data/dados_preparados.csv`, execute `src/preProcess.py` a partir da raiz onde `dados_preparados.csv` estiver acessível. | |
| 3. Para reproduzir a extração (`src/extract.py`) e a simulação completa (`src/simulation.py`), é necessário possuir o arquivo `database.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.0` | |
| * `pandas==2.3.1` | |
| * `numpy==2.3.2` | |
| * `joblib==1.5.3` | |
| * `xgboost==3.4.1` | |
| > **Atenção:** Artefatos `.pkl` serializados com `scikit-learn==1.8.0` devem ser carregados preferencialmente na mesma versão do `scikit-learn` para evitar avisos ou incompatibilidades de desserialização. | |
| ## Licença e Atribuições | |
| * **Dados:** Os dados em `data/dados_preparados.csv` sã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 `LICENSE` especí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_diff` e 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. | |