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