| Title: | Demographic Analysis |
| Version: | 0.1.0 |
| Description: | Tool for demographic modeling and analysis, combining stochastic simulation-based projections with classic demographic methods. Provides utilities for disaggregating population data using Karup-King interpolation, fitting Brass relational logit models, calculating fertility and mortality metrics, building life tables, and performing hierarchical subnational population projections. Relational life table estimation and interpolation methods are described in Brass (1975) "Methods for Estimating Fertility and Mortality from Limited and Defective Data", Preston et al. (2001, ISBN:978-0631226161) "Demography: Measuring and Modeling Population Processes", Siegel and Swanson (2004, ISBN:978-0126419559) "The Methods and Materials of Demography", and Raftery et al. (2012) "Bayesian probabilistic population projections for all countries" <doi:10.1073/pnas.1211452109>. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| Depends: | R (≥ 4.1) |
| Imports: | dplyr, stats, tidyr |
| Suggests: | testthat (≥ 3.0.0) |
| LazyData: | true |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-07-15 23:14:12 UTC; manue |
| Author: | Edward Owusu Manu [aut, cre] |
| Maintainer: | Edward Owusu Manu <edward.manu@statsghana.gov.gh> |
| Repository: | CRAN |
| Date/Publication: | 2026-07-23 13:20:07 UTC |
DemogAnr: Demographic Analysis
Description
Tool for demographic modeling and analysis, combining stochastic simulation-based projections with classic demographic methods. Provides utilities for disaggregating population data using Karup-King interpolation, fitting Brass relational logit models, calculating fertility and mortality metrics, building life tables, and performing hierarchical subnational population projections. Relational life table estimation and interpolation methods are described in Brass (1975) "Methods for Estimating Fertility and Mortality from Limited and Defective Data", Preston et al. (2001, ISBN:978-0631226161) "Demography: Measuring and Modeling Population Processes", Siegel and Swanson (2004, ISBN:978-0126419559) "The Methods and Materials of Demography", and Raftery et al. (2012) "Bayesian probabilistic population projections for all countries" doi:10.1073/pnas.1211452109.
Author(s)
Maintainer: Edward Owusu Manu edward.manu@statsghana.gov.gh
Brass Relational Logit Model
Description
Fits the Brass relational logit model to an observed series of cumulative
probabilities of dying q(x) = 1 - l(x)/l(0) using a standard life
table. The observed logits are regressed on the logits of the standard, and
the fitted relationship (alpha, beta) is used to predict a complete,
smoothed series of q(x), including for ages where the observed value
is missing (NA).
Usage
brass_logit(
data,
qx_col,
age_col,
standard,
standards_data = NULL,
verbose = FALSE
)
Arguments
data |
A data frame containing the observed cumulative probabilities
of dying |
qx_col |
Column name for the cumulative probability of dying
|
age_col |
Column name for age in the data frame. |
standard |
Standard to use ("African" or "GeneralUN"). |
standards_data |
Standards dataset (default: included standards). |
verbose |
Logical. If |
Details
The Brass logit of a survivorship value is
Y(x) = 0.5 \log\{(1 - l(x))/l(x)\} = 0.5 \log\{q(x)/(1 - q(x))\},
and predicted probabilities are recovered with the inverse transform
q(x) = \exp(2Y)/(1 + \exp(2Y)).
Note that the input must be cumulative probabilities of dying by age
x (i.e. 1 - l(x)), which increase with age, and not the
age-interval probabilities {}_nq_x. Values of exactly 0 or 1 (for
example q(0) = 0) are excluded from the fit.
Value
A list containing the fitted model (model), the alpha/beta
coefficients, and data: the input data with a predicted_qx column of
smoothed/completed cumulative probabilities and a predicted_lx column of
the implied survivorship l(x) = 1 - q(x).
References
Brass, W. (1971). On the scale of mortality. In W. Brass (Ed.), Biological Aspects of Demography (pp. 69-110). London: Taylor & Francis.
Brass, W. (1975). Methods for Estimating Fertility and Mortality from Limited and Defective Data. Chapel Hill: Carolina Population Center, University of North Carolina.
Moultrie, T., Dorrington, R., Hill, A., Hill, K., Timaeus, I., & Zaba, B. (Eds.). (2013). Tools for Demographic Estimation. Paris: International Union for the Scientific Study of Population (IUSSP). https://demographicestimation.iussp.org/
Newell, C. (1988). Methods and Models in Demography. New York: Guilford Press. (Chapter on model life tables.)
Examples
# Observed cumulative probabilities of dying q(x) = 1 - l(x),
# with gaps (NA) to be filled by the model:
observed_data <- data.frame(
age = c(1, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50),
qx = c(0.10, 0.15, NA, 0.19, 0.21, NA, 0.26, 0.30, NA, 0.38, 0.44)
)
model <- brass_logit(
data = observed_data,
qx_col = "qx",
age_col = "age",
standard = "African"
)
model$coefficients
model$data
Grouped population data by 5-year age groups
Description
Example population counts in 5-year age groups (0-4 to 75-79) for the years
2021 to 2035, used to demonstrate karup_king().
Usage
data
Format
A data frame with 16 rows (age groups) and 16 variables:
- 2021
Numeric. Population in the age group in 2021.
- 2022
Numeric. Population in the age group in 2022.
- 2023
Numeric. Population in the age group in 2023.
- 2024
Numeric. Population in the age group in 2024.
- 2025
Numeric. Population in the age group in 2025.
- 2026
Numeric. Population in the age group in 2026.
- 2027
Numeric. Population in the age group in 2027.
- 2028
Numeric. Population in the age group in 2028.
- 2029
Numeric. Population in the age group in 2029.
- 2030
Numeric. Population in the age group in 2030.
- 2031
Numeric. Population in the age group in 2031.
- 2032
Numeric. Population in the age group in 2032.
- 2033
Numeric. Population in the age group in 2033.
- 2034
Numeric. Population in the age group in 2034.
- 2035
Numeric. Population in the age group in 2035.
- age_col
Character. The 5-year age group, e.g. "0-4", "5-9", ..., "75-79".
Source
Simulated data based on population structures from the Ghana Statistical Service.
Calculate CDR and ASDR
Description
This function calculates the Crude Death Rate (CDR) and Age-Specific Death Rates (ASDR).
Usage
dem.cdr(
data,
type,
age_col = NULL,
population_col,
deaths_col,
verbose = FALSE
)
Arguments
data |
A data frame containing demographic data. |
type |
A string or vector specifying the type(s) of death rate calculation. Options: "CDR", "ASDR". Use "all" to calculate both. |
age_col |
The column name for age groups (used for "ASDR"). |
population_col |
The column name for total population. |
deaths_col |
The column name for total deaths. |
verbose |
Logical. If TRUE, prints progress messages during execution. |
Value
A list of named outputs for the requested death rate calculations.
References
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161. (Chapter 2: Age-Specific Rates and Probabilities.)
Newell, C. (1988). Methods and Models in Demography. New York: Guilford Press.
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.). San Diego: Elsevier Academic Press. ISBN 978-0126419559. (Chapter on mortality measures.)
Examples
data <- data.frame(
age = c("0-4", "5-9", "10-14"),
population = c(10000, 12000, 11000),
deaths = c(100, 50, 30)
)
dem.cdr(data, type = "all", age_col = "age",
population_col = "population", deaths_col = "deaths")
Calculate Fertility Metrics
Description
This function calculates various fertility metrics (CBR, GFR, ASFR, TFR) based on user input and a dataframe with demographic data.
Usage
dem.fert(
data,
type,
age_col = NULL,
population_col,
women_col = NULL,
births_col,
age_interval = 5,
verbose = FALSE
)
Arguments
data |
A dataframe containing demographic data. |
type |
A string or vector specifying the type(s) of fertility calculation. Options: "CBR", "GFR", "ASFR", "TFR". Use "all" to calculate all metrics. |
age_col |
The column name for age groups (used for "ASFR" and "TFR"). |
population_col |
The column name for total population. |
women_col |
The column name for number of women (used for "GFR", "ASFR", and "TFR"). |
births_col |
The column name for live births. |
age_interval |
Width (in years) of the age groups, used to compute TFR from the ASFRs (default 5, for standard 5-year age groups). |
verbose |
Logical. If TRUE, prints progress messages during execution. |
Value
A list of named outputs for the requested fertility calculations and the modified dataframe with ASFR.
References
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161. (Chapter 5: Fertility and Reproduction.)
Newell, C. (1988). Methods and Models in Demography. New York: Guilford Press.
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.). San Diego: Elsevier Academic Press. ISBN 978-0126419559. (Chapter on fertility measures.)
Examples
demo_data <- data.frame(
age = c("15-19", "20-24", "25-29"),
population = c(10000, 12000, 11000),
women = c(5000, 6000, 5500),
live_births = c(200, 400, 300)
)
# Calculate ASFR
dem.fert(demo_data, type = "ASFR", age_col = "age",
population_col = "population", women_col = "women", births_col = "live_births")
# Calculate all metrics
dem.fert(demo_data, type = "all", age_col = "age",
population_col = "population", women_col = "women", births_col = "live_births")
Calculate Maternal Mortality Metrics
Description
This function calculates the maternal mortality rate (maternal deaths per 100,000 women of reproductive age) and the maternal mortality ratio (maternal deaths per 100,000 live births).
Usage
dem.mmr(data, deaths_col, births_col, pop_women, verbose = FALSE)
Arguments
data |
A dataframe containing demographic data. |
deaths_col |
The column name for maternal deaths. |
births_col |
The column name for live births. |
pop_women |
The column containing the number of women of reproductive age. |
verbose |
Logical. If TRUE, prints progress messages during execution. |
Value
An object of class dem_mmr: a list with results (the maternal
mortality rate MMR per 100,000 women, and the maternal mortality ratio
MMR_Ratio per 100,000 live births) and modified_data (the input data
with per-row mm_rate and mm_ratio columns).
References
World Health Organization (1992). International Statistical Classification of Diseases and Related Health Problems, 10th Revision (ICD-10). Geneva: World Health Organization. (Definitions of maternal death and maternal mortality measures.)
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161.
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.). San Diego: Elsevier Academic Press. ISBN 978-0126419559. (Chapter on health demography and maternal mortality.)
Examples
demo_data <- data.frame(
age=c("15-24", "25-34", "35-44"),
maternal_deaths = c(5, 10, 15),
live_births = c(5000, 7000, 6000),
women =c(20000, 22000, 32000)
)
dem.mmr(demo_data, deaths_col = "maternal_deaths", births_col = "live_births", pop_women = "women")
Calculate Child Mortality Metrics by Age
Description
This function calculates child mortality metrics (neonatal, infant, child, under-5) based on single-age data. It requires columns for age, denominator (live births or population), and deaths.
Usage
dm.chm(
data,
age_col,
live_births,
deaths_col,
type = c("neonatal", "infant", "child", "under5"),
age_in_months = NULL,
verbose = FALSE
)
Arguments
data |
A dataframe containing demographic data. |
age_col |
The column name representing the age (in years or months for neonates). |
live_births |
The column name for the denominator at each age (live births, or mid-year population if births are unavailable). |
deaths_col |
The column name representing deaths at each age. |
type |
The type of mortality calculation to perform: "neonatal", "infant", "child", or "under5". |
age_in_months |
(Optional) The column name for age in months for neonatal mortality. |
verbose |
Logical. If TRUE, prints progress messages during execution. |
Details
The result is expressed per 1,000 of the supplied denominator. If the denominator is live births (as is conventional for neonatal and infant mortality), the result is a rate per 1,000 live births. If a mid-year population is supplied instead (often the only option for the child and under-5 groups from census data), the result is a death rate per 1,000 population, which is not identical to the cohort probability of dying (e.g. 5q0) reported by survey programmes such as the DHS.
Value
A numeric value representing the mortality rate per 1,000 live births.
References
Pollard, A. H., Yusuf, F., & Pollard, G. N. (1990). Demographic Techniques (3rd ed.). Sydney: Pergamon Press.
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161. (Chapters 1-2: rates versus probabilities of dying.)
Examples
demo_data <- data.frame(
age = 0:10,
population = c(1000, 950, 900, 850, 800, 750, 700, 650, 600, 550, 500),
deaths = c(30, 20, 15, 10, 5, 2, 1, 1, 0, 0, 0)
)
dm.chm(demo_data,age_col = "age",
live_births = "population",
deaths_col = "deaths",
type = "under5")
Karup-King coefficients for the first age group
Description
The standard Karup-King third-difference osculatory interpolation multipliers used to split the first 5-year age group into single years. Rows are the five single-year ages within the group; columns are the weights applied to the first, second, and third 5-year groups.
Usage
first_coef
Format
A 5 x 3 data frame of numeric coefficients.
Source
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.), Appendix C.
Ghana 2010 Population and Housing Census mortality data
Description
Population and deaths by age group from the Ghana 2010 Population and
Housing Census, used to demonstrate lifetable().
Usage
gphc2010
Format
A data frame with 21 rows and 3 variables:
- Age
Numeric. Lower bound of the age group (0, 1, 5, 10, ...).
- Pop
Numeric. Population in the age group.
- Deaths
Numeric. Deaths in the age group.
Source
Ghana Statistical Service, 2010 Population and Housing Census.
Smart Interpolation Function
Description
Performs interpolation on numeric data, supporting linear, quadratic, Lagrange, and cubic spline methods. Can handle both vector and dataframe inputs.
Usage
interpolation(
x,
y,
x_new,
data = NULL,
y_cols = NULL,
method = c("auto", "linear", "quadratic", "lagrange", "spline"),
verbose = FALSE
)
Arguments
x |
Numeric vector of x-values. |
y |
Numeric vector of y-values (ignored if using a dataframe). |
x_new |
Numeric vector of new x-values to interpolate. |
data |
Optional dataframe containing y-values to interpolate. |
y_cols |
Character vector of column names in |
method |
Character. Interpolation method: |
verbose |
Logical. If |
Value
If vectors x and y are provided, returns a named numeric vector of interpolated values.
If a dataframe is provided, returns the original dataframe with additional interpolated columns.
References
Shryock, H. S., Siegel, J. S., & Larmon, E. A. (1973). The Methods and Materials of Demography. Washington, DC: US Bureau of the Census. (Appendix C: Interpolation and graduation.)
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.). San Diego: Elsevier Academic Press. ISBN 978-0126419559. (Appendix C: Selected General Methods.)
Press, W. H., Teukolsky, S. A., Vetterling, W. T., & Flannery, B. P. (2007). Numerical Recipes: The Art of Scientific Computing (3rd ed.). Cambridge: Cambridge University Press. ISBN 978-0521880688. (Chapter 3: Interpolation and Extrapolation.)
Examples
# Example 1: Interpolating between points (vector input)
x <- c(1, 2, 3, 4, 5)
y <- c(2, 4, 6, 8, 10)
x_new <- c(2.5, 3.5, 4.5)
interpolation(x, y, x_new, method = "linear")
# Example 2: Interpolating for a dataframe
data <- data.frame(
category = c("A", "B", "C"),
y1 = c(2, 5, 9),
y2 = c(3, 6, 10)
)
x_new <- c(2.5, 3.5)
interpolation(x = c(1, 2), data = data, y_cols = c("y1", "y2"), x_new = x_new, method = "spline")
Split Age Groups into Single-Year Ages
Description
This function takes grouped population data (e.g., 5-year age groups) and distributes the population into single-year age groups using the Karup-King third-difference osculatory interpolation coefficients. The user can specify the column containing age groups, one or more population columns, and (optionally) custom coefficient matrices for the first, middle, and last groups.
Usage
karup_king(
df,
age_col = "age_group",
pops = "population",
first_coef = NULL,
middle_coef = NULL,
last_coef = NULL,
verbose = FALSE
)
Arguments
df |
A data frame containing grouped population data. |
age_col |
A string specifying the column in |
pops |
A string or vector of strings specifying one or more columns in |
first_coef |
A 5x3 matrix of coefficients for splitting the first age group. Defaults to the packaged Karup-King multipliers (first_coef). |
middle_coef |
A 5x3 matrix of coefficients for splitting middle age groups. Defaults to the packaged Karup-King multipliers (middle_coef). |
last_coef |
A 5x3 matrix of coefficients for splitting the last age group. Defaults to the packaged Karup-King multipliers (last_coef). |
verbose |
Logical. If |
Details
Each coefficient matrix has 5 rows (one per single year within the 5-year group) and 3 columns (weights applied to the neighbouring 5-year groups). The defaults are the standard Karup-King multipliers (Siegel & Swanson 2004, Appendix C): first_coef for the first group (columns: current, next, next+1), middle_coef for interior groups (columns: previous, current, next), and last_coef for the last group (columns: previous-1, previous, current).
Value
A data frame with single-year ages and corresponding population estimates for each specified population column. Ages beyond the range of the input age groups (overflow ages) are removed.
References
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.). San Diego: Elsevier Academic Press. ISBN 978-0126419559. (Appendix C: Karup-King osculatory interpolation multipliers.)
Shryock, H. S., Siegel, J. S., & Larmon, E. A. (1973). The Methods and Materials of Demography. Washington, DC: US Bureau of the Census. (Appendix C: Interpolation and graduation.)
Examples
data(data)
head(data)
# Split the 5-year age groups into single years for the 2021 population,
# using the packaged Karup-King coefficients:
single <- karup_king(df = data, age_col = "age_col", pops = "2021")
head(single)
# Population totals are (approximately) preserved:
sum(data[["2021"]])
sum(single[["2021"]])
Karup-King coefficients for the last age group
Description
The standard Karup-King third-difference osculatory interpolation multipliers used to split the last 5-year age group into single years. Rows are the five single-year ages within the group; columns are the weights applied to the antepenultimate, penultimate, and last 5-year groups.
Usage
last_coef
Format
A 5 x 3 data frame of numeric coefficients.
Source
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.), Appendix C.
lifetable
Description
This function computes a complete life table based on given mortality rates or raw mortality data. It takes a dataframe with the necessary inputs and computes standard life table metrics.
Usage
lifetable(
data,
age = "Age",
nMx = NULL,
pop = NULL,
Dx = NULL,
sex = c("male", "female"),
radix = 1e+05,
verbose = FALSE
)
Arguments
data |
A data frame containing age-specific mortality data. |
age |
String: name of the column with the lower bound of each age group, e.g., 0, 1, 5, 10, ... |
nMx |
String (optional): name of the column with observed mortality rates. If not provided, |
pop |
String (optional): name of the column with total population (exposure) in each age group. Used to compute |
Dx |
String (optional): name of the column with deaths in each age group. Used to compute |
sex |
Character: "male" (default) or "female". Determines the
Coale-Demeny coefficients used for |
radix |
Numeric: the life table radix, i.e. survivors at exact age 0 (default 100,000). |
verbose |
Logical. If |
Details
Interval widths n are derived from the age column (e.g. ages 0, 1, 5,
10, ... give widths 1, 4, 5, ...). Probabilities of dying are obtained from
the death rates with the standard conversion
{}_nq_x = n \cdot {}_nM_x / (1 + (n - {}_na_x) \cdot {}_nM_x).
The average person-years lived by those dying in the interval
({}_na_x) use the Coale-Demeny model values for ages 0 and 1-4
(which depend on sex and the level of infant mortality; see Preston
et al. 2001, Table 3.3), n/2 for other closed intervals, and
1/{}_nM_x for the open-ended interval. Person-years lived are
{}_nL_x = n \cdot l_{x+n} + {}_na_x \cdot {}_nd_x for closed
intervals and l_x / M_x for the open-ended interval.
Value
A list containing:
metricsA list with the life expectancy at birth and the total life table deaths.
lifetableA dataframe of the complete life table.
References
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161. (Chapter 3: The Life Table and Single Decrement Processes; Table 3.3 for the Coale-Demeny separation factors.)
Chiang, C. L. (1984). The Life Table and Its Applications. Malabar, FL: Robert E. Krieger Publishing.
Coale, A. J., & Demeny, P. (1983). Regional Model Life Tables and Stable Populations (2nd ed.). New York: Academic Press. (Source of the a0 and 4a1 separation factors.)
Examples
# Example computing rates from deaths and population
data(gphc2010)
res <- lifetable(data = gphc2010, age = "Age", pop = "Pop", Dx = "Deaths")
res$metrics
head(res$lifetable)
Compute Life Table Using Age and nqx
Description
This function computes a life table from a data frame containing age groups and
age-interval probabilities of dying (nqx). It calculates key life table
components such as lx, dx, Lx, Tx, and ex.
Usage
lifetable_nqx(data, age, nqx, l0 = 1e+05, verbose = FALSE)
Arguments
data |
A data frame containing age and nqx columns. |
age |
A string specifying the column name for age groups (lower bounds, e.g. 0, 1, 5, 10, ...). Ages must be strictly increasing. |
nqx |
A string specifying the column name for the probabilities of dying
between age |
l0 |
Radix of the life table; survivors at age 0 (default = 100,000). |
verbose |
Logical. If |
Details
Interval widths n are derived from the age column (e.g. ages 0, 1, 5,
10, ... give widths 1, 4, 5, ...). Person-years lived in each closed
interval are approximated as {}_nL_x = n(l_x - d_x/2), i.e. deaths are
assumed to occur at the midpoint of the interval. For the open-ended last
age group, person-years are approximated with the classical rule of thumb
L_{x+} = l_x \log_{10}(l_x) (equivalent to
e_x \approx \log_{10} l_x), which is used when no death rate for the
open interval is available. If death rates are available, lifetable()
provides a more precise treatment of the open interval.
Value
A data frame with the computed life table, including:
AgeAge groups.
nWidth of each age interval (
Inffor the last, open-ended group).nqxProbability of dying between age
xandx+n.lxNumber of survivors at the beginning of each age group.
dxNumber of deaths within each age group.
LxPerson-years lived within each age group.
TxCumulative person-years lived above a specific age group.
exLife expectancy at the beginning of each age group.
References
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161. (Chapter 3: The Life Table and Single Decrement Processes.)
Chiang, C. L. (1984). The Life Table and Its Applications. Malabar, FL: Robert E. Krieger Publishing.
Examples
# Example data
data <- data.frame(
age = c(0, 1, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85),
nqx = c(0.05, 0.01, 0.005, 0.002, 0.003, 0.004, 0.005, 0.007, 0.010, 0.015,
0.020, 0.030, 0.050, 0.070, 0.100, 0.150, 0.200, 0.300, 1.000)
)
life_table <- lifetable_nqx(data, age = "age", nqx = "nqx")
print(life_table)
Hierarchical Subnational Population Projection
Description
Projects lower-level geographies (e.g., Districts) while constraining them to higher-level control totals (e.g., Regions or National) provided within the dataset.
Usage
math_project(
data,
sub_group_col,
parent_group_col = NULL,
pop_cols,
time_vals,
target_times,
method = c("linear", "exponential", "geometric", "constant_share", "shift_share",
"share_of_growth"),
parent_totals_cols = NULL,
verbose = FALSE
)
Arguments
data |
Dataframe containing the subnational population data. |
sub_group_col |
Character. Column name for the lower-level geography (e.g., "District"). |
parent_group_col |
Character. Optional. Column name for the higher-level geography (e.g., "Region"). If NULL, assumes a single national parent group. |
pop_cols |
Character vector of length 2. Column names for Base Year and Launch Year populations. |
time_vals |
Numeric vector of length 2. The years corresponding to pop_cols. |
target_times |
Numeric vector. The future years to project. |
method |
Character. The projection method. |
parent_totals_cols |
Character vector. Optional. Column names in |
verbose |
Logical. If |
Value
A dataframe appending the projected columns to the original data.
References
Smith, S. K., Tayman, J., & Swanson, D. A. (2013). A Practitioner's Guide to State and Local Population Projections. Dordrecht: Springer. doi:10.1007/978-94-007-7551-0 (Trend extrapolation, constant-share, shift-share, and share-of-growth methods.)
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.). San Diego: Elsevier Academic Press. ISBN 978-0126419559. (Chapter on population projections.)
Rowland, D. T. (2003). Demographic Methods and Concepts. Oxford: Oxford University Press. ISBN 978-0198752639. (Chapter on population projections.)
Examples
districts <- data.frame(
Region = c("A", "A", "B", "B"),
District = c("A1", "A2", "B1", "B2"),
pop2010 = c(10000, 20000, 15000, 5000),
pop2020 = c(12000, 26000, 16500, 5500)
)
# Exponential extrapolation of each district
math_project(districts,
sub_group_col = "District", parent_group_col = "Region",
pop_cols = c("pop2010", "pop2020"), time_vals = c(2010, 2020),
target_times = c(2025, 2030), method = "exponential"
)
Karup-King coefficients for middle age groups
Description
The standard Karup-King third-difference osculatory interpolation multipliers used to split interior 5-year age groups into single years. Rows are the five single-year ages within the group; columns are the weights applied to the previous, current, and next 5-year groups.
Usage
middle_coef
Format
A 5 x 3 data frame of numeric coefficients.
Source
Siegel, J. S., & Swanson, D. A. (Eds.). (2004). The Methods and Materials of Demography (2nd ed.), Appendix C.
Basic Probabilistic Population Projection
Description
This function projects population trajectories for multiple administrative regions using a simple stochastic (simulation-based) exponential growth model, inspired by the probabilistic projection literature (e.g. Raftery et al. 2012), but without a full Bayesian model.
For each region, num_samples growth-rate trajectories are simulated. The
annual growth rate of each trajectory is the sum of a random baseline, a
fertility effect (increasing in TFR), a mortality effect (decreasing in the
death rate), a migration effect (with the sign of net migration), and
random noise. Each trajectory is propagated independently through all
years, so that uncertainty accumulates over the projection horizon, and the
results are summarised per region and year.
Usage
project_population(
data,
future_year,
base_year,
region_var = "region",
subregion_var = "subregion",
base_pop_var = "base_pop",
TFR_var = "TFR",
death_rate_var = "death_rate",
net_migration_var = "net_migration",
num_samples = 2000,
random_seed = 42,
verbose = FALSE
)
Arguments
data |
A data frame containing projection parameters. |
future_year |
Numeric. The target year for the projection. |
base_year |
Numeric. The base year for the projection. |
region_var |
Character. Column name for the region. |
subregion_var |
Character. Column name for the subregion. |
base_pop_var |
Character. Column name for the base population. |
TFR_var |
Character. Column name for the Total Fertility Rate (TFR). |
death_rate_var |
Character. Column name for the death rate. |
net_migration_var |
Character. Column name for net migration. |
num_samples |
Integer. Number of simulation samples (default: 2000). |
random_seed |
Integer. Random seed for reproducibility (default: 42). |
verbose |
Logical. If |
Value
A data frame with one row per region, subregion, and year,
containing the summary statistics of the simulated population trajectories:
lower (25th percentile), median, mean, and upper (75th percentile).
References
Raftery, A. E., Li, N., Sevcikova, H., Gerland, P., & Heilig, G. K. (2012). Bayesian probabilistic population projections for all countries. Proceedings of the National Academy of Sciences, 109(35), 13915-13921. doi:10.1073/pnas.1211452109 (Inspiration for the stochastic/probabilistic projection logic.)
Preston, S. H., Heuveline, P., & Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers. ISBN 978-0631226161. (Chapter 6: Population Projections.)
Rowland, D. T. (2003). Demographic Methods and Concepts. Oxford: Oxford University Press. ISBN 978-0198752639. (Chapter on population projections.)
Examples
data(region2000)
proj <- project_population(region2000,
base_year = 2000, future_year = 2009,
TFR_var = "TFR", base_pop_var = "base_pop",
region_var = "Country", death_rate_var = "death_rate",
net_migration_var = "net_migration",
subregion_var = "Region",
num_samples = 1000
)
head(proj)
Regional projection parameters, Ghana 2000
Description
Base-year demographic parameters for the regions of Ghana in 2000, used to
demonstrate project_population().
Usage
region2000
Format
A data frame with 16 rows and 6 variables:
- Country
Character. Country name.
- Region
Character. Region name.
- base_pop
Numeric. Base-year population.
- TFR
Numeric. Total fertility rate.
- death_rate
Numeric. Crude death rate.
- net_migration
Numeric. Net migration (persons).
Source
Derived from Ghana Statistical Service census publications.
Brass standard life tables
Description
Survivorship values l(x) (radix 1) and their Brass logits for the
African and General United Nations standards, used by brass_logit().
Usage
standards
Format
A data frame with 24 rows and 5 variables:
- Age
Numeric. Exact age x.
- GeneralUN
Numeric. l(x) of the General UN standard.
- GeneralUN_logit
Numeric. Brass logit of the General UN standard.
- African
Numeric. l(x) of the African standard.
- African_logit
Numeric. Brass logit of the African standard.
Source
Brass, W. (1971). On the scale of mortality. In Biological Aspects of Demography. London: Taylor & Francis. United Nations model life table publications.
District-level demographic test data
Description
Simulated district-level demographic panel data (population, births,
deaths, migration) by age group and sex, for testing subnational
projection workflows such as math_project().
Usage
testdata
Format
A data frame with 1224 rows and 10 variables:
- region
Character. Region name.
- district
Character. District name.
- year
Numeric. Calendar year.
- age_group
Character. Age group label.
- sex
Character. "Male" or "Female".
- population
Numeric. Population count.
- births
Numeric. Live births.
- deaths
Numeric. Deaths.
- in_migration
Numeric. In-migrants.
- out_migration
Numeric. Out-migrants.
Source
Simulated data.