Package 'bayesLife'

Bayesian Projection of the Life Expectancy

Description

Collection of functions for making probabilistic projections of the life expectancy for all countries of the world, using a Bayesian hierarchical model and the United Nations demographic time series. Projections on a subnational level are also supported.

Details

The projection follows a method developed by Chunn et al (2010, 2013). It uses historical data provided by the United Nations to simulate a posterior distribution of the life expectancy for all countries in the world simultaneously.

The package is implemented in a similar way as the bayesTFR package and thus, many functions have their equivalents in bayesTFR. The main functions of the bayesLife package are:

• run.e0.mcmc: Runs 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 using continue.e0.mcmc.

• e0.predict: Using the posterior parameter samples it derives posterior trajectories of the life expectancy for all countries.

• e0.jmale.predict: Given existing outputs of e0.predict for female life expectancy, this function estimates and predicts a joint male life expectancy as described in Raftery et al (2014).

• e0.predict.subnat: Given existing projections on national level, it generates projections on a subnational level, for both, female and male (Sevcikova and Raftery 2021).

A number of functions analyzing results are included in the package:

• e0.trajectories.plot: Shows the posterior trajectories for a given country, including their median and given probability intervals.

• e0.trajectories.table: Shows the posterior trajectories for a given country in a tabular form.

• e0.map and e0.map.gvis: Show a world map of life expectancy for a given projection period.

• e0.DLcurve.plot: Shows the posterior curves of the double logistic function used in the simulation, including their median and given probability intervals.

• e0.partraces.plot and e0.partraces.cs.plot: Plot the MCMC traces of country-independent parameters and country-specific parameters, respectively.

• e0.pardensity.plot and e0.pardensity.cs.plot: Plot the posterior density of the MCMCs for country-independent parameters and country-specific parameters, respectively.

• summary.bayesLife.mcmc.set: Summary function for the MCMC results.

• summary.bayesLife.prediction: Summary function for the prediction results.

For MCMC diagnostics, function e0.coda.list.mcmc creates an object of type “mcmc.list” that can be used with the coda package. Furthermore, function e0.diagnose analyzes the MCMCs using the Raftery diagnostics implemented in the coda package and gives information about parameters that did not converge. Function e0.dl.coverage computes a goodness of fit of the double logistic function.

Existing simulation results can be accessed using the get.e0.mcmc function. An existing prediction can be accessed via get.e0.prediction. Existing predictions on a subnational level can be accessed via get.rege0.prediction.

For a table with countries included in the mcmc or prediction object, the function get.countries.table can be used in the same way as in bayesTFR.

Historical data are taken from one of the packages wpp2019 (default), wpp2017, wpp2015, wpp2012 or wpp2010, depending on users settings. For more recent data, package wpp2022 can be installed from Github (@PPgp).

Note

There is a directory ex-data shipped with the package which contains results from an example simulation, containing one chain with 60 iterations. The Example section below shows how these results were created. These data are used in Example sections throughout the manual. The user can either reproduce the data in her/his local directory, or use the ones from the package.

Author(s)

Hana Sevcikova, Adrian Raftery, Jennifer Chunn

Maintainer: Hana Sevcikova <[email protected]>

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>

A. E. Raftery, N. Li, H. Sevcikova, P. Gerland, G. K. Heilig (2012). Bayesian probabilistic population projections for all countries. Proceedings of the National Academy of Sciences 109:13915-13921.

A. E. Raftery, N. Lalic, P. Gerland (2014). Joint Probabilistic Projection of Female and Male Life Expectancy. Demographic Research, 30:795-822.

H. Sevcikova, A. E. Raftery (2021). Probabilistic Projection of Subnational Life Expectancy. Journal of Official Statistics, , Vol. 37, no. 3, 591-610.

See Also

bayesTFR

Examples

## Not run: 
sim.dir <- tempfile()
m <- run.e0.mcmc(sex = 'F', nr.chains = 1, iter = 60, seed = 1, 
        thin = 1, output.dir = sim.dir, verbose = TRUE)
pred <- e0.predict(m, burnin = 30, verbose = TRUE)
summary(pred, country = "Canada")
unlink(sim.dir, recursive = TRUE)
## End(Not run)

---

MCMC Simulation Object

Description

MCMC simulation object bayesLife.mcmc containing information about one MCMC chain. A set of such objects belonging to the same simulation together with a bayesLife.mcmc.meta object constitute a bayesLife.mcmc.set object.

Details

An object bayesLife.mcmc points to a place on disk (element output.dir) where MCMC results from all iterations are stored. They can be retrieved to the memory using get.e0.mcmc(...).

The object is in standard cases not to be manipulated by itself, but rather as part of a bayesLife.mcmc.set object.

Value

A bayesLife.mcmc object contains parameters of the Bayesian hierarchical model, more specifically, their initial values (all names with the suffix .ini) and values from the last iteration. These are:
Triangle/Triangle.ini, lambda/lambda.ini - world parameters, containing four values each. They correspond to model parameters $\Delta_1, \dots, \Delta_4$ and $\lambda_1, \dots \lambda_4$, respectively.
k/k.ini, z/z.ini, omega/omega.ini, lambda.k/lambda.k.ini,
lambda.z/lambda.z.ini - world parameters, containing one value each. They correspond to model parameters $k$, $z$, $\omega$, $\lambda_k$, and $\lambda_z$, respectively.
Triangle.c - country-specific parameter $\Delta^c_1, \dots, \Delta^c_4$ with four values for each country, i.e. an $4 \times C$ matrix where $C$ is the number of countries.
k.c, z.c - country-specific parameters $k^c$ and $z^c$ (1d arrays of length $C$).
Furthermore, the object contains components:

iter	Total number of iterations the simulation was started with.
finished.iter	Number of iterations that were finished. Results from the last finished iteration are stored in the parameters above.
length	Length of the MCMC stored on disk. It differs from finished.iter only if thin is larger than one.
thin	Thinning interval used when simulating the MCMCs.
id	Identifier of this chain.
output.dir	Subdirectory (relative to output.dir in the bayesLife.mcmc.meta object) where results of this chain are stored.
traces	This is a placeholder for keeping whole parameter traces in the memory. If the processing operates in a low memory mode, it will be 0. It can be filled in using the function get.e0.mcmc(..., low.memory=FALSE). In such a case, traces is a $I \times J$ array where $I$ is the MCMC length and $J$ is the number of parameters.
traces.burnin	Burnin used to retrieve the traces, i.e. how many stored iterations are missing from the beginning in the traces array comparing to the ‘raw’ traces on the disk.
rng.state	State of the random number generator at the end of the last finished interation.
meta	Object of class bayesLife.mcmc.meta used for simulation of this chain.

Author(s)

Hana Sevcikova

See Also

run.e0.mcmc, get.e0.mcmc, bayesLife.mcmc.set, bayesLife.mcmc.meta

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
# loads traces from one chain
m <- get.e0.mcmc(sim.dir, low.memory = FALSE, burnin = 40, chain.ids = 1)
# should have 20 rows, since 60 iterations in total minus 40 burnin
dim(e0.mcmc(m, 1)$traces)
summary(m)

---

MCMC Simulation Meta Object

Description

Simulation meta object bayesLife.mcmc.meta used by all chains of the same MCMC simulation. It contains information that is common to all chains. It is a part of a bayesLife.mcmc.set object.

Details

The object is in standard cases not to be manipulated by itself, but rather as part of a bayesLife.mcmc.set object.

Value

A bayesLife.mcmc.meta object stores values of the various input arguments of the run.e0.mcmc function. These are sex, nr.chains, start.year, present.year, wpp.year, my.e0.file, compression.type.
Furthermore, it contains components:

e0.matrix.all	A $q \times n$ matrix with the United Nations life expectancy estimates. $q$ is number of years, $n$ is number of countries (see nr.countries below). The first $n_e$ columns correspond to countries included in the MCMC estimation (see nr.countries.estimation below), where $n_e <= n$. The order of the countries corresponds to the order of countries in the element regions and regionsDT, see below.
e0.matrix	Like e0.matrix.all, but it has NA values for years that were excluded from the estimation due to setting the start.year and present.year argument, and the ‘last.observed’ column (see Details in run.e0.mcmc).
d.ct	A difference e0 matrix of size $(q-1) \times n$. Each element $x_{t,i}$ is a difference $y_{t+1,i}-y_{t,i}$ where $y$ denotes elements of the e0.matrix. Outliers are set to NA.
loessSD	Matrix of the same dimension as d.ct. It contains values of the loess_sd dataset at the e0 levels of e0.matrix. See also compute.loess.
nr.countries	Number of countries included in the e0 matrices.
nr.countries.estimation	Number of countries included in the MCMC estimation. It must be smaller or equal to nr.countries.
Tc.index	A list with one element per country. For each country, it contains the index within e0.matrix where the observed historical data are not NA, i.e. it points to the data used in the estimation.
regions	List of arrays of length nr.countries. These are: name - Region name for each country. code - Region code for each country. area_name - Area name for each country. area_code - Area code for each country. country_name - Array of country names. country_code - Array of country codes. Any country indices in the bayesLife.mcmc.meta object are derived from this component.
regionsDT	Like regions but for convenience it is a data.table object. A country in i-th row of this table has e0 data stored in the i-th column of e0.matrix.
output.dir	Directory for storing simulation output.
mcmc.options	List of various options used in the estimation. See e0mcmc.options.
country.bounds	List of country-specific bounds of the various parameter priors, as constructed from the country.overwrites option (see e0mcmc.options).
suppl.data	If supplemental data were used in the simulation (i.e. start year was set prior to 1950), this is a list containing information about the additional data. It has the following components of the same form as described above, but related only to the additional data: e0.matrix, regions, regionsDT, Tc.index, nr.countries, d.ct, loessSD. In addition, it has the vectors index.from.all.countries - a vector of size nr.countries (all countries) where each element is an index to the supplemental data, i.e. a match from regions$country_code to suppl.data$regions$country_code. index.to.all.countries - a vector of size suppl.data$nr.countries (additional countries) where each element is an index to all data, i.e. a match from suppl.data$regions$country_code to regions$country_code.

Author(s)

Hana Sevcikova

See Also

run.e0.mcmc, get.e0.mcmc, e0mcmc.options

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
m <- get.e0.mcmc(sim.dir)
summary(m, meta.only = TRUE)
names(m$meta)

---

Computing Residuals and Fitting Local Polynomial Regression

Description

Functions for computing residuals from the observed life expectancy and MCMC estimation, and fitting a local polynomial regression.

Usage

compute.residuals(sim.dir, burnin = 1000)

compute.loess(sim.dir = NULL, burnin = 1000, residuals = NULL)

Arguments

sim.dir	Directory with the MCMC estimation. In compute.loess, it is only used if residuals is not given.
burnin	Number of (unthinned) iterations to be discarded. In compute.loess, it is only used if residuals is not given.
residuals	Residuals can be computed outside of the compute.loess function and passed as the residuals argument. If not given, the compute.loess function calls compute.residuals internally, in which case sim.dir must be given.

Details

The Bayesian hierarchical model for life expectancy uses a lowess curve as a multiplier of the variance. The dataset is stored in the package as the loess_sd dataset. These functions can be used to re-compute this loess_sd dataset. In such a case, the simulation should be run with the argument constant.variance = TRUE (in run.e0.mcmc).

The residuals are computed for each country as the absolute differences between the observed life expectancy increases and the mean of the estimated double logistic function at the corresponding life expectancy level.

Value

compute.residuals returns a data frame with columns ‘x’ (life expectancy levels) and ‘y’ (absolute residuals).

compute.loess also returns a data frame with columns ‘x’ and ‘y’, where ‘x’ is the same as before (with added a minimum and maximum) and ‘y’ is the local polynomial fit with constant tails.

Author(s)

Hana Sevcikova

See Also

run.e0.mcmc

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
resid <- compute.residuals(sim.dir, burnin = 30)
lws <- compute.loess(residuals = resid)

# plot residuals and loess
plot(resid$x, resid$y, ylim = c(0, 4))
lines(lws$x, lws$y, col = "red")

---

Converting Trajectories of Life Expectancy into ACSII Files

Description

Converts trajectories of the life expectancy stored in a binary format into two CSV files of a UN-specific format.

Usage

convert.e0.trajectories(dir = file.path(getwd(), "bayesLife.output"), 
    n = 1000, subdir = "predictions", output.dir = NULL, verbose = FALSE)

Arguments

dir	Directory containing the prediction object. It should correspond to the output.dir argument of the e0.predict function.
n	Number of trajectories to be stored. It can be either a single number or the word “all” in which case all available trajectories are converted.
subdir	Name of subdirectory of dir containing the prediction.
output.dir	Directory in which the resulting files will be stored. If NULL the same directory is used as for the prediction. Otherwise, if the directory contains joint predictions for both sexes, the ouptuts are stored into subdirectories ‘F’ and ‘M’.
verbose	Logical switching log messages on and off.

Details

The function creates two files per sex. One is called “ascii_trajectories.csv”, it is a comma-separated table with the following columns:

“LocID”:

country code

“Period”:

prediction interval, e.g. 2015-2020

“Year”:

middle year of the prediction interval

“Trajectory”:

identifier of the trajectory

“e0”:

life expectancy

The second file is called “ascii_trajectories_wide.csv”, it is also a comma-separated table and it contains the same information as above but in a ‘transposed’ format. I.e. the data for one country are ordered in columns, thus, there is one column per country. The country columns are ordered alphabetically.

If n is smaller than the total number of trajectories, the trajectories are selected using equal spacing.

Note

This function is automatically called from the e0.predict function, therefore in standard cases it will not be needed to call it directly. However, it can be useful for example, if different number of trajectories are to be converted, without having to re-run the prediction.

Author(s)

Hana Sevcikova

See Also

write.e0.projection.summary, e0.predict

Examples

## Not run: 
sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
pred.dir <- file.path(getwd(), "exampleLEpred")

# stores 10 trajectories out of 30 (60-30) into 
# exampleLEpred/predictions/ascii_trajectories.csv (for female)
# and exampleLEpred/predictions/joint_male/ascii_trajectories.csv (for male)
e0.predict(sim.dir = sim.dir, output.dir = pred.dir, 
            burnin = 30, save.as.ascii = 10, verbose = TRUE)
            
# stores all 30 trajectories into the current directory
convert.e0.trajectories(dir = pred.dir, n = "all", output.dir = ".", verbose = TRUE)

# Note: If the output.dir argument in e0.predict is omitted, 
# call convert.e0.trajectories with dir = sim.dir 

## End(Not run)

---

Convertion to coda's Objects

Description

The functions convert MCMC traces (simulated using run.e0.mcmc) into objects that can be used with the coda package.

Usage

e0.coda.list.mcmc(mcmc.list = NULL, country = NULL, chain.ids = NULL, 
    sim.dir = file.path(getwd(), "bayesLife.output"), 
    par.names = NULL, par.names.cs = NULL, low.memory = FALSE, ...)
    
## S3 method for class 'bayesLife.mcmc'
coda.mcmc(mcmc, country = NULL, par.names = NULL, par.names.cs = NULL, ...)

Arguments

mcmc.list	List of bayesLife.mcmc objects, or an object of class bayesLife.mcmc.set or bayesLife.prediction. If it is NULL, the MCMCs are loaded from sim.dir. Either mcmc.list or sim.dir must be given.
mcmc	Object of class bayesLife.mcmc.
country	Country name or code. It is used in connection with the par.names.cs argument (see below).
chain.ids	Vector of chain identifiers. By default, all chains available in the mcmc.list object are included.
sim.dir	Directory with the MCMC simulation results. Only used if mcmc.list is NULL.
par.names	Names of country-independent parameters to be included.
par.names.cs	Names of country-specific parameters to be included. The argument country is used to filter out traces that correspond to a specific country. If country is not given, for each parameter, traces for all countries are included.
low.memory	Logical indicating if the function should run in a memory-efficient mode.
...	Additional arguments passed to the coda's mcmc function, such as burnin and thin.

Value

The function e0.coda.list.mcmc returns an object of class “mcmc.list”. The function coda.mcmc returns an object of class “mcmc”, both defined in the coda package.

Author(s)

Hana Sevcikova

See Also

e0.partraces.plot for plotting the MCMC traces and summary.bayesLife.mcmc.set.

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
coda.list <- e0.coda.list.mcmc(sim.dir = sim.dir, country = "France", burnin = 30)
summary(coda.list)

---

Convergence Diagnostics for Markov Chain Monte Carlo of Life Expectancy

Description

Function e0.diagnose runs convergence diagnostics of existing MCMCs, using the raftery.diag function from the coda package.

Usage

e0.diagnose(sim.dir, thin = 225, burnin = 10000, express = FALSE, 
    country.sampling.prop = NULL, keep.thin.mcmc = FALSE, verbose = TRUE)

Arguments

sim.dir	Directory with the MCMC simulation results.
thin	Thinning interval.
burnin	Number of iterations to be discarded from the beginning of the parameter traces.
express	Logical. If TRUE, the convergence diagnostics is run only on the country-independent parameters. If FALSE, the country-specific parameters are included in the diagnostics. The number of countries can be controlled by country.sampling.prop.
country.sampling.prop	Proportion of countries that are included in the diagnostics. If it is NULL and express=FALSE, all countries are included. Setting here a number between 0 and 1, one can limit the number of countries which are then randomly sampled. Note that for long MCMCs, this argument may significantly influence the run-time of this function.
keep.thin.mcmc	Logical. If TRUE the thinned traces used for computing the diagnostics are stored on disk (see create.thinned.e0.mcmc).
verbose	Logical switching log messages on and off.

Details

The function invokes the e0.raftery.diag function separately for country-independent parameters and for country-specific parameters. It results in two possible states: red, i.e. it did not converge, and green, i.e. it converged. The resulting object is stored in
‘{sim.dir}/diagnostics/bayesLife.convergence_{thin}_{burnin}.rda’ and can be accessed using the function get.e0.convergence.

Function has.mcmc.converged from the bayesTFR package can be used to check if the existing diagnostics converged.

Value

e0.diagnose returns an object of class bayesLife.convergence with components:

result	Table containing all not-converged parameters. Its columns include ‘Total iterations needed’ and ‘Remaining iterations’.
lresult.country.independent	Number of rows in result that correspond to country-independent paramters. These rows are groupped at the beginning of the table.
country.independent	Result of e0.raftery.diag processed on country-independent parameters.
country.specific	Result of e0.raftery.diag processed on country-specific parameters.
iter.needed	Number of additional iterations suggested in order to achieve convergence.
iter.total	Total number of iterations of the original unthinned set of chains.
use.nr.traj	Suggestion for number of trajectories in generating predictions.
burnin	Burnin used.
thin	Thinning interval used.
status	Vector of character strings containing the result status. Possible values: ‘green’, ‘red’.
mcmc.set	Object of class bayesLife.mcmc.set that corresponds to the original set of MCMCs on which the diagnostics was run.
thin.mcmc	If keep.thin.mcmc is TRUE, it is an object of class bayesLife.mcmc.set that corresponds to the thinned mcmc set on which the diagnostics was run, otherwise NULL.
express	Value of the input argument express.
nr.countries	Vector with elements used - number of countries used in this diagnostics, and total - number of countries that this mcmc.set object was estimated on.

Author(s)

Hana Sevcikova, Adrian Raftery

See Also

e0.raftery.diag, raftery.diag, summary.bayesLife.convergence, get.e0.convergence, create.thinned.e0.mcmc

---

Goodness of Fit of the Double Logistic Function

Description

The function computes coverage, i.e. the ratio of observed data fitted within the given probability intervals of the predictive posterior distribution of the double logistic function, as well as the root mean square error of the simulation.

Usage

e0.dl.coverage(sim.dir, pi = c(80, 90, 95), burnin = 10000, verbose = TRUE)

Arguments

sim.dir	Directory with the MCMC simulation results. If a prediction and its corresponding thinned mcmcs are available in the simulation directory, those are taken for assessing the goodness of fit.
pi	Probability interval. It can be a single number or an array.
burnin	Burnin. Only relevant if sim.dir does not contain thinned chains.
verbose	Logical switching log messages on and off.

Value

List with the same components as tfr.dl.coverage.

Note

To see the fit visually per country, use e0.DLcurve.plot(..., predictive.distr=TRUE,...).

Author(s)

Hana Sevcikova

See Also

e0.DLcurve.plot

Examples

## Not run: 
sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
e0 <- get.e0.mcmc(sim.dir)
# Note that this simulation is a toy example and thus has not converged.
gof <- e0.dl.coverage(sim.dir)
gof$country.coverage
e0.DLcurve.plot(e0, country=608, predictive.distr=TRUE, pi=c(80, 90, 95))

## End(Not run)

---

Plotting Posterior Distribution of the Double Logistic Function of Life Expectancy

Description

The functions plot the posterior distribution of the double logistic function used in the simulation, including their median and given probability intervals.

Usage

e0.DLcurve.plot(mcmc.list, country, burnin = NULL, pi = 80, 
    e0.lim = NULL, nr.curves = 20, predictive.distr = FALSE, ylim = NULL, 
    xlab = "e(0)", ylab = "5-year gains", main = NULL, show.legend = TRUE, 
    col = c('black', 'red', "#00000020"), ...)
    
e0.DLcurve.plot.all(mcmc.list = NULL, sim.dir = NULL, 
    output.dir = file.path(getwd(), "DLcurves"),
    output.type = "png", burnin = NULL, verbose = FALSE, ...)
    
e0.parDL.plot(mcmc.set, country = NULL, burnin = NULL, lty = 2, 
    ann = TRUE, ...)
	
e0.world.dlcurves(x, mcmc.list, burnin = NULL, ...)

e0.country.dlcurves(x, mcmc.list, country, burnin = NULL, ...)

Arguments

mcmc.list	List of bayesLife.mcmc objects, an object of class bayesLife.mcmc.set or of class bayesLife.prediction. In case of e0.DLcurve.plot.all if it si NULL, it is loaded from sim.dir.
mcmc.set	Object of class bayesLife.mcmc.set or bayesLife.prediction.
country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.
burnin	Number of iterations to be discarded from the beginning of parameter traces.
pi	Probability interval. It can be a single number or an array.
e0.lim	It can be a tuple of the minimum and maximum life expectancy to be shown in the plot. If NULL, it takes the minimum of observed data and 40, and the maximum of observed data and 90.
nr.curves	Number of curves to be plotted. If NULL, all curves are plotted.
predictive.distr	Logical. If TRUE, an error term is added to each trajectory.
ylim, xlab, ylab, main, lty	Graphical parameters passed to the plot function.
show.legend	Logical determining if the legend should be shown.
col	Vector of colors in this order: 1. observed data points, 2. quantiles, 3. trajectories
...	Additional graphical parameters. In addition, any arguments from e0.DLcurve.plot except country can be passed to e0.DLcurve.plot.all.
sim.dir	Directory with the simulation results. Only relevant, if mcmc.list is NULL.
output.dir	Directory into which resulting graphs are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
verbose	Logical switching log messages on and off.
x	e0 values for which the double logistic should be computed.
ann	Logical if parameters should be annotated.

Details

e0.DLcurve.plot plots double logistic curves for the given country. e0.DLcurve.plot.all creates such plots for all countries and stores them in output.dir. Parameters passed to the double logistic function are either thinned traces created by the e0.predict function (if mcmc.list is an object of class bayesLife.prediction), or they are selected by equal spacing from the MCMC traces. In the former case, burnin is set automatically; in the latter case, burnin defaults to 0 since such object has already been “burned”. If nr.curves is smaller than 2000, the median and probability intervals are computed on a sample of 2000 equally spaced data points, otherwise on all plotted curves.

Function e0.parDL.plot draws the means of the DL parameters as vertical and horizontal lines. The lines are added to the current graphical device and annotated if ann is TRUE. If country is NULL, the mean of world parameters are drawn.

Function e0.world.dlcurves returns the DL curves of the hierarchical distribution. Function e0.country.dlcurves returns DL curves for a given country. If mcmc.list is a prediction object, burnin should not be given, as such object has already been “burned”.

Value

e0.world.dlcurves and e0.country.dlcurves return a matrix of size $N \times M$ where $N$ is the number of trajectories and $M$ is the number of values of $x$.

Author(s)

Hana Sevcikova

Examples

## Not run: 
sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
mcmc.set <- get.e0.mcmc(sim.dir = sim.dir)
e0.DLcurve.plot(mcmc.set, country = "Japan", burnin = 40)
e0.parDL.plot(mcmc.set, "Japan")

# add the median of the hierarchical DL curves
x <- seq(40, 90, length = 100)
world <- e0.world.dlcurves(x, mcmc.set, burnin = 40)
qw <- apply(world, 2, median) 
lines(x, qw, col = 'blue')

## End(Not run)

---

Posterior Distribution of Gaps in Female and Male Life Expectancy

Description

The functions plot the posterior distribution of the gaps between female and male life expectancy, modeled and predicted using a model described in Lalic (2011) and Raftery, Lalic & Gerland (2014). This can be done for one country (e0.gap.plot) or for all countries (e0.gap.plot.all).

Usage

e0.gap.plot(e0.pred, country, e0.pred2 = NULL, pi = c(80, 95), 
    nr.traj = 0, xlim = NULL, ylim = NULL, type = "b", 
    xlab = "Year", ylab = "Gap in life expectancy", main = NULL, 
    show.legend = TRUE, ...)
    
e0.gap.plot.all(e0.pred, output.dir = file.path(getwd(), "e0gaps"),
    output.type = "png", verbose = FALSE, ...)

Arguments

e0.pred	Object of class bayesLife.prediction containing female projections. If e0.pred2 is not given, then this object must contain the ‘joint.male’ component, generated using the e0.jmale.predict function.
country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.
e0.pred2	Object of class bayesLife.prediction containing male projections. By default the male projections is taken from the joint female-male projections in e0.pred, see above.
pi	Probability interval. It can be a single number or an array.
nr.traj	Number of trajectories to be plotted.
xlim, ylim, type, xlab, ylab, main	Graphical parameters passed to the plot function.
show.legend	Logical controlling whether the legend should be drawn.
output.dir	Directory into which resulting graphs are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
verbose	Logical switching log messages on and off.
...	Additional graphical parameters. In addition, for e0.gap.plot.all, ... contains any of the arguments of e0.gap.plot.

Author(s)

Hana Sevcikova

References

Lalic, N. (2011). Master's thesis at the Department of Statistics, University of Washington.

A. E. Raftery, N. Lalic, P. Gerland (2014). Joint Probabilistic Projection of Female and Male Life Expectancy. Demographic Research, 30:795-822.

See Also

e0.joint.plot, e0.jmale.estimate, e0.jmale.predict, get.e0.jmale.prediction

Examples

# See example for e0.jmale.predict

---

Estimation of the Joint Female-Male Model

Description

The function estimates the joint female-male model of life expectancy, as described in Raftery et al. (2014, 2012) and Lalic (2011). It consist of two equations with t-distributed errors, see Details below.

Usage

e0.jmale.estimate(mcmc.set, countries.index = NULL, 
    estDof.eq1 = TRUE, start.eq1 = list(dof = 2), max.e0.eq1 = 83, 
    estDof.eq2 = TRUE, start.eq2 = list(dof = 2),
    constant.gap.eq2 = TRUE, include.suppl.gap = FALSE, 
    my.e0.file = NULL, my.locations.file = NULL, 
    verbose = FALSE)

Arguments

mcmc.set	Object of class bayesLife.mcmc.set containing estimation results of female life expectancy.
countries.index	Index of countries (within the mcmc.set object) to be included in the estimation. By default, all countries included in the estimation of mcmc.set are used.
estDof.eq1, estDof.eq2	Logical, controlling whether the degrees of freedom of the first and second equation, respectively, should be estimated. If it is FALSE the degrees of freedom are set using the arguments start.eq1 and start.eq2, respectively.
start.eq1, start.eq2	Argument start of the tlm function of the hett package, which is applied to the first and second equation of the model, respectively. It is a list of possibly four named components, ("beta", "lambda", "dof", "omega"), for the location, scale, degrees of freedom parameters and random scale effects respectively. If estDof.eq1 (estDof.eq2) is FALSE, the "dof" component must be given.
max.e0.eq1	Maximum female life expectancy of records included in the estimation of the first equation (parameter $M$ in Details below).
constant.gap.eq2	Logical. If TRUE the coefficient of the second equation ($\gamma_1$) is set to one and the standard deviation is estimated under the assumption of normal distribution.
include.suppl.gap	If TRUE data prior 1950 are used in the estimation of the gap model.
my.e0.file	File name containing user-specified male time series for one or more countries. The function replaces the corresponding country data from the WPP dataset by values in this file. Only columns are replaced that match column names of the WPP dataset.
my.locations.file	File name containing user-specified locations if different from the default UNlocations dataset. It should be the same file as passed to run.e0.mcmc for female life expectancy.
verbose	Logical switching log messages on and off. If TRUE summary results from the tlm function of both equations are shown.

Details

The joint female-male life expectancy model is a model for estimating gaps $G$ between female and male life expectancy. It consists of two parts, see Equation (1) in Raftery et al. (2012):
1. If $l_{c,t} \leq M$, then

$G_{c,t} = \beta_0 + \beta_1 l_{c,1953} + \beta_2 G_{c,t-1} + \beta_3 l_{c,t} + \beta_4 (l_{c,t}-75)_+ + \epsilon_{c,t}$

where $\epsilon_{c,t}$ is iid $t(\mu=0, \sigma_1^2, \nu_1)$.

2. If $l_{c,t} > M$, then

$G_{c,t} = \gamma_1 G_{c,t-1} + \epsilon_{c,t}$

where $\epsilon_{c,t}$ is iid $t(\mu=0, \sigma_2^2, \nu_2)$.

Here, $t$ is the time and $c$ is the country index. $G_{c,t}$ is the gap for country $c$ at time $t$ and $l_{c,t}$ is the female life expectancy for country $c$ at time $t$. $M$ can be set in the max.e0.eq1 argument.

Using the tlm function of the hett package, the function estimates the coefficients $\beta_i$ ($i=1,\dots,4$) and $\gamma_1$, as well as paramteres $\sigma_j$ ($j=1,2$) and optionally the degrees of freedom $\nu_j$ ($j=1,2$). If constant.gap.eq2 is TRUE, $\gamma_1$ is set to 1 and $\epsilon_{c,t}$ is iid $N(\mu=0, \sigma_2^2)$.

The mcmc.set object should be a bayesLife.mcmc.set object obtained from a simulation of a female life expectancy. Note that since only the observed data and no MCMC results are used in this estimation, the mcmc.set object can be obtained from a toy simulation such as in the example below. The function extracts observed data from this object and treats them as $l_{c,t}$. For the male historical time series, the function takes the male WPP dataset (e0M) from the same wpp package as the female data, and possibly partly replaces the male dataset by any user-specified data given in my.e0.file.

Value

List with the components, eq1 and eq2, each containing estimation results from the first and second equation, respectively. These are:

coefficients	Estimated coefficients $\beta_i$.
sigma	Parameter $\sigma_j$.
dof	Degrees of freedom $\nu_j$. If estDof.eq1 (estDof.eq2) is TRUE this parameter is estimated, otherwise it is set to the value of start.eq1$dof (start.eq2$dof).

Author(s)

Hana Sevcikova

References

A. E. Raftery, N. Lalic, P. Gerland (2014). Joint Probabilistic Projection of Female and Male Life Expectancy. Demographic Research, 30:795-822.

A. E. Raftery, N. Li, H. Sevcikova , P. Gerland, G. K. Heilig (2012). Bayesian probabilistic population projections for all countries. Proceedings of the National Academy of Sciences 109:13915-13921.

Lalic, N. (2011). Master's thesis at the Department of Statistics, University of Washington.

See Also

e0.jmale.predict

Examples

## Not run: 
sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
m <- get.e0.mcmc(sim.dir)
fit <- e0.jmale.estimate(m, verbose = TRUE)

## End(Not run)

---

Prediction of the Joint Female-Male Model

Description

Prediction of the joint female-male model of life expectancy, as described in Raftery et al. (2014, 2012) and Lalic (2011).

Usage

e0.jmale.predict(e0.pred, estimates = NULL, gap.lim = c(0, 18), 
    max.e0.eq1.pred = 86, my.e0.file = NULL, my.locations.file = NULL,
    save.as.ascii = 1000, resample.outrange = TRUE, verbose = TRUE, ...)

Arguments

e0.pred	Object of class bayesLife.prediction containing female projections of life expectancy.
estimates	List of the same structure as returned by e0.jmale.estimate, containing the model estimation results. If it is not given, the e0.jmale.estimate function is invoked.
gap.lim	Vector of length two giving the minimum and maximum bounds for the female-male life expectancy gaps. See argument resample.outrange for two ways of handling gaps that fall outside of this range.
max.e0.eq1.pred	Maximum female life expectancy for male projections handled by the first equation (parameter $M$ in Equation (1) in Raftery et al. (2012)).
my.e0.file	File name containing user-specified male time series for one or more countries. The function replaces the corresponding country data from the WPP dataset by values in this file. Only columns are replaced that match column names of the WPP dataset.
my.locations.file	File name containing user-specified locations if different from the default UNlocations dataset. It should be the same file as passed to run.e0.mcmc for female life expectancy.
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.
resample.outrange	Logical indicating if values outside of the allowed gap range given by gap.lim should be resampled. If set to FALSE, such values are truncated instead.
verbose	Logical switching log messages on and off.
...	Further arguments passed to e0.jmale.estimate.

Details

If no estimates are given, the function invokes an estimation by calling e0.jmale.estimate. Using those estimates, the male life expectancy is projected forward in time (as a function of a female-male gap), using the female predictions from e0.pred. The initial male data point is extracted from the male WPP dataset (e0M) and possibly partly replaced by any user-specified data given in my.e0.file.

The resulting trajectory files are stored in a subdirectory of the female prediction directory, called ‘joint_male’. Furthermore, an object of class bayesLife.prediction is created and added to e0.pred as a component called joint.male.

The predicted gaps can be viewed using the e0.gap.plot function.

Value

Updated e0.pred object where a new component was added, called joint.male. It is also an object of class bayesLife.prediction and it contains results from this prediction.

Author(s)

Hana Sevcikova

References

A. E. Raftery, N. Lalic, P. Gerland (2014). Joint Probabilistic Projection of Female and Male Life Expectancy. Demographic Research, 30:795-822.

A. E. Raftery, N. Li, H. Sevcikova , P. Gerland, G. K. Heilig (2012). Bayesian probabilistic population projections for all countries. Proceedings of the National Academy of Sciences 109:13915-13921.

Lalic, N. (2011). Master's thesis at the Department of Statistics, University of Washington.

See Also

e0.jmale.estimate, get.e0.jmale.prediction, e0.predict, e0.gap.plot

Examples

## Not run: 
sim.dir <- tempfile()
m <- run.e0.mcmc(sex = 'F', nr.chains = 1, iter = 30, thin = 1, output.dir = sim.dir)
pred <- e0.predict(m, burnin = 15, verbose = FALSE, save.as.ascii = 0, 
                    predict.jmale = FALSE)
both.pred <- e0.jmale.predict(pred)
e0.trajectories.plot(both.pred, 'Guatemala') # Female
e0.trajectories.plot(get.e0.jmale.prediction(both.pred), 'Guatemala') # Male

# Marginal distribution of the sex-specific projections
e0.trajectories.plot(both.pred, 'GTM', both.sexes = TRUE,  pi = 80)

# Plotting the gaps
e0.gap.plot(both.pred, 'GTM')

# Joint distribution of the sex-specific projections
e0.joint.plot(both.pred, 'Guatemala', pi = 80, years = c(2013, 2043, 2093))

unlink(sim.dir, recursive = TRUE)

## End(Not run)

---

Joint Posterior Distribution of Female and Male Life Expectancy

Description

The functions plot the joint posterior distribution of female and male life expectancy, modeled and predicted using the joint model described in Lalic (2011) and Raftery, Lalic & Gerland (2014). This can be done for one country (e0.joint.plot) or for all countries (e0.joint.plot.all).

Usage

e0.joint.plot(e0.pred, country, pi = 95, years, nr.points = 500, 
    obs.pch = 17, obs.cex=1, xlim = NULL, 
    ylim = NULL, xlab = "Female life expectancy", ylab = "Male life expectancy", 
    main = NULL, col = NULL, show.legend = TRUE, add = FALSE, ...)
    
e0.joint.plot.all(e0.pred, output.dir = file.path(getwd(), "e0joint"),
    output.type = "png", verbose = FALSE, ...)

Arguments

e0.pred	Object of class bayesLife.prediction containing female projections.
country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.
pi	Probability interval. It can be a single number or an array.
years	Array of future years for which to plot the distribution.
nr.points	Number of points shown in the plot for each year.
obs.pch, obs.cex	Graphical parameters used for displaying observed data or data without variation.
xlim, ylim, xlab, ylab, main	Graphical parameters passed to the plot function.
col	Array of colors, one for each year.
show.legend	Logical controlling whether the legend should be drawn.
add	Logical controlling whether the distribution should be plotted into a new graphic device (FALSE) or into an existing device (TRUE).
output.dir	Directory into which resulting graphs are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
verbose	Logical switching log messages on and off.
...	Additional graphical parameters passed to the lines function drawing ellipses. In addition, for e0.joint.plot.all, ... contains any of the arguments of e0.joint.plot.

Author(s)

Hana Sevcikova, Adrian Raftery

References

Lalic, N. (2011). Master's thesis at the Department of Statistics, University of Washington.

A. E. Raftery, N. Lalic, P. Gerland (2014). Joint Probabilistic Projection of Female and Male Life Expectancy. Demographic Research, 30:795-822.

See Also

e0.gap.plot, e0.trajectories.plot, e0.jmale.predict

Examples

# See example for e0.jmale.predict

---

World Map of the Life Expectancy

Description

Generates a world map of the life expectancy for given quantile and projection or estimation period, using different techniques: e0.map and e0.map.all use rworldmap, e0.ggmap uses ggplot2, and e0.map.gvis creates an interactive map via GoogleVis.

Usage

e0.map(pred, ...)
	
e0.ggmap(pred, ...)

e0.map.all(pred, output.dir, output.type = "png", 
    e0.range = NULL, nr.cats = 50, same.scale = TRUE, 
    quantile = 0.5, file.prefix = "e0wrldmap_", ...)
			
get.e0.map.parameters(pred, e0.range = NULL, 
    nr.cats = 50, same.scale = TRUE, quantile = 0.5, ...)
    
e0.map.gvis(pred, ...)

Arguments

pred	Object of class bayesLife.prediction.
output.dir	Directory into which resulting maps are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
e0.range	Range of the life expectancy to be displayed. It is of the form c(e0.min, e0.max). By default, the whole range is considered. Note that countries with values outside of the given range will appear white.
nr.cats	Number of color categories.
same.scale	Logical controlling if maps for all years of this prediction object should be on the same color scale.
quantile	Quantile for which the map should be generated. It must be equal to one of the values in dimnames(pred$quantiles[[2]]), i.e. 0, 0.025, 0.05, 0.1, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.75, 0.8, 0.9, 0.95, 0.975, 1. Value 0.5 corresponds to the median.
file.prefix	Prefix for file names.
...	In e0.map, ... are all arguments that can be passed to tfr.map, such as quantile, year, projection.index, par.name, adjusted, device, main, device.args, and data.args. In e0.map.gvis, ... are all arguments that can be passed to tfr.map.gvis. In e0.ggmap, ... are arguments that can be passed to tfr.ggmap. In addition, functions that use the rworldmap package accept arguments passed to the rworldmap::mapCountryData function.

Details

e0.map creates a single map for the given time period and quantile. e0.map.all generates a sequence of maps, namely one for each projection period. If the package fields is installed, a color bar legend at the botom of the map is created.

Function get.e0.map.parameters can be used in combination with e0.map. (Note that get.e0.map.parameters is called from inside of e0.map.all.) It sets breakpoints for the color scheme using quantiles of a fitted gamma distribution.

Function e0.ggmap is similar to e0.map, but used the ggplot2 package in combination with the geom_sf function.

Function e0.map.gvis creates an interactive map using the googleVis package and opens it in an internet browser. It also generates a table of the mapped values that can be sorted by columns interactively in the browser.

By default, both e0.map, e0.ggmap and e0.map.gvis produce maps of life expectancy. Alternatively, the functions can be used to plot country-specific MCMC parameters into a world map. They are given by the argument par.name. One can pass any value from e0.parameter.names.cs.extended().

Value

get.e0.map.parameters returns a list with elements:

pred	The object of class bayesLife.prediction used in the function.
quantile	Value of the argument quantile.
catMethod	If the argument same.scale is TRUE, this element contains breakpoints for categorization. It is generated from a fitted gamma distribution. Otherwise, it is NULL.
numCats	Number of categories.
coulourPalette	Subset of the rainbow palette, starting from dark blue and ending at red.
...	Additional arguments passed to the function.

Author(s)

Hana Sevcikova, Adrian Raftery

See Also

tfr.map

Examples

## Not run: 
sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
pred <- get.e0.prediction(sim.dir = sim.dir)

# Using ggplot2
e0.ggmap(pred, same.scale = TRUE)
e0.ggmap(pred, year = 2100, same.scale = TRUE)

# Using rworldmap
# Uses heat colors and seven categories by default
e0.map(pred)
# Uses more colors with more suitable categorization
params <- get.e0.map.parameters(pred)
do.call('e0.map', params)
# Another projection year on the same scale
do.call('e0.map', c(list(year = 2043), params))

# Interactive map (requires Flash)
e0.map.gvis(pred, year = 2043)
## End(Not run)

---

Editing the Projection Medians

Description

These functions are to be used by expert analysts. They allow to change the projection medians either to specific values, including the WPP values, or shift the medians by a given constant or a factor.

Usage

e0.median.set(sim.dir, country, values, years = NULL, joint.male = FALSE, ...)

e0.median.shift(sim.dir, country, reset = FALSE, shift = 0, 
    from = NULL, to = NULL, joint.male = FALSE, ...)
    
e0.median.adjust.jmale(sim.dir, countries, factors = c(1.2, 1.1),
    subdir = "predictions")

e0.median.reset(sim.dir, countries = NULL, joint.male = FALSE, ...)

e0.shift.prediction.to.wpp(sim.dir, joint.male = FALSE,
    subdir = "predictions", ...)

Arguments

sim.dir	Directory containing the prediction object.
country	Name or numerical code of a country.
countries	Vector of country names or codes. In the e0.median.reset function, if this argument is NULL (default), the reset is done for all countries.
values	Array of the new median values.
years	Numeric vector giving years which values correspond to. Ideally it should be of the same length as values. If it is NULL, values are set starting from the first prediction period. If values correspond to consecutive years, only the first year might be given here. A year $t$ represents a prediction period $[t_i, t_{i+1}]$ if $t_i < t \leq t_{i+1}$.
joint.male	Logical. If TRUE, the function is applied to a male prediction that was generated using the joint female-male model implemented in the function e0.jmale.predict.
reset	Logical. If TRUE medians in a range of from and to are reset to their original values.
shift	Constant by which the medians should be offset. It is not used if reset is TRUE.
from	Year from which the offset/reset should start. By default, it starts at the first prediction period.
to	Year until which the offset/reset should be done. By default, it is set to the last prediction period.
factors	It should be a vector where each element corresponds to one time period. The adjustment of male medians is done as e0m(t) = e0f(t) - gap(t)*factor(t).
subdir	Subdirectory of sim.dir containing the predictions.
...	Additional arguments passed to the underlying adjustment function. For e0.shift.prediction.to.wpp it can be stat with values “median” (default) or “mean” to specify which statistics should be adjusted; verbose to show/hide the progress of the adjustment and wpp.year to adjust it to if it differs from the wpp year of the simulation. For the other functions it can be subdir to specify the location of the prediction.

Details

The function e0.median.set can be used to set the medians of the given country to specific values. Function e0.median.shift can be used to offset the medians by a specific constant, or to reset the medians to their original BHM values. Function e0.median.adjust.jmale adjusts male medians using factors that can expand or shrink the female-male gap.

Functione0.shift.prediction.to.wpp shifts the projected medians or means (if stat is “mean”) so that they correspond to the values found in the e0Fproj (joint.male = FALSE) or e0Mproj (joint.male = TRUE) datasets of the wpp package that either corresponds to the package used for the simulation itself or is given by the wpp.year argument. If using wpp2022 or higher, the dataset name is automatically adjusted depending if it is an annual or a 5-year simulation. Note that regardless if it is an adjustment of the median or mean, the corresponding offset is always converted to a shift of the median.

Function e0.median.reset resets medians of the given countries to the original values. By default it deletes adjustments for all countries.

In all cases, if a median is modified, the corresponding offset is stored in the prediction object (element median.shift). All functions write the updated prediction object back to disk. All functions in the package that use trajectories and trajectory statistics use the median.shift values to offset the results correspondingly, i.e. trajectories are shifted the same way as the medians.

Value

All functions return an updated object of class bayesLife.prediction.

Author(s)

Hana Sevcikova

---

Accessing Parameter Names

Description

Functions for accessing names of the MCMC parameters, either country-independent or country-specific.

Usage

e0.parameter.names(...)
e0.parameter.names.cs(...)
e0.parameter.names.extended(...)
e0.parameter.names.cs.extended(country.code = NULL, ...)

Arguments

country.code	Country code. If it is given, the country-specific parameter names contain the suffix ‘_c$x$’ where $x$ is the country.code.
...	List of options containing elements world.parameters and country.parameters. If not given, they are obtained from the global environment, using e0mcmc.options.

Value

e0.parameter.names returns names of the world parameters.
e0.parameter.names.cs returns names of the country-specific parameters.
e0.parameter.names.extended returns names of all world parameters in their extended format. I.e. parameters ‘Triangle’ and ‘lambda’ have the suffix ‘_1’, ‘_2’, ‘_3’, and ‘_4’.
e0.parameter.names.cs.extended returns names of all country-specific parameters in their extended format. I.e. parameters ‘Triangle.c’ and ‘lambda.c’ are in their extended format with the suffix ‘_1’, ‘_2’ and ‘_3’.

Author(s)

Hana Sevcikova

Examples

e0.parameter.names()
e0.parameter.names.extended()
e0.parameter.names.cs()
e0.parameter.names.cs.extended()

---

Plotting MCMC Parameter Density

Description

Functions for plotting density of the posterior distribution of the MCMC parameters.

Usage

e0.pardensity.plot(mcmc.list = NULL, 
    sim.dir = file.path(getwd(), "bayesLife.output"), 
    chain.ids = NULL, par.names = NULL, 
    burnin = NULL, dev.ncol = 5, low.memory = TRUE, ...)
    
e0.pardensity.cs.plot(country, mcmc.list = NULL, 
    sim.dir = file.path(getwd(), "bayesLife.output"), 
    chain.ids = NULL, par.names = NULL, 
    burnin = NULL, dev.ncol = 3, low.memory = TRUE, ...)

Arguments

country	Name or numerical code of a country.
mcmc.list	List of bayesLife.mcmc objects, or an object of class bayesLife.mcmc.set or of class bayesLife.prediction. If it is NULL, the parameter values are loaded from sim.dir.
sim.dir	Directory with the MCMC simulation results. It is only used if mcmc.list is NULL.
chain.ids	List of MCMC identifiers to be plotted. If it is NULL, all chains found in mcmc.list or sim.dir are plotted.
par.names	Names of parameters for which density should be plotted. By default all country-independent parameters are plotted if used within e0.pardensity.plot, or all country-specific parameters are plotted if used within e0.pardensity.cs.plot.
burnin	Number of iterations to be discarded from the beginning of each chain.
dev.ncol	Number of columns for the graphics device. If the number of parameters is smaller than dev.ncol, the number of columns is automatically decreased.
low.memory	Logical indicating if the processing should run in a memory-efficient mode.
...	Further arguments passed to the density function.

Details

The functions plot the density of the posterior distribution either for country-independent parameters (e0.pardensity.plot) or for country-specific parameters (e0.pardensity.cs.plot), one graph per parameter. One can restrict it to specific chains by setting the chain.ids argument and to specific parameters by setting the par.names argument.

If mcmc.list is an object of class bayesLife.prediction, thinned traces are used instead of the full chains. In such a case, burnin and chain.ids cannot be modified - their value is set to the one used when the thinned traces were created, namely when running e0.predict.

Author(s)

Hana Sevcikova

See Also

e0.partraces.plot

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
e0.pardensity.plot(sim.dir = sim.dir, burnin = 10)
e0.pardensity.cs.plot(country = "Ireland", sim.dir = sim.dir, burnin = 10)

---

Plotting MCMC Parameter Traces

Description

Functions for plotting the MCMC parameter traces.

Usage

e0.partraces.plot(mcmc.list = NULL, 
    sim.dir = file.path(getwd(), "bayesLife.output"), 
    chain.ids = NULL, par.names = NULL, 
    nr.points = NULL, dev.ncol = 5, low.memory = TRUE, ...)
    
e0.partraces.cs.plot(country, mcmc.list = NULL, 
    sim.dir = file.path(getwd(), "bayesLife.output"), 
    chain.ids = NULL, par.names = NULL, 
    nr.points = NULL, dev.ncol = 3, low.memory = TRUE, ...)

Arguments

country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.
mcmc.list	List of bayesLife.mcmc objects, or an object of class bayesLife.mcmc.set or of class bayesLife.prediction. If it is NULL, the traces are loaded from sim.dir.
sim.dir	Directory with the MCMC simulation results. It is only used if mcmc.list is NULL.
chain.ids	List of MCMC identifiers to be plotted. If it is NULL, all chains found in mcmc.list or sim.dir are plotted.
par.names	Names of parameters for which traces should be plotted. By default all country-independent parameters are plotted if used within e0.partraces.plot, or country-specific parameters are plotted if used within e0.partraces.cs.plot.
nr.points	Number of points to be plotted. If NULL, all (stored) points are plotted, otherwise the traces are thinned evenly.
dev.ncol	Number of column for the graphics device. If the number of parameters is smaller than dev.ncol, the number of columns is automatically decreased.
low.memory	Logical indicating if the processing should run in a low-memory mode. If it is FALSE, traces of all available parameters are loaded into memory. Otherwise, parameters are loaded as they are needed and are not kept in the memory.
...	Additional graphical arguments. It can also contain the arguments burnin or thin.

Details

The functions plot MCMC traces either for country-independent parameters (e0.partraces.plot) or for country-specific parameters (e0.partraces.cs.plot), one graph per parameter. One can restrict it to specific chains by setting the chain.ids argument, and to specific parameters by setting the par.names argument.

Author(s)

Hana Sevcikova

See Also

e0.coda.list.mcmc and get.e0.parameter.traces for retrieving the raw values of traces.

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
e0.partraces.plot(sim.dir = sim.dir)
e0.partraces.cs.plot(country = "IRL", sim.dir = sim.dir)

---

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, subdir = "predictions", 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.
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.
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}/{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.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)

---

Generating Posterior Trajectories of the Life Expectancy for Specific Countries or Regions

Description

Using the posterior parameter samples the function generates posterior trajectories of the life expectancy for given countries or regions. It is intended to be used after running run.e0.mcmc.extra, but it can be also used for purposes of testing specific settings on one or a few countries.

Usage

e0.predict.extra(sim.dir = file.path(getwd(), 'bayesLife.output'), 
    prediction.dir = sim.dir, subdir = "predictions", countries = NULL, 
    save.as.ascii = 1000, verbose = TRUE, ...)

Arguments

sim.dir	Directory with the MCMC simulation results.
prediction.dir	Directory where the prediction object and the trajectories are stored.
subdir	Subdirectory of prediction.dir containing the predictions.
countries	Vector of country codes for which the prediction should be made. If it is NULL, the prediction is run for all countries that are included in the MCMC object but for which no prediction was generated.
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 converions is desired. Note that the convertion is done on all countries.
verbose	Logical switching log messages on and off.
...	Additional arguments passed to a joint female-male prediction.

Details

In order to use this function, a prediction object must exist, i.e. the function e0.predict must have been processed prior to using this function.

Trajectories for given countries or regions are generated and stored in binary format along with other countries (in prediction.dir). The existing prediction object is updated and stored in the same directory. If save.as.ascii is larger than zero, trajectories of ALL countries are converted to an ascii format.

If the prediction object contains joint male projections, these are also created for the given countries.

Value

Updated object of class bayesLife.prediction.

Author(s)

Hana Sevcikova

See Also

e0.predict, run.e0.mcmc.extra

---

Generating Posterior Trajectories of Subnational Life Expectancy at Birth

Description

Generates posterior trajectories of the life expectancy at birth (e0) for subregions of given countries, for female and male.

Usage

e0.predict.subnat(countries, my.e0.file, 
    sim.dir = file.path(getwd(), "bayesLife.output"), 
    method = c("ar1", "shift", "scale"),
    predict.jmale = FALSE, my.e0M.file = NULL,
    end.year = 2100, start.year = NULL, subdir = "predictions", 
    output.dir = NULL, annual = NULL, nr.traj = NULL, seed = NULL, 
    ar.pars = NULL, save.as.ascii = 0, verbose = TRUE, 
    jmale.estimates = NULL, ...)
                
e0.jmale.predict.subnat(e0.pred, estimates = NULL, 	
    gap.lim = c(0,18), max.e0.eq1.pred = 86, my.e0.file = NULL, 
    save.as.ascii = 0, verbose = TRUE)
    
subnat.gap.estimates(annual = FALSE)

Arguments

countries	Vector of numerical country codes or country names.
my.e0.file	Tab-separated ASCII file containing the subnational e0 data. In e0.predict.subnat, if female and male e0 are projected jointly (i.e. predict.jmale is TRUE), this file should contain the female e0. In e0.jmale.predict.subnat, this file should contain the male e0. See Details for more information on its format.
sim.dir	Simulation directory with the national projections generated using e0.predict.
method	Method to use for the projections, see the reference paper.
predict.jmale	Logical determining if male projections should be generated as well. If TRUE, the argument my.e0M.file must be given.
my.e0M.file	Tab-separated ASCII file containing the subnational male e0 data.
end.year	End year of the projections.
start.year	Start year of the projections. By default, projections start at the same time point as the national projections.
subdir	Subdirectory of sim.dir containing the national predictions.
output.dir	Directory into which the resulting prediction objects and the trajectories are stored. See below for details.
annual	Logical indicating if the subnational projection should be on an annual scale or a 5-year scale. By default, the scale is matched to the national simulation given by sim.dir. If given, the scale must match to the scale of the subnational data provided in my.e0.file. If the subnational and national scales are not the same, the national trajectories are either interpolated (if annual = TRUE and the national simulation is not annual) or averaged to 5-year values (if annual = FALSE and the national simulation is annual).
nr.traj	Number of trajectories to be generated. If NULL, the number of trajectories in the national projections is used.
seed	Seed of the random number generator. If NULL no seed is set. It can be used to generate reproducible projections.
ar.pars	Named vector containing the parameter estimates for the AR(1) method (i.e. if method = "ar1", default). If given, it must have elements called rho, U, a and b. See the reference paper for details on the estimation. By default for a 5-year simulation, c(rho = 0.95, U = 82.5, a = 0.0482, b = -0.0154) is used. For an annual simulation these default parameters are scaled to c(rho = 0.9898, U = 82.5, a = 0.01, b = -0.0032), see details below.
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. By default no conversion is performed.
verbose	Logical switching log messages on and off.
jmale.estimates, estimates	List with estimates for the female-male gap model. The default values are retrieved using the function subnat.gap.estimates().
...	Additional arguments passed to e0.jmale.predict.subnat, which are gap.lim and max.e0.eq1.pred.
e0.pred	Object of class bayesLife.prediction. It should be one element of the list returned by e0.predict.subnat corresponding to one country.
gap.lim, max.e0.eq1.pred	The same meaning as in e0.jmale.predict.

Details

The e0.predict.subnat function implements the methodology described in Sevcikova and Raftery (2021). Given a set of national bayesLife projections, it applies one of the methods (AR(1), Shift or Scale) to each national trajectory and each subregion of given countries which yields subnational e0 projections.

The file on subnational data passed into my.e0.file and my.e0M.file has to have a column “country_code” with numerical values corresponding to countries given in the argument countries, and column “reg_code” giving the numerical identifier of each subregion. Column “name” should be used for subregion name, and column “country_name” for country name. An optional column “include_code” can be used to eliminate entries from processing. Entries with values of 1 or 2 will be included, all others will be ignored. Column “last.observed” can be used to define which time period contains the last observed data point (given as integer, e.g. year in the middle of the time period). Remaining columns define the time periods, e.g. “2000-2005”, “2005-2010” for a 5-year simulation, or “2020”, “2021” for an annual simulation. The package contains an example of such dataset, see Example below.

The default AR(1) parameters for the “ar1” method were designed for a 5-year simulation, see Sevcikova & Raftery (2021) for more detail. These are $\rho = 0.95, U = 82.5, a = 0.0482, b = -0.0154$. If an annual AR(1) process is desired, we use the following conversion for the autoregressive parameter $\rho$ and the $a$ and $b$ parameters: $\rho^* = \rho^{(1/5)}, a^* = a * \sqrt{((1 - \rho^{(2/5)})/(1 - \rho^2))}, b^* = b * \sqrt{((1 - \rho^{(2/5)})/(1 - \rho^2))}$. The $U$ parameter stays the same for both processes. Thus, the annual parameters are c(rho = 0.9898, U = 82.5, a = 0.01, b = -0.0032). Note that if the ar.pars argument is specified by the user, it is assumed that the parameters have been scaled appropriately and thus, no conversion takes place.

Argument output.dir gives a location on disk where results of the function should be stored. If it is NULL (default), results are stored in the same directory as the national projections. In both cases a subdirectory called “subnat_method” is created in which each country has its own subfolder with the country code in its name. Each such subfolder contains the same type of outputs as in the national case generated using e0.predict, most importantly a directory “predictions” with trajectories for each region.

If the argument predict.jmale is TRUE, the e0.predict.subnat invokes the e0.jmale.predict.subnat function for each country. However, one can call the e0.jmale.predict.subnat function explicitly. It applies the female-male gap model to regions of one country. See e0.jmale.predict for more detail on the model. The default covariates of the model are not estimated on the fly. They were estimated externally using subnational data for about 30 countries and can be viewed using subnat.gap.estimates(), either for estimates derived from 5-year data (default) or annual data (annual = TRUE).

Value

Function e0.predict.subnat returns a list of objects of class bayesLife.prediction. The name of each element includes its country code. Not all elements of the class bayesLife.prediction are available. For example, no mcmc.set is attached to these objects. Thus, not all functions that work with bayesLife.prediction can be applied to these results.

Function e0.jmale.predict.subnat returns an object of class bayesLife.prediction which updates the input e0.pred object by adding a new component called joint.male. This component is also an object of class bayesLife.prediction and it contains results of the male projections.

Note

Even though the resulting object contains subnational results, the names of its elements are the same as in the national case. This allows to apply the same functions on both objects (subnational and national). However, it means that sometimes the meaning of the elements or function arguments does not match the subnational context. For example, various functions expect the argument country. When a subnational object is passed to such a function, country means a subregion.

Author(s)

Hana Sevcikova

References

H. Sevcikova, A. E. Raftery (2021). Probabilistic Projection of Subnational Life Expectancy. Journal of Official Statistics, Vol. 37, no. 3, 591-610.

See Also

get.rege0.prediction, e0.predict, e0.jmale.predict

Examples

# View the example data
my.sube0.file <- file.path(find.package("bayesLife"), 'extdata', 'subnational_e0_template.txt')
sube0 <- read.delim(my.sube0.file, check.names = FALSE)
head(sube0)

# Directory with national projections (contains 30 trajectories for each country)
nat.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")

# Subnational projections for Australia and Canada, 
# including the joint female-male gap model
subnat.dir <- tempfile()
preds <- e0.predict.subnat(c(36, 124), my.e0.file = my.sube0.file,
    sim.dir = nat.dir, output.dir = subnat.dir, start.year = 2018)
    
names(preds)
get.countries.table(preds[["36"]])
summary(preds[["36"]], "Queensland")
e0.trajectories.plot(preds[["36"]], "Queensland")

# plot subnational and national e0 in one plot
nat.pred <- get.e0.prediction(nat.dir)
e0.trajectories.plot(preds[["36"]], 4, pi = 80)
e0.trajectories.plot(nat.pred, "Australia", add = TRUE, 
      col = rep("darkgreen", 5), nr.traj = 0, show.legend = FALSE)
legend("top", c("regional e0", "national e0"), col = c("red", "darkgreen"), 
  lty = 1, bty = 'n')

# Add male projection to Canada, 
# using (wrongly) female data only for demonstration
predCan <- e0.jmale.predict.subnat(preds[["124"]], my.e0.file = my.sube0.file)

# retrieve male prediction object
predCanMale <- get.rege0.prediction(subnat.dir, 124, joint.male = TRUE)
# the same works using
predCanMale <- get.e0.jmale.prediction(predCan)

# Retrieve female and male trajectories
trajsF.Alberta <- get.e0.trajectories(predCan, "Alberta")
trajsM.Alberta <- get.e0.trajectories(predCanMale, "Alberta")
# summary of differences
summary(t(trajsF.Alberta - trajsM.Alberta))

# cleanup
unlink(subnat.dir)

# See more examples in ?get.rege0.prediction

---

Raftery Diagnostics for Parameters of the Life Expectancy

Description

The function computes the Raftery diagnostics for each parameter in the same way as tfr.raftery.diag of the bayesTFR package.

Usage

e0.raftery.diag(mcmc = NULL, sim.dir = file.path(getwd(), "bayesLife.output"), 
    burnin = 0, country = NULL, par.names = NA, par.names.cs = NA,
    country.sampling.prop = 1, verbose = TRUE, ...)

Arguments

mcmc	A bayesLife.mcmc or bayesLife.mcmc.set object.
sim.dir	Directory with the MCMC simulation results. Only used if mcmc is NULL.
burnin	Burnin.
country	Name or code of a country. If it is given, only country-specific parameters parameters of that country are considered.
par.names	Names of country-independent parameters for which the Raftery diagnostics should be computed. By default all parameters are used. If it is NULL, no country-independent parameters are used.
par.names.cs	Names of country-specific parameters for which the Raftery diagnostics should be computed. By default all parameters are used. If it is NULL, no country-specific parameters are used.
country.sampling.prop	Proportion of countries that are included in the diagnostics. It should be between 0 and 1. If it is smaller than 1, the countries are randomly sampled. It is only relevant if par.names.cs is not NULL.
verbose	Logical switching log messages on and off.
...	Additional arguments passed to the e0.coda.list.mcmc function.

Details

See tfr.raftery.diag for details. This function is called from e0.diagnose.

Author(s)

Hana Sevcikova, Adrian Raftery

See Also

tfr.raftery.diag, raftery.diag, e0.diagnose

---

Posterior Distribution of Trajectories of Life Expectancy

Description

The functions plot/tabulate the posterior distribution of trajectories of the life expectancy for a given country, or for all countries, including their median and given probability intervals.

Usage

e0.trajectories.plot(e0.pred, country, pi = c(80, 95), both.sexes = FALSE,
    nr.traj = NULL, adjusted.only = TRUE, typical.trajectory = FALSE, 
    traj.index = NULL, show.mean = FALSE, show.median = TRUE,
    xlim = NULL, ylim = NULL, type = "b", 
    xlab = "Year", ylab = "Life expectancy at birth", main = NULL, 
    lwd = c(2, 2, 2, 2, 1), col = c('black', 'green', 'red', 'red', '#00000020'),
    col2 = c('gray39', 'greenyellow', 'hotpink', 'hotpink', '#00000020'),
    pch = c(1, 2), show.legend = TRUE, add = FALSE, ...)
    
e0.trajectories.plot.all(e0.pred, 
    output.dir = file.path(getwd(), 'e0trajectories'),
    output.type = "png", verbose = FALSE, ...)
	
e0.trajectories.table(e0.pred, country, pi = c(80, 95), 
    both.sexes = FALSE, ...)

Arguments

e0.pred	Object of class bayesLife.prediction.
country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.
pi	Probability interval. It can be a single number or an array. If both.sexes is TRUE the default is 95.
both.sexes	Logical or the character “A”. If TRUE the distribution of both sexes is plotted into one graphics (or tabulated), provided the e0.pred is a female prediction and contains a joint male prediction as a result of running the function e0.jmale.predict. For “A” it plots/tabulates the distribution of the average life expectancy over both sexes.
nr.traj	Number of trajectories to be plotted. If NULL, all trajectories are plotted, otherwise they are thinned evenly. If both.sexes is TRUE the default is zero.
adjusted.only	Logical. By default, if the projection median is adjusted using e.g. e0.median.set, the function plots the adjusted median. If adjusted.only=FALSE the original (non-adjusted) median is plotted as well.
typical.trajectory	Logical. If TRUE one trajectory is shown for which the median absolute deviation from the median e0 projection is the median among all the trajectories.
traj.index	Vector of trajectory indices to show. If not given, the trajectories are selected using equidistant spacing.
show.mean, show.median	Logical indicating if the mean or/and the median of the distribution should be shown.
xlim, ylim, type, xlab, ylab, main	Graphical parameters passed to the plot function.
lwd, col, col2	Vector of five elements giving the line width and color for: 1. observed data, 2. imputed missing data, 3. median, 4. quantiles, 5. trajectories. col2 is only used if both.sexes is TRUE. In such a case, col2 is used for female lines and col is used for male lines, which in this case defaults to c('black', 'green', 'darkgreen', 'darkgreen', 'gray').
pch	Vector of two elements specifying plotting symbols for the observed and imputed data, respectively. It is not used if type is not one of “b”, “p” or “o”.
show.legend	Logical controlling whether the legend should be drawn.
add	Logical controlling whether the trajectories should be plotted into a new graphic device (FALSE) or into an existing device (TRUE). One can use this argument to plot trajectories from multiple countries into one graphics.
...	Additional graphical parameters. In addition, for e0.trajectories.plot.all, ... contains any of the arguments of e0.trajectories.plot, and for e0.trajectories.table, ... contains the pi and country arguments.
output.dir	Directory into which resulting graphs are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
verbose	Logical switching log messages on and off.

Details

e0.trajectories.plot plots posterior distribution of trajectories of life expectancy for a given country. e0.trajectories.table gives the same output in a tabular format.
e0.trajectories.plot.all creates a set of such graphs (one per country) that are stored in output.dir.

The median and given probability intervals are computed using all available trajectories. Thus, nr.traj does not influence those values - it is used only to control the number of trajectories plotted.

Author(s)

Hana Sevcikova

See Also

bayesLife.prediction

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
pred <- get.e0.prediction(sim.dir)
e0.trajectories.table(pred, country = "Japan", pi = c(80, 95))
e0.trajectories.plot(pred, country = "Japan", pi = c(80, 95))

# plot multiple countries into one plot
e0.trajectories.plot(pred, "JP", col = rep("green", 5), nr.traj = 0,
         pi = c(80), show.legend = FALSE, main = "")
e0.trajectories.plot(pred, "USA", col = rep("blue", 5),  
        add = TRUE, nr.traj = 0, pi = c(80), show.legend = FALSE)
legend("topleft", legend = c("Japan", "USA"), col = c("green", "blue"), 
        lty = 1, bty = "n")

---

Global options

Description

Setting, retrieving and updating global options.

Usage

using.bayesLife()
e0options()
e0mcmc.options(..., annual = FALSE)
e0pred.options(...)

e0mcmc.dlpriors.options(prior.choice = "B", annual = FALSE, 
    un.constraints = FALSE)
    
get.DLpriors(prior.choice = NULL, annual = FALSE)

data(DLpriors)

Arguments

...	Arguments in tag = value form, or names of options to retrieve.
annual	Logical indicating if the options are for an annual simulation (TRUE) or a 5-year simulation(FALSE).
prior.choice	A character indicating for which combination of the upper bound on the $z$ parameter and the upper bound of sumTriangle.lim priors for a, delta and tau should be used. Choices are “A” (0.653, 83), “B” (0.653, 86; default), “C” (1.150, 83), “D” (1.150, 86). See Details for more information. Use get.DLpriors() to view the priors. If this argument is NULL no update/choice is taken.
un.constraints	Logical indicating if constraints on the lower bounds of the Triangle parameter posed by the UN in WPP 2022 should be used.

Details

Function using.bayesLife sets all global options to their default values. Function e0options is used to get all options as a named list.

The global options are divided into three main categories, namely options used for MCMC estimations in a 5-year simulation, in a 1-year simulation, and options used for predictions. To set or retrieve options of the first two categories, use e0mcmc.options and use the argument annual to distinguish between them (see section MCMC Options below), while the third category is controlled by e0pred.options (see section Prediction Options below).

Many options are in the form of a list and it is possible to overwrite only single elements of the list. However, if an option is a vector, all elements of the vector have to be defined when updating (see Example).

The dataset DLpriors contains four sets of parameters a, delta and tau (see section MCMC Options below) estimated for different combinations of the upper limit on the z parameter (i.e. maximum 5-year increase of e0; column “Uz”) and the upper bound of the sum of $\Delta_i$ (column “Sa”; set in the sumTriangle.lim option which is interpreted as the value of e0 for which the transition is completed; see below for more detail). A get.DLpriors() call retrieves all available combinations. Function e0mcmc.dlpriors.options can be used to change the default option B (i.e. the upper limit on z being 0.653 and the transition being completed at e0 of 86). Use the column “option” from DLpriors to select the desired combination. In addition, setting the argument un.constraints to TRUE will set the lower limit on the $\Delta_i$ parameters (Triangle, Triangle.c) to the same values as the UN used for WPP 2022. Note that the DLpriors dataset corresponds to parameter values designed for a 5-year simulation. Use get.DLprior(annual = TRUE) to see the equivalents for an annual simulation where various values are divided by five.

Value

e0options returns a list of all global options.

e0mcmc.options, when called with no argument other than annual, it returns a list of options related to the MCMC estimation. The annual argument determines if the values correspond to an annual or 5-year simulation.

e0pred.options, when called with no argument, it returns a list of options related to the prediction.

For both, e0mcmc.options and e0pred.options, when a specific option is queried, it returns the value of that option. When an option is set, a list of the previous values of all MCMC/prediction options is returned invisibly.

get.DLpriors returns the content of the DLpriors dataset.

e0mcmc.dlpriors.options overwrites various values and like e0mcmc.options, it returns a list of the previous values of all MCMC options invisibly.

MCMC Options

a

vector of the $a_1$, ... ,$a_6$ parameters, which are the prior means of the world-level parameters ($\Delta_1$, ..., $\Delta_4$, $k$, $z$).

delta

vector of the $\delta_1$, ... ,$\delta_6$ parameters, which are the prior standard deviations of the world-level parameters ($\Delta_1$, ..., $\Delta_4$, $k$, $z$).

tau

vector of the $\tau_1$, ... ,$\tau_6$ parameters, which is the square root rate of the prior Gamma distribution of the world-level parameters ($\lambda_1$, ..., $\lambda_4$, $\lambda_k$, $\lambda_z$).

Triangle

list with elements:

ini

list with elements:

T1, T2, T3, T4

initial values for $\Delta_1$, ..., $\Delta_4$. If not NULL, then each element should be of the same length as the number of MCMC chains. If it is NULL, the initial values are equally spaced between ini.low and ini.up for the respective parameter. By default in the estimation, if there is just one chain, the initial value is the middle point of the interval.

ini.low, ini.up

vectors of length four. They are the lower and upper bounds for initial values of $\Delta_1$, ..., $\Delta_4$. An $i$-th item is only used if ini$Ti is NULL.

prior.low, prior.up

vectors of length four. They are the lower and upper bounds for the prior (truncated normal) distribution of $\Delta_1$, ..., $\Delta_4$.

slice.width

vector of length four defining the slice width for MCMC slice sampling for the four parameters, $\Delta_1$, ..., $\Delta_4$.

k, z

lists with elements:

ini

vector of initial values for $k$ ($z$). Its length (if not NULL) should correspond to the number of MCMC chains. By default, the initial values are equally spaced between ini.low and ini.up. In case of one chain, the initial value is by default the middle point of the interval.

ini.low, ini.up

single value giving the lower and upper bounds for initial values of $k$ ($z$). It is only used if ini is NULL. Regarding defaults for the $z$ parameter, see Note below.

prior.low, prior.up

single value giving the lower and upper bounds for the prior (truncated normal) distribution of $k$ ($z$). Regarding defaults for the $z$ parameter, see Note below.

slice.width

single value giving the slice width for MCMC slice sampling of the $z$ parameter (not available for $k$).

lambda

list with elements:

ini

list with elements:

T1, T2, T3, T4

initial values for $\lambda_1$, ..., $\lambda_4$. Each element should be of the same length as the number of MCMC chains. If it is NULL, the initial values are equally spaced between ini.low and ini.up of the respective parameter. By default, if there is just one chain, the value is the middle point of the interval.

ini.low, ini.up

vectors of length four. They are the lower and upper bounds for initial values of $\lambda_1$, ..., $\lambda_4$. An $i$-th item is only used if ini$Ti is NULL.

slice.width

vector of length four defining the slice width for MCMC slice sampling for the four parameters, $\lambda_1$, ..., $\lambda_4$.

lambda.k, lambda.z

lists with elements:

ini

vector of initial values for $\lambda_k$ ($\lambda_z$). Its length (if not NULL) should correspond to the number of MCMC chains. By default, the initial values are equally spaced between ini.low and ini.up. In case of one chain, the initial value is by default the middle point of the interval.

ini.low, ini.up

single value giving the lower and upper bounds for initial values of $\lambda_k$ ($\lambda_z$). It is only used if ini is NULL.

slice.width

single value giving the slice width for MCMC slice sampling of the $\lambda_z$ parameter (not available for $\lambda_k$).

omega

list with elements:

ini

vector of initial values for $\omega$. Its length (if not NULL) should correspond to the number of MCMC chains. By default, the initial values are equally spaced between ini.low and ini.up. In case of one chain, the initial value is by default the middle point of the interval.

ini.low, ini.up

single value giving the lower and upper bounds for initial values of $\omega$. It is only used if ini is NULL.

Triangle.c

list with elements:

ini.norm

list with elements:

mean, sd

vectors of size four. They correspond to the means and standard deviations, respectively, for the initial values of the country-specific parameters $\Delta_1^c$, ..., $\Delta_4^c$ which are drawn from a truncated normal distribution with bounds defined by prior.low and prior.up.

prior.low, prior.up

vectors of length four. They are the lower and upper bounds for the prior (truncated normal) distribution of country-specific $\Delta_1^c$, ..., $\Delta_4^c$.

slice.width

vector of length four defining the slice width for MCMC slice sampling of the country-specific $\Delta_1^c$, ..., $\Delta_4^c$.

k.c, z.c

list with elements:

ini.norm

named vector of length two, called “mean” and “sd”. The elements correspond to the means and standard deviations, respectively, for the initial values of the country-specific parameters $k^c$ ($z^c$) which are drawn from a normal distribution truncated between prior.low and prior.up.

prior.low, prior.up

single values giving the lower and upper bounds for the prior (truncated normal) distribution of country-specific $k^c$ ($z^c$). Regarding defaults for $z^c$, see Note below.

slice.width

single value giving the slice width for MCMC slice sampling of the $k^c$ ($z^c$) parameter.

nu

the shape parameter of the Gamma distributions of all $\lambda$ parameters is nu/2.

dl.p1, dl.p2

values of the parameters $p_1$ and $p_2$ of the double logistic function.

sumTriangle.lim

lower and upper limits for the sum of the $\Delta_i$ parameters. MCMC proposals that are outside of this limit are rejected. It is applied to both, the world parameters as well as the country specific parameters. The sum of $\Delta_i$ can be interpreted as the level of e0 at which the transition is completed and is followed by an e0 increase with a constant rate z.

world.parameters

named vector where names are the world parameters and values are the number of sub-parameters. For example, $\Delta$ has 4 sub-parameters, while $k$ and $z$ are both just one parameter.

country.parameters

named vector where names are the country-specific parameters and values are the number of sub-parameters.

outliers

ranges for determining outliers in the historical data. If outliers=c(x, y) then any increase in life expectancy smaller than x or larger than y is considered as an outlier and removed from the estimation.

buffer.size

buffer size (in number of [thinned] iterations) for keeping data in the memory. The smaller the buffer.size the more often will the process access the hard disk and thus, the slower the run. On the other hand, the smaller the buffer.size the less data will be lost in case of failure.

auto.conf

list containing a configuration for an ‘automatic’ run. All items in this list must be integer values. The option is only used if the argument iter in run.e0.mcmc is set to ‘auto’ (see description of argument iter in run.e0.mcmc). The list contains the following elements:

iter

gives the number of iterations in the first chunk of the MCMC simulation.

iter.incr

gives the number of iterations in the following chunks.

nr.chains

gives the number of chains in all chunks of the MCMC simulation.

thin, burnin

used in the convergence diagnostics following each chunk.

max.loops

controls the maximum number of chunks.

country.overwrites

This option allows to overwrite some of the prior parameters for specific countries. If it is not NULL it should be a data frame with an obligatory column ‘country_code’. Each row then corresponds to one country. Other columns can be ‘k.c.prior.low’, ‘k.c.prior.up’, ‘z.c.prior.low’, ‘z.c.prior.up’, ‘Triangle_$x$.c.prior.low’ and ‘Triangle_$x$.c.prior.up’ where $x$ can be an integer from 1 to 4.

Note

Parameter $z$ determines the asymptote in gains in life expectancy. The following text gives an explanation for the choice of upper limits on $z$-related parameters:

The pace of improvement and the asymptotic limit in future gains in female life expectancy vary for each projected trajectory, but ultimately is informed and constrained by the finding that the rate of increase of maximum female life expectancy over the past 150 year has been highly linear (2a, 2b) (i.e., about 2.4 years per decade), albeit at slightly lower pace once the leading countries started to exceed 75 years of female life expectancy at birth in the 1960s (3) (about 2.26 years of gains per decade). By assuming that the asymptotic average rate of increase in life expectancy is nonnegative, life expectancy is assumed to continually increase (on average), and no limit is imposed to life expectancy in the foreseeable future. The increase in maximum female life span among countries with highest life expectancy and reliable data on very old age provide further guidance on future rate of progress which has also been increasingly linear at least since the 1970s (4a-4c) (about 1.25 years per decade for countries like Sweden and Norway), and is used to inform the asymptotic average rate of increase in female life expectancy used in the 2012 WPP Revision. To set the posterior median to an annual gain of 0.125 year (or 5-year gain of 0.625 in this context) the upper bound value of 0.653 is used for the world prior ($z$) and country-specific prior ($z_c$) as default values in the estimation of the double-logistic parameters.

Author(s)

Hana Sevcikova, Patrick Gerland contributed to the documentation.

References

(1) 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>

(2a) Oeppen J, and J.W. Vaupel (2002) Broken limits to life expectancy. Science 296:1029-1031.

(2b) Vaupel, J.W. and K.G.V. Kistowski. 2005. Broken Limits to Life Expectancy. Ageing Horizons (3):6-13.

(3) Vallin, J., and F. Mesle (2009). The Segmented Trend Line of Highest Life Expectancies. Population and Development Review, 35(1), 159-187. doi:10.1111/j.1728-4457.2009.00264.x

(4a) Wilmoth, J. R., L. J. Deegan, H. Lundstrom, and S. Horiuchi (2000). Increase of maximum life-span in Sweden, 1861-1999. Science, 289(5488), 2366-2368.

(4b) Wilmoth, J. R. and J-M. Robine. (2003). The world trend in maximum life span, in: J. R. Carey and S. Tuljapurkar (eds.), Life Span: Evolutionary, Ecological, and Demographic Perspectives, supplement to vol. 29, Population and Development Review, pp. 239-257.

(4c) Wilmoth, J. R. and N. Ouellette (2012). Maximum human lifespan: Will the records be unbroken?, Paper presented at the European Population Conference, Stockholm, Sweden, 13-16 June.

See Also

run.e0.mcmc, e0.predict

Examples

e0mcmc.options("z", "Triangle")
# Set new z$ini.up and Triangle$prior.up
# Modifying single elements of the z-list and Triangle-list.
# However, Triangle$prior.up is a vector and needs all four values.
e0mcmc.options(z = list(ini.up = 0.8), Triangle = list(prior.up = rep(120, 4)))
e0mcmc.options("z", "Triangle")

# revert to defaults
using.bayesLife()
e0mcmc.options("z", "Triangle")

# options for an annual simulation
e0mcmc.options("z", "sumTriangle.lim", annual = TRUE)

# modify using a different set from DLpriors
get.DLpriors(annual = TRUE) # view the DLpriors dataset
e0mcmc.dlpriors.options("C", annual = TRUE) # use C option
# upper bounds for z correspond to values from DLpriors divided by 5
e0mcmc.options("z", "sumTriangle.lim", annual = TRUE)
# set the UN's Triangle lower bound constraints 
e0mcmc.dlpriors.options(NULL, annual = TRUE, un.constraints = TRUE)
e0mcmc.options("Triangle", "Triangle.c", annual = TRUE) # prior.low is modified

---

Accessing a Convergence Object

Description

The functions load objects of class bayesLife.convergence from disk that were created using the function e0.diagnose.

Usage

get.e0.convergence(sim.dir = file.path(getwd(), "bayesLife.output"), 
    thin = 225, burnin = 10000)
	
get.e0.convergence.all(sim.dir = file.path(getwd(), "bayesLife.output"))

Arguments

sim.dir	Simulation directory used for computing the diagnostics.
thin	Thinning interval used with this diagnostics.
burnin	Burnin used for computing the diagnostics.

Details

Function get.e0.convergence loads an object of class bayesLife.convergence for the specific thin and burnin. Function get.e0.convergence.all loads all bayesLife.convergence objects available in sim.dir.

Value

get.e0.convergence returns an object of class bayesLife.convergence;
get.e0.convergence.all returns a list of objects of class bayesLife.convergence.

Author(s)

Hana Sevcikova

See Also

e0.diagnose, summary.bayesLife.convergence.

---

Accessing MCMC Results

Description

The function get.e0.mcmc retrieves results of an MCMC simulation and creates an object of class bayesLife.mcmc.set. Function has.e0.mcmc checks the existence of such results. Function e0.mcmc extracts a single chain, and e0.mcmc.list extracts several or all chains from the simulation results.

Usage

get.e0.mcmc(sim.dir = file.path(getwd(), "bayesLife.output"), 
    chain.ids = NULL, low.memory = TRUE, burnin = 0, verbose = FALSE)
    
has.e0.mcmc(sim.dir)

e0.mcmc(mcmc.set, chain.id = 1)

e0.mcmc.list(mcmc.set, chain.ids = NULL)

Arguments

sim.dir	Directory where the simulation results are stored.
chain.ids	Chain identifiers in case only specific chains should be included in the resulting object. By default, all available chains are included.
low.memory	If FALSE full MCMC traces are loaded into memory.
burnin	Burnin used for loading traces. Only relevant, if low.memory=FALSE.
verbose	Logical switching log messages on and off.
chain.id	Chain identifier.
mcmc.set	Object of class bayesLife.mcmc.set.

Value

get.e0.mcmc returns an object of class bayesLife.mcmc.set. has.e0.mcmc returns a logical value. e0.mcmc returns an object of class bayesLife.mcmc, and e0.mcmc.list returns a list of bayesLife.mcmc objects.

Author(s)

Hana Sevcikova

See Also

bayesLife.mcmc.set

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
m <- get.e0.mcmc(sim.dir)
summary(m)

# summary of the world parameters for a single chain
# (the same as above since there is only one chain in this toy example)
summary(e0.mcmc.list(m)[[1]], par.names.cs = NULL)

# the same as
summary(e0.mcmc(m, chain.id = 1), par.names.cs = NULL)

---

Accessing MCMC Parameter Traces

Description

Functions for accessing traces of the MCMC parameters, either country-independent or country-specific.

Usage

get.e0.parameter.traces(mcmc.list, par.names = NULL, 
    burnin = 0, thinning.index = NULL, thin = NULL)
    
get.e0.parameter.traces.cs(mcmc.list, country.obj, 
    par.names = NULL, burnin = 0, thinning.index = NULL, thin = NULL)

Arguments

mcmc.list	List of bayesLife.mcmc objects.
country.obj	Country object list (see get.country.object).
par.names	Names of country-independent parameters (in case of get.e0.parameter.traces) or country-specific parameters (in case of get.e0.parameter.traces.cs) to be included. By default all parameters are included.
burnin	Burn-in indicating how many iterations should be removed from the beginning of each chain.
thinning.index	Index of the traces for thinning. If it is NULL, thin is used. thinning.index does not include burnin and should be flattened over all chains. For example, if there are two MCMC chains of length 1000, burnin=200 and we want a sample of length 400, then the value should be thinning.index=seq(1,1600, length=400).
thin	Alternative to thinning.index. The above example is equivalent to thin=4.

Value

Both functions return a matrix with columns being the parameters and rows being the MCMC values, attached to one another in case of multiple chains. get.e0.parameter.traces returns country-independent parameters, get.e0.parameter.traces.cs returns country-specific parameters.

Author(s)

Hana Sevcikova

See Also

e0.coda.list.mcmc for another way of retrieving parameter traces.

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
m <- get.e0.mcmc(sim.dir)
e0.values <- get.e0.parameter.traces(m$mcmc.list, burnin = 10, par.names = "z")
hist(e0.values, main = colnames(e0.values))

e0.values.cs <- get.e0.parameter.traces.cs(m$mcmc.list, 
                    get.country.object("Canada", meta = m$meta),
                    burnin = 10, par.names = "z.c")
hist(e0.values.cs, main = colnames(e0.values.cs))

---

Accessing a Prediction Object

Description

Function get.e0.prediction retrieves results of a prediction and creates an object of class bayesLife.prediction. Function has.e0.prediction checks an existence of such results. Analogously, functions get.e0.jmale.prediction and has.e0.jmale.prediction retrieve and check an existence of male predictions from a given female prediction object. Function available.e0.predictions lists predictions available in the given simulation directory.

Usage

get.e0.prediction(mcmc = NULL, sim.dir = NULL, joint.male = FALSE, 
    mcmc.dir = NULL, subdir = "predictions")

has.e0.prediction(mcmc = NULL, sim.dir = NULL, subdir = "predictions")

get.e0.jmale.prediction(e0.pred)

has.e0.jmale.prediction(e0.pred)

available.e0.predictions(mcmc = NULL, sim.dir = NULL, full.names = FALSE)

Arguments

mcmc	Object of class bayesLife.mcmc.set used to make the prediction. If it is NULL, the prediction is loaded from directory given by sim.dir.
sim.dir	Directory where the prediction is stored. It should correspond to the value of the output.dir argument used in the e0.predict function. Only relevant if mcmc is NULL.
joint.male	Logical. If TRUE, the function is applied to a male prediction that was generated using the joint female-male model implemented in the function e0.jmale.predict.
mcmc.dir	Optional argument to be used only in a special case when the mcmc object contained in the prediction object was estimated in different directory than in the one to which it points to (for example due to moving or renaming the original directory). The argument causes that the mcmc is redirected to the given directory.
subdir	Subdirectory of sim.dir for this particular prediction.
full.names	Logical. If TRUE, the directory names are given as full paths, otherwise (default) only the base names.
e0.pred	Object of class bayesLife.prediction.

Details

If mcmc is not NULL, the search directory is set to mcmc$meta$output.dir. This approach assumes that the prediction was stored in the same directory as the MCMC simulation, i.e. the output.dir argument of the e0.predict function was set to NULL. If it is not the case, the argument mcmc.dir should be used.

Usually, all predictions are stored in the subdirectory “predictions” of the simulation directory. If the subdirectory has a different name, the argument subdir should be used. This allows to keep multiple predictions in one (MCMC) simulation directory. The function available.e0.predictions can be used to view all available predictions in the simulation directory.

Function get.e0.jmale.prediction extracts male projections from the e0.pred objects (which should be a female prediction object), if the male prediction was generated using the e0.jmale.predict function. has.e0.jmale.prediction checks if such male prediction was generated.

Value

Functions has.e0.prediction and has.e0.jmale.prediction return a logical indicating if a prediction exists.

Functions get.e0.prediction and get.e0.jmale.prediction return an object of class bayesLife.prediction.

Function available.e0.predictions returns a vector of directory names containing e0 predictions.

Author(s)

Hana Sevcikova

See Also

bayesLife.prediction, e0.predict, summary.bayesLife.prediction, e0.jmale.predict

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")
pred <- get.e0.prediction(sim.dir = sim.dir)
# female prediction summary
summary(pred, country = "Canada")

## Not run: 
# male prediction summary
# (works only if a joint male prediction exists - not the case in this toy example)
summary(get.e0.jmale.prediction(pred), country = "Canada")
## End(Not run)

---

Accessing Trajectories of Life Expectancy

Description

Function for accessing trajectories of the life expectancy.

Usage

get.e0.trajectories(e0.pred, country)

Arguments

e0.pred	Object of class bayesLife.prediction.
country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.

Details

The function loads trajectories of life expectancy for the given country from disk and returns it as a matrix.

Value

Array of size the number of projection periods (including the present year) times the number of trajectories. The row names correspond to the mid-years of the prediction periods.

Author(s)

Hana Sevcikova

See Also

bayesLife.prediction, get.e0.prediction, e0.trajectories.table

Examples

sim.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output") 
pred <- get.e0.prediction(sim.dir=sim.dir)
get.e0.trajectories(pred, "Germany")

---

Accessing Subnational Prediction Objects

Description

Retrieve subnational (regional) prediction results produced by e0.predict.subnat, either for one country or for all available countries.

Usage

get.rege0.prediction(sim.dir, country = NULL, method = "ar1", joint.male = FALSE)

Arguments

sim.dir	Simulation directory of the subnational predictions. It corresponds to the argument output.dir in e0.predict.subnat.
country	Numerical country code. If it is not given, all available subnational predictions are retrieved.
method	Method used for generating the projections. It corresponds to the method argument in e0.predict.subnat.
joint.male	Logical. If TRUE, the function is applied to a male prediction that was generated using the joint female-male gap model implemented in the function e0.jmale.predict.subnat.

Details

Predictions for country $x$ are assumed to be stored in “sim.dir/subnat_method/c$x$”.

Value

If argument country is given, the function returns an object of class bayesLife.prediction. If it is NULL, it returns a list of such objects. Names of the list items are the country codes.

See Also

e0.predict.subnat

Examples

# Subnational example data
my.sube0.file <- file.path(find.package("bayesLife"), 'extdata', 'subnational_e0_template.txt')
sube0 <- read.delim(my.sube0.file, check.names = FALSE)
countries <- unique(sube0[, c("country_code", "country_name")])

# Directory with national projections (contains 30 trajectories for each country)
nat.dir <- file.path(find.package("bayesLife"), "ex-data", "bayesLife.output")

# Subnational projections for all three countries,
# including male projections where female 
# data is used only for demonstration purposes
# (my.e0M.file should contain male e0).
subnat.dir <- tempfile()
e0.predict.subnat(countries$country_code, my.e0.file = my.sube0.file,
    sim.dir = nat.dir, output.dir = subnat.dir, start.year = 2013,
    predict.jmale = TRUE, my.e0M.file = my.sube0.file)
    
# Retrieve results for all countries
preds <- get.rege0.prediction(subnat.dir)
names(preds)

# View tables of subregions for each country
for(i in 1:nrow(countries)) {
  cat("\n\n", countries$country_name[i], "\n")
  print(get.countries.table(preds[[as.character(countries$country_code[i])]]))
}
# Quantiles for individual subregions for female
e0.trajectories.table(preds[["36"]], "Victoria")

# Retrieve results for one country (Canada)
pred <- get.rege0.prediction(subnat.dir, 124)
e0.trajectories.plot(pred, "Quebec", both.sexes = TRUE)

# Retrieve only male results
predM <- get.rege0.prediction(subnat.dir, 124, joint.male = TRUE)
e0.trajectories.table(predM, "Quebec")

# cleanup
unlink(subnat.dir)

# See more examples in ?e0.predict.subnat

---

Creating and Accessing Thinned MCMCs

Description

The function get.thinned.e0.mcmc accesses a thinned and burned version of the given MCMC set. create.thinned.e0.mcmc creates such set.

Usage

get.thinned.e0.mcmc(mcmc.set, thin = 1, burnin = 0)

create.thinned.e0.mcmc(mcmc.set, thin = 1, burnin = 0, 
    output.dir = NULL, verbose = TRUE)

Arguments

mcmc.set	Object of class bayesLife.mcmc.set.
thin, burnin	Thinning interval and burnin used for creating or identifying the thinned object.
output.dir	Directory for storing the thinned object. By default it is stored into the same directory as mcmc.set.
verbose	Logical switching log messages on and off.

Details

The function create.thinned.e0.mcmc is called from e0.predict and thus, the resulting object contains exactly the same MCMCs used for generating projections.

The thinning is done as follows: The given burnin is removed from the beginning of each chain in the original MCMC set. Then each chain is thinned by thin using equal spacing and all chains are collapsed into one single chain per parameter. They are stored in output.dir under the name ‘thinned_mcmc_t_b’ where t is the value of thin and b the value of burnin.

Value

Both functions return an object of class bayesLife.mcmc.set. get.thinned.e0.mcmc returns NULL if such object does not exist.

Author(s)

Hana Sevcikova

See Also

bayesLife.mcmc.set, e0.predict

Examples

## Not run: 
sim.dir <- tempfile()
m <- run.e0.mcmc(nr.chains = 2, iter = 60, thin = 2, output.dir = sim.dir, verbose = TRUE)
pr <- e0.predict(m, burnin = 40, predict.jmale = FALSE) # creates thinned MCMCs
mb <- get.thinned.e0.mcmc(m, thin = 2, burnin = 40)
summary(mb, meta.only = TRUE) # length 20 = 2chains x (60-40)iters./2thin

# the same chain as 
summary(pr$mcmc.set, meta.only = TRUE)

unlink(sim.dir, recursive=TRUE)
## End(Not run)

---