bayesTFR (version 4.2-0)

bayesTFR-package: Bayesian Fertility Projection

Description

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.

Rdversion

1.1

docType

package

Details

ll{ Package: bayesTFR Version: 4.2-0 Date: 2015-7-9 License: GPL (>= 2) URL: http://bayespop.csss.washington.edu }

The projection follows a method developed by Alkema et al. (2011) and Raftery et al (2013). It uses historical data provided by the United Nations (included in the package) 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.

The main functions of the package are:

• run.tfr.mcmc: Evokes running a Markov Chain Monte Carlo (MCMC) simulation for TFR in Phase II using one or more chains, possibly in parallel. It results in a posterior sample of the mcmc parameters. Existing simulation runs can be resumed usingcontinue.tfr.mcmc.
• run.tfr3.mcmc: Starts MCMCs for TFR in Phase III. Existing simulation runs can be resumed usingcontinue.tfr3.mcmc.
• tfr.predict: Using the posterior parameter samples it derives posterior trajectories of the total fertility rate for all countries.
• run.tfr.mcmc.extra: Runs MCMC for extra countries or regions, i.e. for countries not included in the Bayesian hierarchical model. It can be also used for aggregations.
• tfr.predict.extra: Generates predictions for extra countries or aggregated regions.

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:

• tfr.trajectories.plot: Shows the posterior trajectories for a given country, including their median and given probability intervals.
• tfr.trajectories.table: Shows the posterior trajectories for a given country in a tabular form.
• tfr.map: Shows a TFR world map for a given projection period.
• DLcurve.plot: Shows the posterior curves of the double logistic function used in the simulation, including their median and given probability intervals.
• tfr.partraces.plotandtfr.partraces.cs.plot: Plot the Phase II MCMC traces of country-independent parameters and country-specific parameters, respectively.tfr3.partraces.plotandtfr3.partraces.cs.plotdo the same for Phase III MCMCs.
• tfr.pardensity.plotandtfr.pardensity.cs.plot: Plot the posterior density of the Phase II MCMCs for country-independent parameters and country-specific parameters, respectively.tfr3.pardensity.plotandtfr3.pardensity.cs.plotdo the same for Phase III MCMCs.
• summary.bayesTFR.mcmc.set: Summary function for the MCMC results.
• summary.bayesTFR.prediction: Summary function for the prediction results.

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) function. 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 TFR data are taken from one of the packages wpp2008, wpp2010 or wpp2012, depending on users settings.

References

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. http://www.jstatsoft.org/v43/i01/.

L. Alkema, A. E. Raftery, P. Gerland, S. J. Clark, F. Pelletier, Buettner, T., Heilig, G.K. (2011). http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3367999{Probabilistic Projections of the Total Fertility Rate for All Countries.} Demography, Vol. 48, 815-839.

Raftery, A.E., Alkema, L. and Gerland, P. (2014). http://www.ncbi.nlm.nih.gov/pubmed/25324591{Bayesian Population Projections for the United Nations.} Statistical Science, Vol. 29, 58-68.

Examples

# 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)