Package {MortalityLaws}

Type:	Package
Title:	Parametric Mortality Models, Life Tables and HMD
Version:	3.0.0
Maintainer:	Marius D. Pascariu <mpascariu@outlook.com>
Description:	Fit the most popular human mortality 'laws', and construct full and abridged life tables given various input indices. A mortality law is a parametric function that describes the dying-out process of individuals in a population during a significant portion of their life spans. For a comprehensive review of the most important mortality laws see Tabeau (2001) <doi:10.1007/0-306-47562-6_1>. Practical functions for downloading data from various human mortality databases are provided as well.
License:	MIT + file LICENSE
LazyData:	TRUE
Depends:	R (≥ 4.5.0)
Imports:	pbapply (≥ 1.7-4), httr (≥ 1.4.8)
Suggests:	testthat (≥ 3.3.2), knitr, rmarkdown
URL:	https://mpascariu.github.io/MortalityLaws/, https://github.com/mpascariu/MortalityLaws
BugReports:	https://github.com/mpascariu/MortalityLaws/issues
Encoding:	UTF-8
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-10-07 17:15:53 UTC; masax
Author:	Marius D. Pascariu [aut, cre, cph], Vladimir Canudas-Romo [ctb]
Repository:	CRAN
Date/Publication:	2026-10-07 18:00:08 UTC

MortalityLaws: Parametric Mortality Models, Life Tables and HMD

Description

Fit the most popular human mortality 'laws', and construct full and abridged life tables given various input indices. A mortality law is a parametric function that describes the dying-out process of individuals in a population during a significant portion of their life spans. For a comprehensive review of the most important mortality laws see Tabeau (2001) doi:10.1007/0-306-47562-6_1. Practical functions for downloading data from various human mortality databases are provided as well.

Details

To learn more about the package, start with the vignettes: browseVignettes(package = "MortalityLaws")

Author(s)

Maintainer: Marius D. Pascariu mpascariu@outlook.com (ORCID) [copyright holder]

Authors:

• Marius D. Pascariu mpascariu@outlook.com (ORCID) [copyright holder]

Other contributors:

• Vladimir Canudas-Romo [contributor]

See Also

Useful links:

• https://mpascariu.github.io/MortalityLaws/

• https://github.com/mpascariu/MortalityLaws

• Report bugs at https://github.com/mpascariu/MortalityLaws/issues

AHMD sample Data object generated by the ReadAHMD() function.

Description

AHMD sample Data object generated by the ReadAHMD() function.

Usage

AHMD_sample

Format

A list of class ReadAHMD with the following components:

input

A list with the arguments used in the call to ReadAHMD.

data

A data.frame with the columns country, Year, Age, Female, Male and Total.

download.date

A character string with the date of the download.

years

An integer vector with the years covered by the sample.

ages

A character vector with the ages covered by the sample.

Extract the AIC of a Fitted Mortality Law

Description

Returns the Akaike information criterion of a "MortalityLaw" fit, 2 * k - 2 * logLik, with k the number of fitted parameters. Like the log-likelihood it is defined only for the likelihood-based objectives and is NaN otherwise. Use it to compare candidate laws fitted to the same data.

Usage

## S3 method for class 'MortalityLaw'
AIC(object, ...)

Arguments

Value

The AIC value for a single fit, or a named vector of AIC values for a multiple fit.

See Also

MortalityLaw; logLik.MortalityLaw.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"],
                   law = "makeham", opt.method = "poissonL")
AIC(M1)

CHMD sample Data object generated by the ReadCHMD() function.

Description

CHMD sample Data object generated by the ReadCHMD() function.

Usage

CHMD_sample

Format

A list of class ReadCHMD with the following components:

input

A list with the arguments used in the call to ReadCHMD.

data

A data.frame with the columns country, Year, Age, Female, Male and Total.

download.date

A character string with the date of the download.

years

An integer vector with the years covered by the sample.

ages

A character vector with the ages covered by the sample.

HMD sample Data object generated by the ReadHMD() function.

Description

HMD sample Data object generated by the ReadHMD() function.

Usage

HMD_sample

Format

A list of class ReadHMD with the following components:

input

A list with the arguments used in the call to ReadHMD.

data

A data.frame with the columns country, Year, Age, Female, Male and Total.

download.date

A character string with the date of the download.

years

An integer vector with the years covered by the sample.

ages

An integer vector with the ages covered by the sample.

Heligman-Pollard Mortality Law - 8 parameters - 1980

Description

The Heligman-Pollard eight-parameter law of the whole lifespan, fitted on the odds of dying q_x/p_x; the fitted quantity is a death probability.

Usage

HP(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

HP(x = 0:100)

Heligman-Pollard 2 Mortality Law - 8 parameters

Description

The Heligman-Pollard law with a logistic old-age term, which keeps the hazard bounded.

Usage

HP2(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

HP2(x = 0:100)

Heligman-Pollard 3 Mortality Law - 9 parameters

Description

The Heligman-Pollard law with an extra parameter in the old-age term, making it a full logistic that bends at the oldest ages.

Usage

HP3(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

HP3(x = 0:100)

Heligman-Pollard 4 Mortality Law - 9 parameters

Description

The Heligman-Pollard law with an extra exponent on the age in the old-age term, so the rise in the hazard can accelerate.

Usage

HP4(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

HP4(x = 0:100)

JMD sample Data object generated by the ReadJMD() function.

Description

JMD sample Data object generated by the ReadJMD() function.

Usage

JMD_sample

Format

A list of class ReadJMD with the following components:

input

A list with the arguments used in the call to ReadJMD.

data

A data.frame with the columns region, Year, Age, Female, Male and Total.

download.date

A character string with the date of the download.

years

An integer vector with the years covered by the sample.

ages

A character vector with the ages covered by the sample.

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 = "andreev_kingkade")

Arguments

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.

The ax argument is passed straight to LifeTable; its default, "andreev_kingkade", is the rule the Human Mortality Database applies to its period life tables (Methods Protocol, version 6; see LifeTable for the alternatives). Because a law is evaluated on a possibly scaled age vector, the first interval is only treated as a one-year interval with the Andreev-Kingkade rule when the ages passed in x really start one year apart.

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.

Matching the coefficients to the model parameters

The coefficients supplied in par are matched to the parameters of the chosen law by name and in any order. For a matrix or a data.frame the column names must therefore be the parameter names of that law (e.g. c("A", "B", "C") for "makeham"); the row names are used as the labels of the resulting life tables and must be supplied. An unnamed vector keeps the positional convention, i.e. the coefficients are read in the order in which the parameters are documented for the law.

Value

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

Author(s)

Marius D. Pascariu

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

Compute Life Tables from Mortality Data

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:

• Death counts and mid-interval population estimates (Dx, Ex)

• Age-specific death rates (mx)

• Death probabilities (qx)

• Survivorship curve (lx)

• Distribution of deaths (dx)

• Remaining life expectancy (ex)

Exactly one of these input options must be provided; supplying more than one is an error. The input can be a numeric vector, matrix, or data.frame. When a matrix or data.frame with multiple columns is supplied, the function computes one life table per column.

Usage

LifeTable(x, Dx = NULL, Ex = NULL,
             mx = NULL,
             qx = NULL,
             lx = NULL,
             dx = NULL,
             ex = NULL,
             sex = NULL,
             lx0 = 1e5,
             ax  = "andreev_kingkade",
             close = NULL,
             omega = NULL,
             fit_from = NULL)

Arguments

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:

• Death rates (mx) and death probabilities (qx)

• Survivorship (lx)

• Distribution of deaths (dx)

• Person-years lived (Lx) and total person-years remaining (Tx)

• Life expectancy (ex)

The life table is constructed sequentially: from the input data the function derives mx, then qx, then lx, dx, Lx, Tx, and finally ex. The conversion between mx and qx follows the ax method. The default, ax = "andreev_kingkade", is the rule the Human Mortality Database applies to its period life tables (Methods Protocol, version 6): the Andreev-Kingkade (2015) formula for the first year of life and half the interval width elsewhere, converted through the exact interval identity so that the mx, qx and ax columns are mutually consistent. The constant-force-of-mortality (CFM) assumption, ax = n + 1/m - n/q, is available with ax = "cfm". When sex is given, the first two values of the ax column can instead be adjusted using the Coale-Demeny method, which accounts for the different infant mortality patterns between males and females; two published parameterisations of that adjustment are available through ax = "preston", expressed in terms of mx, and ax = "coale_demeny", expressed in terms of qx and retrieved from mx by the PAS inversion. The latter reproduces the coefficients used by the Coale-Demeny 1983 regional model tables and by the PAS software.

The ex input runs the table backwards. The survivorship ratio of each closed interval follows from the identity

e_x l_x - e_{x+n} l_{x+n} = nL_x = a_x l_x + (n - a_x) l_{x+n}

, so that r_x = l_{x+n}/l_x = (e_x - a_x)/(e_{x+n} + n - a_x). When ax is supplied as a numeric vector the recovery is a single sweep. When it is not, each interval is solved so that the ax the method in force would assign to the recovered interval reproduces the ratio it came from; the recovered table is then identical to the one the same ex curve describes under that method. The open interval closes by the standard rule, a_N = e_N and m_N = 1/e_N. A curve of life expectancy is allowed to rise with age at the youngest ages (life expectancy at birth is lower than at age one when infant mortality is high), so a rise is not an error; a curve that falls by more than the interval width, or below its own a_x, is not a feasible life table and is reported by age. Because e_x alone does not pin a_x, pass ax alongside ex when the ax convention matters. One nuance follows from the forward build: when ax is "preston" or "coale_demeny" and a sex is given, the forward table adjusts ax in the first two intervals after converting the rates, so its stored mx there does not satisfy the exact identity on its own ax. The inverse returns the identity-consistent mx, so in that one family the recovered mx in the first two rows can differ from the forward table's at the third decimal while ex, qx and ax still reproduce exactly.

Value

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

Author(s)

Marius D. Pascariu

References

Coale, A. J., Demeny, P., and Vaughan, B. (1983). Regional Model Life Tables and Stable Populations. 2nd ed. New York: Academic Press.

Preston, S. H., Heuveline, P., and Guillot, M. (2001). Demography: Measuring and Modeling Population Processes. Oxford: Blackwell Publishers.

When ax is supplied by the user as a numeric vector the conversion between mx and qx uses the exact interval identity qx = nx * mx / (1 + (nx - ax) * mx) (and its inverse) instead of the CFM approximation, so that the mx, qx and ax columns of the result are mutually consistent. The "andreev_kingkade" method does the same, because it builds a numeric ax before the conversion. An ax that an interval cannot support (ax * mx > 1) is replaced with the implied average, 1/mx, and the affected ages are reported.

The open (closing) age interval follows its own rule: ax[N] = 1/mx[N], ex[N] = 1/mx[N] and Lx[N] = lx[N]/mx[N], which keeps the closed table consistent with qx[N] = 1. A user-supplied ax[N] is therefore replaced, with a warning.

That rule assumes the force of mortality is roughly constant above the open age, which holds when the open interval is old (85+ or 90+) but not when the input stops early (70+ or 75+). The close argument addresses that directly: given a mortality-law code, the observed mx[N] is replaced by the model-implied average over the open interval, 1/ex[N], without changing the age grid. The omega argument is a different response to the same problem: it extends the table to omega by extrapolating the rates and closes there. Either argument alone leaves the other's default in place, and the default (close = NULL, omega = NULL) is the standard reciprocal close, so results are unchanged.

Missing values in mx or qx are never masked. They localise to the interval quantities of the affected row (which are returned as NA) and to the cumulative Tx and ex columns at and before that row, while the survivorship chain lx is bridged across the gap, so the ages above it remain computable. A warning names the affected ages.

See Also

LawTable for generating life tables from a fitted parametric mortality law; convertFx for converting between mortality measures.

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)
LT6 <- LifeTable(x, ex = LT1$lt$ex)

LT1
LT5
LT6
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)
LT7 <- LifeTable(x, mx = mx, sex = "female")
LT7

# 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, rep(2, 19), 1, 1, 1)

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

# Example 5 --- The ax methods ------------------------------
# The default 'andreev_kingkade' follows the HMD Methods Protocol v6
# (Andreev-Kingkade a0, half-interval elsewhere). 'cfm' is the plain
# constant-force identity; 'preston' and 'coale_demeny' are the two
# Coale-Demeny conventions for the first two intervals (identical above
# m0 = 0.107).

LT9  <- LifeTable(x, mx = mx, sex = "female", ax = "andreev_kingkade")
LT10 <- LifeTable(x, mx = mx, sex = "female", ax = "cfm")
LT11 <- LifeTable(x, mx = mx, sex = "female", ax = "preston")
LT12 <- LifeTable(x, mx = mx, sex = "female", ax = "coale_demeny")

rbind(
 andreev_kingkade = LT9$lt$ax[1:2], 
 cfm = LT10$lt$ax[1:2],
 preston = LT11$lt$ax[1:2], 
 coale_demeny = LT12$lt$ax[1:2]
)

# Example 6 --- Closing the open interval accurately -----------
# The data stop at 75+; closing there assumes a constant hazard above 75.
# 'close' argument corrects the open-interval rate with a fitted law, on the same
# age grid; 
# 'omega' argument offers the option to extend the table to 110 before closing it.

x5  <- c(0, 1, seq(5, 75, by = 5))
mx5 <- c(.053, .005, .001, .0012, .0018, .002, .003, .004,
         .004, .005, .006, .0093, .0129, .019, .031, .049, .084)
LT13 <- LifeTable(x5, mx = mx5)
LT14 <- LifeTable(x5, mx = mx5, close = "kannisto")
LT15 <- LifeTable(x5, mx = mx5, close = "kannisto", omega = 110)

c(default = LT13$lt$ex[1], close = LT14$lt$ex[1], omega = LT15$lt$ex[1])

Fit Mortality Laws

Description

Fit parametric mortality models given a set of input data. The data can be supplied as death counts and mid-interval population estimates (Dx, Ex), age-specific death rates (mx), or death probabilities (qx). Use the law argument to specify the model to be fitted. Over 30 parametric models are currently implemented; run availableLaws to see the full list. Models can be fitted using maximum likelihood or by optimising a loss function. See the availableLF function for the implemented options.

Usage

MortalityLaw(x, Dx = NULL, Ex = NULL, mx = NULL, qx = NULL,
                law = NULL,
                opt.method = "LF2",
                parS = NULL,
                fit.this.x = x,
                custom.law = NULL,
                show = FALSE, ...)

Arguments

Details

Optimisation: The PORT routines (via nlminb) are used for unconstrained and box-constrained optimisation. Parameters are estimated on the log scale to ensure positivity, and the routine is set to allow up to 5000 iterations. When the optimisation method is "poissonL" or "binomialL", the AIC, BIC and log-likelihood are computed from the likelihood. Otherwise these are set to NaN.

Scaling of the age vector: For models that cover only a portion of the lifespan (e.g., adult or old-age mortality), the age vector x is automatically re-scaled as x = x - min(x) + 1 before fitting. This transformation improves numerical stability and helps the optimisation algorithm converge, especially when the starting age is far from zero. Models that apply this scaling are flagged with SCALE_X = TRUE in the table returned by availableLaws. When using predict.MortalityLaw or LawTable with such models, the same scaling is applied internally, so predictions remain consistent with the fitted coefficients.

Handling matrix input: If Dx, Ex, mx or qx are provided as matrices (with one column per population or time period), the function iterates over the columns and fits a separate model to each, returning a collection of results.

Value

An object of class "MortalityLaw", which is a list with the following components:

Author(s)

Marius D. Pascariu

See Also

availableLaws for a list of all implemented models; availableLF for loss function details; LifeTable for life table construction; ReadHMD for downloading data from the Human Mortality Database.

Examples

# Example 1: Fitting the Makeham model --------------------------
x  <- 45:75
Dx <- ahmd$Dx[paste(x), "1950"]
Ex <- ahmd$Ex[paste(x), "1950"]

M1 <- MortalityLaw(x = x, Dx = Dx, Ex = Ex, law = 'makeham')

M1
ls(M1)
coef(M1)
summary(M1)
fitted(M1)
predict(M1, x = 45:95)
plot(M1, which = 'fit')
plot(M1, which = 'diagnostics')


# Example 2: --------------------------
# We can fit the same model using a different data format
# and a different optimization method.
x  <- 45:75
mx <- ahmd$mx[paste(x), ]
M2 <- MortalityLaw(x = x, mx = mx, law = 'makeham', opt.method = 'LF1')
M2
fitted(M2)
predict(M2, x = 55:90)

# Example 3: --------------------------
# Now let's fit a mortality law that is not defined
# in the package, say a reparameterized Gompertz in
# terms of modal age at death
# hx = b*exp(b*(x-m)) (here b and m are the parameters to be estimated)

# A function with 'x' and 'par' as input has to be defined, which returns
# at least an object called 'hx' (hazard rate).
missov <- function(x, par = c(b = 0.13, M = 45)){
  hx  <- with(as.list(par), b*exp(b*(x - M)) )
  return(as.list(environment()))
}

M3 <- MortalityLaw(x = x, Dx = Dx, Ex = Ex, custom.law = missov)
summary(M3)
plot(M3)
# predict M3 for different ages
predict(M3, x = 85:130)


# Example 4: --------------------------
# Fit Heligman-Pollard model for a single
# year in the dataset between age 0 and 100 and build a life table.

x  <- 0:100
mx <- ahmd$mx[paste(x), "1950"] # select data
M4 <- MortalityLaw(x = x, mx = mx, law = 'HP', opt.method = 'LF2')
M4
plot(M4, which = 'fit')
plot(M4, which = 'diagnostics')
plot(M4, which = 'both')

LifeTable(x = x, qx = fitted(M4))

Download the Australian Human Mortality Database (AHMD)

Description

Download detailed mortality and population data for different provinces and territories in Australia, in a single object from the Australian Human Mortality Database.

Usage

ReadAHMD(what, regions = NULL, interval = "1x1", save = FALSE, show = TRUE)

Arguments

Details

The Australian Human Mortality Database is a "satellite" of the Human Mortality Database, built with the same methodology, so the two are directly comparable. It covers Australia, its states and its territories. See the AHMD website for its history and research team. The database is open, so no login is needed.

Value

A ReadAHMD object that contains:

Author(s)

Marius D. Pascariu

See Also

ReadHMD ReadCHMD

Examples

## Not run: 
# Download demographic data for Australian Capital Territory and
# Tasmania regions in 5x1 format

# Death counts. We don't want to export data outside R.
AHMD_Dx <- ReadAHMD(what = "Dx",
                    regions = c('ACT', 'TAS'),
                    interval  = "5x1",
                    save = FALSE)
AHMD_Dx

# Download life tables for female population in all the states and export data.
LTF <- ReadAHMD(what = "LT_f", interval  = "5x1", save = FALSE)
LTF

## End(Not run)

Download the Canadian Human Mortality Database (CHMD)

Description

Download detailed mortality and population data for different provinces and territories in Canada, in a single object from the Canadian Human Mortality Database.

Usage

ReadCHMD(what, regions = NULL, interval = "1x1", save = FALSE, show = TRUE)

Arguments

Details

The Canadian Human Mortality Database is a "satellite" of the Human Mortality Database, built with the same methodology, so the two are directly comparable. It covers Canada, its provinces and its territories. See the CHMD website for its history and research team; the data are validated and corrected for the period it covers.

Value

A ReadCHMD object that contains:

Author(s)

Marius D. Pascariu

See Also

ReadHMD ReadAHMD

Examples

## Not run: 
# Download demographic data for Quebec and Saskatchewan regions in 1x1 format

# Death counts. We don't want to export data outside R.
CHMD_Dx <- ReadCHMD(what = "Dx",
                    regions = c('QUE', 'SAS'),
                    interval  = "1x1",
                    save = FALSE)

# Download life tables for female population. To export data use save = TRUE.
LTF <- ReadCHMD(what = "LT_f",
                regions = c('QUE', 'SAS'),
                interval  = "1x1",
                save = FALSE)

## End(Not run)

Download The Human Mortality Database (HMD)

Description

Download detailed mortality and population data for different countries and regions in a single object from the Human Mortality Database.

Usage

ReadHMD(
  what,
  countries = NULL,
  interval = "1x1",
  username,
  password,
  save = FALSE,
  show = TRUE
)

Arguments

Details

The Human Mortality Database is the reference source of detailed national mortality and population data; see the project's own pages for its history and research teams. A free account (and acceptance of the user agreement) is required, and a dataset is only as detailed as the country publishes: not every what exists for every country.

The login is performed once per call and reused for every country, so a long countries vector costs one authentication. The password is never stored in the returned object; input carries everything else, for reproducibility.

Value

A ReadHMD object that contains:

Author(s)

Marius D. Pascariu

Examples

## Not run: 


# Download demographic data for 3 countries in 1x1 format
age_int  <- 1  # age interval: 1,5
year_int <- 1  # year interval: 1,5,10
interval <- paste0(age_int, "x", year_int)  # --> 1x1
# And the 3 countries: Sweden Denmark and USA. We have to use the HMD codes
cntr  <- c('SWE', 'DNK', 'USA')

# Download death counts. We don't want to export data outside R.
HMD_Dx <- ReadHMD(what = "Dx",
                  countries = cntr,
                  interval  = interval,
                  username  = "user@email.com",
                  password  = "password",
                  save = FALSE)
HMD_Dx

# Download life tables for female population and export data.
LTF <- ReadHMD(what = "LT_f",
               countries = cntr,
               interval  = interval,
               username  = "user@email.com",
               password  = "password",
               save = TRUE)
LTF

## End(Not run)

Download the Japanese Mortality Database (JMD)

Description

Download detailed mortality and population data of the 47 prefectures in Japan, in a single object. The source of data is the Japanese Mortality Database.

Usage

ReadJMD(what, regions = NULL, interval = "1x1", save = FALSE, show = TRUE)

Arguments

Details

The Japanese Mortality Database is a mortality database reorganised to be consistent with the Human Mortality Database, for all Japan and by prefecture; see the JMD website for its research project and methods. The database is open, so no login is needed. Its life tables are built to be internationally comparable, so they need not match the official Japanese life tables, which use a different base population and estimation method.

The region codes are prefecture names, not the numeric JIS codes used in the server's folder names; the reader maps one to the other internally.

Value

A ReadJMD object that contains:

Author(s)

Marius D. Pascariu

See Also

ReadHMD ReadCHMD

Examples

## Not run: 
# Download demographic data for Fukushima and Tokyo regions in 1x1 format

# Death counts. We don't want to export data outside R.
JMD_Dx <- ReadJMD(what = "Dx",
                  regions = c('Fukushima', 'Tokyo'),
                  interval  = "1x1",
                  save = FALSE)
JMD_Dx

# Download life tables for female population in all the states and export data.
LTF <- ReadJMD(what = "LT_f", interval  = "5x5", save = FALSE)
LTF

## End(Not run)

MortalityLaws Test Data

Description

Dataset containing altered death rates (mx), death counts (Dx) and exposures (Ex) for the female population living in England & Wales in four different years: 1850, 1900, 1950 and 2010. This dataset is provided for testing purposes only. Download the actual data free of charge from https://www.mortality.org. Once a username and a password are created on the website, the function ReadHMD can be used for downloading.

Usage

ahmd

Format

A list with the components mx, Dx and Ex. Each component is a data.frame with 111 rows (ages 0 to 110) and one column per year: 1850, 1900, 1950 and 2010.

Source

Human Mortality Database

See Also

ReadHMD

Examples

head(ahmd$mx)

Check Data Availability in HMD

Description

Returns information about the data available in the Human Mortality Database (HMD), including the range of years covered by the life tables for each country or region.

Usage

availableHMD(link = "https://www.mortality.org/Data/DataAvailability")

Arguments

Details

The function scrapes the availability table published on the HMD site, so it needs no account. It is a thin companion to ReadHMD, useful for checking what exists before a download; every failure (no connection, a non-200 status, a body that is not a table) is reported with a message() and returns NULL rather than raising an error.

Value

A data frame with one row per country or region, or NULL when the website cannot be reached or the response carries no table.

Author(s)

Marius D. Pascariu

See Also

ReadHMD

Examples

## Not run: 
availableHMD()

## End(Not run)

Check Available Loss Functions

Description

Returns information about the loss functions implemented for use with the optimisation procedure in the MortalityLaw function.

Usage

availableLF()

Details

The two likelihoods ("poissonL", "binomialL") are the only objectives that yield a log-likelihood, an AIC and a BIC; the six loss functions ("LF1" to "LF6") leave those measures undefined (NaN) and are compared on the deviance or the loss itself. "LF2", the squared log-ratio, is the default: it is scale-free and robust, and it has been observed to return reliable estimates for the high-parameter laws such as Heligman-Pollard. There is no universally best choice, so it is worth trying more than one.

Value

A list of class availableLF with the components:

Author(s)

Marius D. Pascariu

See Also

MortalityLaw

Examples

availableLF()

Check the Available Mortality Laws

Description

The law catalogue. It lists every parametric model that MortalityLaw can fit, with the formula and the code to pass through law, and says where each model applies. Use it to choose a law before fitting; there is no need to know the functional form, only its code and the age range it is meant for. For a comprehensive review of the mortality laws themselves, Tabeau (2001) is a good starting point.

Usage

availableLaws(law = NULL)

Arguments

Details

The TYPE column says where on the lifespan the law belongs, read off the legend in the second component of the result: a law covering the whole range (6) is fitted over all ages, while a law for old age (5) is fitted from the adult ages up. The FIT column says whether the law describes a hazard, mu[x], or a death probability, q[x]; MortalityLaw and LawTable handle both. The SCALE_X column flags the laws whose age vector is rescaled during fitting for numerical stability, which matters when the fitted coefficients are reused outside the fitted age range (see LawTable).

A law is normally reached through the law argument of MortalityLaw, but each one is also a function that can be called by name for a plain hazard or death probability curve; those help pages exist for reference and are kept out of the help index. A law that is not in the catalogue can still be fitted by passing it as a function through the custom.law argument; see the examples on the MortalityLaw page.

A few laws carry a caveat worth knowing before choosing them, all documented in the model catalogue and their catalogue entries:

• "scholey": its truncation parameter is identified only on day- or week-level data over the first year of life; on single-year ages it collapses and the fit reduces to "scholey_shifted_power", with a warning.

• "opperman": the published middle term has a free sign; the package uses the negative branch the log-scale engine permits, which is the branch mortality data occupy.

• "steffensen": the formula is attributed to Steffensen (1930), but the attribution is not verified against the paywalled source.

• "HP", "HP2", "HP3", "HP4" and "kostaki": high-parameter models; fit them with opt.method = "LF2".

• "gompertz_logquad" and "makeham_logquad": the sign of the quadratic term is fixed to the decelerating branch that mortality data occupy; the accelerating branch cannot be fitted.

• "beard_makeham" and "perks": the same four-parameter Perks-Beard logistic written two ways, so they fit identical curves; "beard", "kannisto" and "kannisto_makeham" are its two- and three-parameter cases. Pick one of them, not several.

• "demoivre": the 1725 baseline, kept for completeness. Its hazard is defined only below a limiting age, so it must not be extrapolated and the fit warns every time.

• "weibull": not defined at birth, so age 0 is reported as missing and takes no part in the fit; start the fit at age 1.

Two entries in the reference list are background for the infant laws rather than the source of a catalogue code: Harper (1936), and de Beer and Janssen (2016), whose infancy term is the fitted pareto_2.

Value

The output is of the "availableLaws" class with the following components:

Author(s)

Marius D. Pascariu

References

1. De Moivre, A. (1725). Annuities on Lives: or, the Valuation of Annuities upon any Number of Lives. London: William Pearson.

2. Gompertz, B. (1825). On the Nature of the Function Expressive of the Law of Human Mortality, and on a New Mode of Determining the Value of Life Contingencies. Philosophical Transactions of the Royal Society of London, 115, 513-583.

3. Makeham, W. (1860). On the Law of Mortality and Construction of Annuity Tables. The Assurance Magazine and Journal of the Institute of Actuaries, 8(6), 301-310. doi:10.1017/S204616580000126X

4. Thiele, T. (1871). On a Mathematical Formula to express the Rate of Mortality throughout the whole of Life, tested by a Series of Observations made use of by the Danish Life Insurance Company of 1871. Journal of the Institute of Actuaries and Assurance Magazine, 16(5), 313-329. doi:10.1017/S2046167400043688

5. Lomax, K. S. (1954). Business Failures: Another Example of the Analysis of Failure Data. Journal of the American Statistical Association, 49(268), 847-852. doi:10.1080/01621459.1954.10501239

6. Vaupel, J. W. and Yashin, A. I. (1983). The Deviant Dynamics of Death in Heterogeneous Populations. IIASA Research Report RR-83-1. Laxenburg, Austria.

7. de Beer, J. and Janssen, F. (2016). A new parametric model to assess delay and compression of mortality. Population Health Metrics, 14(1), 46. doi:10.1186/s12963-016-0113-1

8. Scholey, J. (2019). The Age-Trajectory of Infant Mortality in the United States: Parametric Models and Generative Mechanisms. PAA Annual Conference, Austin.

9. Oppermann, L. H. F. (1870). On the graduation of life tables, with special application to the rate of mortality in infancy and childhood. The Insurance Record Minutes from a meeting in the Institute of Actuaries, 42.

10. Wittstein, T. and D. Bumsted. (1883). The Mathematical Law of Mortality. Journal of the Institute of Actuaries and Assurance Magazine, 24(3), 153-173.

11. Steffensen, J. (1930). Infantile mortality from an actuarial point of view. Skandinavisk Aktuarietidskrift 13, 272-286. doi:10.1080/03461238.1930.10416902

12. Perks, W. (1932). On Some Experiments in the Graduation of Mortality Statistics. Journal of the Institute of Actuaries, 63(1), 12-57. doi:10.1017/S0020268100046680

13. Harper, F. S. (1936). An actuarial study of infant mortality. Scandinavian Actuarial Journal 1936 (3-4), 234-270. doi:10.1080/03461238.1936.10405113

14. Weibull, W. (1951). A statistical distribution function of wide applicability. Journal of applied mechanics 18, 293-297. doi:10.1115/1.4010337

15. Beard, R. E. (1971). Some aspects of theories of mortality, cause of death analysis, forecasting and stochastic processes. Biological aspects of demography 999, 57-68.

16. Vaupel, J., Manton, K.G., and Stallard, E. (1979). The impact of heterogeneity in individual frailty on the dynamics of mortality. Demography 16(3): 439-454. doi:10.2307/2061224

17. Siler, W. (1979), A Competing-Risk Model for Animal Mortality. Ecology, 60: 750-757. doi:10.2307/1936612

18. Heligman, L., & Pollard, J. (1980). The age pattern of mortality. Journal of the Institute of Actuaries, 107(1), 49-80. doi:10.1017/S0020268100040257

19. Rogers A and Planck F (1983). MODEL: A General Program for Estimating Parametrized Model Schedules of Fertility, Mortality, Migration, and Marital and Labor Force Status Transitions. IIASA Working Paper. IIASA, Laxenburg, Austria: WP-83-102

20. Martinelle S. (1987). A generalized Perks formula for old-age mortality. Stockholm, Sweden, Statistiska centralbyran, 1987. 55 p. (R&D Report, Research-Methods-Development, U/STM No. 38)

21. Forfar, D. O., McCutcheon, J. J. and Wilkie, A. D. (1988). On graduation by mathematical formula. Journal of the Institute of Actuaries, 115(1), 1-149.

22. Carriere J.F. (1992). Parametric models for life tables. Transactions of the Society of Actuaries. Vol.44

23. Kostaki A. (1992). A nine-parameter version of the Heligman-Pollard formula. Mathematical Population Studies. Vol. 3 277-288. doi:10.1080/08898489209525346

24. Thatcher AR, Kannisto V and Vaupel JW (1998). The force of mortality at ages 80 to 120. Odense Monographs on Population Aging Vol. 5, Odense University Press, 1998. 104, 20 p. Odense, Denmark

25. Tabeau E. (2001). A Review of Demographic Forecasting Models for Mortality. In: Tabeau E., van den Berg Jeths A., Heathcote C. (eds) Forecasting Mortality in Developed Countries. European Studies of Population, vol 9. Springer, Dordrecht. doi:10.1007/0-306-47562-6_1

26. Finkelstein M. (2012) Discussing the Strehler-Mildvan model of mortality Demographic Research, Vol. 26(9), 191-206. doi:10.4054/DemRes.2012.26.9

See Also

MortalityLaw to fit a law; LawTable to build a life table from fitted coefficients; availableLF for the loss functions.

MortalityLaw

Examples

availableLaws()

Beard Model - 1971

Description

The Beard logistic hazard, \mu_x = A \exp(Bx) / (1 + K A \exp(Bx)), which levels off at old age.

Usage

beard(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

beard(x = 50:100)

Makeham-Beard Model - 1971

Description

The Beard logistic hazard plus a constant, covering the age-independent component and the old-age levelling-off.

Usage

beard_makeham(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

beard_makeham(x = 0:100)

Carriere Mortality Law - 1992

Description

A mixture law: Weibull + inverse-Weibull + Gompertz components combined on the survivorship, with the mixture weights normalised to the simplex.

Usage

carriere1(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

carriere1(x = 0:100)

Carriere Mortality Law - 1992

Description

A mixture law: Weibull + inverse-Gompertz + Gompertz components combined on the survivorship, with the mixture weights normalised to the simplex.

Usage

carriere2(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

carriere2(x = 0:100)

Convert Life Table Indicators

Description

Easily convert between different life table indicators (e.g., from death rates mx to death probabilities qx, or from survivorship lx to life expectancy ex). The function wraps LifeTable internally, so the conversion relies on the same constant-force-of-mortality (CFM) assumption and life-table methodology used throughout the package.

Usage

convertFx(
  x,
  data,
  from = c("mx", "qx", "dx", "lx", "ex"),
  to = c("mx", "qx", "dx", "lx", "Lx", "Tx", "ex"),
  ...
)

Arguments

Details

This function provides a convenient interface for converting a single mortality indicator into another, without having to call LifeTable directly and extract the desired column.

The supported input types (from) are: mx, qx, dx, lx, and ex.

The supported output types (to) are: mx, qx, dx, lx, Lx, Tx, and ex.

There are 35 possible from-to combinations (5 inputs \times 7 outputs). Conversions that need a single life-table identity, such as mx to qx or dx to lx, are computed directly from that relation. All the other conversions are obtained from the full life-table computation; for example, converting mx to ex will internally compute qx, lx, dx, Lx, and Tx in sequence. A ex input is converted by building the life table that reproduces the supplied curve (see LifeTable).

When data is a vector, the function returns a named vector. When data is a matrix or data.frame with multiple columns, the function applies the conversion column-wise and returns a matrix with the same row and column names as the input.

Value

A numeric vector or matrix of class "convertFx" containing the converted life table indicator. If the input was a named object, the output retains those names. The result carries the ages it is indexed by (x), the conversion (from, to) and the input curve (input) as attributes, which is what plot.convertFx draws. It behaves like the underlying numeric vector or matrix in every other respect; subsetting returns the bare values.

Author(s)

Marius D. Pascariu

See Also

LifeTable for the underlying life-table construction; LawTable for generating life tables from parametric mortality laws; plot.convertFx for plotting a conversion.

Examples

# ---- Basic conversions ----

x  <- 0:110
mx <- ahmd$mx

# Convert death rates to death probabilities
qx <- convertFx(x, data = mx, from = "mx", to = "qx")

# Convert death rates to death distribution
dx <- convertFx(x, data = mx, from = "mx", to = "dx")

# Convert death rates to survivorship
lx <- convertFx(x, data = mx, from = "mx", to = "lx")

# Convert death rates to life expectancy
ex <- convertFx(x, data = mx, from = "mx", to = "ex")

De Moivre Mortality Law - 1725

Description

The oldest law in the catalogue: survivorship falls linearly to zero at a limiting age, l_x = N - x, so the hazard rises steeply as age approaches N, \mu_x = 1/(N - x). A historical baseline rather than a curve to graduate data with. USE WITH CARE: the hazard is defined only below N, so a prediction past the fitted ages can be negative, and MortalityLaw warns whenever it fits this law.

Usage

demoivre(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

demoivre(x = 0:95)

Extract the Deviance of a Fitted Mortality Law

Description

Returns the deviance of a "MortalityLaw" fit. For a fit entered from death counts and exposures (Dx, Ex) it is the Poisson deviance, the quantity opt.method = "poissonL" minimises. For a fit entered from rates (mx or qx) there is no count likelihood, so it is the sum of squared log-residuals.

Usage

## S3 method for class 'MortalityLaw'
deviance(object, ...)

Arguments

Value

The deviance for a single fit, or a named vector of deviances for a multiple fit.

See Also

MortalityLaw; dispersion.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"],
                   law = "makeham", opt.method = "poissonL")
deviance(M1)

Extract the Residual Degrees of Freedom of a Fitted Mortality Law

Description

Returns the residual degrees of freedom of a "MortalityLaw" fit, the number of fitted ages minus the number of estimated parameters.

Usage

## S3 method for class 'MortalityLaw'
df.residual(object, ...)

Arguments

Value

The residual degrees of freedom for a single fit, or a named vector for a multiple fit.

See Also

MortalityLaw; dispersion.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"],
                   law = "makeham", opt.method = "poissonL")
df.residual(M1)

Dispersion of a Fitted Mortality Law

Description

Returns the dispersion of the fit, a scalar measure of how far the fitted values spread around the data. For the count cases it is the Pearson chi-square divided by the residual degrees of freedom, the GLM dispersion (about 1 for a correctly specified Poisson model); for the rate cases it is the mean squared log-residual. The value is also reported by summary.MortalityLaw.

Usage

dispersion(object, ...)

## S3 method for class 'MortalityLaw'
dispersion(object, ...)

Arguments

Value

The dispersion for a single fit, or a named vector of dispersions for a multiple fit.

See Also

MortalityLaw; deviance.MortalityLaw.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"],
                   law = "makeham", opt.method = "poissonL")
dispersion(M1)

Gamma-Gompertz Model - 1979

Description

The Gamma-Gompertz hazard, the marginal hazard of a Gompertz population with Gamma-distributed frailty; the frailty produces the old-age levelling-off.

Usage

ggompertz(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

ggompertz(x = 50:120)

Gompertz Mortality Law - 1825

Description

The exponential rise of mortality with age, the classic adult and old-age law. The hazard is unbounded, so fit it over the adult ages.

Usage

gompertz(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

gompertz(x = 45:90)

Gompertz Mortality Law - informative parameterization

Description

The Gompertz hazard in terms of its mode M and dispersion \sigma, \mu_x = (1/\sigma) \exp((x - M)/\sigma); the same curve as gompertz with coefficients that read off the plot.

Usage

gompertz0(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

gompertz0(x = 45:90)

Gompertz Log-Quadratic Mortality Law (GM(0,3)) - 1988

Description

The generalised Gompertz-Makeham formula without the Makeham constant: a Gompertz whose log hazard is quadratic, \mu_x = K \exp(B_1 x - B_2 x^2). It is the GM(0, 3) member of the family and the log-quadratic law used to test for deceleration in old age; prefer it when background mortality is negligible and the constant of makeham_logquad is not wanted. SIGN IS A CHOICE, as in makeham_logquad: only the decelerating branch is reachable.

Usage

gompertz_logquad(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

gompertz_logquad(x = 0:100)

Inverse-Gompertz Mortality Law - informative parameterization

Description

The inverse-Gompertz hazard, which falls with age; it describes the decline of mortality after the infant peak.

Usage

invgompertz(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

invgompertz(x = 15:25)

Inverse-Weibull Mortality Law

Description

The inverse-Weibull hazard; useful for childhood and the teenage years, where the logarithm of the hazard is concave.

Usage

invweibull(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

invweibull(x = 1:20)

Kannisto Mortality Law - 1998

Description

The Kannisto logistic hazard, which rises like Gompertz and levels off at a ceiling of one; the field standard for closing a life table at old age (see the close and omega arguments of LifeTable).

Usage

kannisto(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

kannisto(x = 85:120)

Kannisto-Makeham Mortality Law - 1998

Description

The Kannisto logistic hazard plus a constant, for the age-independent component above the logistic ceiling.

Usage

kannisto_makeham(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

kannisto_makeham(x = 85:120)

Kostaki Model - 1992

Description

A nine-parameter Heligman-Pollard variant whose accident-hump term has two dispersion parameters, one either side of a cut age, so the hump can be asymmetric.

Usage

kostaki(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

kostaki(x = 0:100)

Extract the Log-Likelihood of a Fitted Mortality Law

Description

Returns the maximised log-likelihood of a "MortalityLaw" fit. It is only defined when the objective was a likelihood, that is when the model was fitted with opt.method = "poissonL" or "binomialL"; for the loss-function objectives the value is NaN. For a multiple fit the log-likelihoods are returned as a named vector.

Usage

## S3 method for class 'MortalityLaw'
logLik(object, ...)

Arguments

Value

An object of class "logLik" for a single fit, or a named numeric vector of log-likelihoods for a multiple fit.

See Also

MortalityLaw; AIC.MortalityLaw.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"],
                   law = "makeham", opt.method = "poissonL")
logLik(M1)

Makeham Mortality Law - 1860

Description

The Gompertz hazard plus a constant, \mu_x = A \exp(Bx) + C, so that the age-independent component of mortality is represented too.

Usage

makeham(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

makeham(x = 45:90)

Makeham Mortality Law - informative parameterization

Description

The Makeham hazard with the exponential term in mode/dispersion form, \mu_x = (1/\sigma) \exp((x - M)/\sigma) + C.

Usage

makeham0(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

makeham0(x = 45:90)

Makeham Log-Quadratic Mortality Law (GM(1,3)) - 1988

Description

The generalised Gompertz-Makeham graduation formula of Forfar, McCutcheon and Wilkie: a Makeham constant plus a Gompertz whose log hazard carries a quadratic term, \mu_x = A_0 + K \exp(B_1 x - B_2 x^2). The quadratic term bends the exponential rise downward, so the hazard decelerates at the oldest ages. This is the family UK pensioner tables are graduated with (the CMI S2 and 08 series) and the best-fitting law for the Canadian CPM2014 experience. SIGN IS A CHOICE: the published fits put a negative coefficient on the square, so it is written here as -B_2 x^2 with B_2 > 0, the branch the engine's positive parameters permit; the accelerating branch is out of reach.

Usage

makeham_logquad(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

makeham_logquad(x = 0:100)

Martinelle Model - 1987

Description

A generalisation of the Perks formula for old age, with an extra linear term that lets the hazard keep some exponential rise above the logistic plateau.

Usage

martinelle(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

martinelle(x = 0:100)

Negative Gompertz Mortality Law - 1871

Description

The Gompertz hazard with a negative exponent, the hazard of a negative Gompertz distribution; proposed by Thiele for the risk of death prior to maturity, and reused by Siler.

Usage

neggompertz(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

neggompertz(x = 0:20)

Opperman Mortality Law - 1870

Description

A three-term hazard across the whole lifespan, \mu_x = A/\sqrt{x + 1} - B + C\sqrt{x + 1}, evaluated at ages shifted by one year so the term stays finite at age 0. THIS SIGN IS A CHOICE: the published form writes the middle term with a free sign (+b); the engine estimates on the log scale and so requires positivity, hence the - B (b = -B < 0) branch, which is the branch mortality data occupy. See the opperman entry of availableLaws.

Usage

opperman(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

opperman(x = 1:25)

Pareto II Mortality Law - 1954

Description

The hazard of a Pareto type II (Lomax) distribution, \mu_x = A / (x + C); a shifted power hazard with the exponent fixed at one.

Usage

pareto_2(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

pareto_2(x = 1:20)

Perks Model - 1932

Description

The Perks logistic hazard, \mu_x = (A + B C^x) / (1 + D C^x), which flattens the Gompertz rise at the oldest ages.

Usage

perks(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

perks(x = 50:100)

Plot a Life Table

Description

Draws the classic life table figures in the house style: the survivorship l_x, the hazard m_x on a log scale, the death distribution d_x and the life expectancy e_x. When the table holds several life tables, from a matrix input or from a LawTable built on several parameter sets, each table is drawn as one curve and the legend labels the tables.

Usage

## S3 method for class 'LifeTable'
plot(x, which = c("all", "lx", "hazard", "dx", "ex"), split = NULL, ...)

Arguments

Value

The object x, invisibly. Called for the plot it draws.

Author(s)

Marius D. Pascariu

See Also

LifeTable, LawTable.

Examples

x  <- as.numeric(rownames(ahmd$mx))
LT <- LifeTable(x = x, mx = ahmd$mx[, c("1950", "2010")])
plot(LT)
plot(LT, which = "lx")
plot(LT, split = c(1, 4))

Plot a Fitted Mortality Law

Description

Draws the figures of a "MortalityLaw" fit in the house style. The fit chart puts the observed and the fitted mortality on a log scale, with the fitted age range shaded and a goodness-of-fit subtitle. The residual diagnostics give the deviance residuals against age and against the fitted values, each with a band of two standard deviations and a lowess smooth, plus a normal Q-Q plot and the residual distribution with a normal density.

Usage

## S3 method for class 'MortalityLaw'
plot(x, which = c("both", "fit", "diagnostics"), split = NULL, ...)

Arguments

Value

The object x, invisibly. Called for the figures it draws.

Author(s)

Marius D. Pascariu

See Also

MortalityLaw.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"], law = "makeham")
plot(M1, which = "fit")
plot(M1, which = "diagnostics")
plot(M1, which = "diagnostics", split = c(1, 4))
plot(M1, which = "both")

Plot a Life Table Indicator Conversion

Description

Draws the result of convertFx in the house style: the input indicator in one panel and the converted output indicator in the other, sharing the age axis when they are stacked. Rates and probabilities (mx, qx) go on a log scale. A matrix input draws one curve per column in both panels.

Usage

## S3 method for class 'convertFx'
plot(x, split = NULL, ...)

Arguments

Value

The object x, invisibly. Called for the plot it draws.

Author(s)

Marius D. Pascariu

See Also

convertFx.

Examples

# convert death rates (mx) to life expectancies (ex)
x  <- 0:105
mx <- ahmd$mx[paste(x), "2010"]
ex <- convertFx(x = x, data = mx, from = "mx", to = "ex")
plot(ex)
plot(ex, split = c(2, 1))

# convert life expectancy (ex) to 1-year probability of dying (qx)
qx <- convertFx(x = x, data = ex, from = "ex", to = "qx")
plot(qx)

Predict from a Fitted Mortality Law

Description

Evaluates a fitted mortality law at new ages. The coefficients are reused as they are, so the prediction is an extrapolation of the fitted curve: it is meaningful over the ages that the law describes and becomes unreliable far outside the fitted range. Models that scale the age vector during fitting (the SCALE_X column of availableLaws) are rescaled internally, so the prediction stays consistent with the coefficients.

Usage

## S3 method for class 'MortalityLaw'
predict(object, x, ...)

Arguments

Value

A named vector of predicted mortality values for a single fit, or a matrix with one column per fit. The values are hazards (mu[x]) or death probabilities (q[x]), depending on the law; see the FIT column of availableLaws.

Author(s)

Marius D. Pascariu

See Also

MortalityLaw; fitted.

Examples

# Extrapolate old-age mortality with the Kannisto model
# Fit ages 80-94 and extrapolate up to 120.

Mx <- ahmd$mx[paste(80:94), "1950"]
M1 <- MortalityLaw(x = 80:94, mx  = Mx, law = 'kannisto')
fitted(M1)
predict(M1, x = 80:120)

# See more examples in MortalityLaw function help page.

Print a Life Table

Description

Prints a life table in a readable form: a header with the type (full or abridged), the number of tables and the age intervals, then the first and the last rows of every column, with the middle rows elided.

Usage

## S3 method for class 'LifeTable'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

LifeTable.

Print a Fitted Mortality Law

Description

Prints a compact one-line description of a "MortalityLaw" object: the law that was fitted and whether the fitted values are hazards (mx) or death probabilities (qx).

Usage

## S3 method for class 'MortalityLaw'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

MortalityLaw to fit a law; summary.MortalityLaw for the full diagnostic summary.

Print a ReadAHMD Object

Description

Prints the header of an AHMD download (web address, download date, data type, interval, year and age coverage, regions) followed by the first and the last rows of the data.

Usage

## S3 method for class 'ReadAHMD'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

ReadAHMD.

Print a ReadCHMD Object

Description

Prints the header of a CHMD download (web address, download date, data type, interval, year and age coverage, regions) followed by the first and the last rows of the data.

Usage

## S3 method for class 'ReadCHMD'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

ReadCHMD.

Print a ReadHMD Object

Description

Prints the header of an HMD download (web address, account, download date, data type, interval, year and age coverage, countries) followed by the first and the last rows of the data.

Usage

## S3 method for class 'ReadHMD'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

ReadHMD.

Print a ReadJMD Object

Description

Prints the header of a JMD download (web address, download date, data type, interval, year and age coverage, regions) followed by the first and the last rows of the data.

Usage

## S3 method for class 'ReadJMD'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

ReadJMD.

Print Available Loss Functions

Description

Prints the table of loss functions and their codes, with the legend that explains the notation, followed by a short note on choosing between them.

Usage

## S3 method for class 'availableLF'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

Print the Available Mortality Laws

Description

Prints the catalogue of mortality laws (year, name, model formula, type and code) followed by the legend that explains the type numbers.

Usage

## S3 method for class 'availableLaws'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

availableLaws.

Print a Converted Life Table Indicator

Description

Prints the conversion that produced the object and the converted values.

Usage

## S3 method for class 'convertFx'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

convertFx.

Print a MortalityLaw Summary

Description

Prints the contents of a "summary.MortalityLaw" object: the model description, the fit window, the matched call, the coefficients, the fit measures (method and optimiser outcome, deviance, R-squared and RMSE, and for likelihood-based fits the goodness-of-fit block) and the residuals on the raw and the deviance scale.

Usage

## S3 method for class 'summary.MortalityLaw'
print(x, ...)

Arguments

Value

The object x, invisibly. Called for its printed output.

See Also

summary.MortalityLaw.

Quadratic Model

Description

A plain quadratic hazard, \mu_x = A + Bx + Cx^2; a smooth baseline over the adult ages that cannot level off at the oldest ages.

Usage

quadratic(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

quadratic(x = 0:100)

Rogers-Planck Model - 1983

Description

A parametric whole-lifespan schedule with infancy, middle-age hump and old- age terms, developed for model life tables.

Usage

rogersplanck(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

rogersplanck(x = 0:100)

Scholey Mortality Law - 2019

Description

The Scholey exponentially-truncated power hazard, \mu_x = A (x + C)^{-B} \exp(-Dx), the best-fitting parametric form on his day-level US infant data; it nests the negative Gompertz, Pareto II, shifted power and shifted Weibull hazards. AGE RESOLUTION MATTERS: D is identified only on day- or week-level data over the first year; on single years of age it collapses to the boundary and the fit reduces to scholey_shifted_power, in which case the engine warns.

Usage

scholey(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

scholey(x = seq(0, 1, by = 1/12))

Shifted Power Mortality Law - 2019

Description

The Scholey flexibly-shifted power hazard, \mu_x = A (x + C)^{-B}; a shifted Weibull hazard, and the truncated-power law with the exponential term switched off.

Usage

scholey_shifted_power(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

scholey_shifted_power(x = 0:10)

Siler Mortality Law - 1979

Description

A three-term competing-risks hazard: a declining infancy term, a constant background term and a rising old-age term.

Usage

siler(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

siler(x = 0:100)

Steffensen Model - 1930

Description

The Perks hazard with an extra B*C^-x denominator term that peaks at birth and decays geometrically, so the hazard is dampened at young ages and converges to Perks at old ages. ATTRIBUTION IS UNVERIFIED: the citation to Steffensen (1930) is real, but whether the 1930 text contains this form is not (the scan is paywalled), so it is documented as attributed.

Usage

steffensen(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

steffensen(x = 0:100)

Strehler-Mildvan Model - 1960

Description

The Strehler-Mildvan form, from a model of declining vitality with age; it predicts a negative intercept-slope correlation across populations.

Usage

strehler_mildvan(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

strehler_mildvan(x = 30:85)

Summarise a Fitted Mortality Law

Description

Collects the fitted coefficients, the fit measures and a summary of the residuals into a compact object for printing, and rounds them to digits. The fit measures cover the fit window (the ages fitted and the ages reported), the optimisation (method used, optimiser outcome), the deviance with its degrees of freedom and dispersion, and the R-squared and RMSE of the fit. For a likelihood-based fit the maximised log-likelihood with its information criteria is included. When more than four curves were fitted only the first and the last two are kept in the printed coefficients and fit measures, so the output fits on one screen.

Usage

## S3 method for class 'MortalityLaw'
summary(object, ..., digits = max(3L, getOption("digits") - 3L))

Arguments

Value

An object of class "summary.MortalityLaw", a list holding the model information, the matched call, the rounded coefficients, the goodness-of-fit measures, the deviance and the degrees of freedom, the R-squared and RMSE of the fit, the optimisation outcome, the fit window and the residual summaries on the raw and the deviance scale.

See Also

MortalityLaw to fit a law; coef and fitted for the extracted values.

Examples

x  <- 45:75
M1 <- MortalityLaw(x = x, Dx = ahmd$Dx[as.character(x), "1950"],
                   Ex = ahmd$Ex[as.character(x), "1950"], law = "makeham")
summary(M1)

Thiele Mortality Law - 1871

Description

A three-component hazard over the whole lifespan: a declining infancy term, a Gaussian accident hump and a rising old-age term.

Usage

thiele(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

thiele(x = 0:100)

Van der Maen Model - 1943

Description

A quadratic hazard with a reciprocal closing term, \mu_x = A + Bx + Cx^2 + I/(N - x), so the table can close at a finite age N.

Usage

vandermaen(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

vandermaen(x = 0:100)

Van der Maen 2 Model - 1943

Description

The linear form of the Van der Maen hazard with the same reciprocal closing term, \mu_x = A + Bx + I/(N - x).

Usage

vandermaen2(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

vandermaen2(x = 0:100)

Weibull Mortality Law - 1939

Description

The Weibull hazard; increasing when \sigma < M, non-increasing otherwise. NOT DEFINED AT BIRTH: the hazard is 0 when the shape is greater than one and unbounded when it is smaller, so age 0 is reported as missing and carries no weight in the fit; fit the law from age 1.

Usage

weibull(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

weibull(x = 1:20)

Wittstein Mortality Law - 1883

Description

A two-term law giving a death probability rather than a hazard, q_x = (1/B) A^{-(Bx)^N} + A^{-(M - x)^N}, so it covers both ends of the lifespan.

Usage

wittstein(x, par = NULL)

Arguments

Value

A list of rates and model parameters.

Examples

wittstein(x = 0:100)