AgePopDenom is an R package designed to facilitate the generation of fine-scale, age-structured population denominators for public health decision-making and service delivery. By combining census and household survey data with a novel parameter-based geostatistical modeling approach, the package produces high-resolution (5km x 5km) population estimates disaggregated by age.
Age-structured population estimates at fine spatial resolution are needed for public health planning, disease surveillance, and the denominators behind estimates of disease burden, vaccination coverage, and intervention impact. Such data are scarce. Censuses are infrequent and often lack subnational detail, national projections rest on aggregate assumptions that limit their use for local planning, and household surveys such as DHS and MICS are not designed for subnational estimation. Existing fine-scale population models mostly estimate total population or a few age groups such as under-fives, and methods for estimating full age distributions at small-area level remain limited.
AgePopDenom addresses this gap by modeling the continuous age distribution at each survey location with a Gamma distribution whose parameters are linked through bivariate Gaussian processes. It then combines the fitted model with WorldPop gridded population rasters and administrative boundaries to produce 5km x 5km estimates of population by single year of age, with uncertainty quantification. It is intended for epidemiologists, demographers, and programme staff who need age-specific denominators where census microdata are unavailable or out of date.
Before installing AgePopDenom, ensure your system meets the following requirements:
Windows
# Check if Rtools is installed and properly configured
pkgbuild::has_build_tools()
If FALSE, download and install Rtools from: CRAN Rtools
echo 'export PATH="C:/rtools43/usr/bin;C:/rtools43/mingw64/bin:$PATH"' >> ~/.Renviron
Sys.getenv("PATH")
It should include C:/rtools43/usr/bin and C:/rtools43/mingw64/bin.
g++ --version
It should output GCC version 10 or later.
mkdir -p ~/.R
nano ~/.R/Makevars.win
Add the following lines:
CXX14=C:/rtools43/mingw64/bin/g++
CXX17=C:/rtools43/mingw64/bin/g++
CXX20=C:/rtools43/mingw64/bin/g++
Save and exit (CTRL+X, then Y, then Enter).
macOS
xcode-select --install
brew install gcc
brew install llvm
For Zsh (default on macOS):
echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc
echo 'export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"' >> ~/.zshrc
source ~/.zshrc
For Bash:
echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.bashrc
echo 'export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"' >> ~/.bashrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"' >> ~/.bashrc
source ~/.bashrc
clang++ --version
It should output Homebrew Clang (e.g., Homebrew clang version XXXXX).
~/.R/Makevars file:
nano ~/.R/Makevars
Add the following lines:
CXX=/opt/homebrew/opt/llvm/bin/clang++
CXX11=/opt/homebrew/opt/llvm/bin/clang++
CXX14=/opt/homebrew/opt/llvm/bin/clang++
CXX17=/opt/homebrew/opt/llvm/bin/clang++
CXX20=/opt/homebrew/opt/llvm/bin/clang++
Save and exit (CTRL+X, then Y, then Enter).
Linux (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install build-essential libxml2-dev
sudo apt-get install g++
sudo apt-get install clang
g++ --version
clang++ --version
Restart R and install TMB:
install.packages("TMB", type = "source")
Once the setup is complete, follow the instructions below to download AgePopDenom
AgePopDenom is available on CRAN, you will be able to install it using the following command:
install.packages("AgePopDenom")
To get the development version from GitHub, use:
# install.packages("devtools")
# devtools::install_github("truenomad/AgePopDenom")
install.packages("AgePopDenom", repos = c('https://truenomad.r-universe.dev', 'https://cloud.r-project.org'))
Then load it in R:
library(AgePopDenom)
AgePopDenom relies on microdata from the Demographic and Health Surveys (DHS) Program, a long-running survey programme that has fielded nationally representative household surveys on population, health, and nutrition in over 90 low- and middle-income countries since 1984.
DHS microdata are free but not openly downloadable — access is granted per project. Before running the pipeline:
download_dhs_datasets() — the underlying rdhs client authenticates against your DHS account using those credentials.See ?download_dhs_datasets for further details.
To try AgePopDenom before requesting DHS access, use the simulated example data. The package ships with a small DHS-like survey dataset for The Gambia and a simulator, simulate_dummy_dhs_pr(), that regenerates it. The shapefiles and population rasters used by the pipeline are openly available and downloaded automatically — only the survey microdata normally require a DHS account.
Run the full pipeline end-to-end with simulated data (inside an RStudio project):
library(AgePopDenom)
# Create the project scaffolding in the current directory
init()
# Simulate a DHS-like survey dataset for The Gambia and save it
# where the workflow expects processed survey data
simulate_dummy_dhs_pr()
# Download open data: district shapefile and WorldPop population
# raster, then extract the urban extent raster shipped with the package
download_shapefile("GMB")
download_pop_rasters("GMB")
extract_afurextent()
# Fit the geostatistical model and generate all outputs
run_full_workflow("GMB")
All outputs are written to 03_outputs/: model objects (3a_model_outputs), plots such as the age pyramid and prediction rasters (3b_visualizations), age-stratified population tables (3c_table_outputs), and a compiled Excel workbook (3d_compiled_results).
A pre-simulated copy of the same dataset is included in the package if you prefer to inspect it directly:
example_data <- system.file(
"extdata", "example_dhs_pr_gmb.rds",
package = "AgePopDenom"
)
dummy_dhs <- readRDS(example_data)
The quick start run above produces, among other outputs, predicted gamma parameter surfaces and the resulting mean age prediction at a 5 km × 5 km resolution:
as well as age pyramids of the modelled population structure by region:
Age-stratified population tables with 95% uncertainty intervals are written both as .rds files and as a compiled Excel workbook, for example:
| country | region | popsize | 0-1y mean | 0-1y lower | 0-1y upper |
|---|---|---|---|---|---|
| GAMBIA | CENTRAL RIVER REGION | 264,587 | 5,531 | 1,371 | 14,923 |
| GAMBIA | LOWER RIVER REGION | 96,310 | 1,593 | 755 | 2,902 |
| GAMBIA | NORTH BANK EAST REGION | 268,492 | 4,429 | 1,932 | 8,422 |
(Values shown are from the simulated example dataset, not real DHS data.)
init()
# Example for Kenya and Uganda
countries <- c("KEN", "UGA")
# Get DHS data
download_dhs_datasets(countries,
email = "my_email@example.com",
project = "Population denominator project")
# Process DHS data
process_dhs_data()
# Download shapefiles
download_shapefile(countries)
# Download population rasters from worldpop
download_pop_rasters(countries)
# Extract urban extent raster
extract_afurextent()
run_full_workflow(countries)
For detailed documentation and examples, visit our package website.
For support, bug reports, or feature requests, please contact:
Alternatively, open an issue on the GitHub repository.
We welcome contributions from the community to improve AgePopDenom.