Metadata-Version: 2.4
Name: tr-nufus
Version: 0.1.0
Summary: Population projection methods for Turkish plan reports: arithmetic, geometric, exponential, logistic, İller Bankası, least-squares trend, ratio and cohort-component (Leslie) projections, TÜİK growth rates and MAPE back-testing.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YusufEminoglu/tr_nufus_sdk
Project-URL: Repository, https://github.com/YusufEminoglu/tr_nufus_sdk
Project-URL: Issues, https://github.com/YusufEminoglu/tr_nufus_sdk/issues
Project-URL: Changelog, https://github.com/YusufEminoglu/tr_nufus_sdk/blob/main/CHANGELOG.md
Keywords: population-projection,nufus-projeksiyonu,demography,urban-planning,imar-plani,iller-bankasi,tuik,adnks,logistic-growth,cohort-component,leslie-matrix,turkey,turkiye
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Natural Language :: Turkish
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Sociology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-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"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# tr-nufus

[![PyPI version](https://img.shields.io/pypi/v/tr-nufus.svg?color=10b981)](https://pypi.org/project/tr-nufus/)
[![Python version support](https://img.shields.io/pypi/pyversions/tr-nufus.svg?color=3b82f6)](https://pypi.org/project/tr-nufus/)
[![CI](https://github.com/YusufEminoglu/tr_nufus_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/tr_nufus_sdk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/YusufEminoglu/tr_nufus_sdk/blob/main/LICENSE)

**English summary.** `tr-nufus` implements the population projection methods
used in Turkish development-plan reports (*plan açıklama raporu*), İller
Bankası infrastructure projects and planning education: arithmetic, geometric,
exponential, logistic (three-point and least squares), the İller Bankası
method, least-squares trends, the ratio (share) method and a two-sex
cohort-component projection with Leslie matrices. It also computes TÜİK's
annual growth rate in per mille, doubling times, back-tests methods against
held-out census years (MAPE) and writes Turkish Markdown tables, from Python or
from the Turkish-language `tr-nufus` command line tool.

---

**Türkçe.** `tr-nufus`, imar planı açıklama raporlarında, İller Bankası
içmesuyu/kanalizasyon projelerinde ve şehir planlama derslerinde kullanılan
nüfus projeksiyonu yöntemlerini tek bir küçük Python paketinde toplar:

- **Aritmetik (doğrusal) artış**, **geometrik artış**, **üstel (eksponansiyel) artış**
- **İller Bankası yöntemi** (çoğalma katsayısı %1-%3 aralığına sınırlanır; kaynağı aşağıda)
- **Lojistik eğri**: eşit aralıklı üç sayımdan (Pearl-Reed) ve en küçük kareler ile
- **En küçük kareler doğrusal / polinom trendi**
- **Oran (pay) yöntemi**: ilçenin il (ya da bölge) projeksiyonundaki payı
- **Kohort bileşenler yöntemi**: yaş grubu × cinsiyet, hayatta kalma oranları,
  doğurganlık, net göç; Leslie matrisi
- TÜİK tanımıyla **yıllık nüfus artış hızı (‰)**, **ikiye katlanma süresi**
- Son sayım(lar)ı dışarıda bırakarak **yöntem karşılaştırması (MAPE)**
- Plan raporuna doğrudan yapıştırılabilen **Türkçe Markdown / CSV tablolar**

Tek bağımlılık `numpy`'dir. Python 3.9 ve üzeri gerekir.

> **Veri notu.** Paket TÜİK verisi içermez. ADNKS (Adrese Dayalı Nüfus Kayıt
> Sistemi) ve genel nüfus sayımı rakamlarını kendiniz
> [TÜİK Veri Portalı](https://data.tuik.gov.tr)'ndan alıp verirsiniz. Örneklerde
> kullanılan "Örnekkent" verileri **tamamen varsayımsaldır**.

## Kurulum

```bash
pip install tr-nufus
```

## Hızlı başlangıç (komut satırı)

Girdi, iki sütunlu bir CSV dosyasıdır (`;`, `,` veya sekme ile ayrılmış;
`yil;nufus`, `Yıl;Nüfus`, `year,population` gibi başlıklar tanınır;
`1.234.567` biçimindeki binlik ayraçları okunur):

```text
yil;nufus
1990;38400
2000;46900
2010;55300
2015;59800
2020;63900
2023;66100
```

```bash
tr-nufus ornek > ornekkent.csv            # varsayımsal örnek veri
tr-nufus hiz ornekkent.csv                # dönemlik yıllık artış hızı (‰)
tr-nufus projeksiyon ornekkent.csv --hedef 2030 2040 2058
tr-nufus karsilastir ornekkent.csv --test 1
tr-nufus projeksiyon ornekkent.csv --rapor --test 1 -o nufus_bolumu.md
tr-nufus hiz --seri "2017=80810525,2018=82003882,2019=83154997"
```

`tr-nufus projeksiyon ornekkent.csv --hedef 2030 2040 2058` çıktısı:

| Yöntem | 2030 | 2040 | 2058 | Parametre |
| :--- | ---: | ---: | ---: | :--- |
| Aritmetik artış | 71.976 | 80.370 | 95.479 | ka = 839,4 kişi/yıl |
| Geometrik artış | 74.171 | 87.440 | 117.589 | r = %1,659 /yıl |
| Üstel (eksponansiyel) artış (en küçük kareler) | 75.640 | 89.170 | 119.911 | r = ‰16,46 /yıl |
| İller Bankası yöntemi | 74.171 | 87.440 | 117.589 | Ç = %1,659 |
| Lojistik eğri (en küçük kareler) | 71.422 | 78.032 | 87.103 | K = 100.806, r = 0,0343 /yıl, bükülme yılı ≈ 2004,1 |
| Lojistik eğri (üç nokta: 2000, 2010, 2020) | 72.355 | 80.344 | 92.800 | K = 120.597, r = 0,0286 /yıl, bükülme yılı ≈ 2015,8 |
| En küçük kareler doğrusal trend | 72.250 | 80.701 | 95.912 | P = 55.067 + 845,084·x, x = t − 2009,7 |
| En küçük kareler 2. derece polinom | 71.994 | 80.087 | 94.337 | P = 55.150 + 841,206·x − 0,630·x², x = t − 2009,7 |

`tr-nufus karsilastir ornekkent.csv --test 1` (yöntemler 1990-2020 verisiyle
kurulur, 2023 değeriyle sınanır):

| Sıra | Yöntem | 2023 tahmini | MAPE (%) |
| :--- | :--- | ---: | ---: |
| Gerçek | TÜİK / sayım değeri | 66.100 | - |
| 1 | Lojistik eğri (en küçük kareler) | 66.338 | 0,36 |
| 2 | Aritmetik artış | 66.450 | 0,53 |
| 3 | Lojistik eğri (üç nokta) | 66.467 | 0,56 |
| ... | ... | ... | ... |

Komutlar:

| Komut | İşlev |
| :--- | :--- |
| `hiz` | Ardışık sayımlar arası nüfus artışı, yıllık artış hızı (‰), bileşik artış (%), ikiye katlanma süresi |
| `projeksiyon` | Hedef yıllar için yöntem tablosu; `--rapor` ile tam plan raporu bölümü (geçmiş gelişim + projeksiyon + `--test` ile sınama) |
| `karsilastir` | Son `--test` sayımı dışarıda bırakıp her yöntemi sınar, MAPE'ye göre sıralar |
| `kohort` | JSON yapılandırmasından kohort bileşenler projeksiyonu (`--yil` ile yaş-cinsiyet tablosu) |
| `ornek` | Varsayımsal örnek CSV; `--kohort` ile örnek kohort yapılandırması (JSON) |
| `yontemler` | Yöntem anahtarlarını listeler |

Önemli seçenekler: `--yontem aritmetik iller_bankasi lojistik ...`,
`--hedef 2030 2035`, `--ufuk 35 --adim 5` (hedef verilmezse son sayımdan
sonraki 35 yıl, 5'er yıllık), `--ilbank-mod endpoints|mean_consecutive`,
`--sinirsiz` (İller Bankası %1-%3 sınırını kaldırır), `--doygunluk K`
(lojistik doygunluk nüfusu), `--derece 2`, `--bicim markdown|text|csv`, `-o dosya`.

## Python API

```python
from tr_nufus import (
    CensusSeries, fit, fit_iller_bankasi, fit_logistic_three_point, fit_ratio,
    annual_growth_rate_permille, doubling_time, compare_methods,
    projection_table, plan_report,
)

s = CensusSeries.from_csv("ornekkent.csv", name="Örnekkent")
# ya da: CensusSeries.from_mapping({2000: 46_900, 2010: 55_300, 2023: 66_100})

annual_growth_rate_permille(82_003_882, 83_154_997, 1)   # 13.94 (TÜİK: binde 13,9)
doubling_time(16.46)                                     # 42.1 yıl

ib = fit_iller_bankasi(s)                 # İller Bankası 2013: ilk ve son sayım
ib.params                                 # {'k': 1.659, 's': 1.659, 't_s': 2023.0, 'P_s': 66100.0}
ib.at(2058)                               # 117 589
fit_iller_bankasi(s, mode="mean_consecutive")   # ÇŞB 2018: ardışık oranların ortalaması
fit_iller_bankasi(s, bounds=None)               # sınırsız (geometrik)

lojistik = fit_logistic_three_point(s)    # eşit aralıklı 2000-2010-2020
lojistik.params["K"]                      # doygunluk nüfusu

models = [fit(s, k) for k in ("aritmetik", "geometrik", "iller_bankasi", "lojistik")]
print(projection_table(models, [2030, 2040, 2050]))

comp = compare_methods(s, n_test=1)       # son sayımı dışarıda bırak, MAPE
comp.best.label, comp.best.mape
print(plan_report(s, models, [2030, 2040, 2050], comp))
```

Oran yöntemi (ilçenin il projeksiyonundaki payı); büyük alanın gelecekteki
nüfusu bir sözlük (örneğin TÜİK il projeksiyonu) ya da başka bir modeldir:

```python
ilce = CensusSeries.from_mapping({2010: 52_000, 2020: 61_000})
il = CensusSeries.from_mapping({2010: 1_050_000, 2020: 1_160_000})
m = fit_ratio(ilce, il, {2030: 1_260_000, 2040: 1_330_000}, trend="linear")
m.predict([2030, 2040])
```

Kohort bileşenler yöntemi:

```python
from tr_nufus import CohortComponentModel, example_cohort_config, leslie_matrix, dominant_growth

model = CohortComponentModel(
    base_female=[...], base_male=[...],            # 0-4, 5-9, ..., 65+ (n grup)
    survival_female=[...], survival_male=[...],    # S[i] = nL(i+1)/nL(i); son değer açık grup
    fertility=[...],                               # yaşa özel yıllık doğurganlık hızları
    birth_survival_female=0.992, birth_survival_male=0.990,   # 5L0 / (5·l0)
    srb=1.05,                                      # doğumda cinsiyet oranı (erkek/kız)
    net_migration_female=[...], net_migration_male=[...],     # 5 yıllık net göç
    base_year=2023, timing="end",                  # göç dönem sonunda ya da "half"
)
proj = model.project(steps=4)                      # 2023, 2028, ..., 2043
proj.as_dict(); proj.age_table(2033)
lam, r = dominant_growth(model.leslie_female)      # kapalı nüfusun içsel artış hızı
```

Hayat tablosundan hayatta kalma oranları: `survival_ratios_from_Lx(nLx)`.
Örnek yapılandırma: `tr-nufus ornek --kohort` ya da `example_cohort_config()`
(varsayımsal).

### API özeti

| Nesne | Açıklama |
| :--- | :--- |
| `CensusSeries` | Yıl → nüfus serisi; `from_mapping`, `from_pairs`, `from_csv`, `split`, `subset` |
| `annual_growth_rate_permille`, `doubling_time`, `interval_rates`, `overall_rate` | Artış hızları |
| `fit_arithmetic`, `fit_geometric`, `fit_exponential` | `mode="endpoints"`, `"mean_consecutive"` (üstelde ayrıca `"least_squares"`) |
| `fit_iller_bankasi` | `mode=`, `bounds=(1, 3)` |
| `fit_logistic_three_point`, `fit_logistic` | Lojistik; `saturation=` ile K verilebilir |
| `fit_polynomial`, `fit_linear_trend` | En küçük kareler trendi |
| `fit_ratio` | Oran (pay) yöntemi; `trend="constant" / "mean" / "linear"` |
| `fit(series, "anahtar")`, `METHODS` | Anahtarla yöntem seçimi |
| `Projection.predict`, `.at`, `.params`, `.label`, `.formula` | Ortak model arayüzü |
| `CohortComponentModel`, `leslie_matrix`, `dominant_growth`, `survival_ratios_from_Lx` | Kohort bileşenler |
| `compare_methods`, `mape` | Sınama |
| `growth_table`, `projection_table`, `comparison_table`, `cohort_table`, `plan_report`, `format_tr` | Türkçe tablolar |

Yöntem anahtarları: `aritmetik`, `geometrik`, `ustel`, `iller_bankasi`,
`lojistik`, `lojistik_3nokta`, `dogrusal_trend`, `polinom` (İngilizce takma
adlar da kabul edilir: `arithmetic`, `geometric`, `exponential`, `logistic`,
`logistic3`, `linear_trend`, `polynomial`). `fit(s, "ustel")` en küçük kareler
üstel eğrisini verir; iki uç sayıma dayalı üstel model `fit_exponential(s)`
ile alınır ve geometrik modelle aynı projeksiyonu üretir.

## Yöntemler, formüller ve kaynaklar

Gösterim: `NS`, `tS` son sayım; `NE`, `tE` ilk sayım; `NG` hedef yıl `tG`
nüfusu. Sayım temelli yöntemler (aritmetik, geometrik, üstel, İller Bankası)
**son sayımdan başlar**; en küçük kareler yöntemleri eğrinin kendisini kullanır.

**TÜİK yıllık nüfus artış hızı (‰).** `r = ln(Pt / P0) / t × 1000`. TÜİK ADNKS
haber bültenlerinde yayımlanan değerlerle sınandı (testlerde): Türkiye nüfusu
2017→2018 binde 14,7; 2018→2019 binde 13,9; 2022→2023 binde 1,1; 2023→2024
binde 3,4; 2024→2025 binde 5,0. 2018→2019 için basit yüzde değişim binde 14,0
verirdi; yayımlanan 13,9 logaritmik tanımı doğrular. İkiye katlanma süresi
`T = ln 2 / (r/1000)`.

**Aritmetik artış.** `ka = (NS − NE) / (tS − tE)`, `NG = NS + ka (tG − tS)`
(İller Bankası 2013, Ek-1). `mode="mean_consecutive"`: ardışık dönemlerin
yıllık artışlarının ortalaması (ÇŞB 2018, Ek-1 md. 1.3.2.1.1).

**Geometrik / üstel artış.** `r = [(NS/NE)^(1/(tS−tE)) − 1]`,
`NG = NS (1 + r)^(tG−tS)`; üstel: `r = (ln NS − ln NE)/(tS − tE)`,
`NG = NS e^(r (tG−tS))` (İller Bankası 2013, Ek-1 "Geometrik Artış
(Eksponansiyel) Yöntemi"; ÇŞB 2018 denklem 1.3.b-c ardışık hızların
ortalamasıyla). İki uç noktadan kurulduğunda iki model aynı sonucu verir.

**İller Bankası yöntemi.** Geometrik artışın sınırlandırılmış biçimidir:

```text
Ç  = [ (NS / NE)^(1 / (tS − tE)) − 1 ] × 100        (çoğalma katsayısı, %)
Ç < 1 ise Ç = 1;   1 ≤ Ç ≤ 3 ise Ç;   Ç > 3 ise Ç = 3
NG = NS × (1 + Ç/100)^(tG − tS)
```

- *İller Bankası A.Ş., İçmesuyu Tesisleri Etüt, Fizibilite ve Projelerinin
  Hazırlanmasına Ait Teknik Şartname (2013)*, md. 4.4.2 ve Ek-1 "Nüfus
  Projeksiyonu Yöntemleri": Ç ilk (`NE`) ve son (`NS`) sayımdan hesaplanır;
  nüfus projeksiyonunda biri İller Bankası yöntemi olmak üzere en az üç yöntem
  kullanılır; inşaat bitiminden sonra 30 yıl + işletmeye alınmaya kadar 5 yıl
  = 5'er yıllık aralıklarla 35 yıllık projeksiyon (`NG = NS (1+Ç/100)^(n+5+30)`).
  [jmo.org.tr kopyası](https://www.jmo.org.tr/mevzuat/mevzuat_detay_pdf.php?kod=233)
- *T.C. Çevre ve Şehircilik Bakanlığı, Kanalizasyon Sistemlerinin Etüt, Planlama
  ve Projelendirilmesine İlişkin Teknik Esaslar, Ek-1 (2018)*, md. 1.3.2.1.2,
  denklem 1.2.b-d: ardışık sayımlar için `s` değerlerinin aritmetik ortalaması
  alınır ve `k = 1 (s̄ < 1)`, `k = s̄ (1 ≤ s̄ ≤ 3)`, `k = 3 (s̄ > 3)` uygulanır.
  [csb.gov.tr](https://webdosya.csb.gov.tr/db/altyapi/icerikler/ekler-20180215122652.pdf)

`fit_iller_bankasi(mode="endpoints")` (varsayılan) İller Bankası 2013
şartnamesini, `mode="mean_consecutive"` ÇŞB 2018 esaslarını izler. Sınırlar
`bounds=` ile değiştirilebilir ya da kaldırılabilir.

**Lojistik eğri.** `P(t) = K / (1 + m e^(−r (t − t0)))` (Pearl & Reed 1920).
Eşit aralıklı (`n` yıl) üç sayım `P0, P1, P2` için:
`K = (2 P0 P1 P2 − P1² (P0 + P2)) / (P0 P2 − P1²)`, `m = (K − P0)/P0`,
`r = (1/n) ln[P1 (K − P0) / (P0 (K − P1))]`. Yalnızca artış yavaşlıyorsa
(`P1² > P0 P2`) doygunluk nüfusu vardır; aksi halde hata verilir. En küçük
kareler sürümü (`fit_logistic`) herhangi sayıda ve aralıkta sayım kullanır:
`K` taraması ve altın oran araması ile başlangıç değerleri bulunur, ardından
`(K, m, r)` Levenberg-Marquardt ile nüfus biriminde hata kareleri toplamını
en aza indirecek biçimde iyileştirilir. Doygunluk nüfusu plandan biliniyorsa
`saturation=` ile verilebilir.

**En küçük kareler trendi.** `numpy.polyfit` ile yıllar ortalamaya göre
merkezlenerek doğrusal ya da polinom eğri. Yüksek dereceler dışa
kestirimde kararsızdır; 1. veya 2. derece önerilir.

**Oran (pay) yöntemi.** `P(t) = s(t) × P_büyük(t)`, `s = P_küçük / P_büyük`;
pay sabit (son pay), ortalama ya da doğrusal eğilimle sürdürülür (Smith,
Tayman & Swanson 2013, *A Practitioner's Guide to State and Local Population
Projections*, Springer).

**Kohort bileşenler yöntemi.** Preston, Heuveline & Guillot (2001),
*Demography: Measuring and Modeling Population Processes*, böl. 6; Leslie
(1945), *Biometrika* 33(3). Bir adım = yaş grubu genişliği (genellikle 5 yıl):

```text
W(i+1, t+5) = S(i) · W(i, t)                      (son grup: S(n−2)·W(n−2) + S(n−1)·W(n−1))
Doğumlar    = 5/2 · Σ [ f(i) + f(i+1) · S(i) ] · W(i, t)
Kız 0-4     = Doğumlar · bs_k / (1 + SRB),  Erkek 0-4 = Doğumlar · bs_e · SRB / (1 + SRB)
```

Net göç dönem sonunda eklenir (`timing="end"`) ya da yarısı dönem başında,
yarısı sonunda (`timing="half"`). Kadın Leslie matrisinin baskın özdeğeri
`λ` kapalı nüfusun 5 yıllık artış çarpanıdır (`dominant_growth`).

**MAPE.** `100/n × Σ |Gerçek − Tahmin| / Gerçek`. `compare_methods` modeli
son `n_test` gözlem dışarıda bırakılarak kurar ve bu gözlemlerle sınar.

## Sınırlar ve uyarılar

- Matematiksel yöntemler geçmiş eğilimi sürdürür; göç, imar planı kararları,
  afet sonrası yer değiştirme, üniversite / askeri nüfus ve mevsimlik nüfus ayrıca
  değerlendirilmelidir (İller Bankası 2013, md. 4.4.2 de bunu ister).
- İller Bankası yöntemi varsayılan sınırlarla nüfusu azalan bir yerleşimi bile
  yılda %1 artırır; bu yöntemin özelliğidir, raporda belirtin.
- 2007 öncesi genel nüfus sayımları (Ekim ayı, *de facto*) ile ADNKS (31
  Aralık, ikamet esaslı) sonuçları doğrudan karşılaştırılabilir değildir; kesirli
  yıl (örn. 2000,79) girilebilir ama tanım farkını paket düzeltmez.
- Kohort modeli sabit oranlar kullanır (oranları dönem dönem değiştirmez);
  açık yaş grubu için Preston ve ark. (2001) yaklaşımı uygulanır.
- `srb=1.05` (100 kıza 105 erkek) genel biyolojik varsayılandır; bölgesel değer
  için TÜİK doğum istatistiklerini kullanın. Örnek kohort verileri uydurmadır.
- Lojistik en küçük kareler çözümü sayısaldır; doygunluk eğilimi zayıf
  verilerde `K` çok belirsizdir, sonucu fiziksel kapasiteyle (plan nüfusu)
  karşılaştırın.

## Geliştirme

```bash
pip install -e ".[dev]"
pytest --cov=tr_nufus
ruff check . && ruff format --check src tests && mypy src
```

Testler ağ kullanmaz; elle hesaplanmış örnekler, tam lojistik / üstel / ikinci
derece eğrilerin geri elde edilmesi ve TÜİK bültenlerindeki artış hızlarıyla
doğrulama içerir.

## Lisans

MIT © 2026 Yusuf Eminoğlu. Bkz. [LICENSE](LICENSE). Atıf için
[CITATION.cff](CITATION.cff).

## Academic citation

```bibtex
@software{eminoglu_tr_nufus,
  author  = {Eminoğlu, Yusuf},
  title   = {tr-nufus},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/YusufEminoglu/tr_nufus_sdk}
}
```

İletişim: geospacephilo@gmail.com
