A new open-source R package called inedemogR automates the path from the Spanish National Statistics Institute’s public data API to province-level period life tables, replacing a manual data-preparation chore that demographers have long repeated without a shared, tested solution. The package, described in the journal SoftwareX, retrieves age- and sex-specific population figures, births and deaths for Spain’s provinces directly from INE’s dissemination API, harmonises them into analysis-ready tables, and computes single-year life tables following the Human Mortality Database protocol, the international reference standard for life tables built from aggregate data.
The problem inedemogR addresses is a familiar one in computational demography. INE publishes population figures, vital statistics and life tables through a public API that requires no registration, and an existing R wrapper called ineapir already provides general access to that service, including multidimensional filters and metadata. But what ineapir returns is INE’s own table structure: Spanish category labels, totals mixed with their component breakdowns, suppressed small counts, and geographic levels that differ from series to series. Converting those raw tables into complete age-by-sex grids for each province and year, with structural zeros distinguished from genuinely missing values, is work that every analyst repeats and few publish, and it is easy to get wrong.
According to the package documentation, no published software previously combined retrieval of INE’s public aggregate province data with automated computation of HMD-protocol provincial life tables. Neighbouring tools cover other needs: mapSpain supplies Spanish administrative map geometries, ineAtlas covers INE’s household income atlas, and tidycensus plays a similar role for United States census data. Other packages such as MortalityLaws, demography and MortCast can build provincial life tables once a user has assembled provincial deaths and exposures by hand, but they do not assemble those inputs from INE’s data. That assembly, the author argues, is precisely what inedemogR adds.
The package offers two retrieval front ends that share a common tidying, validation, caching and geometry layer. A quick-lookup front end returns population, birth and death totals as one tidy row per geography and year, with optional map geometry. A mortality-workflow front end queries INE’s Tempus3 service directly; because the province-by-age-by-sex population table exceeds the JSON service’s volume limit, the package falls back to INE’s bulk CSV export and parses both formats into a single shape. The output then feeds a fixed sequence of pure functions that compute exposure-to-risk, central death rates and life tables, each consuming and returning a tidy data frame, so any step can be inspected, replaced or tested in isolation.
The demographic methods are established rather than novel. Exposure to risk follows the HMD protocol’s formula as the mean of two January 1 population stocks, adjusted by deaths in the lower and upper Lexis triangles; because INE’s death tables are not classified by birth cohort, deaths are split evenly between the triangles. Single-year life tables follow the HMD protocol, using sex-specific Andreev–Kingkade formulas for the infant term and the Kannisto model, fitted by maximum likelihood, for old-age mortality. Two documented departures from the protocol were forced by INE’s data: the even triangle split instead of a regression-based split, and a Kannisto fit on ages 80 to 99 rather than 80 to 110 and above, because INE’s single-year detail ends at the 100-plus group.
Validation against INE’s own published provincial life tables, which are computed from death microdata with a different methodology, shows close agreement. The author compared life expectancy at birth and at age 65 for all 52 provinces, both sexes and the total, across 2002 to 2024, yielding 3,588 comparisons per measure against a tolerance of 0.25 years fixed before the comparison. For the 50 provinces whose INE tables close at age 95 and above, every comparison fell within tolerance, with a mean absolute difference of 0.031 years for e0 and 0.035 years for e65. Agreement was weaker for Ceuta and Melilla, where INE closes its tables at age 90 and above using the observed mean time lived by that year’s decedents; there, 70 percent of e0 comparisons fell within tolerance, and the package’s e90 exceeded INE’s by 0.78 years in Ceuta and 0.87 in Melilla on average.
The remaining differences concentrate at older ages and appear consistent with differences in terminal-age treatment rather than with the input data. Across 39,939 grouped death rates at ages 1 to 89, the median relative difference from INE’s rates was at most 0.1 percent in absolute value. An Arriaga decomposition of each difference placed it almost entirely at ages 80 and above, with ages 1 to 79 contributing a mean absolute 0.008 years and age 0 less than 0.002, indicating that the differing infant-mortality conventions do not matter. Sensitivity analyses showed that fixing the Kannisto replacement age at 80, 85, 90 or 95 instead of the protocol’s 100-death rule changed e0 by at most 0.05 years on average, while starting the fit at 85 instead of 80 changed e0 by 0.19 years on average in small provinces and up to 1.16 years, supporting the protocol’s choice of 80.
Uncertainty matters most in Spain’s smallest provinces. A Poisson bootstrap of 2024 deaths, with 200 replicates, conditioned on the exposures and modelling choices and therefore measured only death-count variability. The median bootstrap standard deviation of e0 was 0.14 years for women and 0.16 for men in provinces with more than one million inhabitants, but 0.43 and 0.46 years in provinces under 200,000 inhabitants, reaching 0.77 years at most. Differences of a few tenths of a year between small provinces are of the same order as this variability, the paper notes, so any contrast between two particular provinces needs its own uncertainty estimate.
Beyond mortality, the package computes fertility indicators following INE’s methodology, including age-specific fertility rates, total fertility, mean age at childbearing and gross and net reproduction rates. Against INE’s published provincial fertility series for all 52 provinces from 1975 to 2024, covering 2,600 province-years, the mean absolute difference was 0.003 for both total fertility and mean age at childbearing, with 99 percent of TFR values and 98 percent of MAC values agreeing within the 0.01 precision INE publishes. Illustrative outputs include population pyramids, Lexis mortality surfaces and choropleth maps; natural increase has been negative in A Coruña throughout 2002 to 2024, in Barcelona since 2018 and in Sevilla since 2020, while Madrid turned negative in 2020 and was slightly positive again in 2024.
The package enforces reproducibility through several mechanisms. Every retrieved object carries a provenance record with the request, retrieval time and package version, because a fixed package version and a live API do not guarantee identical results when INE revises its series. Results are cached on disk and refreshed only on request, and retrieval stops with an error if the API is unavailable or a response cannot be parsed. Version 0.2.1 ships with 126 software tests, and the repository’s reproducibility folder holds frozen inputs and scripts that regenerate every reported result. The package has documented limits: life tables cover 2002 onwards because earlier provincial populations are top-coded at age 85 and above, the tables are period rather than cohort tables, international migration has not yet been retrieved, and municipal detail is available only through the quick-lookup front end. Planned work adds cohort-component projection, nuptiality indicators and age-heaping diagnostics.
Subject of Research: Reproducible software for retrieving Spanish subnational demographic data and computing provincial period life tables
Article Title: inedemogR: Reproducible retrieval and life-table computation for Spanish subnational demographic data
Article References: Caro-Barrera, J. R. (2026). inedemogR: Reproducible retrieval and life-table computation for Spanish subnational demographic data. SoftwareX, 36, Article 103189. https://doi.org/10.1016/j.softx.2026.103189
Image Credits: AI Generated
DOI: 10.1016/j.softx.2026.103189
Keywords: R package, demography, life tables, Spain, INE, mortality, fertility, Human Mortality Database, reproducibility, open-source software, population statistics, provincial data
News Source: Denise Maddox. (November 4, 2026). New R package turns Spain’s public statistics API into provincial life tables. Scienmag.
