bonsaiforest: Shrinkage Based Forest Plots

Description

Subgroup analyses are routinely performed in clinical trial analyses. From a methodological perspective, two key issues of subgroup analyses are multiplicity (even if only predefined subgroups are investigated) and the low sample sizes of subgroups which lead to highly variable estimates, see e.g. Yusuf et al (1991) doi:10.1001/jama.1991.03470010097038. This package implements subgroup estimates based on Bayesian shrinkage priors, see Carvalho et al (2019) https://proceedings.mlr.press/v5/carvalho09a.html. In addition, estimates based on penalized likelihood inference are available, based on Simon et al (2011) doi:10.18637/jss.v039.i05. The corresponding shrinkage based forest plots address the aforementioned issues and can complement standard forest plots in practical clinical trial analyses.

Author(s)

Maintainer: Isaac Gravestock isaac.gravestock@roche.com

Authors:

• Mar Vazquez Rabunal mar.vazquez_rabunal@roche.com

• Daniel Sabanés Bové daniel.sabanes_bove@roche.com

• Marcel Wolbers marcel.wolbers@roche.com

Other contributors:

• F. Hoffmann-La Roche AG [copyright holder, funder]

See Also

Useful links:

• https://github.com/insightsengineering/bonsaiforest/

• Report bugs at https://github.com/insightsengineering/bonsaiforest/issues

Average Hazard Ratio Estimation

Description

Function to obtain the average hazard ratio.

Usage

ahr_estimation(x_subg, dummy_subg, est_coef, h0, gamma = 1)

Arguments

Value

Average hazard ratio

Examples

ahr_estimation(
  elastic_net_surv$design1, elastic_net_surv$dummy1,
  elastic_net_surv$est_coef, elastic_net_surv$h0
)

Average Hazard Estimation based on Kaplan-Meier Estimates

Description

Average Hazard Estimation based on Kaplan-Meier Estimates

Usage

ahr_from_km(resp, trt, data, status, t_quantile = 0.99)

Arguments

Details

Estimates can be unstable due to the variability of the Kaplan-Meier estimates in the tails. The t_quantile argument can address this, e.g. by setting it to 0.95, the 5% highest times will be discarded. By default, the 1% highest times are discarded.

Value

The estimated average hazard ratio of the treatment (second level of trt) versus the control (first level of trt).

Examples

ahr_from_km("tt_pfs", "arm", example_data, "ev_pfs")
ahr_from_km("tt_pfs", "arm", example_data, "ev_pfs", t_quantile = 0.95)

Compare Treatment Estimate Methods

Description

Function to create a data set with the results for all the methods in order to compare them.

Usage

compare(...)

Arguments

Value

List with a data.frame of the estimated subgroup treatment effects, with the overall treatment effect and with the response type of our data.

Examples

compare(naivepop_fit_surv, naive_fit_surv, elastic_net_fit_surv)

Helper for Cutting into Normal Quantiles

Description

Helper for Cutting into Normal Quantiles

Usage

cut_norm_quant(x, prob, labels = letters[seq_along(c(prob, 1))])

Arguments

Value

The factor variable.

Design Dummy Subgroup x_1a

Description

The dummy design matrix from example_data considering just observations from subgroup x_1a.

Usage

design_dummy1

Format

A matrix with 0 and 1 indicating the subgroups of each of the observations.

Source

This is an artificial example.

Design Matrix Subgroup x_1a

Description

The design matrix from example_data considering just observations from subgroup x_1a.

Usage

design_matrix1

Format

A matrix with 0 and 1 indicating the subgroups of each of the observations and their interactions with the treatment variable.

Source

This is an artificial example.

Elastic Net Penalization Model Estimation

Description

Function to fit the elastic net penalization model to the data. This model penalizes the interaction between the covariates and the treatment but leaves unpenalized the main effects.

Usage

elastic_net(
  resp,
  trt,
  subgr,
  covars,
  data,
  resptype = c("survival", "binary"),
  alpha,
  status = NULL
)

Arguments

Value

List with fit, model, resptype, data, alpha, design_matrix, design_dummy, y, subgr_names.

Examples

elastic_net(
  "tt_pfs", "arm", c("x_1", "x_2"), c("x_1", "x_2", "x_3"),
  example_data, "survival", 1, "ev_pfs"
)

Elastic Net Fit Binary

Description

A fitted model with the elastic_net function and binary data.

Usage

elastic_net_fit_bin

Format

A elastic_net object fitted with example_data, considering as subgroup variables all the covariates x_1, ..., x_10 and binary response type.

Source

This is an artificial example.

Elastic Net Fit Survival

Description

A fitted model with the elastic_net function and survival data.

Usage

elastic_net_fit_surv

Format

A elastic_net object fitted with example_data, considering as subgroup variables all the covariates x_1, ..., x_10 and survival response type.

Source

This is an artificial example.

H0, Coefficients Elastic Net Survival Model and Matrices

Description

List with the cumulative baseline hazard, with the estimated coefficients of the model fitted with an elastic net and survival data, with the general design matrix and with the design and dummy matrices for subgroup x_1a.

Usage

elastic_net_surv

Format

A list with three elements:

• h0: the cumulative baseline hazard.

• est_coef: the estimated coefficients of the fitted model.

• x: the design matrix of the model.

• dummy1: the dummy matrix of the model for subgroup x_1a.

• design1: the design matrix of the model for subgroup x_1a.

Source

This is an artificial example.

Estimated coefficients elastic net Binary

Description

The coefficients of the model elastic_net_fit_bin when lambda takes the value that leads to minimal cross validation error.

Usage

est_coef_bin1

Format

A matrix with the coefficients of the elastic net model.

Source

This is an artificial example.

Example data

Description

A simulated data set for a realistic scenario of a clinical trial.

Usage

example_data

Format

A data.frame with 1000 rows and 14 columns:

• id: Integer variable with the id of the patient.

• arm: Factor variable with 2 levels: control and treatment.

• x_1, x_2, x_3, x_4, x_5, x_6, x_7, x_8, x_9, x_10: Factor variables that represent covariates of the patients (e.g. sex, region, race, etc.).

• tt_pfs: Continuous variable with the progression free survival time of each patient.

• ev_pfs: Binary variable with the progression free survival status of each patient. 0 indicates that the event of interest did not happen and 1 indicates that it did.

Source

This is an artificial dataset.

Generation of Stacked Data by Subgroups

Description

Function to generate stacked data by the subgroups considered in the model.

Usage

generate_stacked_data(
  base_model,
  subgroup_model,
  data,
  resptype = c("survival", "binary")
)

Arguments

Value

Data frame of the stacked data.

Examples

generate_stacked_data(Surv(tt_pfs, ev_pfs) ~ arm, ~ x_1 + x_2, example_data, "survival")

Bayesian Shrinkage Model Estimation

Description

Function to fit a bayesian shrinkage model with a regularized horseshoe prior on the interaction coefficients between the subgrouping covariates and the treatment.

Usage

horseshoe(
  resp,
  trt,
  subgr,
  covars,
  data,
  resptype = c("survival", "binary"),
  status = NULL,
  ...
)

Arguments

Value

List with fit, model, resptype, data, alpha, design_matrix, design_dummy, y, subgr_names.

Examples

horseshoe("ev_pfs", "arm", c("x_1", "x_2"), c("x_1", "x_2", "x_3"),
  example_data, "binary",
  chains = 1, seed = 0, control = list(adapt_delta = 0.95),
  iter = 50 # In practice, you need to omit this or set it much higher!
)

Horseshoe Fit Binary

Description

A fitted model with the horseshoe function and binary data.

Usage

horseshoe_fit_bin

Format

A horseshoe object fitted with example_data, considering as subgroup variables just the covariates x_1 and x_2 and binary response type.

Source

This is an artificial example.

Horseshoe Fit Survival

Description

A fitted model with the horseshoe function and survival data.

Usage

horseshoe_fit_surv

Format

A horseshoe object fitted with example_data, considering as subgroup variables just the covariates x_1 and x_2 and survival response type.

Source

This is an artificial example.

Helper Function to get Kaplan-Meier Estimate

Description

Helper Function to get Kaplan-Meier Estimate

Usage

km_fun(resp, status, data, times)

Arguments

Value

Numeric vector with Kaplan-Meier estimates at times.

Estimation of Log-Odds Ratio

Description

Function to estimate the subgroup log-odds ratio for binary data.

Usage

lor_estimation(x_subg, dummy_subg, est_coef)

Arguments

Value

Log-odds ratio of the studied subgroup.

Examples

lor_estimation(design_matrix1, design_dummy1, est_coef_bin1)

Naive Model Estimation

Description

Function to fit the naive models to the data of each one of the subgroups.

Usage

naive(
  resp,
  trt,
  subgr,
  data,
  resptype = c("survival", "binary"),
  status = NULL
)

Arguments

Value

List with fit, estimates, model, resptype, data.

Examples

naive("tt_pfs", "arm", c("x_1", "x_2"), example_data, "survival", "ev_pfs")

Naive Fit Binary

Description

A fitted model with the naive function and binary data.

Usage

naive_fit_bin

Format

A naive object fitted with example_data, considering as subgroup variables all the covariates x_1, ..., x_10 and binary response type.

Source

This is an artificial example.

Naive Fit Survival

Description

A fitted model with the naive function and survival data.

Usage

naive_fit_surv

Format

A naive object fitted with example_data, considering as subgroup variables all the covariates x_1, ..., x_10 and survival response type.

Source

This is an artificial example.

Naive Overall Population Model Estimation

Description

Function to fit the naive overall population model to the data. This model is going to estimate the subgroup treatment effects with the overall population treatment effect.

Usage

naivepop(resp, trt, data, resptype = c("survival", "binary"), status = NULL)

Arguments

Value

List with fit, model, resptype, data.

Examples

naivepop("tt_pfs", "arm", example_data, "survival", "ev_pfs")

Naivepop Fit Binary

Description

A fitted model with the naivepop function and binary data.

Usage

naivepop_fit_bin

Format

A naivepop object fitted with example_data, considering as subgroup variables all the covariates x_1, ..., x_10 and binary response type.

Source

This is an artificial example.

Naivepop Fit Survival

Description

A fitted model with the naivepop function and survival data.

Usage

naivepop_fit_surv

Format

A naivepop object fitted with example_data, considering as subgroup variables all the covariates x_1, ..., x_10 and survival response type.

Source

This is an artificial example.

Compare Forest Plots

Description

Function to obtain a forest plot with all the different fitted models in order to compare their performance.

Usage

## S3 method for class 'compare.data'
plot(x, ...)

Arguments

Value

Forest plot with all the methods that are compared.

Examples

plot(compare(naivepop_fit_surv, naive_fit_surv, elastic_net_fit_surv))

Forest plot Summary Elastic Net

Description

Plot the forest plot of the summary of a elastic_net object.

Usage

## S3 method for class 'summary.elastic_net'
plot(x, ...)

Arguments

Value

Forest plot

Examples

plot(summary(elastic_net_fit_surv))

Forest plot Summary Horseshoe

Description

Plot the forest plot of the summary of a horseshoe object.

Usage

## S3 method for class 'summary.horseshoe'
plot(x, ...)

Arguments

Value

Forest plot

Examples

plot(summary(horseshoe_fit_bin))

Forest plot Summary Naive

Description

Plot the forest plot of the summary of a naive object.

Usage

## S3 method for class 'summary.naive'
plot(x, ...)

Arguments

Value

Forest plot

Examples

plot(summary(naive_fit_surv))

Data Preprocessing

Description

Function to preprocess the data and obtain the design matrices corresponding to a model with just interaction of the covariates with the treatment, to a model with just the main effects and to a model just with the covariates and one-hot encoding.

Usage

preprocess(trt, subgr, covars, data)

Arguments

Value

List with design_ia, design_main, design_dummy, subgr_names.

Examples

preprocess("arm", c("x_1", "x_2"), c("x_1", "x_2", "x_3"), example_data)

Print Function for Elastic Net Summary

Description

Function that prints the summary of a elastic_net object

Usage

## S3 method for class 'summary.elastic_net'
print(x, ...)

Arguments

Value

The summary of the object.

Examples

print(summary(elastic_net_fit_bin))

Print Function for Horseshoe Summary

Description

Function that prints the summary of a horseshoe object

Usage

## S3 method for class 'summary.horseshoe'
print(x, ...)

Arguments

Value

The summary of the object.

Examples

print(summary(horseshoe_fit_bin))

Print Function for Naive Summary

Description

Function that prints the summary of a naive object

Usage

## S3 method for class 'summary.naive'
print(x, ...)

Arguments

Value

The summary of the object.

Examples

print(summary(naive_fit_bin))

Print Function for Naivepop Summary

Description

Function that prints the summary of a naivepop object

Usage

## S3 method for class 'summary.naivepop'
print(x, ...)

Arguments

Value

The summary of the object.

Examples

print(summary(naivepop_fit_bin))

Generation of a Design Matrix for Simulations

Description

This function uses a block diagonal covariance matrix for the underlying multivariate normal data to create the design matrix in blocks of 10, see the details.

Usage

simul_covariates(n, p_catvar = 10, add_contvars = FALSE, arm_factor = FALSE)

Arguments

Details

The following pattern is repeated for the covariate blocks:

• The first 5 covariates are uncorrelated with everything.

• The covariates 6 to 8 have "moderate" correlation (0.25) between each other.

• The covariates 9 and 10 have "high" correlation (0.5).

By default, only the resulting categorical covariates obtained by thresholding are included. Optionally also the original continuous covariates are included in the returned design matrix.

Value

The design matrix.

Examples

simul_covariates(n = 10, p_catvar = 3, add_contvars = FALSE)
simul_covariates(n = 10, p_catvar = 3, add_contvars = TRUE)
simul_covariates(n = 10, p_catvar = 3, add_contvars = TRUE, arm_factor = TRUE)

Simulate Covariates and Progression Free Survival Data

Description

This combines the covariates simulation via simul_covariates() with 10 categorical covariates, and the PFS simulation via simul_pfs().

Usage

simul_data(n, add_interaction = FALSE, coefs, ...)

Arguments

Details

Regression coefficients are for an AFT with over-parametrized dummy coding for arm-subgroup interactions.

Value

A combined data.frame with the id column, the design matrix and the PFS outcomes.

Examples

set.seed(321)
simul_data(
  n = 100,
  coefs = c(arm1 = 1),
  sigma_aft = 1,
  recr_duration = 0.2,
  rate_cens = 2,
  n_events = 20
)

Simulation of Progression Free Survival Times

Description

Simulation of Progression Free Survival Times

Usage

simul_pfs(
  lp_aft,
  sigma_aft,
  recr_duration,
  rate_cens,
  n_events,
  add_uncensored_pfs = FALSE
)

Arguments

Value

A data.frame with columns tt_pfs (PFS time) and ev_pfs (corresponding event indicator with 1 for an event and 0 for censored), and optionally tt_pfs_uncens.

Examples

set.seed(123)
simul_pfs(
  lp_aft = rnorm(100),
  sigma_aft = 1,
  recr_duration = 0.2,
  rate_cens = 2,
  n_events = 20
)

Subgroup Treatment Effect

Description

Function to obtain the estimated treatment effect in each one of the considered subgroups.

Usage

subgroups(object, est_coef, h0 = NULL, gamma = 1)

Arguments

Value

data.frame with the subgroup names and with the estimated subgroup treatment effects.

Examples

subgroups(
  elastic_net_fit_surv, elastic_net_surv$est_coef,
  elastic_net_surv$h0
)

Summary Elastic Net Function

Description

Function to obtain the naive subgroup treatment effects of an object fitted with the elastic_net function.

Usage

## S3 method for class 'elastic_net'
summary(object, gamma = 1, l = NULL, lambda = NULL, ...)

Arguments

Value

Object of class summary.elastic_net which is a list with the estimated subgroup treatment effects, the resptype, the confidence level and the value of alpha.

Examples

summary(elastic_net_fit_surv)

Summary Horseshoe Function

Description

Function to obtain the estimated subgroup treatment effects from a horseshoe model and a credible interval for them.

Usage

## S3 method for class 'horseshoe'
summary(object, conf = 0.95, gamma = 1, l = NULL, m = 50, ...)

Arguments

Value

Object of class summary.horseshoe which is a list with the approximated posterior distribution of the treatment effects, a data.frame with the estimated subgroup treatment effect (with the median) and the bounds of the credible intervals, the resptype and the confidence level.

Examples

summary(horseshoe_fit_bin)

Summary Naive

Description

Function to obtain the naive subgroup treatment effects of an object fitted with the naive function.

Usage

## S3 method for class 'naive'
summary(object, conf = 0.95, ...)

Arguments

Value

Object of class summary.elastic_net which is a list with a data.frame with 4 columns (the subgroup variables, the estimated treatment effect and the low and high bounds of the confidence interval of the treatment effect), the resptype and the confidence level.

Examples

summary(naive_fit_surv)

Summary Naivepop Function

Description

Function to obtain the overall subgroup treatment effect of a naivepop object.

Usage

## S3 method for class 'naivepop'
summary(object, ...)

Arguments

Value

Object of class summary.naivepop which is a list with the estimated subgroup treatment effects and the resptype.

Examples

summary(naivepop_fit_surv)

Average Survival Curves

Description

Function to obtain the average survival curve from all individual survival curves.

Usage

survival_curves(x, h0, est_coef)

Arguments

Value

The survival probabilities at the sorted event times.

Examples

survival_curves(
  elastic_net_surv$x, elastic_net_surv$h0,
  elastic_net_surv$est_coef
)

Subgroup Treatment Effect Horseshoe

Description

Function to obtain the estimated posterior distribution of the subgroup treatment effects considering a horseshoe fitted model.

Usage

trt_horseshoe(object, gamma = 1, l = NULL, m = 50)

Arguments

Value

Approximated posterior distribution of the subgroup treatment effects.

Examples

trt_horseshoe(horseshoe_fit_surv, m = 1)