predict-tfr: Generating Posterior Trajectories of the Total Fertility Rate

In PPgp/bayesTFR: Bayesian Fertility Projection

Generating Posterior Trajectories of the Total Fertility Rate

Description

Using the posterior parameter samples simulated by run.tfr.mcmc (and possibly run.tfr3.mcmc) the function generates posterior trajectories for the total fertility rate for all countries of the world.

Usage

tfr.predict(mcmc.set = NULL, end.year = 2100, 
    sim.dir = file.path(getwd(), "bayesTFR.output"), 
    replace.output = FALSE, start.year = NULL, 
    nr.traj = NULL, thin = NULL, burnin = 2000,
    use.diagnostics = FALSE, use.tfr3 = TRUE, burnin3 = 2000,
    mu = 2.1, rho = 0.8859, sigmaAR1 = 0.1016, min.tfr = 0.5,
    use.correlation = FALSE, save.as.ascii = 0, output.dir = NULL, 
    subdir = "predictions", low.memory = TRUE, seed = NULL, 
    verbose = TRUE, uncertainty = FALSE, ...)

Arguments

mcmc.set	Object of class bayesTFR.mcmc.set corresponding Phase II MCMCs. If it is NULL, the object is loaded from the directory given by sim.dir.
end.year	End year of the prediction.
sim.dir	Directory with the MCMC simulation results. It should equal to the output.dir argument in run.tfr.mcmc.
replace.output	Logical. If TRUE, existing predictions in output.dir will be replaced by results of this run.
start.year	Start year of the prediction. By default the prediction is started at the next time period after present.year set in the estimation step. If start.year is smaller than the default, projections for countries and time periods that have data available after start.year are set to those data.
nr.traj	Number of trajectories to be generated. If NULL, the argument thin is taken to determine the number of trajectories. If both are NULL, the number of trajectories corresponds to the size of the parameter sample.
thin	Thinning interval used for determining the number of trajectories. Only relevant, if nr.traj is NULL.
burnin	Number of iterations to be discarded from the beginning of the parameter traces.
use.diagnostics	Logical determining if an existing convergence diagnostics for phase II MCMCs should be used for choosing the values of thin and burnin. In such a case, arguments nr.traj, thin and burnin are ignored. The ‘best’ values are chosen from results of running the tfr.diagnose function. Only diagnostics can be used that suggest a convergence of the underlying MCMCs. If there are more than one such objects, the one is chosen whose recommendation for the number of trajectories is larger and closest to 2000.
use.tfr3	Logical determining if phase III should be predicted via MCMCs (simulated via run.tfr3.mcmc) or a classic AR(1) process. If TRUE but no phase III MCMCs were simulated, a warning is given and the prediction switches automatically to a classic AR(1) process.
burnin3	Burnin used for phase III MCMCs. Only relevant if use.tfr3 is TRUE.
save.as.ascii	Either a number determining how many trajectories should be converted into an ASCII file, or “all” in which case all trajectories are converted. It should be set to 0, if no conversion is desired.
output.dir	Directory into which the resulting prediction object and the trajectories are stored. If it is NULL, it is set to either sim.dir, or to output.dir of mcmc.set$meta if mcmc.set is given.
subdir	Subdirectory of output.dir to store the predictions. It is defined relative to output.dir and can only have one level.
low.memory	Logical indicating if the prediction should run in a low-memory mode. If it is FALSE, the whole traces of all parameters, including the burnin, are loaded into memory. Otherwise, burnins are discarded and parameters are loaded as they are needed and are not kept in the memory.
mu	Long-term mean \mu in the AR(1) projection model. Only used if use.tfr3 is FALSE.
rho	Autoregressive parameter \rho in AR(1) projection model. If it is NULL it is estimated from the data. Only used if use.tfr3 is FALSE.
sigmaAR1	Standard deviation s of AR(1) distortion terms in short-term projections. If it is NULL it is estimated from the data. It can be a single value or a vector giving the standard deviations for single projections. If the vector is shorter than the number of projections simulated via the AR(1) process, the last value is repeated for the remaining projections. In case of a single value (default), the standard deviation is kept constant over all AR(1) projections. Only used if use.tfr3 is FALSE.
min.tfr	Smallest TFR value allowed.
use.correlation	Logical. If TRUE the model errors are sampled jointly for all countries (Fosdick and Raftery, 2014).
seed	Seed of the random number generator. If NULL no seed is set. It can be used to generate reproducible projections.
verbose	Logical switching log messages on and off.
uncertainty	Logical. If the MCMC steps has considered uncertainty of past TFR and uncertainty=TRUE, starting point of prediction trajectories will be the last estimated trajectories of TFR. Otherwise, it will use last observed TFR as starting point of prediction.
...	Further arguments passed to the underlying functions.

Details

The trajectories are generated using a distribution of country-specific decline curves (Alkema et al 2011) and either a classic AR(1) process or a country-specific AR(1) process (Raftery et al 2013). Phase II parameter samples simulated using run.tfr.mcmc are used from all chains, from which the given burnin was discarded. They are evenly thinned to match nr.traj or using the thin argument. Such thinned parameter traces, collapsed into one chain, if they do not already exist, are stored on disk into the sub-directory ‘{thinned_mcmc_t_b’ where t is the value of thin and b the value of burnin (see create.thinned.tfr.mcmc).

If Phase III is projected using a BHM (i.e. if use.tfr3 is TRUE), parameter samples simulated via run.tfr3.mcmc are used from which burnin (given by burnin3) is discarded and the chains are evenly thinned in a way that the total size corresponds to the final size of the Phase II parameter samples. Countries for which there are no simulated country-specific Phase III parameters (e.g. because their TFR is still in Phase II or it is an aggregated region) use samples of the “world” AR(1) parameters.

The projection is run for all missing values before the present year, if any. Medians over the trajectories are used as imputed values and the trajectories are discarded. The process then continues by projecting the future values where all generated trajectories are kept.

The resulting prediction object is saved into ‘{output.dir}/{subdir}’. Trajectories for all countries are saved into the same directory in a binary format, one file per country. At the end of the projection, if save.as.ascii is larger than 0, the function converts the given number of trajectories into a CSV file of a UN-specific format. They are selected by equal spacing (see function convert.tfr.trajectories for more details on the conversion). In addition, two summary files are created: one in a user-friendly format, the other using a UN-specific coding of the variants and time (see write.projection.summary for more details).

Value

Object of class bayesTFR.prediction which is a list containing components:

quantiles	A n \times q \times p array of quantile values computed on all trajectories. n is the number of countries, q is the number of quantile bounds and p is the number of projections.
traj.mean.sd	A n \times 2 \times p array holding the mean of all trajectories in the first column and the standard deviation in the second column. n and p are the number of countries and number of projections, respectively.
nr.traj	Number of trajectories.
trf_matrix_reconstructed	Matrix containing imputed TFR values on spots where the original TFR matrix has missing values, i.e. between the last observed data point and the present year.
output.directory	Directory where trajectories corresponding to this prediction are stored.
nr.projections	Number of projections.
burnin, thin, burnin3, thin3	Burnin and thin used for this prediction for Phase II and Phase III, respectively.
end.year	The end year of this prediction.
mu, rho, sigma_t, sigmaAR1	Parameters of the AR(1) process. sigma_t is a vector of actual values of the standard deviation s used for each projection.
min.tfr	Input value of minimum threshold for TFR.
na.index	Index of trajectories for which at least one country got NA values.
mcmc.set	Object of class bayesTFR.mcmc.set used for this prediction, i.e. the burned, thinned, and collapsed MCMC chain.

Author(s)

Hana Sevcikova, Leontine Alkema, Peiran Liu, Bailey Fosdick

References

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. \Sexpr[results=rd]{tools:::Rd_expr_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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s13524-011-0040-5")}.

Raftery, A.E., Alkema, L. and Gerland, P. (2014). Bayesian Population Projections for the United Nations. Statistical Science, Vol. 29, 58-68. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1214/13-STS419")}.

Fosdick, B., Raftery, A.E. (2014). Regional Probabilistic Fertility Forecasting by Modeling Between-Country Correlations. Demographic Research, Vol. 30, 1011-1034. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.4054/demres.2014.30.35")}

See Also

run.tfr.mcmc, run.tfr3.mcmc, create.thinned.tfr.mcmc, convert.tfr.trajectories, write.projection.summary, get.tfr.prediction, summary.bayesTFR.prediction

Examples

## Not run: 
sim.dir <- tempfile()
m <- run.tfr.mcmc(nr.chains=1, iter=10, output.dir=sim.dir, verbose=TRUE)
m3 <- run.tfr3.mcmc(sim.dir=sim.dir, nr.chains=2, iter=40, thin=1, verbose=TRUE)
pred <- tfr.predict(m, burnin=0, burnin3=10, verbose=TRUE)
summary(pred, country="Iceland")
unlink(sim.dir, recursive=TRUE)

## End(Not run)

PPgp/bayesTFR documentation built on Nov. 5, 2024, 1:57 p.m.