Skip to main content

cohortproj icon

cohortproj

PyPI version Python versions pipeline status License: MIT DOI Downloads

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

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

@software{eminoglu_cohortproj,
  author  = {Eminoğlu, Yusuf},
  title   = {cohortproj},
  year    = {2026},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24235568},
  url     = {https://gitlab.com/geophilo1/cohortproj_sdk}
}
  • tr-nufus: population projection methods for Turkish plan reports.
  • urbanscaling: urban scaling laws Y = Y0 N^beta with OLS, RMA, robust fits and SAMIs.
  • ranksize: city-size distributions, Zipf rank-size regression, power-law tails and primacy indices.
  • homeafford: housing affordability metrics such as price-to-income, cost burden and residual income.

License

MIT, see LICENSE.

Metadata

Release files for cohortproj 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cohortproj 0.1.2
File Size Uploaded Provenance Actions
cohortproj-0.1.2.tar.gz 48.0 kB Without provenance Details for cohortproj-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cohortproj 0.1.2
File Interpreter ABI Platform Actions
cohortproj-0.1.2-py3-none-any.whl Python 3 none any Details for cohortproj-0.1.2-py3-none-any.whl

Total release size: 87.7 kB

Release files / cohortproj-0.1.2.tar.gz

Download URL cohortproj-0.1.2.tar.gz
Size 48.0 kB
Tags Source
SHA-256 checksum
How to use checksums
6d8f5a1d50ed478a1ce869b026406389e4c01ddeaed85869de2d857ce4b5ffdd
BLAKE2b-256 checksum
How to use checksums
2ce38b09a0d7aa6e3da548280acc5b55fa2f72105238a819793ac0708e949185
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.2-py3-none-any.whl

Download URL cohortproj-0.1.2-py3-none-any.whl
Size 39.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c59976aea42699c62666c9594a3d5c11d5a119e4f77b65130f5585f9e61e4c93
BLAKE2b-256 checksum
How to use checksums
67c82a86d393e6cb46e93b516bf26e659089e87207138ed5176087bf2b984ef7
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.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page