tr-nufus 0.1.0__tar.gz

tr_nufus-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `CensusSeries`: census / ADNKS series from dicts, pairs or CSV (`;`, `,`, tab; Turkish
+  and English column names; Turkish thousands separators), train/test split.
+- TÜİK annual growth rate in per mille (`r = ln(Pt/P0)/t × 1000`), compound rate,
+  doubling time, interval growth table.
+- Projection methods: arithmetic, geometric, exponential (endpoints, mean of consecutive
+  intervals, least squares), İller Bankası (first-last census per İller Bankası 2013, or
+  mean of consecutive rates per ÇŞB 2018; 1 %-3 % bounds, overridable), logistic
+  (three equally spaced censuses and least squares with Levenberg-Marquardt polish),
+  least-squares linear and polynomial trend, ratio (share of a larger area).
+- Two-sex cohort-component projection with Leslie matrices (survival ratios, age-specific
+  fertility, sex ratio at birth, net migration at end or half-period), dominant eigenvalue,
+  survival ratios from life-table `nLx`.
+- Back-testing against held-out census years with MAPE.
+- Turkish report tables (Markdown / text / CSV) and a plan-report section generator.
+- `tr-nufus` command line interface in Turkish: `hiz`, `projeksiyon`, `karsilastir`,
+  `kohort`, `ornek`, `yontemler`.

tr_nufus-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "tr-nufus"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/tr_nufus_sdk"
+url: "https://pypi.org/project/tr-nufus/"
+abstract: "Population projection methods used in Turkish plan reports and planning education: arithmetic, geometric, exponential, logistic (three-point and least squares), İller Bankası, least-squares polynomial trend, ratio (share) and two-sex cohort-component projection with Leslie matrices; TÜİK annual growth rate (per mille), doubling time, MAPE back-testing against held-out censuses and Turkish Markdown report tables."
+keywords:
+  - population projection
+  - demography
+  - urban planning
+  - İller Bankası
+  - TÜİK
+  - cohort-component
+  - Leslie matrix

tr_nufus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tr_nufus-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/tr_nufus/py.typed
+recursive-include src/tr_nufus *.py
+recursive-include tests *.py
+recursive-include examples *.py *.csv *.json

tr_nufus-0.1.0/PKG-INFO

@@ -0,0 +1,374 @@
+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