Package {chestR}

chestR: Kernel-Weighted Cox Regression

Description

The chestR package implements kernel-weighted Cox regression for exploring treatment effect heterogeneity and identifying candidate predictive biomarkers. A global Cox model is re-fitted at each point on a biomarker grid using Gaussian (or inverse-square) kernel weights; local coefficient estimates are then visualised across biomarker space.

Details

The main workflow is:

1. Fit a global coxph model (base) including treatment and covariates.

2. Call chestr() with biomarker values to obtain local estimates on a grid.

3. Use plot.chestr() / plot(cr, trt.param = ...) to visualise a coefficient.

4. Optionally call chestr_test() for a permutation global test of treatment-effect heterogeneity.

Author(s)

Maintainer: Richard Jackson richj23@liverpool.ac.uk

Authors:

• Caroline Jeffery

See Also

chestr(), plot.chestr(), chestr_test()

Kernel-weighted Cox estimates over a biomarker grid

Description

Fits a weighted Cox model at each point on a biomarker grid. Observations near the grid point receive higher weight, yielding local estimates of treatment and covariate effects.

Usage

chestr(
  base,
  biom,
  grid.size = 25,
  method = c("distance", "square_distance", "legacy"),
  kern.adj = 4,
  bw = NULL,
  min_events_per_df = 10,
  treat_term = NULL
)

Arguments

Value

An object of class "chestr": a list with

• estimates: data.frame of grid coordinates, coefficients, SEs, ESS columns

• base: the fitted coxph model

• biom: biomarker data.frame used for weighting / plotting

• data: analysis data recovered from base when available (for permutation tests)

• treat_term: optional treatment coefficient name

• method, kern.adj, grid.size, min_events_per_df: fitting settings

See Also

plot.chestr(), chestr_test()

Examples

library(survival)
set.seed(1)
n <- 60
dat <- data.frame(
  time = rexp(n, 0.1), status = 1L,
  trt = rbinom(n, 1, 0.5), biom = rnorm(n)
)
dat$status <- as.integer(dat$time < 5)
dat$time[dat$status == 0L] <- 5
base <- coxph(Surv(time, status) ~ trt, data = dat)
cr <- chestr(base, dat$biom, grid.size = 5, min_events_per_df = 0,
             treat_term = "trt")
head(cr$estimates)
plot(cr, trt.param = "trt")

Permutation test for treatment-effect heterogeneity

Description

Tests the null that the treatment effect is constant over biomarker space by permuting treatment labels, re-fitting the global Cox model and chestr() surface, and comparing observed heterogeneity statistics to the permutation null.

Usage

chestr_test(
  x,
  treat_term = NULL,
  data = NULL,
  treat_var = NULL,
  B = 100,
  seed = NULL,
  reliable_only = TRUE
)

Arguments

Details

Where possible, arguments are taken from x:

• treat_term from x$treat_term (or inferred)

• data from x$data (stored by chestr() when recoverable)

• treat_var inferred from treat_term

• grid / kernel / ESS settings from x

Observed statistics are the ESS-weighted L2 deviation and the maximum standardised deviation of local treatment coefficients from the global coefficient.

Value

An object of class "chestr_test" with observed statistics, permutation p-values, and null draws.

See Also

chestr(), plot.chestr()

Examples

library(survival)
set.seed(1)
n <- 80
dat <- data.frame(
  time = rexp(n, 0.15), status = 1L,
  trt = rbinom(n, 1, 0.5),
  b1 = rnorm(n), b2 = rnorm(n)
)
dat$status <- as.integer(dat$time < 4)
dat$time[dat$status == 0L] <- 4
base <- coxph(Surv(time, status) ~ trt, data = dat)
cr <- chestr(base, dat[, c("b1", "b2")], grid.size = 5,
             min_events_per_df = 0, treat_term = "trt")
tst <- chestr_test(cr, B = 19, seed = 1)
tst

Plot local treatment effects from a chestr object

Description

Visualises a local coefficient stored in chestr() output using ggplot2. For two biomarkers, a coloured grid of local log-hazard ratios is shown (point size reflects local information). For a single biomarker, a line of local hazard ratios is shown with a dashed horizontal reference at the global hazard ratio from x$base. Model and biomarker data are taken from x itself.

Usage

## S3 method for class 'chestr'
plot(
  x,
  trt.param = NULL,
  pnt.scale = 3,
  col.scale = NULL,
  pts = TRUE,
  data_cex = 0.6,
  reliable_only = TRUE,
  ...
)

Arguments

Value

The ggplot object (invisibly).

See Also

chestr(), chestr_test()

Examples

library(survival)
set.seed(1)
n <- 60
dat <- data.frame(
  time = rexp(n, 0.1), status = 1L,
  trt = rbinom(n, 1, 0.5), biom = rnorm(n)
)
dat$status <- as.integer(dat$time < 5)
dat$time[dat$status == 0L] <- 5
base <- coxph(Surv(time, status) ~ trt, data = dat)
cr <- chestr(base, dat$biom, grid.size = 5, min_events_per_df = 0,
             treat_term = "trt")
head(cr$estimates)
plot(cr, trt.param = "trt")