e0.predict {bayesLife}

Generating Posterior Trajectories of the Life Expectancy

Description

Using the posterior parameter samples simulated by run.e0.mcmc the function generates posterior trajectories for the life expectancy for all countries of the world.

Usage

e0.predict(mcmc.set = NULL, end.year = 2100, 
    sim.dir = file.path(getwd(), "bayesLife.output"), replace.output = FALSE, 
    predict.jmale = TRUE, nr.traj = NULL, thin = NULL, burnin = 10000, 
    use.diagnostics = FALSE, save.as.ascii = 0, start.year = NULL,  
    output.dir = NULL, low.memory = TRUE, ignore.last.observed = FALSE,
    seed = NULL, verbose = TRUE, ...)

Arguments

mcmc.set

Object of class bayesLife.mcmc.set. 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.e0.mcmc.

replace.output

Logical. If TRUE, existing predictions in output.dir will be replaced by results of this run.

predict.jmale

Logical controlling if a joint female-male prediciton should be performed. This is done only if the underlying mcmcs in sim.dir correspond to a female simulation. In such a case the e0.jmale.predict is invoked. Arguments to this function can be passed in ....

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 minimum of the size of the parameter sample and 2000.

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 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 e0.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.

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 (default).

start.year

This argument should be only used if the start year of the prediction is before or at the present year of the MCMC run (see Details below). By default the prediction starts in the next time period after the present year (passed to run.e0.mcmc).

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.

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.

ignore.last.observed

Logical. By default, the prediction (or imputation) for each country starts one time period after the last observed data point for that country defined by the “last.observed” column in the data. If this argument is set to TRUE, the prediction ignores that “last.observed” value and starts at the last data point found in the data. This allows to exclude some time periods from the estimation, but include them in the prediction.

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.

...

Additional arguments passed to the e0.jmale.predict function.

Details

The trajectories are generated using the double logistic function (Chunn et al. 2013). Parameter samples simulated via run.e0.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.e0.mcmc).

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.

A special case is when the argument start.year is given that is smaller or equal the present year. In such a case, imputed missing values before present year are treated as ordinary predictions (trajectories are kept). All historical data between start year and present year are used as projections.

The resulting prediction object is saved into ‘{output.dir}/predictions’. 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.e0.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.e0.projection.summary for more details).

Value

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

quantiles

A n \times q \times p array of quantile values computed on the trajectories. n is the number of countries, q is the number of quantiles and p is the number of projections. Which quantiles are to be computed is determined by the global option e0pred.options("quantiles").

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.

e0.matrix.reconstructed

Matrix containing imputed e0 values on spots where the original e0 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

Burnin used for this prediction.

end.year

The end year of this prediction.

start.year

The start.year input argument.

mcmc.set

Object of class bayesLife.mcmc.set used for this prediction, i.e. the burned, thinned, and collapsed MCMC chain.

joint.male

If e0.jmale.predict was invoked, this is an object of class bayesLife.prediction containing male projections. In addition to the components above, it contains elements fit (estimation results from e0.jmale.estimate) and meta.changes (components of bayesLife.mcmc.meta that differ from the female meta component).

Author(s)

Hana Sevcikova, using code from Jennifer Chunn

References

J. L. Chunn, A. E. Raftery, P. Gerland, H. Sevcikova (2013): Bayesian Probabilistic Projections of Life Expectancy for All Countries. Demography 50(3):777-801. <doi:10.1007/s13524-012-0193-x>

See Also

run.e0.mcmc, e0.jmale.predict, create.thinned.e0.mcmc, convert.e0.trajectories, get.e0.prediction, summary.bayesLife.prediction

Examples

## Not run: 
m <- run.e0.mcmc(nr.chains = 1, iter = 50, thin = 1, verbose = TRUE)
pred <- e0.predict(m, burnin = 25, verbose = TRUE)
summary(pred, country = "Portugal")

# names and codes of countries included
head(get.countries.table(pred, iso = TRUE))
## End(Not run)