e0.predict: Generating Posterior Trajectories of the Life Expectancy
In bayesLife: Bayesian Projection of Life Expectancy

e0.predict

R Documentation

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>

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)

bayesLife documentation built on Sept. 16, 2023, 9:07 a.m.