joint.male.estimate: Estimation of the Joint Female-Male Model
In bayesLife: Bayesian Projection of Life Expectancy

Description Usage Arguments Details Value Author(s) References See Also Examples

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.

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)

`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 (γ_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.

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) <= 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,…,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.

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

Hana Sevcikova

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.

e0.jmale.predict

## 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)