% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/LifeTable.R
\name{LifeTable}
\alias{LifeTable}
\title{Compute Life Tables from Mortality Data}
\usage{
LifeTable(x, Dx = NULL, Ex = NULL,
             mx = NULL,
             qx = NULL,
             lx = NULL,
             dx = NULL,
             sex = NULL,
             lx0 = 1e5,
             ax  = NULL)
}
\arguments{
\item{x}{Numeric vector of ages at the beginning of each age interval. 
For a full life table, use single-year ages (e.g., \code{0:110}). 
For an abridged life table, use the lower bound of each interval 
(e.g., \code{c(0, 1, 5, 10, ..., 110)}).}

\item{Dx}{Death counts. Each element represents the total number of 
deaths during the calendar year to persons aged \code{x} to 
\code{x + n} (where \code{n} is the length of the age interval). 
Must be provided together with \code{Ex}.}

\item{Ex}{Exposure-to-risk in the period. This is usually approximated 
by the mid-year population aged \code{x} to \code{x + n}. Must be 
provided together with \code{Dx}.}

\item{mx}{Age-specific death rate in the age interval \code{[x, x+n)}. 
Defined as \code{Dx / Ex}.}

\item{qx}{Probability of dying within the age interval \code{[x, x+n)}.}

\item{lx}{Probability of surviving to exact age \code{x} (if \code{lx0 = 1}), 
or the number of survivors at exact age \code{x} (if \code{lx0 > 1}). 
When \code{lx} is the sole input, the values are re-scaled to the 
chosen radix \code{lx0}.}

\item{dx}{Number of deaths in the life-table population occurring in 
the age interval \code{[x, x+n)}. When \code{dx} is the sole input, 
the values are re-scaled to sum to \code{lx0}.}

\item{sex}{Sex of the population. Options are \code{NULL} (default), 
\code{"male"}, \code{"female"}, or \code{"total"}. When specified, 
the first two entries of the \code{ax} column are adjusted using 
Coale-Demeny coefficients, producing more accurate life-table values 
at the youngest ages. The adjustment differs slightly between males 
and females.}

\item{lx0}{Radix, the starting population (or probability scale) at 
age 0. Default is \code{100,000}. All subsequent life-table columns 
(\code{lx}, \code{dx}, \code{Lx}, \code{Tx}) are scaled accordingly.}

\item{ax}{Numeric vector representing the average number of person-years 
lived in the age interval by those who die in that interval. If 
\code{NULL} (the default), \code{ax} is estimated internally using 
a standard formula. You may supply a single value (applied to all 
intervals) or a vector of the same length as \code{x}. A common 
assumption is \code{ax = 0.5}, which places deaths at the midpoint 
of each interval.}
}
\value{
An object of class \code{"LifeTable"} containing the following 
  components:
  \item{lt}{A \code{data.frame} with the complete life table, including 
    columns for age interval (\code{x.int}), exact age (\code{x}), 
    death rate (\code{mx}), death probability (\code{qx}), person-years 
    lived by decedents (\code{ax}), survivorship (\code{lx}), death 
    distribution (\code{dx}), person-years lived (\code{Lx}), total 
    person-years remaining (\code{Tx}), and life expectancy (\code{ex}).}
  \item{call}{The matched function call.}
  \item{process_date}{Timestamp of when the life table was computed.}
}
\description{
Construct either a full (single-year age intervals) or an abridged 
(wider age intervals) life table from a variety of input data types. 
The function accepts:
\itemize{
  \item Death counts and mid-interval population estimates (\code{Dx, Ex})
  \item Age-specific death rates (\code{mx})
  \item Death probabilities (\code{qx})
  \item Survivorship curve (\code{lx})
  \item Distribution of deaths (\code{dx})
}
Only one of these input options needs to be provided; the others 
are ignored if present. The input can be a numeric \code{vector}, 
\code{matrix}, or \code{data.frame}. When a \code{matrix} or 
\code{data.frame} with multiple columns is supplied, the function 
computes one life table per column.
}
\details{
A life table (also called a mortality table or actuarial table) 
summarises the mortality experience of a population. For each age 
(or age interval) it reports:
\itemize{
  \item Death rates (\code{mx}) and death probabilities (\code{qx})
  \item Survivorship (\code{lx})
  \item Distribution of deaths (\code{dx})
  \item Person-years lived (\code{Lx}) and total person-years remaining 
        (\code{Tx})
  \item Life expectancy (\code{ex})
}
The life table is constructed sequentially: from the input data the 
function derives \code{mx}, then \code{qx}, then \code{lx}, \code{dx}, 
\code{Lx}, \code{Tx}, and finally \code{ex}. The constant-force-of-mortality 
(CFM) assumption is used to convert between \code{mx} and \code{qx}. 
If the \code{sex} argument is supplied, the first two values of the 
\code{ax} column are adjusted using the Coale-Demeny method, which 
accounts for the different infant mortality patterns between males 
and females.
}
\examples{
# Example 1 --- Full life tables with different inputs ------------

y  <- 1900
x  <- as.numeric(rownames(ahmd$mx))
Dx <- ahmd$Dx[, paste(y)]
Ex <- ahmd$Ex[, paste(y)]

LT1 <- LifeTable(x, Dx = Dx, Ex = Ex)
LT2 <- LifeTable(x, mx = LT1$lt$mx)
LT3 <- LifeTable(x, qx = LT1$lt$qx)
LT4 <- LifeTable(x, lx = LT1$lt$lx)
LT5 <- LifeTable(x, dx = LT1$lt$dx)

LT1
LT5
ls(LT5)

# Example 2 --- Compute multiple life tables at once ------------

LTs <- LifeTable(x, mx = ahmd$mx)
LTs
# A warning is printed if the input contains missing values.
# Some of the missing values can be handled automatically.

# Example 3 --- Abridged life table -----------------------------

x  <- c(0, 1, seq(5, 110, by = 5))
mx <- c(.053, .005, .001, .0012, .0018, .002, .003, .004,
        .004, .005, .006, .0093, .0129, .019, .031, .049,
        .084, .129, .180, .2354, .3085, .390, .478, .551)
LT6 <- LifeTable(x, mx = mx, sex = "female")
LT6

# Example 4 --- Abridged life table using a custom 'ax' --------
# This example reuses the ages (x) and death rates (mx) from Example 3.
# Note that 'ax' must have the same length as 'x', otherwise an error
# will be returned.

my_ax <- c(0.1, 1.5, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2,
           2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1)

LT7 <- LifeTable(x = x, mx = mx, ax = my_ax)

}
\seealso{
\code{\link{LawTable}} for generating life tables from a fitted 
  parametric mortality law; 
  \code{\link{convertFx}} for converting between mortality measures.
}
\author{
Marius D. Pascariu
}
