# ELOmeter — pełna metodologia obliczeń

ELOmeter to publiczny ranking ELO drużyn i trenerów polskich lig piłkarskich
(Ekstraklasa, Betclic I liga, Betclic II liga, Puchar Polski) z modelami
predykcji wyników 1X2.

## Co to jest rating ELO

Rating ELO to pojedyncza liczba opisująca siłę drużyny lub trenera. Po każdym
rozegranym meczu ratingi obu stron zmieniają się o kwotę zależną od stałej
K, różnicy ratingów (oczekiwany wynik) i różnicy goli. Wygrana z silniejszym
przeciwnikiem daje więcej punktów niż wygrana ze słabszym; porażka ze
słabszym obniża rating najbardziej.

## Jak liczymy zmiany meczowe

- Rating startowy każdej nowej drużyny i trenera: **1500**.
- Stała K = **30** (drużyny).
- Przewaga własnego boiska: **+70** pkt ELO dla gospodarza (stała).
- Różnica goli mnoży zmianę: **x1.0** przy jednej bramce różnicy, **x1.5**
  przy dwóch; przy trzech i więcej mnożnik rośnie linearnie wg formuły
  **(11 + GD) / 8** (GD=3 → 1.75, GD=4 → 1.875, GD=5 → 2.0).
- Rewersja sezonowa: **0.90** — po zakończeniu sezonu drużyna zachowuje 90%
  nadwyżki ratingu nad kotwicą swojej ligi (i odpuszcza 90% niedoboru), co
  przyciąga ratingi do poziomu ligi między sezonami.

### Kotwice poziomów lig

Powrót ratingów między sezonami kotwiczony jest na poziomach lig:
ekstraklasa **1650** (1500+150), I liga **1500**, II liga **1380** (1500-120).
Drużyna bez rozpoznanego poziomu (np. znana tylko z Pucharu Polski) wraca do
**1350** (1500 - 150); trenerzy wracają neutralnie do **1500** — poziom
trenera wynika z dorobku, nie z ligi ostatniego występu.

### Ratingi trenerów

Każdy trener ma własny rating ELO zmieniany po meczach tym samym silnikiem
co drużyny. Mnożnik K trenerów zależy od ligi meczu: ekstraklasa 1.0,
I liga 0.75, II liga 0.55, Puchar Polski 0.85 — niższa liga, mniejszy wpływ.
Rating trenera jest korygowany przy awansie lub spadku między sezonami
(macierz kroków korekty zależnej od pary poziomów). W ocenianym wyniku meczu
rating trenerów wpływa z wagą **0.5** (połowiczne mieszanie ratingu trenera
w oczekiwanie). Karta trenera pokazuje „punkty ponad skład": liczbę punktów,
jakie trener dodał ponad średnią ELO jego zespołów w ostatnich **30** meczach.

## Predykcje 1X2

Prognozy na stronach lig i kartach drużyn liczy model Poisson oparty na
ratingach ELO:

1. Różnica sił = rating gospodarza + 70 (przewaga własnego boiska) -
   rating gościa.
2. Do różnicy wchodzi rating trenerów: różnica ratingów trenerów × **0.10**
   modyfikuje siłę (mierzalny, ograniczony wpływ).
3. Współczynniki siły 10^(diff/400 × 0.2); łączna oczekiwana liczba goli
   **2.7** na mecz, podzielona między gospodarza i gościa proporcjonalnie.
4. Rozkład Poissona (do 8 goli na drużynę) daje surowe P(1), P(X), P(2).
5. Kalibracja remisów: **regresja izotoniczna** (scikit-learn) dopasowana na
   niedawnych rozegranych meczach koryguje surowe prawdopodobieństwa;
   ponawiane przetrenowanie co **24 h**. Surowy model systematycznie
   niedoszacowuje remisów — kalibrator tę nierówność prostuje.

Prognozy powstają PRZED meczem (out-of-sample) i są oceniane po rozegraniu.

## Trafność (/trafnosc)

Strona pokazuje skuteczność prognoz 1X2:

- Zakres: rozegrane mecze (walkover i przełożone nie wchodzą do oceny).
  Próbka KPI = ostatnie **1000** rozstrzygniętych meczów (adnotacja w UI);
  agregaty liczone na pełnej próbie danego trybu.
- Preferowane są prognozy „live" (sprzed meczu, out-of-sample); przy ich
  braku użycie rekonstrukcji „backtest" (in-sample z ratingów sprzed meczu).
- Metryki: trafność 1/X/2 (hit-rate), Brier score, log loss oraz baseline
  (naive: zawsze typ gospodarza). Rozbicie per liga.
- Paginacja: 30 wierszy na stronę.

## Aktualizacje danych

- **daily_update**: pełny przebieg (ingest 90minut.pl + recompute ELO +
  prognozy) codziennie o **2:30** czasu Europe/Warsaw.
- **light refresh**: co **4 godziny** odświeżenie bieżącej kolejki, wyników
  i prognoz.
- **checker wyników dnia**: co **60 minut** w godzinach **09:00-23:30**
  kontrola meczów dnia — refresh ok. 1.5 h po planowanych zakończeniach,
  by tabele i prognozy nie wisiały do porannego daily_update.

## Strony

- /: Dashboard — nadchodzące mecze z prognozami 1X2, TOP 5 drużyn i trenerów
  per liga, ostatnie wyniki rozegranych meczów
- /liga/ekstraklasa: Ranking ELO Ekstraklasy — tabela, forma duży drużyny,
  predykcje i przewidywana tabela na koniec sezonu (strefy mistrzostwa,
  pucharów, awansu i spadku)
- /liga/i_liga: Ranking ELO I ligi — jw.
- /liga/ii_liga: Ranking ELO II ligi — jw.
- /liga/puchar: Puchar Polski — rankingi uczestników
- /druzyna/{id}-{slug}: Karta drużyny — krzywa ratingu per sezon, ostatnie i nadchodzące
  mecze, wartość rynkowa (Transfermarkt), wykres jej zmian
- /trenerzy: Ranking trenerów — rating, „punkty ponad skład" (xPTS), status
  zatrudnienia (zatrudniony / bez pracy / zagranica), filtry i paginacja
- /trener/{id}-{slug}: Karta trenera — krzywa ratingu, ostatnie mecze z Δ ELO,
  kariera i przypisania klubowe
- /trafnosc: Trafność prognoz (opisane wyżej)
- /o-nas: O projekcie

## Dane wejściowe

Wyniki i terminy meczów: 90minut.pl. Wartości rynkowe drużyn: Transfermarkt.
Weryfikacja zatrudnienia trenerów: polska Wikipedia (MediaWiki API). Źródła
podpisane w stopkach tabel.