ClockSHAP decomposition

Decompose age deviation into exact, age-conditioned feature contributions for a linear aging clock.

Usage

clockshap(features, age, clock, reference, max_age = NULL)

Arguments

features

A matrix or data.frame of feature values (samples x features).

age

Numeric vector of chronological ages (length = nrow(features)). If sample identifiers are provided (rownames(features) and names(age)), they must match exactly and in the same order.

clock

A linear_clock object.

reference

A reference_profile object.

max_age

Optional numeric scalar. Samples with age > max_age are treated as out of reference range and return NA for expected, deviation, and phi.

Value

An object of class clockshap containing per-feature contributions, deviation values, and metadata.

Examples

set.seed(1)

features <- matrix(rnorm(20), nrow = 5, ncol = 4)
colnames(features) <- paste0("F", 1:4)
age <- c(40, 50, 60, 70, 80)

clock <- linear_clock(
  alpha = 10,
  beta  = setNames(runif(4), colnames(features)),
  mu    = setNames(rep(0, 4), colnames(features)),
  sigma = setNames(rep(1, 4), colnames(features))
)

ref <- fit_reference_profile(
  features = as.data.frame(features),
  age = age
)

cs <- clockshap(features, age, clock, ref)
cs
#> <ClockSHAP object>
#>   Samples : 5 
#>   Features: 4 
#> 
#>   Deviation range:
#>     Min: -0.65 
#>     Max: 0.483 
summary(cs)
#> $n_samples
#> [1] 5
#> 
#> $n_features
#> [1] 4
#> 
#> $deviation
#>     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
#> -0.65025 -0.27286  0.03142  0.00000  0.40913  0.48255 
#> 
#> $age
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>      40      50      60      60      70      80 
#>