FairZipf — Férové statistické ověření Zipfova zákona

English abstract: Most papers claiming to "verify" Zipf's Law rely on OLS regression on log-log rank-frequency plots and report $R^2 > 0.95$ as evidence — a statistically unsound approach. This project implements the rigorous framework of Clauset, Shalizi & Newman (2009): MLE estimation, KS-optimal $x_{\min}$ selection, Monte Carlo goodness-of-fit testing, and Vuong's Likelihood Ratio Test against alternative distributions. The pipeline is applied to two domains: natural language corpora and city-size distributions.

---

Motivace

Velká část článků, které „ověřují" Zipfův zákon, používá OLS regresi na log-log grafech a spokojí se s $R^2 > 0.95$. Tento projekt ukazuje, proč je tento přístup statisticky nekorektní, a implementuje správný postup pro ověření přítomnosti mocninného rozdělení ve dvou doménách: přirozeném jazyce a velikosti měst.

Správný postup (Clauset, Shalizi & Newman 2009)

1. MLE (Maximum Likelihood Estimation) místo OLS pro odhad exponentu $\alpha$
2. KS-optimální $x_{\min}$ — statistické nalezení prahu, od kterého mocninné rozdělení platí
3. Bootstrap GOF test — Monte Carlo $p$-hodnota pro zamítnutí/nezamítnutí Zipfa
4. Vuongův Likelihood Ratio Test — porovnání s log-normálním, Weibullovým a exponenciálním rozdělením
5. Zipf-Mandelbrot — zobecnění s parametrem $\beta$ pro lepší fit u nejfrekventovanějších slov / největších měst

Struktura projektu

FairZipf/
├── data/
│   ├── raw/
│   │   ├── text/        # Vstupní texty (.txt) — není verzováno
│   │   └── geo/         # Geodata (.csv / .txt) — není verzováno
│   └── processed/       # Zpracovaná data — není verzováno
├── notebooks/
│   ├── 01_zipf_text.ipynb   # Pipeline pro přirozený jazyk
│   └── 02_zipf_geo.ipynb    # Pipeline pro velikost měst
├── src/
│   ├── config.py     # Cesty, globální nastavení
│   ├── nlp.py        # Tokenizace a lemmatizace (spaCy + regex fallback)
│   ├── geo.py        # Načítání dat o městech (simplemaps, GeoNames, plain CSV)
│   ├── stats.py      # MLE, bootstrap, LRT, Zipf-Mandelbrot
│   └── viz.py        # Vizualizační funkce (seaborn, Okabe-Ito paleta)
├── results/
│   ├── figures/      # Exportované grafy
│   └── tables/       # Exportované tabulky (CSV)
├── literature/       # PDF papery (není verzováno)
├── requirements.txt
└── README.md

Instalace

python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux / macOS

pip install -r requirements.txt
python -m spacy download cs_core_news_sm   # česky
# python -m spacy download en_core_web_sm  # anglicky

Použití

Přirozený jazyk

1. Vlož textový soubor .txt do data/raw/text/
2. Otevři notebooks/01_zipf_text.ipynb
3. Nastav TEXT_FILENAME a STRATEGY (regex / spacy_tokens / spacy_lemmas)
4. Spusť notebook sekvenčně

Velikost měst

1. Stáhni worldcities.csv ze simplemaps.com/data/world-cities nebo CZ.txt z download.geonames.org/export/dump/ a vlož do data/raw/geo/
2. Otevři notebooks/02_zipf_geo.ipynb
3. Nastav DATA_SOURCE, FILENAME a COUNTRY_FILTER
4. Spusť notebook sekvenčně

Oba notebooky fungují i bez dat — při TEXT_FILENAME = None / DATA_SOURCE = None se automaticky vygenerují syntetická data z mocninného rozdělení se známým $\alpha$, vhodná pro ověření správnosti pipeline.

Reference

• Clauset, A., Shalizi, C. R., & Newman, M. E. J. (2009). Power-law distributions in empirical data. SIAM Review, 51(4), 661–703.
• Alstott, J., Bullmore, E., & Plenz, D. (2014). powerlaw: A Python package for analysis of heavy-tailed distributions. PLOS ONE, 9(1).
• Piantadosi, S. T. (2014). Zipf's word frequency law in natural language: A critical review and future directions. Psychonomic Bulletin & Review, 21(5), 1112–1130.
• Gabaix, X., & Ioannides, Y. M. (2004). The evolution of city size distributions. Handbook of Regional and Urban Economics, 4, 2341–2378.
• Eeckhout, J. (2004). Gibrat's law for (all) cities. American Economic Review, 94(5), 1429–1451.