Version:	2.0.0
Type:	Package
Title:	Tidy Analysis Tools for Mortality, Fertility, Migration and Population Data
Description:	Analysing vital statistics based on tools consistent with the tidyverse. Tools are provided for data visualization, life table calculations, computing net migration numbers, Lee-Carter modelling; functional data modelling and forecasting.
Depends:	R (≥ 4.1.0)
Imports:	cobs, distributional, dplyr, fable, fabletools (≥ 0.3.3), ggplot2, HMDHFDplus (≥ 2.0.3), mgcv, MortalityLaws, patchwork, purrr, rlang, StMoMo, tibble, tidyr, tidyselect, tsibble, vctrs
Suggests:	demography, feasts, future, future.apply, knitr, progressr, rmarkdown, testthat (≥ 3.0.0)
License:	GPL-3
URL:	https://pkg.robjhyndman.com/vital/, https://github.com/robjhyndman/vital
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.2
BugReports:	https://github.com/robjhyndman/vital/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-08-20 06:26:44 UTC; hyndman
Author:	Rob Hyndman [aut, cre, cph], Sixian Tang [aut], Miles McBain [ctb], Mitchell O'Hara-Wild [ctb]
Maintainer:	Rob Hyndman <Rob.Hyndman@monash.edu>
Repository:	CRAN
Date/Publication:	2025-08-20 07:40:02 UTC

vital: Tidy Analysis Tools for Mortality, Fertility, Migration and Population Data

Description

Analysing vital statistics based on tools consistent with the tidyverse. Tools are provided for data visualization, life table calculations, computing net migration numbers, Lee-Carter modelling; functional data modelling and forecasting.

Author(s)

Maintainer: Rob Hyndman Rob.Hyndman@monash.edu (ORCID) [copyright holder]

Authors:

• Sixian Tang (ORCID)

Other contributors:

• Miles McBain (ORCID) [contributor]

• Mitchell O'Hara-Wild (ORCID) [contributor]

See Also

Useful links:

• https://pkg.robjhyndman.com/vital/

• https://github.com/robjhyndman/vital

• Report bugs at https://github.com/robjhyndman/vital/issues

Functional data model

Description

Functional data model of mortality or fertility rates as a function of age. FDM() returns a functional data model applied to the formula's response variable as a function of age.

Usage

FDM(formula, order = 6, ts_model_fn = fable::ARIMA, coherent = FALSE, ...)

Arguments

Value

A model specification.

Author(s)

Rob J Hyndman

References

Hyndman, R. J., and Ullah, S. (2007) Robust forecasting of mortality and fertility rates: a functional data approach. Computational Statistics & Data Analysis, 5, 4942-4956. https://robjhyndman.com/publications/funcfor/

Hyndman, R. J., Booth, H., & Yasmeen, F. (2013). Coherent mortality forecasting: the product-ratio method with functional time series models. Demography, 50(1), 261-283. https://robjhyndman.com/publications/coherentfdm/

Examples

hu <- norway_mortality |>
  dplyr::filter(Sex == "Female", Year > 2010) |>
  smooth_mortality(Mortality) |>
  model(hyndman_ullah = FDM(log(.smooth)))
report(hu)
autoplot(hu)

Functional mean model

Description

FMEAN() returns an iid functional model applied to the formula's response variable as a function of age.

Usage

FMEAN(formula, ...)

Arguments

Value

A model specification.

Author(s)

Rob J Hyndman

Examples

fmean <- norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(mean = FMEAN(Mortality))
report(fmean)
autoplot(fmean) + ggplot2::scale_y_log10()

Functional naive model

Description

FNAIVE() returns an random walk functional model applied to the formula's response variable as a function of age.

Usage

FNAIVE(formula, ...)

Arguments

Value

A model specification.

Author(s)

Rob J Hyndman

Examples

fnaive <- norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(fit = FNAIVE(Mortality))
report(fnaive)
autoplot(fnaive) + ggplot2::scale_y_log10()

Generalized APC stochastic mortality model

Description

A Generalized Age-Period-Cohort (GAPC) stochastic mortality mode is defined in Villegas et al. (2018). The StMoMo package is used to fit the model. Separate functions are available to fit various special cases of the GAPC model.

Usage

GAPC(formula, use_weights = TRUE, clip = 0, zeroCohorts = NULL, ...)

LC2(
  formula,
  link = c("log", "logit"),
  const = c("sum", "last", "first"),
  use_weights = TRUE,
  clip = 0,
  zeroCohorts = NULL,
  ...
)

CBD(
  formula,
  link = c("log", "logit"),
  use_weights = TRUE,
  clip = 0,
  zeroCohorts = NULL,
  ...
)

RH(
  formula,
  link = c("log", "logit"),
  cohortAgeFun = c("1", "NP"),
  use_weights = TRUE,
  clip = 0,
  zeroCohorts = NULL,
  ...
)

APC(
  formula,
  link = c("log", "logit"),
  use_weights = TRUE,
  clip = 0,
  zeroCohorts = NULL,
  ...
)

M7(
  formula,
  link = c("log", "logit"),
  use_weights = TRUE,
  clip = 0,
  zeroCohorts = NULL,
  ...
)

PLAT(
  formula,
  link = c("log", "logit"),
  use_weights = TRUE,
  clip = 0,
  zeroCohorts = NULL,
  ...
)

Arguments

Details

LC2() provides an alternative implementation of the Lee-Carter model based on a GAPC specification. The advantage of this approach over LC() is that it allows for 0 rates in the mortality data. Note that it does not return identical results to LC() because the model formulation is different. For LC2(), do not take logs of the mortality rates because this is handled with the link function. For LC(), you need to take logs of the mortality rates when calling the function.

The Renshaw-Haberman (RH) model due to Renshaw and Haberman (2006) is another special case of a GAPC model, that can be considered an extension of a Lee-Carter model with an age-specific cohort effect.

The Age-Period-Cohort (APC) model is a special case of a GAPC model discussed by Renshaw and Haberman (2011).

The Cairns-Blake-Dowd (CBD) model due to Cairns et al (2006) can be considered another special case of a GAPC model that is primarily intended for forecasting mortality patterns in older populations.

Cairns et al (2009) extended the CBD model by adding a cohort effect and a quadratic age effect, giving the M7 model.

Plat (2009) combined the CBD model with some features of the Lee-Carter model to produce a model that is suitable for full age ranges and captures the cohort effect.

Each of these functions returns a GAPC model applied to the formula's response variable as a function of age. The model will optionally call genWeightMat with arguments clip and zeroCohorts. All other arguments are passed to StMoMo.

Value

A model specification.

Author(s)

Rob J Hyndman

References

Cairns, AJG, Blake, D, and Dowd, K (2006). A two-factor model for stochastic mortality with parameter uncertainty: Theory and calibration. Journal of Risk and Insurance, 73(4), 687-718. doi:10.1111/j.1539-6975.2006.00195.x

Cairns AJG, Blake D, Dowd K, Coughlan GD, Epstein D, Ong A, Balevich I (2009). A quantitative comparison of stochastic mortality models using data from England and Wales and the United States. North American Actuarial Journal, 13(1), 1–35. doi:10.1080/10920277.2009.10597538

Lee, RD, and Carter, LR (1992) Modeling and forecasting US mortality. Journal of the American Statistical Association, 87, 659-671. doi:10.1080/01621459.1992.10475265

Plat R (2009). On stochastic mortality modeling. Insurance: Mathematics and Economics, 45(3), 393–404. doi:10.1016/j.insmatheco.2009.08.006

Renshaw, AE, and Haberman, S (2006). A cohort-based extension to the Lee-Carter model for mortality reduction factors. Insurance: Mathematics and Economics, 38(3), 556-570. doi:10.1016/j.insmatheco.2005.12.001

Renshaw, AE, and Haberman, S (2011). A comparative study of parametric mortality projection models. Insurance: Mathematics and Economics, 48(1), 35–55. <doi:10.1016/j. insmatheco.2010.09.003>

Villegas, AM, Millossovich, P, and Kaishev, VK (2018). StMoMo: An R package for stochastic mortality modelling. Journal of Statistical Software, 84(3), 1-38. doi:10.18637/jss.v084.i03

See Also

LC()

Examples

# Fit the same CBD model using GAPC() and CBD()
gapc <- norway_mortality |>
  dplyr::filter(Sex == "Female", Age > 50, Year > 2000) |>
  model(
    cbd1 = GAPC(Mortality,
      link = "log",
      staticAgeFun = FALSE,
      periodAgeFun = c("1", function(x, ages) x - mean(ages))
    ),
    cbd2 = CBD(Mortality)
  )
glance(gapc)
gapc |>
  dplyr::select(cbd2) |>
  report()

Lee-Carter model

Description

Lee-Carter model of mortality or fertility rates. LC() returns a Lee-Carter model applied to the formula's response variable as a function of age. This produces a standard Lee-Carter model by default, although many other options are available. Missing rates are set to the geometric mean rate for the relevant age.

Usage

LC(
  formula,
  adjust = c("dt", "dxt", "e0", "none"),
  jump_choice = c("fit", "actual"),
  scale = FALSE,
  ...
)

Arguments

Value

A model specification.

Author(s)

Rob J Hyndman

References

Basellini, U, Camarda, C G, and Booth, H (2022) Thirty years on: A review of the Lee-Carter method for forecasting mortality. International Journal of Forecasting, 39(3), 1033-1049.

Booth, H., Maindonald, J., and Smith, L. (2002) Applying Lee-Carter under conditions of variable mortality decline. Population Studies, 56, 325-336.

Lee, R D, and Carter, L R (1992) Modeling and forecasting US mortality. Journal of the American Statistical Association, 87, 659-671.

Lee R D, and Miller T (2001). Evaluating the performance of the Lee-Carter method for forecasting mortality. Demography, 38(4), 537–549.

See Also

LC2(), FDM()

Examples

lc <- norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(lee_carter = LC(log(Mortality)))
report(lc)
autoplot(lc)

Extract age components from a model

Description

For a mable with a single model column, return the model components that are indexed by age.

Usage

age_components(object, ...)

Arguments

Value

vital object containing the age components from the model.

Examples

norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(lee_carter = LC(log(Mortality))) |>
  age_components()

Coerce to a vital object

Description

A vital object is a type of tsibble that contains vital statistics such as births, deaths, and population counts, and mortality and fertility rates. It is a tsibble with a special class that allows for special methods to be used. The object has an attribute that stores variables names needed for some functions, including age, sex, births, deaths and population.

Usage

as_vital(x, ...)

## S3 method for class 'demogdata'
as_vital(x, sex_groups = TRUE, ...)

## S3 method for class 'tbl_ts'
as_vital(
  x,
  .age = NULL,
  .sex = NULL,
  .deaths = NULL,
  .births = NULL,
  .population = NULL,
  reorder = FALSE,
  ...
)

## S3 method for class 'data.frame'
as_vital(
  x,
  key = NULL,
  index,
  .age = NULL,
  .sex = NULL,
  .deaths = NULL,
  .births = NULL,
  .population = NULL,
  reorder = TRUE,
  ...
)

Arguments

Value

A tsibble with class vital.

Author(s)

Rob J Hyndman

See Also

tsibble::tsibble()

Examples

# coerce demogdata object to vital
as_vital(demography::fr.mort)

# create a vital with only age as a key
data.frame(
  year = rep(2010:2015, 100),
  age = rep(0:99, each = 6),
  mx = runif(600, 0, 1)
) |>
  as_vital(
    index = year,
    key = age,
    .age = "age"
  )

Plot forecasts from a vital model

Description

Produces a plot showing forecasts obtained from a model applied to a vital object.

Usage

## S3 method for class 'fbl_vtl_ts'
autoplot(object, ...)

Arguments

Value

A ggplot2 object.

Author(s)

Rob J Hyndman

Examples

library(ggplot2)
norway_mortality |>
  model(ave = FMEAN(Mortality)) |>
  forecast(h = 10) |>
  autoplot() + scale_y_log10()

Plot output from a vital model

Description

Produces a plot showing a model applied to a vital object. This can be applied to one type of model only. So use select() to choose the model column to plot. If there are multiple keys, separate models will be identified by colour.

Usage

## S3 method for class 'mdl_vtl_df'
autoplot(object, ...)

Arguments

Value

A ggplot2 object.

Author(s)

Rob J Hyndman

Examples

library(ggplot2)
norway_mortality |>
  model(ave = FMEAN(Mortality)) |>
  autoplot() + scale_y_log10()

Rainbow plot of demographic data against age

Description

Produce rainbow plot (coloured by time index) of demographic variable against against age.

Usage

## S3 method for class 'vital'
autoplot(object, .vars = NULL, age = age_var(object), ...)

Arguments

Value

A ggplot2 object.

Author(s)

Rob J Hyndman

References

Hyndman, Rob J & Shang, Han Lin (2010) Rainbow plots, bagplots, and boxplots for functional data. Journal of Computational and Graphical Statistics, 19(1), 29-45. https://robjhyndman.com/publications/rainbow-fda/

Examples

autoplot(norway_fertility, Fertility)

Extract cohort components from a model

Description

For a mable with a single model column, return the model components that are indexed by birth year of the cohort.

Usage

cohort_components(object, ...)

Arguments

Value

tsibble object containing the cohort components from the model.

Examples

norway_mortality |>
  dplyr::filter(Sex == "Male", Age > 50, Year > 1960) |>
  model(apc = APC(Mortality)) |>
  cohort_components()

Collapse upper ages into a single age group. Counts are summed while rates are recomputed where possible.

Description

Collapse upper ages into a single age group. Counts are summed while rates are recomputed where possible.

Usage

collapse_ages(.data, max_age = 100)

Arguments

Details

If the object includes deaths, population and mortality rates, then deaths and population are summed and mortality rates are recomputed as deaths/population. But if the object contains mortality rates but not deaths and population, then the last rate remains unchanged (and a warning is generated).

Value

A vital object with the same variables as .data, but with the upper ages collapsed into a single age group.

Author(s)

Rob J Hyndman

Examples

norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  collapse_ages(max_age = 85)

Produce forecasts from a vital model

Description

The forecast function allows you to produce future predictions of a vital model, where the response is a function of age. The forecasts returned contain both point forecasts and their distribution.

Usage

## S3 method for class 'FDM'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  ...
)

## S3 method for class 'LC'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  ...
)

## S3 method for class 'GAPC'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  ...
)

## S3 method for class 'FMEAN'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  ...
)

## S3 method for class 'FNAIVE'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  ...
)

## S3 method for class 'mdl_vtl_df'
forecast(
  object,
  new_data = NULL,
  h = NULL,
  point_forecast = list(.mean = mean),
  simulate = FALSE,
  bootstrap = FALSE,
  times = 5000,
  ...
)

Arguments

Value

A fable containing the following columns:

• .model: The name of the model used to obtain the forecast. Taken from the column names of models in the provided mable.

• The forecast distribution. The name of this column will be the same as the dependent variable in the model(s). If multiple dependent variables exist, it will be named .distribution.

• Point forecasts computed from the distribution using the functions in the point_forecast argument.

• All columns in new_data, excluding those whose names conflict with the above.

Author(s)

Rob J Hyndman and Mitchell O'Hara-Wild

Examples

norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(naive = FNAIVE(Mortality)) |>
  forecast(h = 10)

Generate responses from a mable

Description

Use a fitted model to simulate future data with similar behaviour to the response.

Usage

## S3 method for class 'mdl_vtl_df'
generate(x, new_data = NULL, h = NULL, bootstrap = FALSE, times = 1, ...)

Arguments

Details

Innovations are sampled by the model's assumed error distribution. If bootstrap is TRUE, innovations will be sampled from the model's residuals.

Value

A vital object with simulated values.

Author(s)

Rob J Hyndman and Mitchell O'Hara-Wild

Examples

norway_mortality |>
  model(lc = LC(Mortality)) |>
  generate(times = 3, bootstrap = TRUE)

Future population simulation

Description

Simulate future age-specific population given a starting population and models for fertility, mortality, and migration. If any model is NULL, it is assumed there are no future births, deaths or net migrants, respectively. This is an experimental function and has not been thoroughly tested.

Usage

generate_population(
  starting_population,
  mortality_model = NULL,
  fertility_model = NULL,
  migration_model = NULL,
  h = 10,
  n_reps = 1000,
  female = NULL
)

Arguments

Value

A vital object containing the simulated future population.

Interpolate missing values using a vital model

Description

Uses a fitted vital model to interpolate missing values from a dataset.

Usage

## S3 method for class 'mdl_vtl_df'
interpolate(object, new_data, ...)

Arguments

Value

A vital object with missing values interpolated.

Author(s)

Rob J Hyndman

Examples

nor_female <- norway_mortality |>
  dplyr::filter(Sex == "Female")
nor_female |>
  model(mean = FMEAN(Mortality)) |>
  interpolate(nor_female)

Compute life expectancy from age-specific mortality rates

Description

Returns remaining life expectancy at a given age (0 by default).

Usage

life_expectancy(.data, from_age = 0, mortality)

Arguments

Value

A vital object with life expectancy in column ex.

Author(s)

Rob J Hyndman

References

Chiang CL. (1984) The life table and its applications. Robert E Krieger Publishing Company: Malabar.

Keyfitz, N, and Caswell, H. (2005) Applied Mathematical Demography, Springer-Verlag: New York.

Preston, S.H., Heuveline, P., and Guillot, M. (2001) Demography: measuring and modeling population processes. Blackwell

See Also

life_table()

Examples

# Compute Norwegian life expectancy for females over time
norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  life_expectancy()

Compute period life tables from age-specific mortality rates

Description

All available years and ages are included in the tables. $qx = mx/(1 + ((1-ax) * mx))$ as per Chiang (1984). Warning: the code has only been tested for data based on single-year age groups.

Usage

life_table(.data, mortality)

Arguments

Value

A vital object containing the index, keys, and the new life table variables mx, qx, lx, dx, Lx, Tx and ex.

Author(s)

Rob J Hyndman

References

Chiang CL. (1984) The life table and its applications. Robert E Krieger Publishing Company: Malabar.

Keyfitz, N, and Caswell, H. (2005) Applied mathematical demography, Springer-Verlag: New York.

Preston, S.H., Heuveline, P., and Guillot, M. (2001) Demography: measuring and modeling population processes. Blackwell

Examples

# Compute Norwegian life table for females in 2003
norway_mortality |>
  dplyr::filter(Sex == "Female", Year == 2003) |>
  life_table()

Do a product/ratio transformation

Description

Make a new vital containing products and ratios of a measured variable by a key variable. The most common use case of this function is for mortality rates by sex. That is, we want to compute the geometric mean of age-specific mortality rates, along with the ratio of mortality to the geometric mean for each sex. The latter are equal to the male/female and female/male ratios of mortality rates.

Usage

make_pr(.data, .var, key = Sex)

Arguments

Details

When a measured variable takes value 0, it is set to 10^-6 to avoid infinite values in the ratio.

Value

A vital object

References

Hyndman, R.J., Booth, H., & Yasmeen, F. (2013). Coherent mortality forecasting: the product-ratio method with functional time series models. Demography, 50(1), 261-283.

Examples

pr <- norway_mortality |>
  dplyr::filter(Year > 2015, Sex != "Total") |>
  make_pr(Mortality)
pr |>
  dplyr::filter(Sex == "geometric_mean") |>
  autoplot(Mortality) +
  ggplot2::scale_y_log10()

Do a sum/difference transformation

Description

Make a new vital containing means and differences of a measured variable by a key variable. The most common use case of this function is for migration numbers by sex. That is, we want to compute the age-specific mean migration, along with the difference of migration to the mean for each sex. The latter are equal to half the male/female and female/male differences of migration numbers.

Usage

make_sd(.data, .var, key = Sex)

Arguments

Value

A vital object

References

Hyndman, R.J., Booth, H., & Yasmeen, F. (2013). Coherent mortality forecasting: the product-ratio method with functional time series models. Demography, 50(1), 261-283.

Examples

mig <- net_migration(norway_mortality, norway_births) |>
  dplyr::filter(Sex != "Total")
sd <- mig |>
  make_sd(NetMigration)
sd |>
  autoplot(NetMigration)

Estimate models for vital data

Description

Trains specified model definition(s) on a dataset. This function will estimate the a set of model definitions (passed via ...) to each series within .data (as identified by the key structure). The result will be a mable (a model table), which neatly stores the estimated models in a tabular structure. Rows of the data identify different series within the data, and each model column contains all models from that model definition. Each cell in the mable identifies a single model.

Usage

## S3 method for class 'vital'
model(.data, ..., .safely = TRUE)

Arguments

Value

A mable containing the fitted models.

Parallel

It is possible to estimate models in parallel using the future package. By specifying a future::plan() before estimating the models, they will be computed according to that plan.

Progress

Progress on model estimation can be obtained by wrapping the code with progressr::with_progress(). Further customisation on how progress is reported can be controlled using the progressr package.

Author(s)

Rob J Hyndman and Mitchell O'Hara-Wild

Examples

norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(
    naive = FNAIVE(Mortality),
    mean = FMEAN(Mortality)
  )

Calculate net migration from a vital object

Description

Calculate net migration from a vital object

Usage

net_migration(deaths, births)

Arguments

Value

A vital object containing population, estimated deaths (not actual deaths) and net migration, using the formula Net Migration = Population - lag(Population cohort) - Deaths + Births. Births are returned as Population at Age -1, and deaths are estimated from the life table

References

Hyndman and Booth (2008) Stochastic population forecasts using functional data models for mortality, fertility and migration. International Journal of Forecasting, 24(3), 323-342.

Examples

net_migration(norway_mortality, norway_births)
## Not run: 
# Files downloaded from the [Human Mortality Database](https://mortality.org)
deaths <- read_hmd_files(c("Population.txt", "Mx_1x1.txt"))
births <- read_hmd_file("Births.txt")
mig <- net_migration(deaths, births)

## End(Not run)

Norwegian mortality and births data

Description

norway_births is an annual vital object covering the years 1900-2023, as provided by the Human Mortality Database on 19 August 2025.

norway_fertility is an annual vital covering the years 1967-2022, as provided by the Human Fertility Database on 19 August 2025.

norway_mortality is an annual vital covering the years 1900-2023, as provided by the Human Mortality Database on 19 August 2025.

Format

Time series of class vital

Source

Human Mortality Database https://mortality.org

Human Fertility Database https://www.humanfertility.org

Examples

library(ggplot2)
# Births
norway_births
norway_births |>
  autoplot(Births)
# Deaths
norway_mortality
norway_mortality |>
  dplyr::filter(Age < 85, Year < 1950, Sex != "Total") |>
  autoplot(Mortality) +
  scale_y_log10()
# Fertility
norway_fertility
norway_fertility |>
  autoplot(Fertility)

Read data directly from HFD and construct a vital object for use in other functions

Description

read_hfd reads single-year and single-age data from the Human Fertility Database (HFD https://www.humanfertility.org) and constructs a vital object suitable for use in other functions. This function uses HMDHFDplus::readHFDweb() to download the required data. It is designed to handle age-specific fertility rates. It may be extended to handle other types of data in the future.

Usage

read_hfd(country, username, password, variables = "asfrRR")

Arguments

Details

In order to read the data, users are required to create an account with the HFD website (https://www.humanfertility.org), and obtain a valid username and password.

Value

read_hfd returns a vital object combining the downloaded data.

Author(s)

Rob J Hyndman

Examples

## Not run: 
norway <- read_hfd(
  country = "NOR",
  username = "Nora.Weigh@mymail.com",
  password = "FF!5xeEFa6"
)

## End(Not run)

Read data from files downloaded from HFD and construct a vital object for use in other functions

Description

read_hfd_files reads single-year and single-age data from files downloaded from the Human Mortality Database (HFD https://www.humanfertility.org) and constructs a vital object suitable for use in other functions. This function uses HMDHFDplus::readHFD() to parse the files.

Usage

read_hfd_files(files)

Arguments

Value

read_hfd_files returns a vital object combining the downloaded data.

Author(s)

Rob J Hyndman

Examples

## Not run: 
# File downloaded from the [Human Fertility Database](https://www.humanfertility.org)
fertility <- read_hfd_files("NORasfrRR.txt")

## End(Not run)

Read data directly from HMD and construct a vital object for use in other functions

Description

read_hmd reads single-year and single-age data from the Human Mortality Database (HMD https://www.mortality.org) and constructs a vital object suitable for use in other functions. This function uses HMDHFDplus::readHMDweb() to download the required data. It is designed to handle Deaths, Population, Exposure, Death Rates and Births. By default, Deaths, Population, Exposure and Death Rates are downloaded. It is better to handle Births separately as they are not age-specific.

Usage

read_hmd(
  country,
  username,
  password,
  variables = c("Deaths", "Exposures", "Population", "Mx")
)

Arguments

Details

In order to read the data, users are required to create an account with the HMD website (https://www.mortality.org), and obtain a valid username and password.

Value

read_hmd returns a vital object combining the downloaded data.

Author(s)

Rob J Hyndman

Examples

## Not run: 
norway <- read_hmd(
  country = "Norway",
  username = "Nora.Weigh@mymail.com",
  password = "FF!5xeEFa6"
)
norway_births <- read_hmd(
  country = "Norway",
  username = "Nora.Weigh@mymail.com",
  password = "FF!5xeEFa6",
  variables = "Births"
)

## End(Not run)

Read data from files downloaded from HMD and construct a vital object for use in other functions

Description

read_hmd_files reads single-year and single-age data from files downloaded from the Human Mortality Database (HMD https://www.mortality.org) and constructs a vital object suitable for use in other functions. This function uses HMDHFDplus::readHMD() to parse the files.

Usage

read_hmd_files(files)

Arguments

Value

read_hmd_files returns a vital object combining the downloaded data.

Author(s)

Rob J Hyndman

Examples

## Not run: 
# Files downloaded from the [Human Mortality Database](https://mortality.org)
mortality <- read_hmd_files(
  c("Deaths_1x1.txt", "Exposures_1x1.txt", "Population.txt", "Mx_1x1.txt")
)
births <- read_hmd_files("Births.txt")

## End(Not run)

Read old-age mortality from Kannisto-Thatcher (K-T) database and construct a vital object for use in other functions

Description

read_ktdb reads old-age mortality data classified by sex, age, year of birth, and calendar year for more than 30 countries. The series is available in Kannisto-Thatcher (K-T) database (https://www.demogr.mpg.de/cgi-bin/databases/ktdb/datamap.plx) and constructs a vital object suitable for use in other functions.

Usage

read_ktdb(country, triangle = 1)

Arguments

Value

read_ktdb returns a vital object combining the downloaded data.

Author(s)

Sixian Tang

Examples

## Not run: 
australia <- read_ktdb(country = "Australia")

## End(Not run)

Read old-age mortality data from files downloaded from K-T database

Description

read_ktdb_files reads old-age mortality data from files downloaded from K-T database (https://www.demogr.mpg.de/cgi-bin/databases/ktdb/datamap.plx) and constructs a vital object suitable for use in other functions. If two files are provided, the function will treat them as data for each gender, returning a combined dataset. If only one file is provided, the function will assume that it represents data for a single gender.

Usage

read_ktdb_files(male = NULL, female = NULL, triangle = 1)

Arguments

Value

read_ktdb_files returns a vital object combining the downloaded data.

Author(s)

Sixian Tang

Examples

## Not run: 
# File downloaded from the K-T database
australia_male <- read_ktdb_files("maustl.txt")

## End(Not run)

Read Short-Term Mortality Fluctuations data from the Human Mortality Database

Description

read_stmf reads weekly mortality data from the Short-term Mortality Fluctuations (STMF) series available in the Human Mortality Database (HMD) https://www.mortality.org/Data/STMF), and constructs a vital object suitable for use in other functions.

Usage

read_stmf(country)

Arguments

Value

A vital object combining the downloaded data.

Author(s)

Sixian Tang

Examples

## Not run: 
norway <- read_stmf(country = "NOR")

## End(Not run)

Read STMF data from files downloaded from HMD

Description

read_stmf_files reads weekly mortality data from a file downloaded from the Short-term Mortality Fluctuations (STMF) series available in the Human Mortality Database (HMD) https://www.mortality.org/Data/STMF), and constructs a vital object suitable for use in other functions.

Usage

read_stmf_files(file)

Arguments

Value

read_stmf_files returns a vital object combining the downloaded data.

Author(s)

Rob J Hyndman

Examples

## Not run: 
# File downloaded from the [Human Mortality Database STMF series]
(https://www.mortality.org/Data/STMF)
mortality <- read_stmf_files("AUSstmfout.csv")

## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

fabletools

augment, estimate, forecast, generate, glance, interpolate, model, report, tidy

ggplot2

autoplot

Function to smooth mortality rates using MortalityLaw package

Description

This smoothing function allows smoothing of a variable in a vital object using the MortalityLaw package. The vital object is returned along with some additional columns containing information about the smoothed variable: .smooth containing the smoothed values, and .smooth_se containing the corresponding standard errors.

Usage

smooth_mortality_law(.data, .var, law = "gompertz", ...)

Arguments

Value

vital with added columns containing smoothed values and their standard errors

Author(s)

Sixian Tang and Rob J Hyndman

Examples

norway_mortality |> smooth_mortality_law(Mortality)

Functions to smooth demographic data

Description

These smoothing functions allow smoothing of a variable in a vital object. The vital object is returned along with some additional columns containing information about the smoothed variable: usually .smooth containing the smoothed values, and .smooth_se containing the corresponding standard errors.

Usage

smooth_spline(.data, .var, age_spacing = 1, k = -1)

smooth_mortality(.data, .var, age_spacing = 1, b = 65, power = 0.4, k = 30)

smooth_fertility(.data, .var, age_spacing = 1, lambda = 1e-10)

smooth_loess(.data, .var, age_spacing = 1, span = 0.2)

Arguments

Details

smooth_mortality() use penalized regression splines applied to log mortality with a monotonicity constraint above age b. The methodology is based on Wood (1994). smooth_fertility() uses weighted regression B-splines with a concavity constraint, based on He and Ng (1999). The function smooth_loess() uses locally quadratic regression, while smooth_spline() uses penalized regression splines.

Value

vital with added columns containing smoothed values and their standard errors

Author(s)

Rob J Hyndman

References

Hyndman, R.J., and Ullah, S. (2007) Robust forecasting of mortality and fertility rates: a functional data approach. Computational Statistics & Data Analysis, 51, 4942-4956. https://robjhyndman.com/publications/funcfor/

Examples

library(dplyr)
norway_mortality |>
  filter(Sex == "Female", Year > 2000) |>
  smooth_mortality(Mortality)
norway_fertility |>
  filter(Year > 2000) |>
  smooth_fertility(Fertility)

Extract time components from a model

Description

For a mable with a single model column, return the model components that are indexed by time.

Usage

time_components(object, ...)

Arguments

Value

tsibble object containing the time components from the model.

Examples

norway_mortality |>
  dplyr::filter(Sex == "Female") |>
  model(lee_carter = LC(log(Mortality))) |>
  time_components()

Compute total fertility rate from age-specific fertility rates

Description

Total fertility rate is the expected number of babies per woman in a life-time given the fertility rate at each age of a woman's life.

Usage

total_fertility_rate(.data, fertility)

Arguments

Value

A vital object with total fertility in column tfr.

Author(s)

Rob J Hyndman

Examples

# Compute Norwegian total fertility rates over time
norway_fertility |>
  total_fertility_rate()

Undo a product/ratio transformation

Description

Make a new vital from products and ratios of a measured variable by a key variable. The most common use case of this function is for computing mortality rates by sex, from the sex ratios and geometric mean of the rates.

Usage

undo_pr(.data, .var, key = Sex, times = 2000)

Arguments

Details

Note that when a measured variable takes value 0, the geometric mean is set to 10^-6 to avoid infinite values in the ratio. Therefore, when the transformation is undone, the results will not be identical to the original in the case that the original data was 0.

Value

A vital object

References

Hyndman, R.J., Booth, H., & Yasmeen, F. (2013). Coherent mortality forecasting: the product-ratio method with functional time series models. Demography, 50(1), 261-283.

Examples

# Make products and ratios
orig_data <- norway_mortality |>
  dplyr::filter(Year > 2015, Sex != "Total")
pr <- orig_data |>
  make_pr(Mortality)
# Compare original data with product/ratio version
orig_data
pr
# Undo products and ratios
pr |> undo_pr(Mortality)

Undo a mean/difference transformation

Description

Make a new vital from means and differences of a measured variable by a key variable. The most common use case of this function is for computing migration numbers by sex, from the sex differences and mean of the numbers.

Usage

undo_sd(.data, .var, key = Sex, times = 2000)

Arguments

Value

A vital object

References

Hyndman, R.J., Booth, H., & Yasmeen, F. (2013). Coherent mortality forecasting: the product-ratio method with functional time series models. Demography, 50(1), 261-283.

Examples

# Make sums and differences
mig <- net_migration(norway_mortality, norway_births) |>
  dplyr::filter(Sex != "Total")
sd <- mig |>
  make_sd(NetMigration)
# Undo products and ratios
sd |> undo_sd(NetMigration)

Create a vital object

Description

A vital object is a type of tsibble that contains vital statistics such as births, deaths, and population counts, and mortality and fertility rates. It is a tsibble with a special class that allows for special methods to be used. The object has an attribute that stores variables names needed for some functions, including age, sex, births, deaths and population.

Usage

vital(
  ...,
  key = NULL,
  index,
  .age = NULL,
  .sex = NULL,
  .deaths = NULL,
  .births = NULL,
  .population = NULL,
  regular = TRUE,
  .drop = TRUE
)

Arguments

Value

A tsibble with class vital.

Author(s)

Rob J Hyndman

See Also

tsibble::tsibble()

Examples

# create a vital with only age as a key
vital(
  year = rep(2010:2015, 100),
  age = rep(0:99, each = 6),
  mx = runif(600, 0, 1),
  index = year,
  key = age,
  .age = "age"
)

Return vital variables

Description

A vital object is a special case of a tsibble object with additional attributes identifying the age, sex, deaths, births and population variables. vital_vars() returns a character vector the names of the vital variables.

Usage

vital_vars(x)

Arguments

Value

A character vector of the names of the vital variables.

Examples

vital_vars(norway_mortality)