e0options {bayesLife}

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