lifetable: Life table calculation for YourCast
In IQSS/YourCast: Forecasting Age-Sex-Country-Cause Mortality Rates

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

Creates a list of observed and predicted period life tables across from YourCast output for each geographical unit. This function should only be used when forecasting all-cause mortality rates.

1	lifetable(obj,ax=0.5,a0=0.07,nx=NULL,dv.log=NA)

`obj`	A `yourcast` output object containing all-cause mortality rates.
`ax`	A scalar, numeric vector of length A, or a numeric T by A matrix specifying the average years lived within a given age interval [x,x+n) by individuals who die within that age interval. If a scalar, `ax` is assumed to be constant across all age intervals (except for the first age interval; see `a0`) and across time. If a vector, `ax` is assumed to be constant across time. See ‘Details’. Default: 0.5.
`a0`	A scalar indicating the average years lived within the first age interval by individuals who die within that age interval. Ignored if `ax` is a vector or a matrix. Default: 0.07.
`nx`	A scalar or vector of length A defining the age interval widths. If a scalar, the age intervals have identical widths. If `NULL`, the age interval widths are calculated using the ages in the `yourcast` object. The last age interval is assumed to be open-ended so its length is set to `NA`. Default: `NULL`.
`dv.log`	Logical. Is the dependent variable logged? If `NA`, the function parses the formula in the `yourcast` object to determine if the dependent variable was logged. Default: `NA`.

The input must be a yourcast object containing forecasts of all-cause mortality rates. The death rates do not have to be for one-year age intervals, albeit ax and a0 should be adjusted accordingly based on the age interval size. The rates may either be logged or unlogged. If dv.log is set to NULL, the function parses the formula automatically to determine whether the rates are logged. Setting dv.log to TRUE or FALSE manually sets whether the rates are logged or not.

Specifying ax is necessary to convert mortality rates into conditional probabilities of death. Suppose that m_x is the mortality rate for the n-year age interval [x,x+n). a_x is then defined as the average years lived within the age interval [x,x+n) by individuals who die at that age. The default value of a_x is 0.5, which means that individuals on average live half the year within the age that they die (for single-year age intervals). The default value of a_0 is set to 0.07, following the reported values within the Human Mortality Database for adult females in the United States for the [0,1) age interval in the last decade.

Alternatively, one can specify ax as a vector of length A, where A is the number of age intervals. In this case, a_x is assumed to be constant across time for each age interval. One can also pass a T by A matrix, in which case a_x is allowed to vary over time.

The last age interval is open-ended: [x,∞). The conditional probability of death is set to 1 and a_x is automatically set to 1/m_x.

If a single geographic area, a list with names obs and pred is returned, where the elements are life table arrays calculated using observed and predicted mortality rates, respectively. If multiple geographic areas, a named list of geographic areas is returned, where each element contains a list of observed and predicted life tables.

Each life table array has dimensions T by A by 10, where the third dimension contains the following variables:

`x`	Age interval.
`nx`	Length of age interval.
`ax`	Average years lived within age interval by individuals who die during that age interval.
`qx`	Conditional probability of death for the age interval.
`px`	Conditional probability of survival for the age interval.
`lx`	Number of survivors at the start of the age interval. Set to 100,000 for the first age interval.
`dx`	Number of individuals dying within the age interval.
`Lx`	Person-years lived by individuals in the age interval.
`Tx`	Person-years remaining at start of age interval.
`ex`	Remaining life expectancy at start of age interval.

Konstantin Kashin kkashin@fas.harvard.edu

Preston, S.H., Patrick Heuveline, Michel Guillot. (2000) Demography: Measuring and Modeling Population Processes. Blackwell Publishing.

Wilmoth, J.R. et al. “Methods Protocol for the Human Mortality Database” http://www.mortality.org/.

http://gking.harvard.edu/yourcast

yourcast function and documentation (help(yourcast))

# Run Lee-Carter model for Figure 2.6 in Demographic Forecasting
data(chp.2.6.1)
ff.allc <- log(allc2/popu2) ~  time	
ylc.allc <- yourcast(formula=ff.allc, dataobj=chp.2.6.1, model="LC",
                       elim.collinear=FALSE,
                       sample.frame=c(1950,2000,2001,2060))

# calculate lifetable function assuming ax=2.5 and a0=1.907
# a0 calculated for both males and females from 
# Human Mortality Database for New Zealand for 2000
lt <- lifetable(ylc.allc,ax=2.5,a0=1.907)

# observed lifetable for csid 5150 (New Zealand) for 2000
lt[["5150"]]$obs["2000",,]

# predicted lifetable for csid 5150 (New Zealand) for 2015
lt[["5150"]]$pred["2015",,]