Type: Package
Title: The Double-Gap Life Expectancy Forecasting Model
Version: 1.0.7
Description: Life expectancy is highly correlated over time among countries and between males and females. These associations can be used to improve forecasts. Here we have implemented a method for forecasting female life expectancy based on analysis of the gap between female life expectancy in a country compared with the record level of female life expectancy in the world. Second, to forecast male life expectancy, the gap between male life expectancy and female life expectancy in a country is analysed. We named this method the Double-Gap model. For a detailed description of the method see Pascariu et al. (2018). <doi:10.1016/j.insmatheco.2017.09.011>.
License: GPL-3
LazyData: TRUE
Depends: R (≥ 3.4.0)
Imports: forecast (≥ 8.4), MASS (≥ 7.3), crch (≥ 1.0), pbapply (≥ 1.3), Rdpack (≥ 0.9-0)
Suggests: MortalityLaws (≥ 1.6.0), knitr (≥ 1.20), rmarkdown (≥ 1.10), testthat (≥ 2.0.0), covr (≥ 3.1.0)
RdMacros: Rdpack
RoxygenNote: 7.3.2
Encoding: UTF-8
VignetteBuilder: knitr
URL: https://github.com/mpascariu/MortalityGaps
BugReports: https://github.com/mpascariu/MortalityGaps/issues
NeedsCompilation: no
Packaged: 2025-04-02 06:03:48 UTC; dump_
Author: Marius D. Pascariu ORCID iD [aut, cre]
Maintainer: Marius D. Pascariu <rpascariu@outlook.com>
Repository: CRAN
Date/Publication: 2025-04-02 06:30:02 UTC

MortalityGaps: The Double-Gap Life Expectancy Forecasting Model

Description

Life expectancy is highly correlated over time among countries and between males and females. These associations can be used to improve forecasts. Here we have implemented a method for forecasting female life expectancy based on analysis of the gap between female life expectancy in a country compared with the record level of female life expectancy in the world. Second, to forecast male life expectancy, the gap between male life expectancy and female life expectancy in a country is analysed. We named this method the Double-Gap model. For a detailed description of the method see Pascariu et al. (2018). doi:10.1016/j.insmatheco.2017.09.011.

Details

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

Author(s)

Maintainer: Marius D. Pascariu rpascariu@outlook.com (ORCID)

References

Human Mortality Database (2017). “University of California, Berkeley (USA), and Max Planck Institute for Demographic Research (Germany). Data downloaded on 10/06/2017.” https://www.mortality.org.

Pascariu MD (2018). MortalityLaws: Parametric Mortality Models, Life Tables and HMD. R package version 1.6.0, https://github.com/mpascariu/MortalityLaws.

Pascariu MD, Canudas-Romo V, Vaupel JW (2018). “The double-gap life expectancy forecasting model.” Insurance: Mathematics and Economics, 78, 339–350. doi:10.1016/j.insmatheco.2017.09.011.

See Also

Useful links:


Fit the Double-Gap Life Expectancy Forecasting Model

Description

Fit a Double-Gap model for forecasting life expectancy. The method combines separate forecasts to obtain joint male and female life expectancies that are coherent with a best-practice trend. See the entire description and mathematical formulation of the model in Pascariu et al. (2018)

Usage

DoubleGap(
  DF,
  DM,
  age,
  country,
  years,
  arima.order = NULL,
  drift = NULL,
  tau = NULL,
  A = NULL
)

Arguments

DF

data.frame containing life expectancy records for females. The table must contain the following 4 columns: country, year, age, ex.

DM

data.frame containing life expectancy records for males. The table must have the same format and dimensions as DF.

age

Indicate the age for which the model to be fitted. Assuming DF and DM contain records for different ages, this argument it is used to subset the data. If you want to fit the model for age 0, add age = 0. Type: scalar.

country

Indicate for which country you want to fit the model. The country name or code must exist in DF and DM. Type: character.

years

Period of time to be used. Type: numeric vector.

arima.order

A specification of the the ARIMA model to be used in fitting the best-practice gap. The ARIMA order is country specific. The three integer components (p, d, q) are the AR order, the degree of differencing, and the MA order. Format: numerical vector of length 3. If arima.order = NULL the function conducts a search over possible models according to AIC. See auto.arima for details.

drift

Indicate whether the ARIMA model should include a linear drift term or not. Type: logical value. If drift = NULL, it will be estimate automatically.

tau

The level of female life expectancy at which the sex-gap is expected to stop widening and to start narrowing. If NULL then the model will run an algorithm to find it.

A

The level of female life expectancy where we assume no further change in the sex-gap. If NULL the model will estimate it.

Value

The output is of class DoubleGap with the components:

input

List with arguments provided in input. Saved for convenience.

call

An unevaluated function call, that is, an unevaluated expression which consists of the named function applied to the given arguments.

coefficients

Estimated coefficients.

fitted.values

Fitted values of the selected model.

observed.values

Country specific observed values obtained from input data. This is a data.frame containing information about female, male and best-practice life expectancy measures over time, together with associated gaps in life expectancy.

model.parts

Object containing detailed results of the fitted model.

residuals

Deviance residuals.

Author(s)

Marius D. Pascariu

References

Pascariu MD, Canudas-Romo V, Vaupel JW (2018). “The double-gap life expectancy forecasting model.” Insurance: Mathematics and Economics, 78, 339–350. doi:10.1016/j.insmatheco.2017.09.011.

See Also

predict.DoubleGap

Examples

# Input data ------------------------------------
# Collection of life expectancies for female populations
exF <- MortalityGaps.data$exF
# Life expectancy for male populations
exM <- MortalityGaps.data$exM

# Example 1 ----------------------------------------------
# Fit DG model at age 0 for Australia using data from 1950 to 2014
M0 <- DoubleGap(DF = exF,
                DM = exM,
                age = 0,
                country = "AUS",
                years = 1950:2014)
M0
summary(M0)
ls(M0)

# Forecast life expectancy in Australia until 2030
P0 <- predict(M0, h = 16)
P0
# Plot the results
plot(P0)

## Not run: 
# Example 2 ----------------------------------------------
# Fit DG model at age 0 for Sweden. Provide details about models.
# Reproduce published results in the article.
M1 <- DoubleGap(DF = exF, 
                DM = exM, 
                age = 0, 
                country = "SWE", 
                years = 1950:2014, 
                arima.order = c(2, 1, 1), 
                drift = TRUE, 
                tau = 75, 
                A = 86)
summary(M1)
# Predict model 
P1 <- predict(M1, h = 36)
plot(P1)

# Example 3 ----------------------------------------------
# Fit DG model for USA at age 65.
M2 <- DoubleGap(DF = exF, 
                DM = exM, 
                age = 65, 
                country = "USA", 
                years = 1950:2014, 
                arima.order = c(0, 1, 0), 
                drift = FALSE, 
                tau = 15, 
                A = 24)
summary(M2)
# Predict model 
P2 <- predict(M2, h = 36)
plot(P2)

## End(Not run)

DATA - for testing purposes

Description

Dataset containing records of life expectancy at birth and at age 65 for female and male populations living in 38 countries between 1950 and 2014. This dataset is used in Pascariu et al. (2018) article. The data is provided in the package for testing purposes and to ensure the reproducibility of the results and figures published in the article. By the time you are using this package, the data might be outdated. Download actual demographic data free of charge from Human Mortality Database (2017). Once a username and a password is created on the website the MortalityLaws R package can be used to extract data directly into your R console.

Usage

MortalityGaps.data

Format

An object of class MortalityGaps.data of length 2.

Source

Human Mortality Database

References

Human Mortality Database (2017). “University of California, Berkeley (USA), and Max Planck Institute for Demographic Research (Germany). Data downloaded on 10/06/2017.” https://www.mortality.org.

Pascariu MD (2018). MortalityLaws: Parametric Mortality Models, Life Tables and HMD. R package version 1.6.0, https://github.com/mpascariu/MortalityLaws.

Pascariu MD, Canudas-Romo V, Vaupel JW (2018). “The double-gap life expectancy forecasting model.” Insurance: Mathematics and Economics, 78, 339–350. doi:10.1016/j.insmatheco.2017.09.011.

See Also

ReadHMD


Time series model for the best-practice gap

Description

Time series model for the best-practice gap

Usage

bp_gap.model(X, benchmark, arima.order, drift)

Arguments

X

Input data object generated by prepare_data function.

benchmark

Fitted values given by BP linear model.

arima.order

A specification of the the ARIMA model to be used in fitting the best-practice gap. The ARIMA order is country specific. The three integer components (p, d, q) are the AR order, the degree of differencing, and the MA order. Format: numerical vector of length 3. If arima.order = NULL the function conducts a search over possible models according to AIC. See auto.arima for details.

drift

Indicate whether the ARIMA model should include a linear drift term or not. Type: logical value. If drift = NULL, it will be estimate automatically.


Function to generate correlated prediction intervals from a mvrnorm

Description

Function to generate correlated prediction intervals from a mvrnorm

Usage

compute_CI(pred_results, M1, M2, M3, h, iter, ci, cou)

Arguments

pred_results

An object containing predicted values

M1

Model 1 - Linear regression bp-life-expectancy.

M2

Model 2 - Time-series D-gap.

M3

Model 3 - Sex-gap.

h

The number of steps ahead for which prediction is required.

iter

Number of iterations. Default: 500

ci

Confidence levels. Default: c(0.8, 0.95)

cou

Country name.


Find the fitted values of the Double-Gap model

Description

Find the fitted values of the Double-Gap model

Usage

find_fitted_values(M1, M2, M3)

Arguments

M1

Model 1 - Linear regression bp-life-expectancy.

M2

Model 2 - Time-series D-gap.

M3

Model 3 - Sex-gap.


Find the observed values (from input data). Format.

Description

Find the observed values (from input data). Format.

Usage

find_observed_values(X)

Arguments

X

Input data object generated by prepare_data function.


Find record life expectancy at age x given a set of life tables

Description

Find record life expectancy at age x given a set of life tables

Usage

find_record_ex(X)

Arguments

X

Data-set containing ex records for female and male populations.


Function to find the value of tau

Description

Function to find the value of female life expectancy where the sex-gap is no longer expanding (tau). This method is slightly different than the one indicated in the original paper (likelihood). The main advantage: speed.

Usage

find_tau(X, a = 1.05, f = 0.5)

Arguments

X

Input data object generated by prepare_data function.

a

Adjustment factor for maximum female life expectancy.

f

the smoother span. This gives the proportion of points in the plot which influence the smooth at each value. Larger values give more smoothness.


Generic Plot Function for Class predict.DoubleGap

Description

Generic Plot Function for Class predict.DoubleGap

Usage

## S3 method for class 'predict.DoubleGap'
plot(
  x,
  show.legend = TRUE,
  ylim = NULL,
  asp = 1.8,
  xlab = "\nYear",
  ylab = "\nLife Expectancy Level",
  ...
)

Arguments

x

An object of class predict.DoubleGap

show.legend

Logical. Indicate whether to display the legend or not. Default: TRUE.

ylim

Numeric vectors of length 2, giving the x and y coordinates ranges.

asp

Numeric, giving the aspect ratio y/x.

xlab

A title for the x axis: see title.

ylab

A title for the y axis: see title.

...

Further graphical parameters as in par.

Author(s)

Marius D. Pascariu

See Also

DoubleGap

Examples

# Complete examples are provided in help page of the DoubleGap function.

Generic Predict Function for Class DoubleGap

Description

Predict DoubleGap model

Usage

## S3 method for class 'DoubleGap'
predict(object, h, iter = 500, ci = c(0.8, 0.95), ...)

Arguments

object

An object of class DoubleGap.

h

Number of periods for forecasting.

iter

Number of iterations. Default: 500

ci

Confidence levels. Default: c(0.8, 0.95)

...

Additional arguments affecting the predictions produced.

Value

A list containing predicted value of best-practice life expectancy, best-practice gap, sex gap, and forecast life expectancy for females and males (together with prediction intervals).

Author(s)

Marius D. Pascariu

See Also

DoubleGap

Examples

# Complete examples are provided in help page of the DoubleGap function.

The role of this function is to prepare data in such a way that is ready to use right away in the other functions.

Description

The role of this function is to prepare data in such a way that is ready to use right away in the other functions.

Usage

prepare_data(data)

Arguments

data

Input data from DoubleGap function.


Prepare additional data in order to perform predictions

Description

Prepare additional data in order to perform predictions

Usage

prepare_data_for_prediction(object, h, iter, ci)

Arguments

object

An object of class DoubleGap.

h

Number of periods for forecasting.

iter

Number of iterations. Default: 500

ci

Confidence levels. Default: c(0.8, 0.95)


Print DoubleGap

Description

Print DoubleGap

Usage

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

Arguments

x

Object of class DoubleGap.

...

Further arguments passed to or from other methods.


Print function for HMD4mx data

Description

Print function for HMD4mx data

Usage

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

Arguments

x

A MortalityEstimateData object.

...

Further arguments passed to or from other methods.


Print function for predict.DoubleGap

Description

Print function for predict.DoubleGap

Usage

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

Arguments

x

An object of class predict.DoubleGap.

...

Further arguments passed to or from other methods.


Print summary

Description

Print summary

Usage

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

Arguments

x

Object of class DoubleGap.

...

Further arguments passed to or from other methods.


Fit sex-gap model. This is a modified version of the Raftery linear model for sex differences in life expectancy. This is kind of a AR(2)-X sex_gap ~ sex_gap1 + sex_gap2 + narrow_level

Description

Fit sex-gap model. This is a modified version of the Raftery linear model for sex differences in life expectancy. This is kind of a AR(2)-X sex_gap ~ sex_gap1 + sex_gap2 + narrow_level

Usage

sex_gap.model(X, tau, A)

Arguments

X

Input data object generated by prepare_data function.

tau

The level of female life expectancy at which the sex-gap is expected to stop widening and to start narrowing. If NULL then the model will run an algorithm to find it.

A

The level of female life expectancy where we assume no further change in the sex-gap. If NULL the model will estimate it.


Summary DoubleGap

Description

Summary DoubleGap

Usage

## S3 method for class 'DoubleGap'
summary(object, ...)

Arguments

object

Object of class DoubleGap

...

Further arguments passed to or from other methods.