e0options | R Documentation |

Setting, retrieving and updating global options.

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 in |

`annual` |
Logical indicating if the options are for an annual simulation ( |

`prior.choice` |
A character indicating for which combination of the upper bound on the |

`un.constraints` |
Logical indicating if constraints on the lower bounds of the |

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 *Triangle_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 *Triangle_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.

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

- a
vector of the

*a_1*, ... ,*a_6*parameters, which are the prior means of the world-level parameters (*Triangle_1*, ...,*Triangle_4*,*k*,*z*).- delta
vector of the

*delta_1*, ... ,*delta_6*parameters, which are the prior standard deviations of the world-level parameters (*Triangle_1*, ...,*Triangle_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

*Triangle_1*, ...,*Triangle_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

*Triangle_1*, ...,*Triangle_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

*Triangle_1*, ...,*Triangle_4*.- slice.width
vector of length four defining the slice width for MCMC slice sampling for the four parameters,

*Triangle_1*, ...,*Triangle_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

*Triangle_1_c*, ...,*Triangle_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

*Triangle_1_c*, ...,*Triangle_4_c*.- slice.width
vector of length four defining the slice width for MCMC slice sampling of the country-specific

*Triangle_1_c*, ...,*Triangle_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

*Triangle_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*Triangle_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,

*Triangle*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.

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.

Hana Sevcikova, Patrick Gerland contributed to the documentation.

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

`run.e0.mcmc`

, `e0.predict`

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

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.