cohortproj
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, withnaxby 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
pip install cohortproj
Requires Python 3.9 or newer.
Quickstart
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:
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:
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
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 asrate n (N_x(t) + N*_x(t+n)) / 2withN*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,
naxvalues 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. nqxis 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
@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.
Metadata
Release files for cohortproj 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cohortproj-0.1.0.tar.gz | 46.9 kB | Without provenance | Details for cohortproj-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cohortproj-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for cohortproj-0.1.0-py3-none-any.whl |
Total release size: 86.1 kB
Release files / cohortproj-0.1.0.tar.gz
| Download URL | cohortproj-0.1.0.tar.gz |
|---|---|
| Size | 46.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4f3a4812aa0eaf0b5829b163bdb5abc03dbaa996b1b5f1d21c046f1638ae2d0
|
|
BLAKE2b-256 checksum How to use checksums |
998128ac081b542cac950a30e3113981431225ec5721eec6857293a0abcefe04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / cohortproj-0.1.0-py3-none-any.whl
| Download URL | cohortproj-0.1.0-py3-none-any.whl |
|---|---|
| Size | 39.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62989eeb16a703b47a1669679d7edca93ae4967fc857c53a183afb48f95c909e
|
|
BLAKE2b-256 checksum How to use checksums |
0a3cdeb126b98ac4812491316f0f0929e628826e5ba46bba473333351e5d27b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for cohortproj 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.