# Site Grid — ERA5-Land statik iklim ızgarası

Ne Yetişir? motorunun iklim girdisini canlı Open-Meteo çağrısı yerine kendi
tablomuzdan beslemek için kullanılan betikler. **Uygulamanın çalışma zamanında
kullanılmaz**, yalnız veri üretir.

> ⛔ **Çalıştırmadan önce:** CDS anahtarı gerekiyor ve Türkiye'nin tamamı için
> AÇIK onay şart. Betikler ikisini de kod düzeyinde zorluyor.

---

## Neden saatlik veri indirmiyoruz

Motor iklimden yalnız **4 şey** okuyor (koddan ölçüldü, bkz.
`docs/SITE-GRID-XRAY.md` §2.1): `tavg[12]`, `tmin[12]`, `prec[12]`, `absMin`.

Bunları en az veriyle üretmek için **iki farklı CDS ürünü** kullanılır:

| Ürün | Ne veriyor | Neden gerekli |
|---|---|---|
| `reanalysis-era5-land-monthly-means` | `tavg[12]`, `prec[12]` | Aylık ortalama = saatlik değerlerin ortalaması. Günlük üründen hesaplamakla **matematiksel olarak aynı**, ~30 kat küçük |
| `derived-era5-land-daily-statistics`<br>`daily_statistic=daily_minimum` | `tmin[12]`, `absMin` | **İkame edilemez.** Aylık ürün 2m sıcaklık için saatlik ortalamayı verir; bizim istediğimiz "günlük minimumların aylık ortalaması" AYRI bir istatistiktir ve aylık üründe yoktur. `absMin` (tek bir en soğuk gün) aylık ortalamadan hiç türetilemez |

Saatlik ürün yerine "günlük istatistik" ürününü kullanmak aynı bilgiyi
**~23 kat** daha az veriyle verir.

### Ölçülen hacim (float32, sıkıştırmasız üst sınır)

| Kapsam | Hücre | Aylık (2 değişken) | Günlük min | **Toplam** | Saatlik olsaydı |
|---|---|---|---|---|---|
| Pilot (İç Anadolu) | 1.581 | 4,3 MB | 66,1 MB | **70,4 MB** | 1.586 MB (23×) |
| Türkiye | 13.916 | 38,2 MB | 581,7 MB | **620 MB** | 13.960 MB (23×) |

NetCDF4 sıkıştırmasıyla gerçek boyut bunun altında kalır. Kesin rakam pilot
koşusunda ölçülüp rapora yazılacak.

### Birim tuzağı

`total_precipitation` aylık üründe **m/gün** birimindedir, ayın toplamı değil:

```
aylık toplam (mm) = değer × 1000 × o ayın gün sayısı
```

`02_build_grid.py` bunu uygular. (Google Earth Engine'in ERA5-Land aylık ürünü
FARKLI bir konvansiyon kullanır — o dokümanı referans alma.)

### Bilinen veri sorunu

ERA5-Land **aylık** ortalama ürününde **2022-09 → 2024-02** arasında yağışta
40 mm/ay'a varan tutarsızlık bildirildi. Üretim dönemimiz (1991-2020) bu
aralığın dışında. Dönem ileride uzatılırsa yeniden değerlendirilmeli.

---

## Hangi indisler bedava, hangileri değil

Kural: **indirme maliyetini artıran hiçbir indis hesaplanmaz.**

### Bedava (bu indirmeden çıkar) — hesaplanır ve saklanır

| İndis | Kaynak |
|---|---|
| `tavg[12]`, `prec[12]` | aylık ürün |
| `tmin[12]`, `abs_min` | günlük minimum |
| `mean_temp`, `annual_rain` | türev |
| `frost_days` (Tmin<0 gün/yıl) | günlük minimum |
| `last_spring_frost_doy`, `first_autumn_frost_doy` | günlük minimum |
| `frost_free_days` | yukarıdaki ikisinin farkı |
| `de_martonne` — kuraklık indeksi `P/(T+10)` | türev |
| `driest_quarter_mm` — en kurak 3 ardışık ay | türev |

Bunların hiçbiri **motora bağlanmaz** (direktif). Kolon olarak durur.

### Bedava DEĞİL — hesaplanmaz

| İndis | Ek maliyet | Neden |
|---|---|---|
| `tmax[12]` | +%100 günlük hacim | `daily_maximum` ayrı indirme ister; ayrıca `ClimateProfile`'da böyle bir alan yok |
| GDD (baz 10 °C) | +%100…200 | Günlük ORTALAMA ya da min+max ister. Aylık ortalamadan hesaplanan GDD farklı bir büyüklüktür, eşdeğeri değildir |
| Soğuklama saati (0-7,2 °C) | +~%2.300 | Tanımı gereği **saatlik** veri ister. Direktifle atlandı |

---

## Kurulum

```bash
python3 -m venv scripts/site-grid/.venv
source scripts/site-grid/.venv/bin/activate
pip install -r scripts/site-grid/requirements.txt
```

⚠️ Sistemde **Python 3.14** var (ölçüldü 2026-09-04). `netCDF4` ve bazı bilimsel
paketlerin 3.14 için hazır wheel'i olmayabilir. Derleme hatası alırsan
`python3.12 -m venv ...` ile kur.

### CDS anahtarı

1. https://cds.climate.copernicus.eu/ üzerinden hesap aç
2. İlgili veri setlerinin **Terms of use** sayfasını kabul et (aksi halde istek
   403 döner)
3. `~/.cdsapirc` oluştur:

```
url: https://cds.climate.copernicus.eu/api
key: <UID>:<API-KEY>
```

> 404 alıyorsan `.cdsapirc` eski `api/v2` adresini gösteriyordur; yeni CDS
> farklı bir uç ve yeni biçimde token kullanıyor.

---

## Kullanım

```bash
# 1) Hacim tahmini — indirme YAPMAZ, anahtar bile istemez
python3 scripts/site-grid/01_download_era5.py --estimate
python3 scripts/site-grid/01_download_era5.py --estimate --full

# 2) PİLOT indirme (İç Anadolu, ~70 MB)
python3 scripts/site-grid/01_download_era5.py

# 3) Izgara tablosunu üret
python3 scripts/site-grid/02_build_grid.py                # 1991-2020 (üretim)
python3 scripts/site-grid/02_build_grid.py --overlap      # 2015-2020 (eşdeğerlik)

# 4) Eşdeğerlik kapısı (TS tarafı, motoru gerçekten koşturur)
npx vitest run --config vitest.integration.config.ts \
  __tests__/lib/ne-yetisir/site-grid-equivalence.integration.test.ts

# 5) TÜRKİYE — YALNIZ ONAY SONRASI
python3 scripts/site-grid/01_download_era5.py --full --onayliyorum
```

### Neden pilot bbox Ankara'dan geniş

Eşdeğerlik kapısı mevcut Open-Meteo önbelleğiyle karşılaştırma yapıyor. Dar
Ankara kutusunda önbellekte **yalnız 4 nokta** var (ölçüldü 2026-09-04). İç
Anadolu koridoru (38-41 K / 30-35 D) bunu **7**'ye çıkarıyor ve hâlâ küçük
kalıyor. Örneklem az; rapor bunu gizlemez.

### `--overlap` neden var

Üretim ızgarası **1991-2020** (WMO normali), mevcut motor Open-Meteo'dan
**2015-2024** kullanıyor. İkisini doğrudan karşılaştırmak "sağlayıcı farkı" ile
"dönem farkı"nı birbirine karıştırır. `--overlap` **aynı indirmeden** 2015-2020
alt dönemini üretir, **ek indirme yoktur**, ve sağlayıcı farkını izole eder.

---

## Atıf (ZORUNLU)

CDS verileri 2 Temmuz 2025'ten beri CC-BY 4.0. Ticari kullanım ve yeniden
dağıtım serbest, **tek koşul atıf**:

```
Generated using Copernicus Climate Change Service information 2026
```

`config.COPERNICUS_ATTRIBUTION` sabitinde tutulur, her ızgara satırına yazılır
ve UI'daki "Veri kaynakları" bölümünde gösterilir (Faz 4).

## Çıktılar (git'e girmez)

```
scripts/site-grid/raw/   CDS ham NetCDF
scripts/site-grid/out/   site_grid_<kapsam>_<dönem>.csv
```