File size: 10,347 Bytes
72a3423
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
---
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.