Help for package BayesFBHborrow

Title:

Bayesian Dynamic Borrowing with Flexible Baseline Hazard Function

Version:

2.0.9

Description:

Allows Bayesian borrowing from a historical dataset for time-to- event data. A flexible baseline hazard function is achieved via a piecewise exponential likelihood with time varying split points and smoothing prior on the historic baseline hazards. The method is described in Scott and Lewin (2026) <doi:10.1093/biostatistics/kxag006>, and a paper focused on the software is in Scott, Axillus, Lewin and Izmirlian (2026) <doi:10.48550/arXiv.2408.04327>.

License:

Apache License (≥ 2)

Encoding:

UTF-8

Suggests:

tibble, readxl, testthat (≥ 3.0.0), rmarkdown, ggfortify, condSURV

Config/testthat/edition:

Imports:

rlang, dplyr, invgamma, mvtnorm, checkmate, magrittr, ggplot2, patchwork, kableExtra, stats, survival, survminer, extraDistr, bayestestR

Depends:

R (≥ 4.1)

NeedsCompilation:

Packaged:

2026-06-19 19:44:10 UTC; kthj862

Author:

Darren Scott [aut], Sophia Axillus [aut], Grant Izmirlian [aut, cre]

Maintainer:

Grant Izmirlian <grant.izmirlian@astrazeneca.com>

Repository:

CRAN

Date/Publication:

2026-06-20 17:50:08 UTC

Fit the Bayesian Flexible Baseline Hazard Model with Borrowing via MCMC/MH

Description

Fits the Bayesian Flexible Baseline Hazard Model with Borrowing via MCMC/MH. Each sample in the Gibbs sampler is a piecewise exponential model, with prior over number and location of split points. Accommodates borrowing over a historical control arm as well as G-computation.

Usage

BayesFBHborrow(formula = NULL, data, data_hist = NULL, subset, na.action,
               CntlOnly = FALSE, model_choice = "mix", tuning_parameters = NULL,
               hyperparameters = NULL, iter = 1000, warmup_iter = 100,
               refresh = 0, verbose = FALSE, max_grid = 2000, standardise = TRUE,
               G_compute = FALSE, preprocess = TRUE, fnm_cnd_blh = "cnd_blh",
               fnm_mgnl_haz0 = "mgnl_haz0", fnm_mgnl_haz1 = "mgnl_haz1",
               dbg = FALSE, ...)

Arguments

formula

Optional but most likely preferred. When using the formula/data interface, specify the formula in the form typically used in other survival models e.g. Surv(TOS, Event) ~ Trt + Oth + Covs + etc The first listed covariate must be the treatment variable. The rest can be continuous or factor.

data

Required. The current trial/study data.frame with a treated and a control arm. For the formula/data interface, there is no naming convention for variables as the user specifies these with the formula. For the data only interface, you must name the time to event variable 'tte', and the event variable 'event'. All covariates including the treatment indicator must have the 'X_' prefix.

data_hist

When fitting the full model with borrowing, the historical controls data.frame with variables named to agree with the current trial data.frame specified in the 'data' argument. Comments above regarding the formula/data versus data only interface apply here as well.

subset

When using the formula/data interface, you may also use subset and na.action as you do in other statistical routines in R.

na.action

When using the formula/data interface, you may also use subset and na.action as you do in other statistical routines in R.

CntlOnly

Set to TRUE when running the model with on the historical controls dataset only. The default value is FALSE.

model_choice

Borrowing method. Determine the borrowing per split point by specifying the option "mix" (default) for a mixture of inverse gamma densities or "uni" for a single inverse gamma density. Otherwise, determine the borrowing once for all split points by specifying the option "all".

tuning_parameters

list with components cprop_beta (cprop_beta_0 for historical data), a_lambda, b_lambda, pi_b and alpha. Default is list(cprop_beta=1.1, cprop_beta_0=1.1, a_lambda=0.01, b_lambda=0.01, pi_b=0.5, alpha=0.4). The most important for the user are cprop_beta and cprop_beta_0. Starting at the default values, the user must adjust these values up or down in a series of test runs (iter=200) so that beta_acc_ratio and beta_0_acc_ratio (in the output list) are between 0.3 and 0.4. The relationship between cprop_beta parameters and the acceptance ratios is inverse.

hyperparameters

list with components beta_prior, beta_0_prior, a_tau, b_tau, c_tau, d_tau, type, p_0, a_sigma, b_sigma, phi, clam_smooth, Jmax. Default is list(beta_prior=10^2, beta_0_prior=10^2, a_tau=1, b_tau=0.001, c_tau=1, d_tau=5, type="mix", p_0=0.8, a_sigma=1, b_sigma=1, phi=3, clam_smooth=0.7, Jmax=5).

iter

Number of iterations for MCMC sampler.

warmup_iter

Number of warmup iterations (burn-in) for MCMC sampler.

refresh

Number of iterations between printed screen updates.

verbose

Whether or not to print the progress to the console every refresh iterations. Defaults to FALSE.

max_grid

Grid size for the smoothed baseline hazard. Default value is 2000.

standardise

Whether or not to normalize the current trial baseline hazard to unity and apply the same normalization constant to the historical data. Default is TRUE.

G_compute

If set to TRUE when treatment effect and pretreatment covariates are entered into the model (current trial only or current trial with borrowing), results are displayed as a marginal estimand computed via g-computation. This setting affects the behavior of the 'coef' and 'summary' methods and thus the 'print' method. The default is FALSE which results in display of a conditional estimand.

preprocess

Controls the interpretation of the 'baseline' hazard consequent to recoding of the input dataset(s). When set to TRUE, all continuous variables will be centered at their mean over the dataset in the data argument, and factor variables will be centered to their mean under a hypothetical design having balanced levels for each factor. This defaults to TRUE and works with either the formula/data interface or the data only interface. If complete control over recoding is desired, one must use the data only interface together with preprocess=FALSE. This is the only way to include interactions.

fnm_cnd_blh

Binary files generated during run time which are given a default name prefix with a random hex suffix. The collection of "snapped to common grid" samples from the posterior distribution of the baseline hazards is a matrix of dimension max_grid by iter. Adding updated columns to this very large matrix would result in memory caching and for this reason, these are written out to binary files during the run of the MCMC, and then read back in during the final sumarization. This file is for the conditional baseline hazard. These files are available to the user for computing any functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function.

fnm_mgnl_haz0

Binary files generated during run time which are given a default name prefix with a random hex suffix. The collection of "snapped to common grid" samples from the posterior distribution of the baseline hazards is a matrix of dimension max_grid by iter. Adding updated columns to this very large matrix would result in memory caching and for this reason, these are written out to binary files during the run of the MCMC, and then read back in during the final sumarization. This file is for the control arm log-log marginal hazard. These files are available to the user for computing any functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function.

fnm_mgnl_haz1

Binary files generated during run time which are given a default name prefix with a random hex suffix. The collection of "snapped to common grid" samples from the posterior distribution of the baseline hazards is a matrix of dimension max_grid by iter. Adding updated columns to this very large matrix would result in memory caching and for this reason, these are written out to binary files during the run of the MCMC, and then read back in during the final sumarization. This file is for the treated arm log-log marginal hazard. These files are available to the user for computing any functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function.

dbg

When running in command line mode, set to TRUE in order to enable line by line debugging.

...

Other arguments as needed.

Details

BayesFBHborrow implements our semiparametric Bayesian borrowing model allowing inferences on a current trial with commensurate Bayesian borrowing from a set of historical controls. The model supports covariate adjusted borrowing, which can reduce prior-data conflict and improve power when differences in outcomes are attributable to changes in covariate distribution. As the treatment effect estimator is non-collapsible, the marginal hazard ratio can be estimated via Bayesian G-computation, while still permitting an adjusted analysis to account for control group drift.

Value

Y

Times on study in the 'data' argument data.frame, scaled to unit event rate.

I

Event indicators in the 'data' argument data.frame

X

Treatment indicator and pretreatment covariates in the 'data' argument data.frame, recoded if 'prepocess' is TRUE.

Y_0

Times on study in the 'data_hist' argument data.frame, scaled to unit event rate.

I_0

Event indicators in the 'data_hist' argument data.frame

X_0

Pretreatment covariates in the 'data_hist' argument data.frame, recoded if 'prepocess' is TRUE.

samples

An 'iter' by ncol(X) + 3*J + 4 matrix containing all post warmup samples from the MCMC sampler: the model coefficients, the number of split points, hyperparameters mu and sigma2, the locations of all split points and the values of the piecewise exponential hazards corresponding to the current trial and to the historical controls data distributions.

surv_dat

Median together with 95 percent credible interval of posterior samples of the per arm conditional hazards/survival functions, per arm marginal hazard/survival functions, and marginal treatment effect at each time point on the fine meshed grid of length 'max_grid'.

MTE_dens_dfs

kernel density estimates for samples of the posterior distribution of the marginal treatment effect at information fraction 25, 50, 75 and 100 percent.

T.if

Times on study at 25, 50, 75 and 100 percent information.

fnms

File names of binary files of snapped to fine meshed grid hazard function samples from the posterior. Provided for calculating custom functionals of the hazard function posterior distribution.

beta_acc_ratio

Metropolis-Hastings algorithm acceptance ratio for current data model coefficients. Find value of cprop_beta in tuning_parameters which results in this being between 0.30 and 0.40.

beta_0_acc_ratio

Metropolis-Hastings algorithm acceptance ratio for historical data model coefficients. Find value of cprop_beta in tuning_parameters which results in this being between 0.30 and 0.40.

call

The call which produced the object.

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Scott DAV, Axillus S, Lewin A and Izmirlian G. BayesFBHborrow: An R Package for Bayesian borrowing for time-to-event data from a flexible baseline hazard function (2026) <doi:10.48550/arXiv.2408.04327>

Examples

n_cc_1 <- 200
n_cc_0 <- 100
n_hst <- 100
int_cc <- int_hst <- -log(3)
B_x_cc <- B_x_hst <- c(-0.3,0.5,0.25,-0.5)
B_trt <- log(0.55)

dat_lst <- 
    genBFBHBdat(n_cc_1=200, n_cc_0=100, n_hst=100,
                B_trt=B_trt, B_x_cc=B_x_cc, B_x_hst=B_x_hst, 
                int_cc=int_cc, int_hst=int_hst, shape=2,
                t_er=0.5, t_fin=1.5, X_fact_levs=3)

DAT_cc <- dat_lst$DAT_cc
DAT_hst <- dat_lst$DAT_hst

## using default settings for hyperparameters and tuning parameters
## formula interface
## cntls only; no cov's
  ## Not run: 
    test_f0 <- BayesFBHborrow(Surv(tte, event)~1, data = DAT_hst,
                              CntlOnly=TRUE, iter = 200, warmup_iter = 50,
                              refresh = 0, verbose = FALSE)

    ## cntls only; with cov's
    test_f1 <- BayesFBHborrow(Surv(tte, event) ~ X_01 + X_02 + X_03,
                              data = DAT_hst, CntlOnly=TRUE,
                              iter = 200, warmup_iter = 50, refresh = 0,
                              verbose = FALSE)
    
    ##  trtd+cntls; w/o borrow; no cov's: 
    test_f2 <- BayesFBHborrow(Surv(tte, event) ~ X_trt, data = DAT_cc,
                              iter = 200, warmup_iter = 50, refresh = 0,
                              verbose = FALSE)
    
    ## trtd+cntls; w borrow, no cov's:
    test_f3 <- BayesFBHborrow(Surv(tte, event) ~ X_trt, data = DAT_cc,
                              data_hist = DAT_hst, model_choice = 'mix',
                              iter = 200, warmup_iter = 50, refresh = 0,
                              verbose = FALSE)

    ##  trtd+cntls; w/o borrow; w cov's: 
    test_f4 <- BayesFBHborrow(Surv(tte, event) ~ X_trt + X_01 + X_02 + X_03,
                              data = DAT_cc, model_choice = 'mix',
                              iter = 200, warmup_iter = 50, refresh = 0,
                              verbose = FALSE)
    
    ## trtd+cntls; w borrow, w cov's:
    test_f5 <- BayesFBHborrow(Surv(tte, event) ~ X_trt + X_01 + X_02 + X_03,
                              data = DAT_cc, data_hist = DAT_hst,
                              model_choice = 'mix', iter = 10, warmup_iter = 5,
                              refresh = 0, verbose = FALSE)
  
## End(Not run)

An Method for Easily Combining Two Similar BayesFBHborrow Plots

Description

Combines two survival/hazard plots side by side or two TrtEff density plots atop one another.

Usage

  Combine(p1, p2, lgnd = NULL)

Arguments

p1

First plot

p2

Second plot

lgnd

For the side by side hazard/survival plots the default is that one is conditional and one is marginal. If your use case is different, then put a legend consisting of two character strings to label the plots from left to right. See examples.

Details

Experimental at this stage.

Value

A ggplot2 object

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

  ## Not run: 
      p_haz_nb_wb <- Combine(p_haz_nb, p_haz_wb)
      p_gbcs_TrtEff <- Combine(p_gbcs_nb_TrtEff, p_gbcs_wb_TrtEff, lgnd=c("NB","WB"))
  
## End(Not run)

The coefficients extractor method for the `BayesFBHborrow` class

Description

The coefficients extractor method for the BayesFBHborrow class with functionality dependent upon whether you select the conditional estimand or marginal contrast.

Usage

coef.BayesFBHborrow(object, ...)

Arguments

object

An object of class BayesFBHborrow

...

Not used

Details

Every call to the function runs the sampler and then produces the conditional estimand and marginal contrast for the treatment/pretreatment variable effects. The argument G_compute in the BayesFBHborrow call tells the print, plot, summary and coef methods which version the user wants displayed.

Value

G_compute=FALSE, then coef() will extract the conditional logged hazard ratio coefficients.

If G_compute=TRUE then a table of showing the marginal treatment contrast e.g. the difference between the log-logged marginal survival fucntion at landmark information times, 0.25, 0.50, 0.75, 1.00, with each line showing median (MTE: marginal treatment effect) its exponentiated value and its 95 percent credicble interval.

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

    ## Not run: 
        my_coefs_cndl <- coef(my_bfhb)
        my_coefs_mgnl <- coef(update(my_bfhb, G_compute=TRUE))
    
## End(Not run)

Generate Current Trial/Historical Controls via Weibull Model

Description

Data genereration to simultaneously generate from a proportional hazards Weibull model, two datasets, one to take the role as the current trial and the other to take the role as the historical controls.

Usage

genBFBHBdat(n_cc_1, n_cc_0, n_hst, B_trt, B_x_cc, int_cc, B_x_hst,
            int_hst, X_fact_levs = NULL, shape = 1, t_er, t_fin,
            dbg = FALSE)

Arguments

n_cc_1

Size of treated arm in current trial.

n_cc_0

Size of control arm in current trial.

n_hst

Size of historical controls dataset.

B_trt

Treatment effect (logged hazard ratio).

B_x_cc

Coefficients (logged hazard ratio per unit) for effect of pretreatment covariates in current trial. The leading end of the vector specifies continuous covariates and the tail end of the vector specifies coefficients for levels of factor variables. See X_fact_levs below.

int_cc

Intercept for current trial model.

B_x_hst

Coefficients (logged hazard ratio per unit) for effect of pretreatment covariates in historical coontrols. See X_fact_levs.

int_hst

Intercept for historical control model.

X_fact_levs

A numeric vector of length 'k' which specifies both the number, 'k', of factor variables among the list of pre-treatment covariates, and the number of levels of each factor variable in their components. For example if we desire 3 continous variables and two factor variables having 3 levels and 4 levels, then the coefficient vectors described above B_x_ must be of length 8 (3 + 2 + 3), and X_fact_levs=c(3,4). Any combination from 0/0, n/0, 0/m of continuous and factor variables is possible.

shape

The shape parameter for the Weibull distribution–currently the same for the current trial and historical controls.

t_er

The time at which randomization ends for use in administrative censoring for both the current trial and historical controls.

t_fin

The time of maximum follow-up for use in administrative censoring for both the current trial and historical controls.

dbg

If run at the command line, set dbg=TRUE to run the command line debugger to step through the function line at a time.

Value

A list of two component data.frames, DAT_cc and DAT_hst, the current trial and the historical controls. Both current trial and historical controls set have time to event and event indicator and any pretreatment covariates specified via the arguments B_x_ and X_fact_levs. In addition the current trial, DAT_cc, has a treatment indicator. Variables in the data.frames are named as follows.

tte

Time to event, both data.frames.

event

Event indicator, both data.frames.

X_trt

Treatment indicator, current trial only.

X_01...X_m

Pre-treatment covariates both data.frames.

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

    n_cc_1 <- 200
    n_cc_0 <- 100
    n_hst <- 100
    int_cc <- int_hst <- -log(3)
    B_x_cc <- B_x_hst <- c(-0.3,0.5,0.25,-0.5)
    B_trt <- log(0.55)

    dat_lst <- 
        genBFBHBdat(n_cc_1=200, n_cc_0=100, n_hst=100,
                    B_trt=B_trt, B_x_cc=B_x_cc, B_x_hst=B_x_hst, 
                    int_cc=int_cc, int_hst=int_hst, shape=2,
                    t_er=0.5, t_fin=1.5, X_fact_levs=3)

    DAT_cc <- dat_lst$DAT_cc
    DAT_hst <- dat_lst$DAT_hst

Create group level data

Description

Aggregate individual level data into group level data

Usage

  group_summary(Y, I, X, s)

Arguments

Y

data

I

censoring indicator

X

design matrix

s

split points, J + 2

Value

list of group level data

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

    set.seed(111)

    ## simulate an example data and set your initial values and hyper parameters 
    n_cc_1 <- 200
    n_cc_0 <- 100
    n_hst <- 100
    int_cc <- int_hst <- -log(3)
    B_x_cc <- B_x_hst <- c(-0.3,0.5,0.25,-0.5)
    B_trt <- log(0.55)

    dat_lst <- 
        genBFBHBdat(n_cc_1=200, n_cc_0=100, n_hst=100,
                    B_trt=B_trt, B_x_cc=B_x_cc, B_x_hst=B_x_hst, 
                    int_cc=int_cc, int_hst=int_hst, shape=2,
                    t_er=0.5, t_fin=1.5, X_fact_levs=3)

    DAT_cc <- dat_lst$DAT_cc
    DAT_hst <- dat_lst$DAT_hst    
    
    ## Say we want to know the group level data for the following split points
    s <- with(DAT_cc, quantile(tte, c(0, 0.45, 0.65, 1), names = FALSE))
    
    with(DAT_cc, group_summary(tte, event, X_trt, s))

Initialize lambda hyperparameters

Description

Propose lambda hyperparameters for the choice of initial values for lambda

Usage

  init_lambda_hyperparameters(group_data, s, w = 0.5)

Arguments

group_data

group level data

s

split points

w

weight

Value

shape and rate for the estimated lambda distribution

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

    set.seed(111)

    ## simulate an example data and set your initial values and hyper parameters 
    n_cc_1 <- 200
    n_cc_0 <- 100
    n_hst <- 100
    int_cc <- int_hst <- -log(3)
    B_x_cc <- B_x_hst <- c(-0.3,0.5,0.25,-0.5)
    B_trt <- log(0.55)

    dat_lst <- 
        genBFBHBdat(n_cc_1=200, n_cc_0=100, n_hst=100,
                    B_trt=B_trt, B_x_cc=B_x_cc, B_x_hst=B_x_hst, 
                    int_cc=int_cc, int_hst=int_hst, shape=2,
                    t_er=0.5, t_fin=1.5, X_fact_levs=3)

    DAT_cc <- dat_lst$DAT_cc
    DAT_hst <- dat_lst$DAT_hst    
    
    ## Say we want to know the group level data for the following split points
    s <- with(DAT_cc, quantile(tte, c(0, 0.45, 0.65, 1), names = FALSE))

    grpd_data <- 
      with(DAT_cc, group_summary(tte, event, NULL, s))

    init_lambda_hyperparameters(grpd_data, s)

Plot Method for the BayesFBHborrow Class

Description

The plot method for the BayesFBHborrow class which allows quick convenient plots of important model summaries.

Usage

## S3 method for class 'BayesFBHborrow'
plot(x, type = c("survival", "hazard", "trace", "TrtEff"),
                              col = NULL, InfFrac = NULL, ylim = NULL, ...)

Arguments

x

An object of class BayesFBHborrow.

type

The type of plot desired. Can be one of the following "survival", "hazard", "trace", "TrtEff".

col

When type="trace" is specified you must name a column of the samples data.frame, which is a component of the output.

InfFrac

When type="TrtEff" is specified and the fitted object has been cast to its marginal estimand form, e.g. update(x, G_compute=TRUE), then you must specify 0.25, 0.50, 0.75 or 1 being the information fraction time at which you are deriving the marginal treatment effect. Defaults to 1.

ylim

Sometimes in type="hazard" plots the credible interval ribbons become obnoxious. Hence, this argument. Set to c(0, Mx).

...

Additional arguments to generic plot function

Value

A ggplot2 object.

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

  ## Not run:  
    p_haz_wb <- plot(fit_sim_wb, type="hazard")
    p_gbcs_wb_trace <- plot(fit_gbcs_wb, type="trace", col="tamoxifen")
    p_gbcs_wb_TrtEff <- plot(fit_gbcs_wb, type="TrtEff")
    p_gbcs_wb_TrtEff_mgnl <- plot(update(fit_gbcs_wb, G_compute=TRUE), type="TrtEff")
    p_gbcs_wb_TrtEff_mgnl_75 <- plot(update(fit_gbcs_wb, G_compute=TRUE),
                                     type="TrtEff", InfFrac=0.75)
  
## End(Not run)

Reads in Fine Mesh Grid Hazards MCMC Samples

Description

Reads in fine mesh grid conditional baseline hazard and arm specific marginal hazards of MCMC samples from the posterior that were written out sample at a time during iteration.

Usage

  read_haz_mcmc_smpls(obj)

Arguments

obj

An object of class BayesFBHborrow.

Details

MCMC samples of the baseline hazard are natively represented as number of split-points, location of split-points and piecewise hazards. However the gibbs/MH updating done internally invovles integrals over the time to event CDF is done with respect to a fine mesh grid. Thus all iter samples must be snapped to this common fine mesh grid of length max_grid. Row by row updates of this matrix within iterations of the sampler is impractical as multiple copies and persistence within a loop will quickly consume resources. For this reason themax_grid by iter matrix representations of the conditional baseline hazard, marginal control arm hazard and marginal treated arm hazard are written out to three corresponding binary files: cnd_blh_*.bin, mgnl_haz0_*.bin, and mgnl_haz1_*.bin. The files are written out sample by sample during iterations and then read back in at the end for summarizing. The files are given a unique random hex suffix for each call to the function and are left in the working directory so that the user may use them to calculate any desired functional of the posterior distribution. If you delete the *.bin files it will, of course, not work. The names of the binary files associated with a given result are returned with the object so if desired you can clean house.

Value

A list with components

cnd_haz_0

samples of the conditional baseline hazard posterior as iter by max_grid matrix

mgnl_haz_0

samples of the marginal control arm hazard posterior as iter by max_grid matrix

mgnl_haz_1

samples of the marginal treated arm hazard posterior as iter by max_grid matrix

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

  ## Not run: 
      read_haz_mcmc_smpls(fit_my_bfbhb)
  
## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

survival: Surv
bayestestR: ci
kableExtra: kable

Summary Method for the BayesFBHborrow Class

Description

Summary method for the BayesFBHborrow class

Usage

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

Arguments

object

An object of class BayesFBHborrow.

...

Additional arguments to generic summary

Details

Value

The result of the summary method is an object of class BayesFBHborrow identical to the input with the addition of two new components – the ones shown by the print method.

coefficients

If the original model involved p pre-treatment covariates and a treatment indicator, this will be a 2p + 1 by 4 matrix showing median of the logged hazard ratio, its exponentiated value and its 95 percent credible interval.

surv_summary

Shows arm specific conditional or A 8 by 6 matrix showing arm label C/I, information fraction Description of 'comp2'

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

    ## Not run: 
        my_coefs_cndl <- coef(my_bfhb)
        my_coefs_mgnl <- coef(update(my_bfhb, G_compute=TRUE))
    
## End(Not run)

The Update Method for the `BayesFBHborrow` Class

Description

The Update Method for the BayesFBHborrow Class

Usage

update.BayesFBHborrow(object, formula = NULL, data, data_hist = NULL,
                      subset, na.action, CntlOnly = FALSE, model_choice = "mix",
                      tuning_parameters = NULL, hyperparameters = NULL, iter = 1000,
                      warmup_iter = 100, refresh = 0, verbose = FALSE, max_grid = 2000,
                      standardise = TRUE, G_compute = FALSE, preprocess = TRUE,
                      fnm_cnd_blh = "cnd_blh", fnm_mgnl_haz0 =  "mgnl_haz0",
                      fnm_mgnl_haz1 = "mgnl_haz1", dbg = FALSE, ...)

Arguments

object

An object of class BayesFBHborrow

formula

data

data_hist

subset

When using the formula/data interface, you may also use subset and na.action as you do in other statistical routines in R.

na.action

When using the formula/data interface, you may also use subset and na.action as you do in other statistical routines in R.

CntlOnly

Set to TRUE when running the model with on the historical controls dataset only. The default value is FALSE.

model_choice

tuning_parameters

hyperparameters

iter

Number of iterations for MCMC sampler.

warmup_iter

Number of warmup iterations (burn-in) for MCMC sampler.

refresh

Number of iterations between printed screen updates.

verbose

Whether or not to print the progress to the console every refresh iterations. Defaults to FALSE.

max_grid

Grid size for the smoothed baseline hazard. Default value is 2000.

standardise

Whether or not to normalize the current trial baseline hazard to unity and apply the same normalization constant to the historical data. Default is TRUE.

G_compute

preprocess

fnm_cnd_blh

fnm_mgnl_haz0

Binary files generated during run time which are given a default name prefix with a random hex suffix. The collection of "snapped to common grid" samples from the posterior distribution of the baseline hazards is a matrix of dimension max_grid by iter. Adding updated columns to this very large matrix would result in memory caching and for this reason, these are written out to binary files during the run of the MCMC, and then read back in during the final sumarization. This file is for the control arm log-log marginal hazard. These files are available to the user for computing any functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function.

fnm_mgnl_haz1

Binary files generated during run time which are given a default name prefix with a random hex suffix. The collection of "snapped to common grid" samples from the posterior distribution of the baseline hazards is a matrix of dimension max_grid by iter. Adding updated columns to this very large matrix would result in memory caching and for this reason, these are written out to binary files during the run of the MCMC, and then read back in during the final sumarization. This file is for the treated arm log-log marginal hazard. These files are available to the user for computing any functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function.

dbg

When running in command line mode, set to TRUE in order to enable line by line debugging.

...

Other arguments as needed.

Details

Note that the marginal contrast is always computed in addition to the conditional estimand. If G_compute=FALSE, (the default) in the original call, the print, coef, summary and plot methods will produce results reflecting the conditional estimand, whereas these will reflect the marginal contrast otherwise. NOTE: calling update(my_bfbhb, G_compute=TRUE) doesn't require rerunning the sampler as the results are already there.

Value

An object of class BayesFBHborrow. See the documentation.

Author(s)

Darren A. V. Scott, Sophia Axillus and Grant Izmirlian

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

    ## Not run: 
       update(my_bfbhb, G_compute=TRUE)
    
## End(Not run)

Find the root of the $p_0$ mixture probability equation

Description

Finds the value of the root (in the interval [0, 2]) for the function p0tp involving mixture probability p_0 and hyperparameters b_tau and d_tau.

Usage

 xifinder(b_tau, d_tau, p_0)

Arguments

b_tau

Shape (or scale) parameter for the first mixture component.

d_tau

Shape (or scale) parameter for the second mixture component.

p_0

Mixture proportion; probability for the first component, in (0, 1).

Details

Uses uniroot() to numerically solve for the root of the function p0tp on the interval [0, 2]. The function p0tp should accept arguments x, b_tau, d_tau, and p_0. This is typically used for calibrating the mixture prior or solving for a relevant quantile in hierarchical Bayesian models.

Note: The auxiliary function p0tp must be defined in the environment.

Value

Numeric value; the root of the p0tp equation within the interval.

References

Scott DAV and Lewin A (2026). Borrowing from historical control data in a Bayesian time-to-event model with flexible baseline hazard function. Biostatistics 27(1)

Examples

## Suppose p0tp is defined elsewhere
## Find a root for specific parameters:
  ## Not run: 
    xifinder(b_tau = 0.1, d_tau = 1, p_0 = 0.75)
  
## End(Not run)

Package {BayesFBHborrow}

Fit the Bayesian Flexible Baseline Hazard Model with Borrowing via MCMC/MH

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

An Method for Easily Combining Two Similar BayesFBHborrow Plots

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

The coefficients extractor method for the BayesFBHborrow class

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Generate Current Trial/Historical Controls via Weibull Model

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Create group level data

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Initialize lambda hyperparameters

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Plot Method for the BayesFBHborrow Class

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Reads in Fine Mesh Grid Hazards MCMC Samples

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Objects exported from other packages

Description

Summary Method for the BayesFBHborrow Class

The coefficients extractor method for the `BayesFBHborrow` class

The Update Method for the `BayesFBHborrow` Class