Metadata-Version: 2.4
Name: ysk
Version: 0.1.0
Summary: Tools for downloading and reshaping Turkish YSK open election data
Author-email: "Sencer S." <nospam@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=18.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tqdm>=4.67.0
Requires-Dist: xarray>=2025.1.0
Requires-Dist: zarr>=3.0.0
Provides-Extra: dev
Requires-Dist: basedpyright>=1.31.7; extra == "dev"
Requires-Dist: pandas-stubs>=2.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"

# ysk

YSK acik servisinden indirilip temizlenmis secim sonuclari.

Bu repo, `data/secim.zarr` altinda tek bir xarray/zarr veri seti olarak
duzenlenmis YSK sonuclarini icerir. Veri seti; secim tarihi, makam, yer,
sandik ve tercih eksenleriyle okunabilir. Paket icindeki yardimci fonksiyonlar
bu veriyi analiz icin hazir pandas tablolarina donusturur.

Yer bilgisi il, ilce, belde, mahalle ve sandik seviyelerinde tutulur. Oylar
parti, aday, ittifak veya diger tercih adlariyla kolonlasir; secmen sayilari
ve cinsiyet kirilimi ayni tabloda yer alir.

Ana dosya:

```text
data/secim.zarr
```

## Kurulum

```bash
uv sync
```

Notebook kullanimi icin:

```bash
uv sync --group dev
uv run jupyter lab --ip 0.0.0.0
```

SSH uzerinden baska bir makineden baglaniyorsaniz Jupyter'i `127.0.0.1`
yerine `0.0.0.0` ile baslatin ve tarayicida sunucunun yerel IP adresini
kullanin.

## En Kolay Kullanim

```python
from ysk import secim

df = secim("2024-03-31", "BBB", il="ISTANBUL", seviye="ilce")
df.head()
```

Sonuc, analiz icin hazir bir pandas DataFrame'dir:

```text
                         secmen  oy_kullanan  gecerli  gecersiz  AK PARTI  CHP ...
il       ilce
ISTANBUL ADALAR            ...          ...      ...       ...       ...  ...
         ARNAVUTKOY        ...          ...      ...       ...       ...  ...
```

Varsayilan seviye sandiktir:

```python
df = secim("2024-03-31", "BBB", il="ANKARA", ilce="CANKAYA")
df.head()
```

Sandik seviyesinde indeks genellikle su alanlardan olusur:

```text
il, ilce, belde, mahalle, sandik_no
```

Sabit bir secim ve makam secildiginde `secim` ve `makam` kolonlari sonuc
tablodan dusurulur.

## Secim ve Makam

`secim` tarih, `makam` ise ayni tarihteki secim turudur.

```python
secim("2024-03-31", "BBB")  # buyuksehir belediye baskanligi
secim("2024-03-31", "BM")  # belediye meclisi
secim("2023-05-14", "CB")  # cumhurbaskanligi
secim("2023-05-14", "MV")  # milletvekilligi
```

Birden fazla secimi ayni anda alabilirsiniz:

```python
df = secim(
  ["2019-03-31", "2024-03-31"],
  "BBB",
  il="ISTANBUL",
  ilce="USKUDAR",
)

df.head()
```

Bu durumda kolonlar MultiIndex olur:

```text
secim       2019-03-31                  2024-03-31
alan        secmen  gecerli  CHP ...    secmen  gecerli  CHP ...
il ilce ...
```

Birden fazla makam da birlikte secilebilir:

```python
df = secim("2024-03-31", ["BBB", "BM"], il="ISTANBUL", seviye="ilce")
```

## Seviyeler

`seviye` parametresi tablonun hangi kirilimda donecegini belirler:

```python
secim("2024-03-31", "BBB", seviye="sandik")
secim("2024-03-31", "BBB", seviye="mahalle")
secim("2024-03-31", "BBB", seviye="belde")
secim("2024-03-31", "BBB", seviye="ilce")
secim("2024-03-31", "BBB", seviye="il")
```

`sandik` seviyesi yurt ici sandiklari, gumruk ve ulke satirlarini birlikte
tutar. Daha yuksek seviyeler sandik verisinden gruplanarak hesaplanir.

## Il ve Ilce

```python
ankara = secim("2024-03-31", "BBB", il="ANKARA", seviye="ilce")
cankaya = secim("2024-03-31", "BBB", il="ANKARA", ilce="CANKAYA")
```

Ilce adlarinda bazi tarihsel farklar normalize edilir. Ornegin
`ONDOKUZMAYIS` ve `19 MAYIS` ayni ad altinda hizalanir. `SEMDINLI - DERECIK`
gibi kaynak adlari temizlenerek ilce ve belde bilgisi ayrilir.

## Oy, Secmen ve Cinsiyet

Donen tabloda toplam kolonlari basta gelir:

```text
secmen, oy_kullanan, gecerli, gecersiz,
gecerli_itirazsiz, gecerli_itirazli, kadin, erkek
```

Bunlardan sonra parti, aday, ittifak veya tercih kolonlari gelir.

Ilce seviyesinde kadin secmen sayisi ile CHP oyu arasindaki korelasyon:

```python
df = secim("2024-03-31", "BBB", il="ISTANBUL", seviye="ilce")

df[["kadin", "CHP"]].corr()
```

Sadece belirli tercihleri almak icin:

```python
df = secim(
  "2024-03-31",
  "BBB",
  il="ISTANBUL",
  seviye="ilce",
  tercihler=["CHP", "AK PARTI", "MHP"],
)
```

Sandik seviyesinde oy ve secmen bilgilerini birlikte kullanmak:

```python
df = secim("2024-03-31", "BBB", il="ISTANBUL", ilce="USKUDAR")

df[["secmen", "kadin", "erkek", "CHP", "AK PARTI"]].head()
```

## Ham Xarray Verisi

Hazir zarr veri setini dogrudan xarray ile acmak icin:

```python
from ysk import ham_veri

ds = ham_veri()
ds
```

Alternatif:

```python
import xarray as xr

ds = xr.open_zarr("data/secim.zarr")
```

Ornek secim:

```python
bbb_2024 = ds.sel(secim="2024-03-31").sel(makam="BBB")
```

Eksenleri ve degiskenleri gormek icin:

```python
ds.dims
ds.coords
list(ds.data_vars)
```

Tum zarr'i tek seferde DataFrame'e cevirmek bellek tasmasina yol acabilir:

```python
# Bunu genelde yapmayin:
# ds.oy.to_dataframe()
```

Once secim, makam, il veya ilce ile daraltmak ya da `secim()` yardimcisini
kullanmak daha guvenlidir.

## Yer Iliskileri

Bazi ilce ve beldeler zaman icinde ayrilmis veya ilceye donusmus olabilir.
Bu iliskiler icin:

```python
from ysk import yer_iliskileri

yer_iliskileri().head()
```

Ornek kolonlar:

```text
il, eski_ilce, yeni_ilce, ilk_belde_secimi, ilk_ilce_secimi, iliski_turu
```

## Veri Formati

Ana format zarr'dir. Zarr, xarray ile uyumlu, parca parca okunabilen
N-boyutlu veri saklama formatidir. Bu repo icin dogal model secim, makam,
yer ve tercih eksenleri olan etiketli bir veri setidir.

Parquet tablo/SQL isleri icin daha uygundur. Bu repoda zarr kanonik veri
formati olarak tutulur; analiz tablolarini `secim()` uretir.

## Gelistirme

```bash
uv run ruff check
uv run basedpyright
uv run pytest
```
