bayesTFR-package {bayesTFR}R Documentation

Bayesian Fertility Projection


Collection of functions for making probabilistic projections of total fertility rate (TFR) for all countries of the world, using a Bayesian hierarchical model (BHM) and the United Nations demographic time series. Functions for subnational projections are also available.


The projection follows a method developed by Alkema et al. (2011) and Raftery et al (2014). It uses historical data provided by the United Nations to simulate a posterior distribution of total fertility rates for all countries in the world simultaneously.

The estimation is split into two parts:

  1. BHM for fertility in a transition phase (Phase II), as described in Alkema et al. (2011),

  2. BHM for fertility in a post-transition phase (Phase III), as described in Raftery et al (2013).

The second part is optional and can be replaced by a simple AR(1) process.

In addition, the package allows to assess uncertainty about the past (Liu and Rafftery 2020). Estimation and projection can be performed either for 5-year or 1-year time intervals.

The main functions of the package are:

The order of the functions above roughly corresponds to a typical workflow when using the package: 1. run a Phase II MCMC simulation, 2. run a Phase III MCMC simulation (optional but recommended), 3. generate predictions, 4. analyze results (using the functions below). If there are countries that were not included in steps 1.-3., or if there are aggregated regions for which a prediction is desired, one proceeds with the two functions at the bottom of the list above, followed by the analyzing functions below.

A number of functions analyzing results are included in the package:

For MCMC diagnostics, functions coda.list.mcmc and coda.list.mcmc3 create an object of type “mcmc.list” that can be used with the coda package. Furthermore, function tfr.diagnose and tfr3.diagnose analyze the MCMCs using the Raftery diagnostics implemented in the coda package and gives information about parameters that did not converge.

Existing simulation results can be accessed using the get.tfr.mcmc (Phase II) and get.tfr3.mcmc (Phase III) functions. An existing prediction can be accessed via get.tfr.prediction. Existing convergence diagnostics can be accessed using the get.tfr.convergence, get.tfr.convergence.all, get.tfr3.convergence and get.tfr3.convergence.all functions.

The historical national TFR data are taken from one of the packages wpp2019 (default), wpp2017, wpp2015, wpp2012 or wpp2010, depending on users settings.

Subnational TFR projections can be generated using tfr.predict.subnat. In this case, historical data must be provided by the user. Existing projections can be accessed from disk via get.regtfr.prediction.


There is a directory ex-data shipped with the package which contains results from an example simulation, containing one chain with 60 iterations. The Example section below shows how these results were created. These data are used in Example sections throughout the manual. The user can either reproduce the data in her/his local directory, or use the ones from the package.


Hana Sevcikova <>, Leontine Alkema <>, Peiran Liu (, Adrian Raftery <>, Bailey Fosdick <>, Patrick Gerland (

Maintainer: Hana Sevcikova <>


Hana Sevcikova, Leontine Alkema, Adrian E. Raftery (2011). bayesTFR: An R Package for Probabilistic Projections of the Total Fertility Rate. Journal of Statistical Software, 43(1), 1-29. doi:10.18637/jss.v043.i01.

Peiran Liu, Hana Sevcikova, Adrian E. Raftery (2023): Probabilistic Estimation and Projection of the Annual Total Fertility Rate Accounting for Past Uncertainty: A Major Update of the bayesTFR R Package. Journal of Statistical Software, 106(8), 1-36. doi:10.18637/jss.v106.i08.

L. Alkema, A. E. Raftery, P. Gerland, S. J. Clark, F. Pelletier, Buettner, T., Heilig, G.K. (2011). Probabilistic Projections of the Total Fertility Rate for All Countries. Demography, Vol. 48, 815-839. doi:10.1007/s13524-011-0040-5.

P. Liu, and A. E. Raftery (2020). Accounting for Uncertainty About Past Values In Probabilistic Projections of the Total Fertility Rate for All Countries. Annals of Applied Statistics, Vol 14, no. 2, 685-705. doi:10.1214/19-AOAS1294.

Raftery, A.E., Alkema, L. and Gerland, P. (2014). Bayesian Population Projections for the United Nations. Statistical Science, Vol. 29, 58-68. doi:10.1214/13-STS419.

Hana Sevcikova, Adrian E. Raftery, Patrick Gerland (2018). Probabilistic Projection of Subnational Total Fertility Rates. Demographic Research, Vol. 38(60), 1843-1884. doi:10.4054/DemRes.2018.38.60.


## Not run: 
# This command produces output data such as in the directory ex-data
sim.dir <- tempfile()
# Phase II MCMCs
m <- run.tfr.mcmc(nr.chains=1, iter=60, output.dir=sim.dir, seed=1, verbose=TRUE)
# Phase III MCMCs (not included in the package)
m3 <- run.tfr3.mcmc(sim.dir=sim.dir, nr.chains=2, iter=100, thin=1, seed=1, verbose=TRUE)
# Prediction
pred <- tfr.predict(m, burnin=30, burnin3=50, verbose=TRUE)
summary(pred, country='Ghana')
unlink(sim.dir, recursive=TRUE)

## End(Not run)

[Package bayesTFR version 7.4-2 Index]