mortensor

Flexible probabilistic mortality forecasting from data observed at different granularities: age groups and open age intervals, single or grouped periods, population strata and causes.

mortensor has no preferred model. It implements common mortality models and wraps others from demography, StMoMo, StanMoMo, bamp and forecast behind one interface: every model is fitted with mt_fit(), forecast with mt_forecast() and returns simulated paths of the same form. Models can therefore be compared in the same backtest and combined into ensembles of any composition, and the same steps (smoothing, jump-off, recalibration, coherent totals) apply to all of them.

Caution: experimental, vibe-coded software. Use at your own risk. mortensor is written largely with AI coding assistants ("vibe-coded"). It has unit tests that check its methods against published results and reference implementations, but it has not been peer reviewed, its interfaces still change, and its results can be wrong in ways the tests do not catch. Check results independently before you use them in publications, reports or decisions.

Status: version 0.3.0. Interfaces can still change between versions; NEWS.md lists the changes and dev/progress.md the work packages.

Installation

# install.packages("remotes")
remotes::install_github("kalleEF/mortensor")

Requires R >= 4.3.0. Hard dependencies are data.table and Matrix; models and data adapters that build on other packages (forecast, bamp, StMoMo, StanMoMo, demography, ggplot2) use them when installed.

What it does

Layer	Functions
Data at any granularity	mt_data() (long or wide tables, symbols for suppressed cells, shared populations), mt_add(), as_mt_data() (StMoMo, demography), mt_from_hmd(), mt_read_hmd(), mt_read_genesis(), mt_read_gbe(), mt_validate(), ons_data, de_deaths
Preparation	mt_as_exposure(), mt_subset(), mt_group_levels() (aggregation layers: cause groups, quintiles, regions), mt_relabel(), mt_fill_suppressed()
Harmonisation	mt_regroup(), mt_ungroup() (penalized composite link model with exposure offset, 1D/2D; monotone interpolation), mt_plot_ungroup() and mt_ungroup_check() (diagnostics), mt_smooth() (over age, over time or both; P-splines, Whittaker, GAM), mt_smooth_check(), mt_plot_smooth()
Preprocessing pipelines	mt_prep() with step_ungroup(), step_smooth(), step_regroup(), step_grid(), step_shocks(), step_window(); models fitted to smoothed rates take their observation noise from the raw rates
Describing the past	mt_observed(), life_expectancy(), asr(), prob_dying() on data, mt_contrast() (gaps, ratios), mt_inequality() (SII, RII), lifespan_variation() (e-dagger, entropy, Gini, standard deviation, IQR), standard_population()
Models	rwd(), lee_carter() (Poisson or SVD with the adjustments and period choice of demography; optional rotation of the age pattern, Li, Lee and Gerland 2013; negative binomial deaths, Delwarde, Denuit and Partrat 2007, with a dispersion by age, Li, Hardy and Tan 2009; averaged, filtered and constrained jump-off, Stoeldraijer et al. 2018, De Jong and Tickle 2006), coda() (compositional model of life-table deaths and its coherent version, Oeppen 2008; Bergeron-Boucher et al. 2017), p_splines() (two-dimensional P-splines, Currie, Durban and Eilers 2004; smooth dispersion by age, Djeundje and Currie 2011), (constrained P-splines, Camarda 2019), (age-specific rates of mortality improvement, Bohk-Ewald and Rau 2017), , , (demography), (APC, CBD, RH, M6, M7, M8, Plat, LC), (age-period-cohort-improvement model, Richards et al. 2019), (LC, RH, APC, CBD and M6, Bayesian, in Stan), , (common age effect model, Kleinow 2015; non-diverging forecasts, Enchev, Kleinow and Cairns 2017), (subpopulations relative to a reference population, Villegas and Haberman 2014), (trend of a reference population and stationary spreads, Jarner and Kryger 2011; Jarner and Jallbjørn 2022), (demography), and (bamp), (Nordpred age-period-cohort model, Møller et al. 2003); experimental: (three-way Lee-Carter), (multiway compositional model, Bergeron-Boucher et al. 2018), (also 2S-CoDA, Kjærgaard et al. 2019)

Function map

The objects of an analysis and the functions that connect them. The function map (on the website: Articles, Function map) shows every function with its purpose, the possible workflows and what the package does not cover.

Example

library(mortensor)

# deaths and populations by sex, age group and deprivation decile, England
# 2001-2019 (ONS; Open Government Licence)
x <- mt_data(deaths = ons_data, population = ons_data, by = c("sex", "imd_decile"),
             age = "age_group", value = c(deaths = "all_causes", population = "population"))
x <- mt_as_exposure(x, type = "midyear")
# deciles to quintiles: an aggregation layer with its own name
x <- mt_group_levels(x, "imd_decile", function(d) paste0("Q", ceiling(as.numeric(d) / 2)),
                     name = "quintile")
mt_validate(x)

fit <- mt_fit(li_lee(common_by = "sex"), x)
fc <- mt_forecast(fit, h = 15, n_draws = 500, seed = 1)
life_expectancy(fc, at = 0)

bt <- mt_backtest(li_lee(common_by = "sex"), x, origins = 2008:2014, h = 5)
mt_score(bt)

The examples of the help pages simulate data with mt_example(deaths = "single"), because the default mt_example() has deaths in 5-year groups and exposures in single years, which a model fits only after ungrouping (mt_ungroup(), step_ungroup()) or regrouping (mt_regroup()).

Vignettes:

• Start: Getting started, Your own data, from CSV to report.
• Concepts, one at a time: Ungrouping age groups: methods and diagnostics, Smoothing death rates, Where a forecast starts: the jump-off, Backtesting and scores, Overdispersion: extra variation in death counts, Tuning and recalibration, Coherent forecasts: totals and their parts, Dependence between groups, Decomposing differences in life expectancy, Lifespan variation.
• Models: Choosing and combining models (implemented and wrapped models side by side, ensembles of any combination), Model reference, Bayesian age-period-cohort models with bamp.
• Benchmarks: Benchmarks: how well the pipeline works, Comparison with demography, bamp and StMoMo.
• Applications: Inequality in England: life expectancy and causes of death by deprivation (ONS), Causes of death by deprivation: coherent and combined forecasts (ONS), Differences between the German Laender (Destatis), Excess mortality.
• Help: Frequently asked questions, Function map.

Development

See CLAUDE.md for conventions and commands, and dev/implementation-plan.md for the plan.

Licence

GPL-3.