MortalityLaws (version 2.2.0)

LawTable: Compute Life Tables from Parameters of a Mortality Law

Description

Generate a complete life table directly from the fitted parameters of a parametric mortality model. This function evaluates the mortality law at the given ages and passes the resulting death rates (mx) or death probabilities (qx) to LifeTable for further computation of all standard life-table columns (lx, dx, Lx, Tx, ex, etc.).

Usage

LawTable(x, par, law, sex = NULL, lx0 = 1e+05, ax = NULL)

Value

An object of class "LifeTable" containing the following components:

lt

A data.frame with the complete life table, including columns for age interval (x.int), exact age (x), death rate (mx), death probability (qx), person-years lived by decedents (ax), survivorship (lx), death distribution (dx), person-years lived (Lx), total person-years remaining (Tx), and life expectancy (ex).

call

The matched function call.

process_date

Timestamp of when the life table was computed.

Arguments

x

Numeric vector of ages at the beginning of each age interval. For a full life table, use single-year ages (e.g., 0:110). For an abridged life table, use the lower bound of each interval (e.g., c(0, 1, 5, 10, ..., 110)).

par

The parameters of the mortality model. Can be:

• A numeric vector containing the coefficients (for a single life table).

• A numeric matrix or data.frame where each row corresponds to a separate set of parameters (producing multiple life tables). Column names should match the parameter names of the chosen law.

law

The name of the mortality law to be used (e.g., "gompertz", "makeham"). Run availableLaws to see all options.

sex

Sex of the population. Options are NULL (default), "male", "female", or "total". When specified, the first two entries of the 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.

lx0

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

ax

Numeric vector representing the average number of person-years lived in the age interval by those who die in that interval. If NULL (the default), 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 x. A common assumption is ax = 0.5, which places deaths at the midpoint of each interval.

Author

Marius D. Pascariu

Details

This function is designed to work with models that have been fitted externally (e.g., via MortalityLaw or by hand). The par argument must contain the estimated coefficients of the mortality law, and law must be one of the valid codes listed by availableLaws.

Important caveat: age scaling during fitting

Several mortality laws (e.g., Gompertz, Makeham) internally scale the age vector during optimisation to ensure numerical stability. If the model was fitted using MortalityLaw over an age range [a, b], the published coefficients correspond to the scaled ages, not the original ages. Consequently, LawTable will only produce valid life tables for ages \(\ge a\) (the lower bound of the fitting range). Attempting to use the same coefficients at younger ages will yield incorrect results (e.g., life expectancy at age 25 will equal that at age 45).

To determine which models apply age scaling, run:

A <- availableLaws()$table
A[, c("CODE", "SCALE_X")]

Models with SCALE_X = TRUE rescale the age vector internally. When using LawTable with such a model, make sure the x argument starts from the same lower age bound used during fitting.

For models that do not scale (e.g., Heligman-Pollard "HP"), this limitation does not apply, and LawTable can be used for any age range.

See Also

LifeTable for constructing life tables from raw mortality data; MortalityLaw for fitting parametric mortality models; availableLaws for the list of implemented laws and their scaling behaviour.

Examples

# Example 1 --- Makeham --- multiple life tables from a matrix of parameters

x1 <- 45:100
L1 <- "makeham"
C1 <- matrix(
  c(0.00717, 0.07789, 0.00363,
    0.01018, 0.07229, 0.00001,
    0.00298, 0.09585, 0.00002,
    0.00067, 0.11572, 0.00078),
  nrow = 4,
  dimnames = list(1:4, c("A", "B", "C"))
)

LawTable(x = x1, par = C1, law = L1)

# ---- Important note on age scaling ----

# The Makeham model applies internal age scaling during fitting.
# If the coefficients above were estimated over ages 45-100, the life
# table produced by LawTable is valid only from age 45 onward.

# ---- Example 1B: correct usage ----
LawTable(x = 45:100, par = c(0.00717, 0.07789, 0.00363), law = L1)

# ---- Example 1C: incorrect usage ----
# The code below uses the same coefficients but starts at age 25.
# Because the model was fitted on scaled ages (starting at 45),
# the life table at age 25 will be meaningless (e.g., e25 equals e45).
if (FALSE) {
LawTable(x = 25:100, par = c(0.00717, 0.07789, 0.00363), law = L1)
}

# ---- How to check which laws apply scaling ----
A <- availableLaws()$table
A[, c("CODE", "SCALE_X")]

# Example 2 --- Heligman-Pollard (no scaling) ---

x2 <- 0:110
L2 <- "HP"
C2 <- c(0.00223, 0.01461, 0.12292, 0.00091,
        2.75201, 29.01877, 0.00002, 1.11411)

LawTable(x = x2, par = C2, law = L2)

# Because "HP" does NOT scale the age vector, the output is valid for
# any starting age. Compare:
LawTable(x = 3:110, par = C2, law = L2)
# Note that e3 = 70.31 in both tables, confirming consistency.