rwlifetable (version 0.1.0-6)

tw_crude_mx: Computes crude/raw death rates/probabilities using triple rolling windows

Description

This function estimates (crude/raw) death rates/probabilities (life tables) using rolling windows in three dimensions (e.g., age, time and income) from a given experience of mortality, summarized in a three-dimension array of (either initial or times of) exposed to risk and a three-dimension dataset of recorded deaths.

Usage

tw_crude_mx(
  exposed,
  deaths,
  dim1.window = 2,
  dim2.window = 2,
  dim3.window = 2,
  dim1.wb = dim1.window,
  dim1.wf = dim1.window,
  dim2.wb = dim2.window,
  dim2.wf = dim2.window,
  dim3.wb = dim3.window,
  dim3.wf = dim3.window,
  weights = 1,
  initial = FALSE,
  partial = FALSE
)

Value

A list with six three-dimension arrays: `mx`, `qx`, `Lx`, `dx`, `Lx.total`, `dx.total`. When `partial = FALSE` these arrays are of order (n - dim1.wb - dim1.wf) x (T - dim2.wb - dim2.wf) x (I - dim3.wb - dim3.wf); otherwise, they are of order nxTxI. The names of the rows, columns and slices of these arrays are inherited from the corresponding names in the `deaths` object, ensuring that if the row, column and slice names indicate relevant data, this contextual information is preserved.

mx

The `mx` array holds the crude death rates estimated after determining the number of individuals (time) exposed to risk and deaths to be used for each estimate using the specified rolling windows with the defined `weights`.

qx

The `qx` array contains the raw death probabilities, derived from `mx`, based on the assumption that, on average, each deceased individual lives for half a year in the year of their death.

Lx

The `Lx` array contains the actual time exposures used to compute the estimates.

dx

The `dx` array contains the number of deaths used to compute the estimates..

Lx.total

The `Lx.total` array contains the total numbers for time exposures which corresponds to all factor-weights being equal. If `weights` is a constant matrix `Lx` and `Lx.total` coincide.

dx.total

The `dx.total` array contains the total numbers deaths which corresponds to all factor-weights being equal. If `weights` is a constant array `dx` and `dx.total` coincide.

Arguments

exposed

A three-dimensional array of order n×T×I. It is recommended (and when `initial = TRUE` assumed) that the first dimension corresponds to age. For each row-column-slice combination, the array contains either the initial number of individuals exposed to risk in the portfolio (population) or the exposure time for those at risk within the portfolio. By default, the array contains exposure times. When `exposed` contains the initial number of individuals exposed to risk, (i) the first dimension represents must represent ages, and (ii) exposure times are estimated based on the assumptions of uniformity and a closed demographic system. It is also assumed that the order of rows, columns, and slices in `deaths` and `exposed` is consistent (i.e., identical) and that the sequence of values (levels) across the three dimensions is ordered sequentially.

deaths

A three-dimension array of order nxTxI. It is recommended (and when `initial = TRUE` assumed) that the first dimension corresponds to age. For each combination of row-column-slice, the array contains the number of deaths recorded in the portfolio (population). It is assumed that the order of rows, columns, and slices in `deaths` and `exposed` is consistent (i.e., identical) and that the sequence of values (levels) across the three dimensions is ordered sequentially.

dim1.window

An non-negative integer indicating the number of preceding and succeeding levels to be included in the rolling window for dimension 1. Default, 2.

dim2.window

An non-negative integer indicating the number of preceding and succeeding levels to be included in the rolling window for dimension 2. Default, 2.

dim3.window

An non-negative integer indicating the number of preceding and succeeding levels to be included in the rolling window for dimension 3. Default, 2.

dim1.wb

An non-negative integer indicating the number of preceding levels to be included in the rolling window for dimension 1. Default, `dim1.window`. If `dim1.wb` and `dim1.window` differ, the definition of `dim1.wb` takes precedence, allowing non-centered dimension 1 windows.

dim1.wf

An non-negative integer indicating the number of succeeding levels to be included in the rolling window for dimension 1. Default, `dim1.window`. If `dim1.wf` and `dim1.window` differ, the definition of `dim1.wf` takes precedence, allowing non-centered dimension 1 windows.

dim2.wb

An non-negative integer indicating the number of preceding levels to be included in the rolling window for dimension 2. Default, `dim2.window`. If `dim2.wb` and `dim2.window` differ, the definition of `dim2.wb` takes precedence, allowing non-centered dimension 2 windows.

dim2.wf

An non-negative integer indicating the number of succeeding levels to be included in the rolling window for dimension 2. Default, `dim2.window`. If `dim2.wf` and `dim2.window` differ, the definition of `dim2.wf` takes precedence, allowing non-centered dimension 2 windows.

dim3.wb

An non-negative integer indicating the number of preceding levels to be included in the rolling window for dimension 3. Default, `dim3.window`. If `dim3.wb` and `dim3.window` differ, the definition of `dim3.wb` takes precedence, allowing non-centered dimension 3 windows.

dim3.wf

An non-negative integer indicating the number of succeeding levels to be included in the rolling window for dimension 3. Default, `dim3.window`. If `dim3.wf` and `dim3.window` differ, the definition of `dim3.wf` takes precedence, allowing non-centered dimension 3 windows.

weights

A three-dimension array of order (dim1.wb + dim1.wf + 1) x (dim2.wb + dim2.wf + 1) x (dim3.wb + dim3.wf + 1) of real positive numbers indicating the multiplicative factors to be applied to the different components of the triple rolling window. Default, `1`; meaning all the components of the rolling window are aggregated as available in `exposed` and `deaths`.

initial

A TRUE/FALSE argument indicating whether the numbers in `exposed` represent the initial number of individuals exposed to risk in the portfolio (population), which corresponds to `initial = TRUE`, or the time exposed to risk, with `initial = FALSE` as default.

partial

A TRUE/FALSE argument indicating whether estimates obtained using incomplete rolling windows should be also computed. Default, `FALSE`; meaning crude death rates are estimated only for combinations where the corresponding triple rolling window is complete.

Author

Jose M. Pavia

Josep Lledo

Examples

exposed0 <- structure(list(Year2017 = c(6078.14, 5841.78, 5575.70, 5726.18, 5458.21, 5197.56,
                                     5018.12, 4791.56, 4245.15, 4321.65, 4179.3),
                           Year2018 = c(5978.73, 5473.78, 5572.23, 5495.19, 5148.47, 4845.14,
                                     4739.54, 4222.01, 4476.99, 4306.45, 4108.58),
                           Year2019 = c(5593.23, 5551.41, 5260.44, 5079.56, 4873.37, 4857.78,
                                     4536.12, 4453.85, 4310.89, 4015.02, 3974.25)),
                            class = "data.frame", row.names = 68:78)


deaths0 <- structure(list(Year2017 = c(144, 102, 113, 122, 156, 110, 126, 132, 120, 172, 110),
                           Year2018 = c(111, 122, 109, 116, 162, 154, 115, 146, 100, 169, 146),
                           Year2019 = c(100, 123, 113, 151, 122, 110, 137, 175, 137, 110, 155)),
                          class = "data.frame", row.names = 68:78)

exposed <- deaths <- array(NA, dim = c(11, 3, 5))
set.seed(123)
for (kk in 1:5){
   exposed[, , kk] <- as.matrix(exposed0) +
                       matrix(runif(33, 0, 100), nrow = 11, ncol = 3)
   deaths[, , kk] <- as.matrix(deaths0) +
                       matrix(runif(33, 0, 5), nrow = 11, ncol = 3)
}
dimnames(exposed) <- dimnames(deaths) <- list(68:78,
                                              paste0("Y", 2017:2019),
                                              paste0("I", 1:5))

example <- tw_crude_mx(exposed = exposed, deaths = deaths, dim1.window = 2,
                       dim2.window = 1, dim3.window = 1, initial = FALSE)