bayesTFR (version 2.1-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 and the United Nations demographic time series.

Rdversion

1.1

docType

package

Details

ll{ Package: bayesTFR Version: 2.1-0 Date: 2012-12-14 Depends: R (>= 2.14.2), mvtnorm, coda Suggests: rworldmap, fields, snowFT, googleVis License: GPL (>= 2) URL: http://bayespop.csss.washington.edu }

The projection follows a method developed by Alkema et al. 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 main functions of the package are:

• run.tfr.mcmc: Evokes running a Markov Chain Monte Carlo (MCMC) simulation for 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.
• 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 an MCMC simulation, 2. generate predictions, 3. analyze results (using the functions below). If there are countries that were not included in steps 1. and 2., 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 MCMC traces of country-independent parameters and country-specific parameters, respectively.
• tfr.pardensity.plotandtfr.pardensity.cs.plot: Plot the posterior density of the MCMCs for country-independent parameters and country-specific parameters, respectively.
• summary.bayesTFR.mcmc.set: Summary function for the MCMC results.
• summary.bayesTFR.prediction: Summary function for the prediction results.

For MCMC diagnostics, function coda.list.mcmc creates an object of type mcmc.list that can be used with the coda package. Furthermore, function tfr.diagnose analyzes 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 function. An existing prediction can be accessed via get.tfr.prediction. Existing convergence diagnostics can be accessed using the get.tfr.convergence and get.tfr.convergence.all functions.

There are a few important datasets used as an input into the MCMC simulations, provided by the United Nations Population Division:

• UN2008,UN2010: Contains the historical data of total fertility rates as available for WPP 2008 and WPP 2010.
• WPP2008_LOCATIONS,WPP2010_LOCATIONS: Location dataset (for WPP 2008 and WPP 2010) used as a filter and look-up table.

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). Probabilistic Projections of the Total Fertility Rate for All Countries. Demography, Vol. 48, 815-839. (A Working Paper version at http://www.csss.washington.edu/Papers [nr. 97])

Examples

# This command produces output data such as in the directory ex-data
m <- run.tfr.mcmc(nr.chains=1, iter=60, seed=1, verbose=TRUE)
pred <- tfr.predict(m, burnin=30, verbose=TRUE)
summary(pred, country='Ghana')