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)
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.
Arguments in tag = value form, or names of options to retrieve.
Logical indicating if the options are for an annual simulation (TRUE) or a 5-year simulation(FALSE).
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.
Logical indicating if constraints on the lower bounds of the Triangle parameter posed by the UN in WPP 2022 should be used.
vector of the \(a_1\), ... ,\(a_6\) parameters, which are the prior means of the world-level parameters (\(\Delta_1\), ..., \(\Delta_4\), \(k\), \(z\)).
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\)).
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\)).
list with elements:
list with elements:
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.
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.
vectors of length four. They are the lower and upper bounds for the prior (truncated normal) distribution of \(\Delta_1\), ..., \(\Delta_4\).
vector of length four defining the slice width for MCMC slice sampling for the four parameters, \(\Delta_1\), ..., \(\Delta_4\).
lists with elements:
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.
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.
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.
single value giving the slice width for MCMC slice sampling of the \(z\) parameter (not available for \(k\)).
list with elements:
list with elements:
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.
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.
vector of length four defining the slice width for MCMC slice sampling for the four parameters, \(\lambda_1\), ..., \(\lambda_4\).
lists with elements:
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.
single value giving the lower and upper bounds for initial values of \(\lambda_k\) (\(\lambda_z\)). It is only used if ini is NULL.
single value giving the slice width for MCMC slice sampling of the \(\lambda_z\) parameter (not available for \(\lambda_k\)).
list with elements:
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.
single value giving the lower and upper bounds for initial values of \(\omega\). It is only used if ini is NULL.
list with elements:
list with elements:
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.
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\).
vector of length four defining the slice width for MCMC slice sampling of the country-specific \(\Delta_1^c\), ..., \(\Delta_4^c\).
list with elements:
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.
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.
single value giving the slice width for MCMC slice sampling of the \(k^c\) (\(z^c\)) parameter.
the shape parameter of the Gamma distributions of all \(\lambda\) parameters is nu/2.
values of the parameters \(p_1\) and \(p_2\) of the double logistic function.
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.
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.
named vector where names are the country-specific parameters and values are the number of sub-parameters.
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 (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.
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:
gives the number of iterations in the first chunk of the MCMC simulation.
gives the number of iterations in the following chunks.
gives the number of chains in all chunks of the MCMC simulation.
used in the convergence diagnostics following each chunk.
controls the maximum number of chunks.
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.
Hana Sevcikova, Patrick Gerland contributed to the documentation.
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.
(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
Run the code above in your browser using DataLab