Package {shapleyHALE}

Title: Shapley Value Decomposition of Health-Adjusted Life Expectancy
Version: 0.1.0
Description: Implements a Shapley-value framework to decompose changes in health-adjusted life expectancy (HALE) into additive contributions of individual diseases or causes, fully accounting for higher-order interactions. Separates mortality and disability effects and provides second-order Shapley interaction indices. Uncertainty is propagated via parametric bootstrap.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
Imports: data.table, foreach, doParallel, stats
Suggests: testthat (≥ 3.0.0), ggplot2, knitr, rmarkdown
VignetteBuilder: knitr
Depends: R (≥ 3.5)
Config/testthat/edition: 3
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-21 05:25:11 UTC; admin
Author: Jun-Yan Xi ORCID iD [aut, cre] (affiliation: Sun Yat-sen University)
Maintainer: Jun-Yan Xi <xijy3@mail2.sysu.edu.cn>
Repository: CRAN
Date/Publication: 2026-07-30 16:10:01 UTC

Example age group information

Description

Matches the age groups in demo_gbd.

Usage

age_info_demo

Format

A data.table with columns:

age_id

numeric age group ID

age_start

start of interval

width

interval width (years)

Align matrix columns to a full set of cause IDs

Description

Align matrix columns to a full set of cause IDs

Usage

align_mat(mat, full)

Arguments

mat

matrix

full

character vector of all column names

Value

matrix with columns ordered as 'full', missing columns filled with 0

Parametric bootstrap Shapley decomposition

Description

Performs bootstrap uncertainty analysis by sampling rates from triangular distributions defined by point estimates and 95

Usage

bootstrap_shapley(
  deaths_data,
  ylds_data,
  base_year,
  target_year,
  cause_ids,
  age_ids,
  ages_info,
  n_boot = 1000,
  n_perm_inner = 5000,
  parallel = FALSE,
  n_cores = NULL
)

Arguments

deaths_data

data.table with mortality rates (cols: year, cause_id, age_id, val, lower, upper)

ylds_data

data.table with YLD rates (same structure)

base_year

baseline year

target_year

target year

cause_ids

character vector of cause IDs

age_ids

numeric vector of age IDs in correct order

ages_info

data.frame with age_start and width, matching age_ids

n_boot

number of bootstrap iterations (default 1000)

n_perm_inner

number of Shapley permutations per bootstrap (default 5000)

parallel

logical, use parallel processing?

n_cores

number of cores (NULL = detectCores()-1)

Value

list containing point estimates and bootstrap summaries

Compute health-adjusted life expectancy

Description

Sullivan method combining mortality and YLD rates.

Usage

compute_hale(mx, yld_rate, ages)

Arguments

mx

numeric vector of age-specific mortality rates (per person-year)

yld_rate

numeric vector of YLD rates (per person-year)

ages

data.frame with columns 'age_start' and 'width'

Value

list containing HALE0 and LE0

Examples

ages <- data.frame(age_start = c(0,1,5), width = c(1,4,5))
compute_hale(c(0.01,0.02,0.05), c(0.1,0.1,0.1), ages)

Second-order Shapley interaction indices

Description

Quantifies pairwise synergies/antagonisms among the leading causes.

Usage

compute_shapley_interactions(
  base_mx,
  base_yld,
  target_mx,
  target_yld,
  causes,
  ages,
  top_n = 20,
  n_perm = 1000,
  point_est = NULL
)

Arguments

base_mx

matrix, baseline mortality rates

base_yld

matrix, baseline YLD rates

target_mx

matrix, target mortality rates

target_yld

matrix, target YLD rates

causes

character vector of all cause IDs

ages

data.frame with age_start and width

top_n

number of leading causes to consider (default 20)

n_perm

number of permutations (default 1000)

point_est

optional named vector of total Shapley values (for ranking)

Value

data.table with columns cause_A, cause_B, interaction

Create cause-rate matrix from GBD-style data.table

Description

Create cause-rate matrix from GBD-style data.table

Usage

create_rate_matrix(data, year_val, cause_ids, age_ids)

Arguments

data

data.table with columns year, cause_id, age_id, val

year_val

numeric year

cause_ids

character vector of cause IDs

age_ids

numeric vector of age IDs in correct order

Value

matrix (ages x causes)

Demo GBD rates (simulated)

Description

A small simulated dataset mimicking GBD cause-specific mortality and YLD rates.

Usage

demo_gbd

Format

A data.table with columns:

measure_id

1 = mortality, 3 = YLD

sex_id

3 = both sexes

year

1990 or 2023

cause_id

character cause identifier

cause_name

cause name

age_id

numeric age group ID

val

point estimate (rate)

upper

upper 95% UI

lower

lower 95% UI

Source

Simulated for package examples.

Triangular random number generator

Description

Triangular random number generator

Usage

rtriang(n, a, b, c)

Arguments

n

number of observations

a

lower limit

b

upper limit

c

mode

Value

numeric vector

Shapley decomposition of HALE change

Description

Decomposes the HALE change between baseline and target into additive contributions of individual causes, separating mortality and disability effects.

Usage

run_shapley_decomp(
  base_mx,
  base_yld,
  target_mx,
  target_yld,
  causes = NULL,
  ages,
  n_perm = 5000
)

Arguments

base_mx

matrix of baseline mortality rates (age x cause)

base_yld

matrix of baseline YLD rates (age x cause)

target_mx

matrix of target mortality rates

target_yld

matrix of target YLD rates

causes

character vector of cause IDs (column names)

ages

data.frame with 'age_start' and 'width'

n_perm

number of random permutations (default 5000)

Value

list with total_change, total_effect, death_effect, disability_effect