cohortproj 0.1.0__tar.gz

cohortproj-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+### Added
+- Abridged and single-year period life tables from death rates or deaths and exposure,
+  with mid-point, constant-hazard, Coale-Demeny (ages 0 and 1-4), Keyfitz iterative or
+  user-supplied `nax`; optional `qx` input; collapsing of 0 and 1-4 into 0-4; mortality
+  scaling.
+- Survival ratios for projection steps, including the open age group and births.
+- Fertility measures: ASFR, TFR, GRR, NRR, mean age of childbearing, rescaling to a target
+  TFR, placement of reproductive-age schedules on full age groups.
+- Cohort-component projection for one or both sexes with net migration as counts or
+  annual rates (end, start or half timing) and time-varying schedules.
+- Leslie matrices, Leslie projection, stable population (growth rate, stable age
+  distribution, reproductive values, damping ratio, birth rate) and Lotka's intrinsic rate.
+- Simple one-sex multiregional and two-region projection, equivalent growth matrix and
+  long-run regional shares.
+- Age-structure indicators: dependency ratios, ageing index, support ratio, median and mean
+  age, sex ratios, population-pyramid data.
+- Scenario runs with fertility, mortality and migration variants and a comparison table.
+- CSV / JSON I/O and the command line: `cohortproj lifetable | project | stable | structure`.
+
+### Fixed
+- `leslie_matrix(..., open_group=False)`: the survival ratio into the last group used
+  `nL` of the open group (`T_A`) over `nL(A-n)`, which can exceed 1 under low mortality;
+  it now uses `T_A / T_(A-n)`.

cohortproj-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+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: "cohortproj"
+version: "0.1.0"
+date-released: "2026-11-15"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/cohortproj_sdk"
+url: "https://pypi.org/project/cohortproj/"
+abstract: "Cohort-component population projection following Preston, Heuveline and Guillot (2001): abridged and single-year life tables with standard nax choices, survival ratios, age-specific fertility, TFR, GRR and NRR, net migration as counts or rates, Leslie matrices, stable population and Lotka's intrinsic growth rate, a simple multiregional extension, age-structure indicators and scenario runs."
+keywords:
+  - demography
+  - population projection
+  - cohort-component method
+  - life table
+  - Leslie matrix
+  - stable population

cohortproj-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.

cohortproj-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/cohortproj/py.typed
+recursive-include src/cohortproj *.py
+recursive-include tests *.py
+recursive-include examples *.py

cohortproj-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: cohortproj
+Version: 0.1.0
+Summary: Cohort-component population projection: abridged and single-year life tables, survival ratios, fertility measures, migration, Leslie matrices, stable population, a simple multiregional model, age-structure indicators and scenario runs.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/geophilo1/cohortproj_sdk
+Project-URL: Repository, https://gitlab.com/geophilo1/cohortproj_sdk
+Project-URL: Issues, https://gitlab.com/geophilo1/cohortproj_sdk/-/work_items
+Project-URL: Changelog, https://gitlab.com/geophilo1/cohortproj_sdk/-/blob/main/CHANGELOG.md
+Keywords: demography,population-projection,cohort-component,life-table,leslie-matrix,stable-population,fertility,mortality,migration,multiregional,dependency-ratio,population-pyramid,urban-planning
+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: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+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
+
+# cohortproj
+
+[![PyPI](https://img.shields.io/pypi/v/cohortproj.svg)](https://pypi.org/project/cohortproj/)
+[![Python](https://img.shields.io/pypi/pyversions/cohortproj.svg)](https://pypi.org/project/cohortproj/)
+[![pipeline](https://gitlab.com/geophilo1/cohortproj_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/cohortproj_sdk/-/pipelines)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/cohortproj_sdk/-/blob/main/LICENSE)
+
+**Cohort-component population projection, life tables and Leslie matrices in plain NumPy.**
+
+`cohortproj` implements the standard demographic toolkit of Preston, Heuveline & Guillot,
+*Demography: Measuring and Modeling Population Processes* (2001):
+
+- **Life tables**: abridged (0, 1-4, 5-9, ...) and single-year period life tables from
+  death rates or deaths and exposure: `nqx`, `lx`, `ndx`, `nLx`, `Tx`, `ex`, with `nax`
+  by mid-point, constant hazard, Coale-Demeny (ages 0 and 1-4), Keyfitz's iterative
+  graduation, or user-supplied values.
+- **Survival ratios** for projection steps, including the open age group and births.
+- **Fertility**: age-specific rates, TFR, GRR, NRR, mean age of childbearing, rescaling to a
+  target TFR; the sex ratio at birth is always an explicit input.
+- **Cohort-component projection** for one or both sexes, with net migration as counts or
+  annual rates and a stated timing convention, constant or time-varying schedules.
+- **Leslie matrices**, the **stable population** (intrinsic growth rate, stable age
+  distribution, reproductive values, damping ratio) and the intrinsic rate from Lotka's
+  equation.
+- **Multiregional extension**: a simple one-sex multi-region (and two-region) projection
+  with age-specific transition probabilities, its equivalent growth matrix and long-run
+  regional shares.
+- **Age structure**: dependency ratios, ageing index, support ratio, median and mean age,
+  sex ratios and population-pyramid data.
+- **Scenarios**: fertility, mortality and migration variants run side by side.
+
+It needs only NumPy. A command-line tool reads CSV tables and writes JSON and CSV.
+
+## Installation
+
+```bash
+pip install cohortproj
+```
+
+Requires Python 3.9 or newer.
+
+## Quickstart
+
+```python
+import numpy as np
+import cohortproj as cp
+
+# abridged life table from death rates (0, 1-4, 5-9, ..., 85+)
+lt_ages = cp.abridged_ages(85)
+female_lt = cp.life_table(mx_female, lt_ages, nax="coale-demeny", sex="female")
+male_lt = cp.life_table(mx_male, lt_ages, nax="coale-demeny", sex="male")
+female_lt.e0, female_lt.records()
+
+# projection on 5-year groups 0-4 ... 85+ (abridged tables are collapsed to 0-4)
+ages = cp.regular_ages(5, 85)
+asfr = cp.expand_asfr([0.02, 0.09, 0.12, 0.09, 0.04, 0.01, 0.002], 15, ages)
+proj = cp.project(female, ages, female_lt, asfr, srb=1.05, steps=6,
+                  male=male, male_life=male_lt,
+                  migration_female=mig_f, migration_male=mig_m,
+                  timing="half", start_year=2025)
+proj.total, proj.summary(), proj.records()
+
+# stable population
+les = cp.leslie_matrix(female_lt, asfr, srb=1.05)
+st = cp.stable_population(les)
+st.growth_rate, st.age_distribution, st.reproductive_values
+cp.intrinsic_growth_rate(asfr, female_lt, srb=1.05)     # Lotka
+
+# age structure
+s = cp.age_structure(proj.female[-1], ages, proj.male[-1])
+s.median_age, s.dependency["old"]
+cp.pyramid(proj.female[-1], proj.male[-1], ages)
+```
+
+Scenarios:
+
+```python
+base = cp.ProjectionInputs(female=female, ages=ages, female_life=female_lt, asfr=asfr,
+                           srb=1.05, steps=6, male=male, male_life=male_lt)
+runs = cp.run_scenarios(base, [
+    cp.Scenario("medium"),
+    cp.Scenario("low", tfr=cp.linear_path(1.9, 1.3, 6)),
+    cp.Scenario("higher mortality", mortality_factor=1.2),
+    cp.Scenario("closed", migration_factor=0.0),
+])
+runs.table            # year-by-year totals, TFR, median age, dependency ratios
+runs.final("total")
+```
+
+Two regions:
+
+```python
+mr = cp.two_region_project(pop_urban, pop_rural, ages, lt_urban, lt_rural,
+                           asfr_urban, asfr_rural, out_1_to_2=0.02, out_2_to_1=0.06,
+                           srb=1.05, steps=10, names=("urban", "rural"))
+mr.totals
+cp.multiregional_stable([lt_urban, lt_rural], np.vstack([asfr_urban, asfr_rural]),
+                        migration, srb=1.05, n_ages=ages.size).regional_shares
+```
+
+## Command line
+
+```bash
+cohortproj lifetable life_female.csv --nax coale-demeny --sex female --csv lt.csv
+cohortproj project input.csv --srb 1.05 --steps 6 --start-year 2025 \
+    --life-female life_female.csv --life-male life_male.csv --nax coale-demeny \
+    --timing half --csv projection_long.csv -o projection.json
+cohortproj stable input.csv --srb 1.05 --life-female life_female.csv --matrix
+cohortproj structure population.csv --csv pyramid.csv
+```
+
+CSV columns: `age` (lower bounds or labels such as `5-9` and `85+`) plus `mx` (or `deaths`
+and `exposure`, optional `ax` and `qx`) for life tables; `female`, `asfr` and optionally
+`male`, `mx_female`, `mx_male`, `migration_female`, `migration_male` for projections.
+Every command prints JSON or writes it with `-o`.
+
+## API overview
+
+| Area | Functions / classes |
+| --- | --- |
+| Life tables | `life_table -> LifeTable` (`records()`, `collapse_infant()`, `scaled()`), `life_table_from_deaths`, `coale_demeny_a0`, `coale_demeny_a1`, `mx_to_qx`, `qx_to_mx`, `NAX_METHODS` |
+| Survival | `survival_ratios -> SurvivalRatios` |
+| Fertility | `asfr`, `tfr`, `grr`, `nrr`, `mean_age_childbearing`, `scale_to_tfr`, `expand_asfr`, `fraction_female` |
+| Projection | `project -> Projection` (`total`, `summary()`, `records()`, `to_dict()`) |
+| Leslie / stable | `leslie_matrix -> LeslieMatrix`, `project_leslie`, `stable_population -> StablePopulation`, `intrinsic_growth_rate` |
+| Multiregional | `multiregional_project`, `two_region_project -> MultiRegionProjection`, `growth_matrix`, `multiregional_stable` |
+| Structure | `dependency_ratios`, `median_age`, `mean_age`, `pyramid`, `sex_ratios`, `age_structure`, `structure_series` |
+| Scenarios | `ProjectionInputs`, `Scenario`, `run_scenario`, `run_scenarios -> ScenarioComparison`, `linear_path` |
+| Helpers / I/O | `abridged_ages`, `regular_ages`, `age_labels`, `read_table`, `write_records`, `write_json` |
+
+## Methods and sources
+
+| Item | Definition | Source |
+| --- | --- | --- |
+| `nqx` | `n m / (1 + (n - a) m)`; open group `q = 1`, `L = l / m` | Preston et al. (2001), ch. 3 |
+| `nax`, mid-point | `n / 2` | Preston et al. (2001), ch. 3 |
+| `nax`, constant hazard | `1/m - n e^(-nm) / (1 - e^(-nm))`, `q = 1 - e^(-nm)` | Preston et al. (2001), §3.3 |
+| `nax`, Coale-Demeny | `1a0`, `4a1` as linear functions of `1m0` (Table 3.3) | Coale & Demeny (1983) via Preston et al. (2001) |
+| `nax`, Keyfitz | `(-(n/24) d(x-n) + (n/2) d(x) + (n/24) d(x+n)) / d(x)`, iterated | Keyfitz (1966); Preston et al. (2001) |
+| Survival ratios | `nL(x+n)/nLx`; open `T_A/T_(A-n)`; births `nL0/(n l0)` | Preston et al. (2001), §6.2 |
+| Births | `n sum F_x (N^F_x(t) + N^F_x(t+n)) / 2`, split by `1/(1+SRB)` | Preston et al. (2001), §6.2 |
+| TFR, GRR, NRR | `n sum F`; `TFR/(1+SRB)`; `sum F L / l0 /(1+SRB)` | Preston et al. (2001), ch. 5 |
+| Leslie matrix | first row `nL0/(2 l0) (F_x + F_(x+n) s_x) / (1+SRB)`, sub-diagonal `s_x` | Leslie (1945); Preston et al. (2001), §6.5 |
+| Intrinsic rate | `sum e^(-r(x+n/2)) F_x L_x / l0 / (1+SRB) = 1` | Lotka (1939); Preston et al. (2001), ch. 7 |
+| Multiregional | survive, then move survivors with age-specific transition probabilities | after Rogers (1975), simplified |
+| Dependency ratios | `100 P(0-14)/P(15-64)`, `100 P(65+)/P(15-64)` (bounds are parameters) | United Nations convention |
+
+### Conventions and assumptions
+
+- **Migration timing.** Net migrant counts are indexed by age group at the **end** of a
+  step. `timing="end"` adds them after survival; `"start"` applies the cohort's survival
+  ratio (they arrive at the start); `"half"` splits them between the two. Newborn migrants
+  are added at the end. Annual rates become counts as `rate n (N_x(t) + N*_x(t+n)) / 2`
+  with `N*` the closed projection.
+- **Deaths** in the projection summary are the balancing item
+  `N(t) + births + migrants - N(t+n)`; with `"start"` or `"half"` timing they include
+  deaths of migrants.
+- **Leslie and projection agree exactly**: for a female population without migration the
+  Leslie matrix reproduces `project()` to rounding.
+- **No defaults for population assumptions**: the sex ratio at birth, `nax` values beyond
+  the Coale-Demeny ages, fertility and migration schedules and scenario variants are
+  always the user's choice. The 15 / 65 dependency bounds follow the UN convention and can
+  be changed.
+- `nqx` is capped at 1 when very high death rates would push it above 1; check such input.
+
+## Limitations
+
+- The multiregional model is a projection device with transition probabilities, not
+  Rogers' full multiregional life table, and is one-sex (female).
+- Projection steps must equal the age-group width (5-year groups with 5-year steps,
+  single years with 1-year steps).
+- No model life tables, mortality forecasting (Lee-Carter) or fertility models are bundled;
+  supply the schedules.
+- The mean age of an open age group needs a representative age (`open_mean`); the default
+  is only a rough approximation.
+
+## References
+
+- Coale, A. J. & Demeny, P. (1983). *Regional Model Life Tables and Stable Populations*,
+  2nd ed. Academic Press, New York.
+- Keyfitz, N. (1966). A life table that agrees with the data. *Journal of the American
+  Statistical Association* 61(314), 305-312.
+- Leslie, P. H. (1945). On the use of matrices in certain population mathematics.
+  *Biometrika* 33(3), 183-212.
+- Lotka, A. J. (1939). *Théorie analytique des associations biologiques. Deuxième partie:
+  analyse démographique avec application particulière à l'espèce humaine*. Hermann, Paris.
+- Preston, S. H., Heuveline, P. & Guillot, M. (2001). *Demography: Measuring and Modeling
+  Population Processes*. Blackwell, Oxford.
+- Rogers, A. (1975). *Introduction to Multiregional Mathematical Demography*. Wiley, New
+  York.
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_cohortproj,
+  author  = {Eminoğlu, Yusuf},
+  title   = {cohortproj},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://gitlab.com/geophilo1/cohortproj_sdk}
+}
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

cohortproj-0.1.0/README.md

@@ -0,0 +1,206 @@
+# cohortproj
+
+[![PyPI](https://img.shields.io/pypi/v/cohortproj.svg)](https://pypi.org/project/cohortproj/)
+[![Python](https://img.shields.io/pypi/pyversions/cohortproj.svg)](https://pypi.org/project/cohortproj/)
+[![pipeline](https://gitlab.com/geophilo1/cohortproj_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/cohortproj_sdk/-/pipelines)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/cohortproj_sdk/-/blob/main/LICENSE)
+
+**Cohort-component population projection, life tables and Leslie matrices in plain NumPy.**
+
+`cohortproj` implements the standard demographic toolkit of Preston, Heuveline & Guillot,
+*Demography: Measuring and Modeling Population Processes* (2001):
+
+- **Life tables**: abridged (0, 1-4, 5-9, ...) and single-year period life tables from
+  death rates or deaths and exposure: `nqx`, `lx`, `ndx`, `nLx`, `Tx`, `ex`, with `nax`
+  by mid-point, constant hazard, Coale-Demeny (ages 0 and 1-4), Keyfitz's iterative
+  graduation, or user-supplied values.
+- **Survival ratios** for projection steps, including the open age group and births.
+- **Fertility**: age-specific rates, TFR, GRR, NRR, mean age of childbearing, rescaling to a
+  target TFR; the sex ratio at birth is always an explicit input.
+- **Cohort-component projection** for one or both sexes, with net migration as counts or
+  annual rates and a stated timing convention, constant or time-varying schedules.
+- **Leslie matrices**, the **stable population** (intrinsic growth rate, stable age
+  distribution, reproductive values, damping ratio) and the intrinsic rate from Lotka's
+  equation.
+- **Multiregional extension**: a simple one-sex multi-region (and two-region) projection
+  with age-specific transition probabilities, its equivalent growth matrix and long-run
+  regional shares.
+- **Age structure**: dependency ratios, ageing index, support ratio, median and mean age,
+  sex ratios and population-pyramid data.
+- **Scenarios**: fertility, mortality and migration variants run side by side.
+
+It needs only NumPy. A command-line tool reads CSV tables and writes JSON and CSV.
+
+## Installation
+
+```bash
+pip install cohortproj
+```
+
+Requires Python 3.9 or newer.
+
+## Quickstart
+
+```python
+import numpy as np
+import cohortproj as cp
+
+# abridged life table from death rates (0, 1-4, 5-9, ..., 85+)
+lt_ages = cp.abridged_ages(85)
+female_lt = cp.life_table(mx_female, lt_ages, nax="coale-demeny", sex="female")
+male_lt = cp.life_table(mx_male, lt_ages, nax="coale-demeny", sex="male")
+female_lt.e0, female_lt.records()
+
+# projection on 5-year groups 0-4 ... 85+ (abridged tables are collapsed to 0-4)
+ages = cp.regular_ages(5, 85)
+asfr = cp.expand_asfr([0.02, 0.09, 0.12, 0.09, 0.04, 0.01, 0.002], 15, ages)
+proj = cp.project(female, ages, female_lt, asfr, srb=1.05, steps=6,
+                  male=male, male_life=male_lt,
+                  migration_female=mig_f, migration_male=mig_m,
+                  timing="half", start_year=2025)
+proj.total, proj.summary(), proj.records()
+
+# stable population
+les = cp.leslie_matrix(female_lt, asfr, srb=1.05)
+st = cp.stable_population(les)
+st.growth_rate, st.age_distribution, st.reproductive_values
+cp.intrinsic_growth_rate(asfr, female_lt, srb=1.05)     # Lotka
+
+# age structure
+s = cp.age_structure(proj.female[-1], ages, proj.male[-1])
+s.median_age, s.dependency["old"]
+cp.pyramid(proj.female[-1], proj.male[-1], ages)
+```
+
+Scenarios:
+
+```python
+base = cp.ProjectionInputs(female=female, ages=ages, female_life=female_lt, asfr=asfr,
+                           srb=1.05, steps=6, male=male, male_life=male_lt)
+runs = cp.run_scenarios(base, [
+    cp.Scenario("medium"),
+    cp.Scenario("low", tfr=cp.linear_path(1.9, 1.3, 6)),
+    cp.Scenario("higher mortality", mortality_factor=1.2),
+    cp.Scenario("closed", migration_factor=0.0),
+])
+runs.table            # year-by-year totals, TFR, median age, dependency ratios
+runs.final("total")
+```
+
+Two regions:
+
+```python
+mr = cp.two_region_project(pop_urban, pop_rural, ages, lt_urban, lt_rural,
+                           asfr_urban, asfr_rural, out_1_to_2=0.02, out_2_to_1=0.06,
+                           srb=1.05, steps=10, names=("urban", "rural"))
+mr.totals
+cp.multiregional_stable([lt_urban, lt_rural], np.vstack([asfr_urban, asfr_rural]),
+                        migration, srb=1.05, n_ages=ages.size).regional_shares
+```
+
+## Command line
+
+```bash
+cohortproj lifetable life_female.csv --nax coale-demeny --sex female --csv lt.csv
+cohortproj project input.csv --srb 1.05 --steps 6 --start-year 2025 \
+    --life-female life_female.csv --life-male life_male.csv --nax coale-demeny \
+    --timing half --csv projection_long.csv -o projection.json
+cohortproj stable input.csv --srb 1.05 --life-female life_female.csv --matrix
+cohortproj structure population.csv --csv pyramid.csv
+```
+
+CSV columns: `age` (lower bounds or labels such as `5-9` and `85+`) plus `mx` (or `deaths`
+and `exposure`, optional `ax` and `qx`) for life tables; `female`, `asfr` and optionally
+`male`, `mx_female`, `mx_male`, `migration_female`, `migration_male` for projections.
+Every command prints JSON or writes it with `-o`.
+
+## API overview
+
+| Area | Functions / classes |
+| --- | --- |
+| Life tables | `life_table -> LifeTable` (`records()`, `collapse_infant()`, `scaled()`), `life_table_from_deaths`, `coale_demeny_a0`, `coale_demeny_a1`, `mx_to_qx`, `qx_to_mx`, `NAX_METHODS` |
+| Survival | `survival_ratios -> SurvivalRatios` |
+| Fertility | `asfr`, `tfr`, `grr`, `nrr`, `mean_age_childbearing`, `scale_to_tfr`, `expand_asfr`, `fraction_female` |
+| Projection | `project -> Projection` (`total`, `summary()`, `records()`, `to_dict()`) |
+| Leslie / stable | `leslie_matrix -> LeslieMatrix`, `project_leslie`, `stable_population -> StablePopulation`, `intrinsic_growth_rate` |
+| Multiregional | `multiregional_project`, `two_region_project -> MultiRegionProjection`, `growth_matrix`, `multiregional_stable` |
+| Structure | `dependency_ratios`, `median_age`, `mean_age`, `pyramid`, `sex_ratios`, `age_structure`, `structure_series` |
+| Scenarios | `ProjectionInputs`, `Scenario`, `run_scenario`, `run_scenarios -> ScenarioComparison`, `linear_path` |
+| Helpers / I/O | `abridged_ages`, `regular_ages`, `age_labels`, `read_table`, `write_records`, `write_json` |
+
+## Methods and sources
+
+| Item | Definition | Source |
+| --- | --- | --- |
+| `nqx` | `n m / (1 + (n - a) m)`; open group `q = 1`, `L = l / m` | Preston et al. (2001), ch. 3 |
+| `nax`, mid-point | `n / 2` | Preston et al. (2001), ch. 3 |
+| `nax`, constant hazard | `1/m - n e^(-nm) / (1 - e^(-nm))`, `q = 1 - e^(-nm)` | Preston et al. (2001), §3.3 |
+| `nax`, Coale-Demeny | `1a0`, `4a1` as linear functions of `1m0` (Table 3.3) | Coale & Demeny (1983) via Preston et al. (2001) |
+| `nax`, Keyfitz | `(-(n/24) d(x-n) + (n/2) d(x) + (n/24) d(x+n)) / d(x)`, iterated | Keyfitz (1966); Preston et al. (2001) |
+| Survival ratios | `nL(x+n)/nLx`; open `T_A/T_(A-n)`; births `nL0/(n l0)` | Preston et al. (2001), §6.2 |
+| Births | `n sum F_x (N^F_x(t) + N^F_x(t+n)) / 2`, split by `1/(1+SRB)` | Preston et al. (2001), §6.2 |
+| TFR, GRR, NRR | `n sum F`; `TFR/(1+SRB)`; `sum F L / l0 /(1+SRB)` | Preston et al. (2001), ch. 5 |
+| Leslie matrix | first row `nL0/(2 l0) (F_x + F_(x+n) s_x) / (1+SRB)`, sub-diagonal `s_x` | Leslie (1945); Preston et al. (2001), §6.5 |
+| Intrinsic rate | `sum e^(-r(x+n/2)) F_x L_x / l0 / (1+SRB) = 1` | Lotka (1939); Preston et al. (2001), ch. 7 |
+| Multiregional | survive, then move survivors with age-specific transition probabilities | after Rogers (1975), simplified |
+| Dependency ratios | `100 P(0-14)/P(15-64)`, `100 P(65+)/P(15-64)` (bounds are parameters) | United Nations convention |
+
+### Conventions and assumptions
+
+- **Migration timing.** Net migrant counts are indexed by age group at the **end** of a
+  step. `timing="end"` adds them after survival; `"start"` applies the cohort's survival
+  ratio (they arrive at the start); `"half"` splits them between the two. Newborn migrants
+  are added at the end. Annual rates become counts as `rate n (N_x(t) + N*_x(t+n)) / 2`
+  with `N*` the closed projection.
+- **Deaths** in the projection summary are the balancing item
+  `N(t) + births + migrants - N(t+n)`; with `"start"` or `"half"` timing they include
+  deaths of migrants.
+- **Leslie and projection agree exactly**: for a female population without migration the
+  Leslie matrix reproduces `project()` to rounding.
+- **No defaults for population assumptions**: the sex ratio at birth, `nax` values beyond
+  the Coale-Demeny ages, fertility and migration schedules and scenario variants are
+  always the user's choice. The 15 / 65 dependency bounds follow the UN convention and can
+  be changed.
+- `nqx` is capped at 1 when very high death rates would push it above 1; check such input.
+
+## Limitations
+
+- The multiregional model is a projection device with transition probabilities, not
+  Rogers' full multiregional life table, and is one-sex (female).
+- Projection steps must equal the age-group width (5-year groups with 5-year steps,
+  single years with 1-year steps).
+- No model life tables, mortality forecasting (Lee-Carter) or fertility models are bundled;
+  supply the schedules.
+- The mean age of an open age group needs a representative age (`open_mean`); the default
+  is only a rough approximation.
+
+## References
+
+- Coale, A. J. & Demeny, P. (1983). *Regional Model Life Tables and Stable Populations*,
+  2nd ed. Academic Press, New York.
+- Keyfitz, N. (1966). A life table that agrees with the data. *Journal of the American
+  Statistical Association* 61(314), 305-312.
+- Leslie, P. H. (1945). On the use of matrices in certain population mathematics.
+  *Biometrika* 33(3), 183-212.
+- Lotka, A. J. (1939). *Théorie analytique des associations biologiques. Deuxième partie:
+  analyse démographique avec application particulière à l'espèce humaine*. Hermann, Paris.
+- Preston, S. H., Heuveline, P. & Guillot, M. (2001). *Demography: Measuring and Modeling
+  Population Processes*. Blackwell, Oxford.
+- Rogers, A. (1975). *Introduction to Multiregional Mathematical Demography*. Wiley, New
+  York.
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_cohortproj,
+  author  = {Eminoğlu, Yusuf},
+  title   = {cohortproj},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://gitlab.com/geophilo1/cohortproj_sdk}
+}
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

cohortproj-0.1.0/examples/quickstart.py

@@ -0,0 +1,101 @@
+"""cohortproj quickstart with synthetic schedules (no input files needed).
+
+Run:  python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+import cohortproj as cp
+
+
+def gompertz(ages: np.ndarray, a: float, infant: float) -> np.ndarray:
+    m = a * np.exp(0.1 * ages)
+    m[0] = infant
+    m[1] = 0.001
+    return m
+
+
+def main() -> None:
+    # 1. Abridged life tables (0, 1-4, 5-9, ..., 85+) with Coale-Demeny nax at young ages
+    lt_ages = cp.abridged_ages(85)
+    female_lt = cp.life_table(
+        gompertz(lt_ages, 5e-5, 0.015), lt_ages, nax="coale-demeny", sex="female"
+    )
+    male_lt = cp.life_table(gompertz(lt_ages, 8e-5, 0.018), lt_ages, nax="coale-demeny", sex="male")
+    print(f"e0 female {female_lt.e0:.1f}, male {male_lt.e0:.1f}")
+
+    # 2. Fertility on 5-year groups 0-4 ... 85+, scaled to a TFR of 1.9
+    ages = cp.regular_ages(5, 85)
+    shape = cp.expand_asfr([0.02, 0.09, 0.12, 0.09, 0.04, 0.01, 0.002], 15, ages)
+    asfr = cp.scale_to_tfr(shape, 1.9)
+    srb = 1.05  # the user's assumption
+    print(f"TFR {cp.tfr(asfr):.2f}, NRR {cp.nrr(asfr, female_lt, srb):.3f}")
+
+    # 3. Base population and net migration (counts per 5-year step, end-of-step ages)
+    female = np.linspace(42_000, 6_000, ages.size)
+    male = female * np.linspace(1.04, 0.7, ages.size)
+    migration = np.zeros(ages.size)
+    migration[4:8] = [1_500, 2_000, 1_200, 600]
+
+    proj = cp.project(
+        female,
+        ages,
+        female_lt,
+        asfr,
+        srb,
+        steps=6,
+        male=male,
+        male_life=male_lt,
+        migration_female=migration,
+        migration_male=migration,
+        timing="half",
+        start_year=2025,
+    )
+    for row in proj.summary():
+        print(
+            f"{row['year_start']:.0f}-{row['year_end']:.0f}: "
+            f"{row['population_start']:,.0f} -> {row['population_end']:,.0f} "
+            f"(births {row['births']:,.0f}, deaths {row['deaths']:,.0f})"
+        )
+    final = cp.age_structure(
+        proj.female[-1], ages, proj.male[-1] if proj.male is not None else None
+    )
+    print(
+        f"2055 median age {final.median_age:.1f}, old-age dependency {final.dependency['old']:.1f}"
+    )
+
+    # 4. Leslie matrix, stable population and Lotka's r
+    stable = cp.stable_population(cp.leslie_matrix(female_lt, asfr, srb))
+    lotka = cp.intrinsic_growth_rate(asfr, female_lt, srb)
+    print(f"Intrinsic r: Leslie {stable.growth_rate:.5f}, Lotka {lotka['r']:.5f}")
+
+    # 5. Scenarios
+    base = cp.ProjectionInputs(
+        female=female,
+        ages=ages,
+        female_life=female_lt,
+        asfr=asfr,
+        srb=srb,
+        steps=6,
+        male=male,
+        male_life=male_lt,
+        migration_female=migration,
+        migration_male=migration,
+        start_year=2025,
+    )
+    runs = cp.run_scenarios(
+        base,
+        [
+            cp.Scenario("medium"),
+            cp.Scenario("low fertility", tfr=cp.linear_path(1.9, 1.3, 6)),
+            cp.Scenario("no migration", migration_factor=0.0),
+        ],
+    )
+    for name, total in runs.final("total").items():
+        print(f"  {name:14s} 2055 population {total:,.0f}")
+
+
+if __name__ == "__main__":
+    main()