Help for package lillies

Title:

Estimation of Life Years Lost

Version:

0.2.12

Description:

Estimation of life expectancy and Life Years Lost (LYL, or lillies for short) for a given population, for example those with a given disease or condition. In addition, the package can be used to compare estimates from different populations, or to estimate confidence intervals. Technical details of the method are available in Plana-Ripoll et al. (2020) <doi:10.1371/journal.pone.0228073> and Andersen (2017) <doi:10.1002/sim.7357>.

Depends:

R (≥ 3.5.0)

License:

MIT + file LICENSE

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.2.3

Imports:

dplyr, knitr, pracma, progress, rlang, survival, tidyr, utils, methods

Suggests:

ggplot2

NeedsCompilation:

Packaged:

2023-07-21 22:42:04 UTC; au464894

Author:

Oleguer Plana-Ripoll

[aut, cre]

Maintainer:

Oleguer Plana-Ripoll <opr@clin.au.dk>

Repository:

CRAN

Date/Publication:

2023-08-07 10:40:02 UTC

Simulated aggregated data for Life Years Lost estimation.

Description

A dataset containing age-specific number of new cases, number of deaths and mortality rates for a simulated disease with onset after age 40 years. Data is available for ages 40-90 years.

Usage

aggreg_data

Format

A data frame with 50 rows and 4 variables:

age: age
new_cases: number of new cases diagnosed at that specific age
deaths: number of deaths among the diagnosed at that specific age
rate: age-specific mortality rates among the diagnosed

Source

Simulated data

Life Years Lost at one specific age.

Description

lyl estimates remaining life expectancy and Life Years Lost for a given population after a specific age age_speficic and restrictied to a maximum theoretical age \tau.

Usage

lyl(
  data,
  t0 = NULL,
  t,
  status,
  age_specific,
  censoring_label = "Alive",
  death_labels = "Dead",
  tau = 100
)

Arguments

data

A dataframe, where each raw represents a person. The dataframe will have a time-to-event format with at least two variables: age at end of follow-up (t) and status indicator with death/censoring (status). Note that this package is not developed to be used with tibbles.

t0

Age at start of the follow-up time. Default is NULL, which means all subjects are followed from birth. For delayed entry, t0 indicates age at beginning of follow-up.

t

Age at the end of the follow-up time (death or censoring).

status

Status indicator, normally 0=alive, 1=dead. Other choices are TRUE/FALSE (TRUE = death) or 1/2 (2=death). For multiple causes of death (competing risks analysis), the status variable will be a factor, whose first level is treated as censoring; or a numeric variable, whose lowest level is treated as censoring. In the latter case, the label for censoring is censoring_label ("Alive" by default).

age_specific

Specific age at which the Life Years Lost have to be estimated.

censoring_label

Label for censoring status. If status is not a factor, "Alive" by default. If status is a factor, the first level will be treated as censoring label.

death_labels

Label for event status. For only one cause of death, "Dead" is the default. For multiple causes, the default are the values given in variable status.

tau

Remaining life expectancy and Life Years Lost are estimated restrictied to a maximum theoretical age \tau (\tau=100 years by default).

Value

A list with class "lyl" containing the following components:

data: Data frame with 3 variables and as many observations as the original data provided to estimate Life Years Lost: t0, t, and status
LYL: Data frame with 1 observation and at least 3 variables: age which corresponds to age_spefific; life_exp which is the estimated remaining life expectancy at age age_specific years and before age tau years; and one variable corresponding to the estimated Life Years Lost for each specific cause of death. If only one cause of death is considered (no competing risks), this variable is Dead and includes the total overall Life Years Lost
tau: Maximum theoretical age \tau
age_specific: Specific age at which the Life Years Lost have been estimated
data_plot: A data frame in long format with 3 variables time, cause, and cip used to create a Figure of Life Years Lost with function plot.
censoring_label: Label for censoring status
death_labels: Label(s) for death status
competing_risks: Logical value (TRUE = more than one cause of death (competing risks))
type: Whether the estimation is at "age_specific" or "age_range".

References

Andersen PK. Life years lost among patients with a given disease. Statistics in Medicine. 2017;36(22):3573- 3582.
Andersen PK. Decomposition of number of life years lost according to causes of death. Statistics in Medicine. 2013;32(30):5278-5285.
Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = death,
                      age_specific = 45, tau = 95)

# Summarize and plot the data
summary(lyl_estimation)
plot(lyl_estimation)

# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after age 45
# years and before age 95 years

lyl_estimation2 <- lyl(data = simu_data, t = age_death, status = cause_death,
                       age_specific = 45, tau = 95)

# Summarize and plot the data
summary(lyl_estimation2)
plot(lyl_estimation2)

Plot Life Years Lost at one specific age for two different populations

Description

lyl_2plot was used to create a figure of Life Years Lost at one specific age for two different populations. Please use lyl_compare_plot instead.

Usage

lyl_2plot(
  x,
  y,
  color_alive = NA,
  colors = NA,
  labels = c("Population of interest", "Reference population"),
  ...
)

Arguments

x

An object of class lyl (obtained with function lyl).

y

An object of class lyl (obtained with function lyl).

color_alive

Color to be used for the censoring category. Default is NA, and default color is "white".

colors

Vector with one color for each cause of death. Default is NA, and default colors are used.

labels

Vector with labels for the two populations (default are "Population of interest" for x, and "Reference population" for y)

...

Additional arguments affecting the plot produced.

Value

A plot with survival function and stacked cause-specific cumulative incidences for two populations side by side.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = cause_death,
                      age_specific = 45, tau = 95)

# Same estimate for those with a specific disease
diseased <- simu_data[!is.na(simu_data$age_disease), ]

lyl_estimation1 <- lyl(data = diseased, t0 = age_disease,
                       t = age_death, status = cause_death,
                      age_specific = 45, tau = 95)

# Plot the data
lyl_compare_plot(list(lyl_estimation1, lyl_estimation))

Life Years Lost at one specific age using aggregated data.

Description

lyl estimates differences in remaining life expectancy and Life Years Lost for two given life tables data and data0 after a specific age age_speficic and restrictied to a maximum theoretical age \tau.

Usage

lyl_aggregated(
  data,
  age,
  rates,
  surv,
  data0,
  age0,
  rates0,
  surv0,
  age_specific,
  censoring_label = "Alive",
  death_labels = "Dead",
  tau = 100
)

Arguments

data

A dataframe, where each raw represents an age, for the population of interest. The dataframe will contain information on age-specific mortality rates or survivial probability (if both parameters are provided, rates will be used).

age

Variable in data containing information on age.

rates

Variable in data containing information on age-specific mortality rates.

surv

Variable in data containing information on age-specific survival probability.

data0

A dataframe, where each raw represents an age, for the population of reference The dataframe will contain information on age-specific mortality rates or survivial probability (if both parameters are provided, rates will be used).

age0

Variable in data0 containing information on age.

rates0

Variable in data0 containing information on age-specific mortality rates.

surv0

Variable in data0 containing information on age-specific survival probability.

age_specific

Specific age at which the Life Years Lost have to be estimated.

censoring_label

Label for censoring status ("Alive" by default).

death_labels

Label for event status ("Dead" by default).

tau

Remaining life expectancy and Life Years Lost are estimated restrictied to a maximum theoretical age \tau (\tau=100 years by default).

Value

A list with class "lyl_aggregated" containing the following components:

data: Name of the dataset preovided in parameter data
data0: Name of the dataset preovided in parameter data0
LYL: Data frame with 1 observation and 3 variables: age which corresponds to age_spefific; and life_exp and life_exp0 which are the estimated remaining life expectancies at age age_specific years and before age tau years for the population provided in data and data0, respectively
tau: Maximum theoretical age \tau
age_specific: Specific age at which the Life Years Lost have been estimated
data_plot: A data frame in long format with 3 variables time, cause, and cip used to create a Figure of Life Years Lost with function plot.
censoring_label: Label for censoring status
death_labels: Label(s) for death status
type: Whether the estimation is at "age_specific" or "age_range"

References

Andersen PK. Life years lost among patients with a given disease. Statistics in Medicine. 2017;36(22):3573- 3582.
Andersen PK. Decomposition of number of life years lost according to causes of death. Statistics in Medicine. 2013;32(30):5278-5285.
Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.#'

Examples

# Load simulated data as example
data(aggreg_data)
data(pop_ref)

# Estimate remaining life expectancy and Life Years
# Lost after age 70 years and before age 90 years
lyl_summary_data70 <- lyl_aggregated(data = aggreg_data, age = age, rates = rate,
                                     data0 = pop_ref, age0 = age, surv0 = survival,
                                     age_specific = 70, tau = 90)

# Summarize and plot the data
summary(lyl_summary_data70)
plot(lyl_summary_data70)

Life Years Lost at a range of different ages using aggregated data.

Description

lyl estimates differences in remaining life expectancy and Life Years Lost for two given life tables data and data0 after a range of specific ages (age_begin to age_end) and restrictied to a maximum theoretical age \tau.

Usage

lyl_aggregated_range(
  data,
  age,
  rates,
  surv,
  weights,
  data0,
  age0,
  rates0,
  surv0,
  age_begin,
  age_end,
  censoring_label = "Alive",
  death_labels = "Dead",
  tau = 100
)

Arguments

data

age

Variable in data containing information on age.

rates

Variable in data containing information on age-specific mortality rates.

surv

Variable in data containing information on age-specific survival probability.

weights

Variable in data containing information on number of new cases per age. A weighted average is provided using these weights.

data0

age0

Variable in data0 containing information on age.

rates0

Variable in data0 containing information on age-specific mortality rates.

surv0

Variable in data0 containing information on age-specific survival probability.

age_begin

Specific starting age at which the Life Years Lost have to be estimated.

age_end

Specific ending age at which the Life Years Lost have to be estimated.

censoring_label

Label for censoring status ("Alive" by default).

death_labels

Label for event status ("Dead" by default).

tau

Remaining life expectancy and Life Years Lost are estimated restrictied to a maximum theoretical age \tau (\tau=100 years by default).

Value

A list with class "lyl_aggregated" containing the following components:

data: Name of the dataset preovided in parameter data
data0: Name of the dataset preovided in parameter data0
LYL: Data frame with 1 observation and 2 variables: life_exp and life_exp0 which are the estimated remaining life expectancies averaged over the age range and before age tau years for the population provided in data and data0, respectively
tau: Maximum theoretical age \tau
age_begin: Specific starting age at which the Life Years Lost have been estimated
age_end: Specific ending age at which the Life Years Lost have been estimated
data_plot: A data frame in long format with 3 variables time, cause, and cip used to create a Figure of Life Years Lost with function plot.
censoring_label: Label for censoring status
death_labels: Label(s) for death status
type: Whether the estimation is at "age_specific" or "age_range".

References

Andersen PK. Life years lost among patients with a given disease. Statistics in Medicine. 2017;36(22):3573- 3582.
Andersen PK. Decomposition of number of life years lost according to causes of death. Statistics in Medicine. 2013;32(30):5278-5285.
Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.#'

Examples

# Load simulated data as example
data(aggreg_data)
data(pop_ref)

# Estimate remaining life expectancy and Life Years
# Lost after each age from 40 to 89 years and before age 90 years
lyl_summary_data <- lyl_aggregated_range(data = aggreg_data, age = age,
                                         rates = rate, weights = new_cases,
                                         data0 = pop_ref, age0 = age, surv0 = survival,
                                         age_begin = 40, age_end = 89, tau = 90)

# Summarize the data
summary(lyl_summary_data)

Plot number of persons at risk at each specific age.

Description

Given a lyl_range-class object, lyl_checkplot draws numbers of persons at risk of dying at each specific age from age_begin until age \tau.

Usage

lyl_checkplot(x)

Arguments

x

An object of class lyl_range obtained with the lyl_range function.

Value

A plot with the number of persons at risk at each specific age.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after each age from 0 to 94 years and before age 95 years
lyl_estimation <- lyl_range(data = simu_data, t = age_death, status = death,
                            age_begin = 45, age_end = 50, tau = 95)

# Check whether small numbers could compromise the results
lyl_checkplot(lyl_estimation)

# The plot can be modified with a usual ggplot2 format
lyl_checkplot(lyl_estimation) +
  ggplot2::geom_hline(yintercept = 10, linetype = "dashed", color = "red") +
  ggplot2::xlab("Age [in years]") +
  ggplot2::ggtitle("Persons at risk of dying at each age 0-94 years")

Confidence intervals for Life Years Lost.

Description

lyl_ci estimates confidence intervals for Life Years Lost using non-parametric bootstrap. The confidence level can be specified when summarizing the results with the function summary.lyl_ci.

Usage

lyl_ci(lyl_estimation, niter = 1000)

Arguments

lyl_estimation

An object of class lyl or lyl_range.

niter

Number of iterations for the bootstrap (default is 1,000).

Value

A list with class "lyl_ci" containing the following components:

LYL: Data frame with one observation per age and at least 3 variables: age; life_exp which is the estimated remaining life expectancy at age age_specific years and before age tau years; and one variable corresponding to the estimated Life Years Lost for each specific cause of death. If only one cause of death is considered (no competing risks), this variable is Dead and includes the total overall Life Years Lost
LYL_ci: Data frame with one observation per age-iteration and at least 4 variables: age; iteration, which correspond to each specific iteration; life_exp which is the estimated remaining life expectancy at age age_specific years and before age tau years; and one variable corresponding to the estimated Life Years Lost for each specific cause of death. If only one cause of death is considered (no competing risks), this variable is Dead and includes the total overall Life Years Lost
tau: Maximum theoretical age \tau
age_specific: Specific age at which the Life Years Lost have been estimated
age_begin: Specific starting age at which the Life Years Lost have been estimated
age_end: Specific ending age at which the Life Years Lost have been estimated
death_labels: Label(s) for death status
competing_risks: Logical value (TRUE = more than one cause of death (competing risks))
type: Whether the estimation is at "age_specific" or "age_range".
niter: Number of iterations used to estimate the confidence intervals

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = death,
                      age_specific = 45, tau = 95)


# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation_ci <- lyl_ci(lyl_estimation, niter = 3)
summary(lyl_estimation_ci)
plot(lyl_estimation_ci)

# Estimate remaining life expectancy and Life Years
# Lost after each age from 0 to 94 years and before age 95 years
lyl_estimation2 <- lyl_range(data = simu_data, t = age_death, status = death,
                             age_begin = 0, age_end = 94, tau = 95)

# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation_ci2 <- lyl_ci(lyl_estimation2, niter = 3)
summary(lyl_estimation_ci2, weights = simu_data$age_disease)
plot(lyl_estimation_ci2, weights = simu_data$age_disease)

Plot Life Years Lost at one specific age for two or more different populations

Description

lyl_compare_plot creates a figure of Life Years Lost at one specific age for two or more different populations.

Usage

lyl_compare_plot(
  x,
  color_alive = NA,
  colors = NA,
  nrow = NULL,
  ncol = NULL,
  dir = "h",
  reverse_legend = FALSE,
  labels = NA,
  ...
)

Arguments

x

A list of objects of class lyl (obtained with function lyl).

color_alive

Color to be used for the censoring category. Default is NA, and default color is "white".

colors

Vector with one color for each cause of death. Default is NA, and default colors are used.

nrow

Number of rows to be passed to facet_wrap.

ncol

Number of columns to be passed to facet_wrap.

dir

Direction to be passed to facet_wrap: either "h" for horizontal, the default, or "v", for vertical.

reverse_legend

Reverse the order of elements in the legend. Ddefault is FALSE, indicating that first is the censoring label and then all causes of death.

labels

Vector with labels for the two populations (default are "Population of interest" for x, and "Reference population" for y)

...

Additional arguments affecting the plot produced.

Value

A plot with survival function and stacked cause-specific cumulative incidences for two populations side by side.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = cause_death,
                      age_specific = 45, tau = 95)

# Same estimate for those with a specific disease
diseased <- simu_data[!is.na(simu_data$age_disease), ]

lyl_estimation1 <- lyl(data = diseased, t0 = age_disease,
                       t = age_death, status = cause_death,
                      age_specific = 45, tau = 95)

# Plot the data
lyl_compare_plot(list(lyl_estimation1, lyl_estimation))
lyl_compare_plot(list(lyl_estimation1, lyl_estimation),
          labels = c("Population with a disease", "General population"))

# The plot can be modified with a usual ggplot2 format
lyl_compare_plot(list(lyl_estimation1, lyl_estimation)) +
  ggplot2::xlab("Age [in years]") +
  ggplot2::ggtitle("Differences in Life Years Lost at age 45 years")

Summarize differences in Life Years Lost.

Description

lyl_diff summarizes differences in estimated Life Years Lost in two different populations: lyl_estimation compared to lyl_estimation0.

Usage

lyl_diff(
  lyl_population1,
  lyl_population0,
  decimals = 2,
  level = 0.95,
  weights = NA
)

Arguments

lyl_population1

Population of interest: An object of class lyl or lyl_range (obtained with functions lyl or lyl_range). Alternatively, an object of class lyl_ci can be provided for bootstrapped confidence intervals.

lyl_population0

Reference population: An object of class lyl or lyl_range (obtained with functions lyl or lyl_range). Alternatively, an object of class lyl_ci can be provided for bootstrapped confidence intervals.

decimals

Number of decimals to be reported (default is 2).

level

Confidence level if lyl_population1 or lyl_population0 is obtained with the lyl_ci function (default is 0.95 for 95% confidence intervals)

weights

Vector with age distribution of disease/condition onset to be used when Life Years Lost are estimated over a range of ages (with lyl_range function). If weights are not provided (dafault is weights = NA), then the differences in Life Years Lost at each age is provided. If weights are provided, then a weighted average is provided.

Value

A table with the summary of the differences between two populations.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

### For the overall population and for those with a disease
diseased <- simu_data[!is.na(simu_data$age_disease), ]

# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after age 45
# years and before age 95 years
lyl_estimation0 <- lyl(data = simu_data, t = age_death, status = cause_death,
                       age_specific = 45, tau = 95)
lyl_estimation1 <- lyl(data = diseased, t0 = age_disease,
                       t = age_death, status = cause_death,
                       age_specific = 45, tau = 95)
lyl_diff(lyl_estimation1, lyl_estimation0)
lyl_compare_plot(list(lyl_estimation1, lyl_estimation0))


# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation1_ci <- lyl_ci(lyl_estimation1, niter = 3)

lyl_estimation0_ci <- lyl_ci(lyl_estimation0, niter = 3)
lyl_diff(lyl_estimation1_ci, lyl_estimation0_ci)

# It is also possible to assume no uncertainty for one of the estimates
lyl_diff(lyl_estimation1_ci, lyl_estimation0)

# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after each age
# from 0 to 94 years and before age 95 years
lyl_estimation2 <- lyl_range(data = simu_data, t = age_death, status = cause_death,
                             age_begin = 0, age_end = 94, tau = 95)
lyl_estimation3 <- lyl_range(data = diseased, t0 = age_disease,
                             t = age_death, status = cause_death,
                             age_begin = 0, age_end = 94, tau = 95)
lyl_diff(lyl_estimation3, lyl_estimation2)
lyl_diff(lyl_estimation3, lyl_estimation2, weights = diseased$age_disease)

# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation3_ci <- lyl_ci(lyl_estimation3, niter = 3)
lyl_diff(lyl_estimation3_ci, lyl_estimation2, weights = diseased$age_disease)

Summarize differences in Life Years Lost.

Description

lyl_diff summarizes differences in estimated Life Years Lost in two different populations: lyl_estimation1 compared to a life table provided in data_ref.

Usage

lyl_diff_ref(
  lyl_population1,
  data_ref,
  age,
  surv,
  rates,
  decimals = 2,
  level = 0.95,
  weights = NA,
  lyl_population0
)

Arguments

lyl_population1

data_ref

age

Variable in data_ref containing information on age.

surv

Variable in data_ref containing information on age-specific survival probability.

rates

Variable in data_ref containing information on age-specific mortality rates.

decimals

Number of decimals to be reported (default is 2).

level

Confidence level if lyl_population1 or lyl_population0 is obtained with the lyl_ci function (default is 0.95 for 95% confidence intervals)

weights

lyl_population0

Parameter automatically created.

Value

A table with the summary of the differences between two populations.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)
data(pop_ref)

# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after age 45
# years and before age 95 years for those with a disease
diseased <- simu_data[!is.na(simu_data$age_disease), ]
lyl_estimation1 <- lyl(data = diseased, t0 = age_disease,
                       t = age_death, status = cause_death,
                       age_specific = 45, tau = 95)
lyl_diff_ref(lyl_estimation1, pop_ref, age = age, surv = survival)
lyl_diff_ref(lyl_estimation1, pop_ref, age = age, rates = mortality_rates)

# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation1_ci <- lyl_ci(lyl_estimation1, niter = 3)
lyl_diff_ref(lyl_estimation1_ci, pop_ref, age = age, surv = survival)


# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after each age
# from 0 to 94 years and before age 95 years
lyl_estimation2 <- lyl_range(data = diseased, t0 = age_disease,
                             t = age_death, status = cause_death,
                             age_begin = 0, age_end = 94, tau = 95)
lyl_diff_ref(lyl_estimation2, pop_ref, age = age, surv = survival)
lyl_diff_ref(lyl_estimation2, pop_ref, age = age, surv = survival, weights = diseased$age_disease)

Life Years Lost at a range of different ages.

Description

lyl estimates remaining life expectancy and Life Years Lost for a given population after a range of specific ages (age_begin to age_end) and restrictied to a maximum theoretical age \tau.

Usage

lyl_range(
  data,
  t0 = NULL,
  t,
  status,
  age_begin,
  age_end,
  censoring_label = "Alive",
  death_labels = "Dead",
  tau = 100
)

Arguments

data

t0

Age at start of the follow-up time. Default is NULL, which means all subjects are followed from birth. For delayed entry, t0 indicates beginning of follow-up.

t

Age at the end of the follow-up time (death or censoring).

status

age_begin

Specific starting age at which the Life Years Lost have to be estimated.

age_end

Specific ending age at which the Life Years Lost have to be estimated.

censoring_label

Label for censoring status. If status is not a factor, "Alive" by default. If status is a factor, the first level will be treated as censoring label.

death_labels

Label for event status. For only one cause of death, "Dead" is the default. For multiple causes, the default are the values given in variable status.

tau

Remaining life expectancy and Life Years Lost are estimated restrictied to a maximum theoretical age \tau (\tau=100 years by default).

Value

A list with class "lyl_range" containing the following components:

data: Data frame with 3 variables and as many observations as the original data provided to estimate Life Years Lost: t0, t, and status
LYL: Data frame with (age_end - age_begin + 1) observations and at least 3 variables: age which corresponds to each specific age from age_begin to age_end; life_exp which is the estimated remaining life expectancy at age specific age and before age tau years; and one variable corresponding to the estimated Life Years Lost for each specific cause of death. If only one cause of death is considered (no competing risks), this variable is Dead and includes the total overall Life Years Lost
tau: Maximum theoretical age \tau
age_begin: Specific starting age at which the Life Years Lost have been estimated
age_end: Specific ending age at which the Life Years Lost have been estimated
censoring_label: Label for censoring status
death_labels: Label(s) for death status
competing_risks: Logical value (TRUE = more than one cause of death (competing risks))
numbers_at_risk: Data frame with (tau - age_begin + 1) observations and 2 variables: age which corresponds to each specific age from age_begin to tau; and number which is the number of persons at risk of dying at each specific age
type: Whether the estimation is at "age_specific" or "age_range".

References

Andersen PK. Life years lost among patients with a given disease. Statistics in Medicine. 2017;36(22):3573- 3582.
Andersen PK. Decomposition of number of life years lost according to causes of death. Statistics in Medicine. 2013;32(30):5278-5285.
Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)


# Estimate remaining life expectancy and Life Years
# Lost after each age from 0 to 94 years and before age 95 years
lyl_estimation <- lyl_range(data = simu_data, t = age_death, status = death,
                            age_begin = 0, age_end = 94, tau = 95)

# Visualize data at each different specific age
summary(lyl_estimation)
plot(lyl_estimation)

# Summarize data over an age distribution
summary(lyl_estimation, weights = simu_data$age_disease)

# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after each age
# from 0 to 94 years and before age 95 years
lyl_estimation2 <- lyl_range(data = simu_data, t = age_death, status = cause_death,
                             age_begin = 0, age_end = 94, tau = 95)

# Visualize data at each different specific age
summary(lyl_estimation2)
plot(lyl_estimation2)

# Summarize data over an age distribution
summary(lyl_estimation2, weights = simu_data$age_disease)

Plot Life Years Lost at one specific age

Description

plot for objects of class lyl creates a figure of Life Years Lost at one specific age.

Usage

## S3 method for class 'lyl'
plot(x, color_alive = NA, colors = NA, reverse_legend = FALSE, ...)

Arguments

x

An object of class lyl (obtained with function lyl).

color_alive

Color to be used for the censoring category. Default is NA, and default color is "white".

colors

Vector with one color for each cause of death. Default is NA, and default colors are used.

reverse_legend

Reverse the order of elements in the legend. Ddefault is FALSE, indicating that first is the censoring label and then all causes of death.

...

Additional arguments affecting the plot produced.

Value

A plot with survival function and stacked cause-specific cumulative incidences.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = cause_death,
                      age_specific = 45, tau = 95)

# Summarize and plot the data
plot(lyl_estimation)
plot(lyl_estimation, colors = c("chocolate", "cornflowerblue"))

# The plot can be modified with a usual ggplot2 format
plot(lyl_estimation) +
  ggplot2::xlab("Age [in years]") +
  ggplot2::ggtitle("Life Years Lost at age 45 years")

Plot Life Years Lost at one specific age for two different populations obtained from aggregated data

Description

plot for objects of class lyl_aggregated creates a figure of Life Years Lost at one specific age for two different populations.

Usage

## S3 method for class 'lyl_aggregated'
plot(
  x,
  color_alive = NA,
  colors = NA,
  labels = c("Population of interest", "Reference population"),
  ...
)

Arguments

x

An object of class lyl_aggregated (obtained with function lyl_aggregated).

color_alive

Color to be used for the censoring category. Default is NA, and default color is "white".

colors

Vector with one color for each cause of death. Default is NA, and default colors are used.

labels

Vector with labels for the two populations (default are "Population of interest" for data, and "Reference population" for data0; which are provided to function lyl_aggregated.)

...

Additional arguments affecting the plot produced.

Value

A plot with survival function and stacked cause-specific cumulative incidences for two populations side by side.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(aggreg_data)
data(pop_ref)

# Estimate remaining life expectancy and Life Years
# Lost after age 70 years and before age 90 years
lyl_summary_data70 <- lyl_aggregated(data = aggreg_data, age = age, rates = rate,
                                     data0 = pop_ref, age0 = age, surv0 = survival,
                                     age_specific = 70, tau = 90)

# Plot the data
plot(lyl_summary_data70)

Plot evolution of bootstrapped parameters for Life Years Lost

Description

plot for objects of class lyl_ci creates a figure of the bootstrapped Life Years Lost to examine if the number of iterations is enough.

Usage

## S3 method for class 'lyl_ci'
plot(x, level = 0.95, weights, ...)

Arguments

x

An object of class lyl_ci (obtained with function lyl_ci).

level

Confidence level (default is 0.95 for 95% confidence intervals)

weights

Vector with age distribution of disease/condition onset to be used when Life Years Lost are estimated over a range of ages (with lyl_range function).

...

Additional arguments affecting the plot produced.

Value

A plot with the evolution of bootstrapped parameters.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples


# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = death,
                      age_specific = 45, tau = 95)


# Calculate bootstrapped confidence interval (10 iterations to test)
lyl_estimation_ci <- lyl_ci(lyl_estimation, niter = 10)
plot(lyl_estimation_ci)

# Estimate remaining life expectancy and Life Years
# Lost after each age from 0 to 94 years and before age 95 years
lyl_estimation2 <- lyl_range(data = simu_data, t = age_death, status = death,
                             age_begin = 0, age_end = 94, tau = 95)

# Calculate bootstrapped confidence interval
lyl_estimation_ci2 <- lyl_ci(lyl_estimation2)
plot(lyl_estimation_ci2, weights = simu_data$age_disease)

Plot Life Years Lost at a range of different ages

Description

plot for objects of class lyl_range creates a figure of Life Years Lost at a range of different ages.

Usage

## S3 method for class 'lyl_range'
plot(x, colors = NA, ...)

Arguments

x

An object of class lyl_range (obtained with function lyl_range).

colors

Vector with one color for each cause of death. Default is NA, and default colors are used.

...

Additional arguments affecting the plot produced.

Value

A plot with age-specific life expectancy and life years lost.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)


# Estimate remaining life expectancy and Life Years
# Lost due to specific causes of death after each age
# from 30 to 40 years and before age 95 years
lyl_estimation <- lyl_range(data = simu_data, t = age_death, status = cause_death,
                             age_begin = 30, age_end = 40, tau = 95)

# Summarize and plot the data
plot(lyl_estimation)
plot(lyl_estimation, colors = c("chocolate", "cornflowerblue"))

# The plot can be modified with a usual ggplot2 format
plot(lyl_estimation) +
  ggplot2::xlab("Age [in years]") +
  ggplot2::ggtitle("Life Years Lost at ages 30-40 years")

Aggregated data for Life Years Lost estimation.

Description

A dataset containing age-specific survival probability and mortality rates for Danish women in years 2017-2018.

Usage

pop_ref

Format

A data frame with 100 rows and 3 variables:

age: age
survival: survival probability at that specific age
mortality_rates: age-specific mortality rates

Source

Statistics Danmark (https://www.dst.dk/en/Statistik/emner/befolkning-og-valg/)

Simulated population for Life Years Lost estimation.

Description

A dataset containing age and cause of death, as well as age at disease diagnosis (or start of a condition) for 100,000 simulated persons.

Usage

simu_data

Format

A data frame with 100000 rows and 6 variables:

id: unique identifier of each person
age_start: age at start of follow-up (0 for all individuals)
age_death: age at end of follow-up (death or censoring)
death: logical variable (TRUE = death / FALSE = censoring)
cause_death: factor variable with 3 levels: "Alive" (for those censored) and "Natural" and "Unnatural" (for those dying of natural and unnatural causes of death, respectively)
age_disease: age at developing a specific disease or condition for those 32,391 individuals that develop the disease (missing for the remaining 67,609)

Source

Simulated data

Summarize Life Years Lost at one specific age

Description

summary for objects of class lyl summarizes Life Years Lost at one specific age.

Usage

## S3 method for class 'lyl'
summary(object, decimals = 2, difference = FALSE, ...)

Arguments

object

An object of class lyl (obtained with function lyl).

decimals

Number of decimals to be reported (default is 2).

difference

Parameter automatically created by the package.

...

Additional arguments affecting the summary produced.

Value

A table with the summary of the results.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = death,
                      age_specific = 45, tau = 95)

# Summarize and plot the data
summary(lyl_estimation)

Summarize Life Years Lost at one specific age

Description

summary for objects of class lyl_aggregated summarizes Life Years Lost.

Usage

## S3 method for class 'lyl_aggregated'
summary(object, decimals = 2, ...)

Arguments

object

An object of class lyl_aggregated (obtained with function lyl_aggregated or lyl_aggregated_range).

decimals

Number of decimals to be reported (default is 2).

...

Additional arguments affecting the summary produced.

Value

A table with the summary of the results.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(aggreg_data)
data(pop_ref)

# Estimate remaining life expectancy and Life Years
# Lost after age 70 years and before age 90 years
lyl_summary_data70 <- lyl_aggregated(data = aggreg_data, age = age, rates = rate,
                                     data0 = pop_ref, age0 = age, surv0 = survival,
                                     age_specific = 70, tau = 90)

# Summarize and plot the data
summary(lyl_summary_data70)

Summarize Life Years Lost with confidence intervals

Description

summary for objects of class lyl_ci summarizes Life Years Lost at one specific age or over a range of different ages, including bootstrapped confidence intervals

Usage

## S3 method for class 'lyl_ci'
summary(
  object,
  decimals = 2,
  level = 0.95,
  weights = NA,
  difference = FALSE,
  ...
)

Arguments

object

An object of class lyl_ci (obtained with function lyl_ci).

decimals

Number of decimals to be reported (default is 2).

level

Confidence level (default is 0.95 for 95% confidence intervals)

weights

difference

Parameter automatically created by the package.

...

Additional arguments affecting the summary produced.

Value

A table with the summary of the results.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)

# Estimate remaining life expectancy and Life Years
# Lost after age 45 years and before age 95 years
lyl_estimation <- lyl(data = simu_data, t = age_death, status = death,
                      age_specific = 45, tau = 95)

# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation_ci <- lyl_ci(lyl_estimation, niter = 3)
summary(lyl_estimation_ci)


# Estimate remaining life expectancy and Life Years
# Lost after each age from 0 to 94 years and before age 95 years
lyl_estimation2 <- lyl_range(data = simu_data, t = age_death, status = death,
                             age_begin = 0, age_end = 94, tau = 95)

# Calculate bootstrapped confidence interval (3 iterations to test; more are necessary)
lyl_estimation_ci2 <- lyl_ci(lyl_estimation2, niter = 3)
summary(lyl_estimation_ci2, weights = simu_data$age_disease)

Summarize Life Years Lost over a range of differents ages

Description

summary for objects of class lyl_range summarizes Life Years Lost over a range of different ages.

Usage

## S3 method for class 'lyl_range'
summary(object, decimals = 2, weights = NA, difference = FALSE, ...)

Arguments

object

An object of class lyl_range (obtained with function lyl_range).

decimals

Number of decimals to be reported (default is 2).

weights

Vector with age distribution of disease/condition onset. If weights are not provided (dafault is weights = NA), then the differences in Life Years Lost at each age are summarized. If weights are provided, then a weighted average is provided.

difference

Parameter automatically created by the package.

...

Additional arguments affecting the summary produced.

Value

A table with the summary of the results.

References

Plana-Ripoll et al. lillies – An R package for the estimation of excess Life Years Lost among patients with a given disease or condition. PLoS ONE. 2020;15(3):e0228073.

Examples

# Load simulated data as example
data(simu_data)


# Estimate remaining life expectancy and Life Years
# Lost after each age from 0 to 94 years and before age 95 years
lyl_estimation <- lyl_range(data = simu_data, t = age_death, status = death,
                            age_begin = 0, age_end = 94, tau = 95)

# Visualize data at each different specific age
summary(lyl_estimation)

# Summarize data over an age distribution
summary(lyl_estimation, weights = simu_data$age_disease)

Simulated aggregated data for Life Years Lost estimation.

Description

Usage

Format

Source

Life Years Lost at one specific age.

Description

Usage

Arguments

Value

References

See Also

Examples

Plot Life Years Lost at one specific age for two different populations

Description

Usage

Arguments

Value

References

See Also

Examples

Life Years Lost at one specific age using aggregated data.

Description

Usage

Arguments

Value

References

See Also

Examples

Life Years Lost at a range of different ages using aggregated data.

Description

Usage

Arguments

Value

References

See Also

Examples

Plot number of persons at risk at each specific age.

Description

Usage

Arguments

Value

References

See Also

Examples

Confidence intervals for Life Years Lost.

Description

Usage

Arguments

Value

References

See Also

Examples

Plot Life Years Lost at one specific age for two or more different populations

Description

Usage

Arguments

Value

References

See Also

Examples

Summarize differences in Life Years Lost.

Description

Usage

Arguments

Value

References

See Also

Examples

Summarize differences in Life Years Lost.

Description

Usage

Arguments

Value

References

See Also

Examples

Life Years Lost at a range of different ages.

Description

Usage