Package 'BayesFBHborrow'

Title: Bayesian Dynamic Borrowing with Flexible Baseline Hazard Function
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>.
Authors: Darren Scott [aut], Sophia Axillus [aut], Grant Izmirlian [aut, cre]
Maintainer: Grant Izmirlian <[email protected]>
License: Apache License (>= 2)
Version: 2.0.20
Built: 2026-10-20 00:04:40 UTC
Source: https://github.com/cran/BayesFBHborrow

Help Index

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_haz_0 = "cnd_haz_0",
               fnm_cnd_cumHz_0 = "cnd_cumHz_0", fnm_lml_mgnl_surv_0 = "lml_mgnl_surv_0",
               fnm_lml_mgnl_surv_1 = "lml_mgnl_surv_1", fnm_mgnl_haz_0 = "mgnl_haz_0",
               fnm_mgnl_haz_1 = "mgnl_haz_1", sfx = NULL,
               keep_bin_files = FALSE, n_chains = 1L, hpc_max_cores = 16,
               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_haz_0

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. These files are written to a hidden subdirectory named .xxxxxx (dot randome hex string) in the current working directory. Their complete paths are stored in the resulting object and are available to the user for computing any downstream functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function. This file contains samples of the conditional baseline hazard. These are given default names so there's no need to specify them. Default behavior is to delete them unless the user specifies otherwise (see below).

fnm_cnd_cumHz_0

(see above) This file contains samples of the conditional baseline cumulative hazard.

fnm_lml_mgnl_surv_0

(see above) This file contains samples of the logged negative logged control arm marginal survival function.

fnm_lml_mgnl_surv_1

(see above) This file contains samples of the logged negative logged treated arm marginal survival function.

fnm_mgnl_haz_0

(see above) This file contains samples of the control arm marginal hazard which have been derived as the finite difference quotient of the exponentiated values in the lml_mgnl_surv_0 file.

fnm_mgnl_haz_1

(see above) This file contains samples of the treated arm marginal hazard which have been derived as the finite difference quotient of the exponentiated values in the lml_mgnl_surv_0 file.

sfx

The name of the subdirectory created in the current working directory to contain these binary files. Also used in the suffix of the file names. The default behavior is to give this a random 6 digit hex string so there's no need to specify this argument either.

keep_bin_files

Defaults to FALSE as the default behavior is to delete the entire temp binary file directory when the run concludes. If the user wishes to perform downstream calculation using the full set of MCMC/MH sampled functions snapped to the finely spaced grid then set this to TRUE and then use read_haz_mcmc_samples (see below).

n_chains

Number of chains to sample in parallel post warmup. This is determined automatically by the function depending on the capabilities of your machine and the OS you are using (unix alike [mac/WSL], HPC cluster, or windows). No need to set this

hpc_max_cores

If you use the HPC cluster either in the workbench or setting up an interactive node at the command line, you should request 'Rstudio large' and then set the number of cores to anything up to 32. You should request 16GB of ram so you might have to play with setting until you're given permission to open the session. At AZ I've had success with 16GB and 16 cores. In any case, set this to the number of cores you're able to get.

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. The package now fully implements parallel computation using parallelly, future and future.apply.

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>

See Also

plot, summary, update methods for class "BayesFBHborrow" objects

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 <- trial_data(dat_lst)
DAT_hst <- historical_data(dat_lst)

## using default settings for hyperparameters and tuning parameters
## formula interface
## cntls only; no cov's
  
    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)

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

## S3 method for class 'BayesFBHborrow'
coef(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)

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>

See Also

BayesFBHborrow,

Examples

## Not run: 
        my_coefs_cndl <- coef(my_bfhb)
        my_coefs_mgnl <- coef(update(my_bfhb, G_compute=TRUE))
    
## 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)

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>

See Also

plot.BayesFBHborrow, BayesFBHborrow

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)

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)

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>

See Also

BayesFBHborrow,

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 <- trial_data(dat_lst)
    DAT_hst <- historical_data(dat_lst)

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)

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>

See Also

BayesFBHborrow,

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 <- trial_data(dat_lst)
    DAT_hst <- historical_data(dat_lst)
    
    ## 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))

Historical controls data extractor for a BFBHBdat object

Description

Historical controls data extractor for object of class BFBHBdat as returned by the simulation routine genBFBHBdat.

Usage

historical_data(x)

Arguments

x

An object of class BFBHdat as returned by the simulation routine genBFBHBdat

Value

The historical controls data.frame with variables

tte

Time to event
evnet

Event indicator
X_01 ... X_0n

Pre-treatment covariates as directed in the call to genBFBHBdat

Author(s)

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

See Also

trial_data, genBFBHBdat

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 <- trial_data(dat_lst)
    DAT_hst <- historical_data(dat_lst)

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)

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>

See Also

BayesFBHborrow,

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 <- trial_data(dat_lst)
    DAT_hst <- historical_data(dat_lst)
    
    ## 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)

Marginal Treatment Effect Extractor

Description

Marginal Treatment Effect Extractor. Works on any BayesFBHborrow object having one or more pretreatment covariates.

Usage

MTE(object, ...)

Arguments

object

an object of class BayesFBHborrow e.g. result of the main method.

...

other arguments for the update method

Value

A table (data.frame) showing the marginal treatment at 25%, 50%, 75% and 100%

InfFrac

Information fraction: portion of total events observed 0.25, 0.50, 0.75 and 1.00 defining landmark times at which the marginal treament effect is calculated.
Time

The landmark times at which the indicated information fractions are attained.
MTE

The calculated marginal treatment effect, e.g. the difference of arm specific logged negative logged marginal survival functions; on the scale of logged relative risk
exp(MTE)

Exponentiated marginal treatment effect; on the scale of relative risk.
MTE_L

The lower bound of the 95% credible interval for MTE.
MTE_U

The upper bound of the 95% credible interval for MTE.

Author(s)

Darrent Scott; Sophia Axillus and Grant Izmirlian

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", "cumulative hazard",
                                          "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", "cumulative hazard", "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)

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>

See Also

BayesFBHborrow, Combine

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 corresponding values of the 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 a common fine mesh grid of length max_grid. Row by row updates of this matrix within iterations of the sampler is impractical based upon the way R handles updating arrays involving multiple copies of it and persistence of this memory usage within a loop until completion. This will quickly consume free memory resulting in diskcaching and ultimately machine freeze. For this reason binary file writes, per iteration of the sampling loop, are done for the snapped to grid versions of the following fucntions: the control arm conditional hazard, conditional cumulative hazard, arm specific logged negative logged marginal survival functions for which the difference is the marginal treatment effect as a function of time, and the marginal hazards, computed as the finite difference quotient of the their exponentiated values. These files are then read back in after the sampling loop for the summarization step. The corresponding six file names in order given above are: cnd_haz_0_*.bin, cnd_cumHz0_*.bin, lml_mgnl_surv_0_*.bin, lml_mgnl_surv_1_*.bin, mgnl_haz_0_*.bin, and _mgnl_haz_1_*.bin. The default behavior is to delete them when the main routine, BayesFBHborrow, exits. However, if the user wishes to use them in downstream calculation of functionals of the posterior distribution of these quantities, the argument keep_binary_files should be set to TRUE. Then one calls this function with the single argument object, the result of BayesFBHborrow. The names of the binary files associated with a given result are returned with the object.

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)

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>

See Also

BayesFBHborrow

Examples

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

Ad-hoc Relative Efficiency for Model With and Without Borrowing

Description

Calculates an ad-hoc relative efficiency for a model with and without borrowing, both being fitted BayesFBHborrow models. This is done by computing the squared ratio of the widths of their 95% credible intervals about the estimated treatment effect.

Usage

rel_eff(wb, nb, G_compute = FALSE)

Arguments

wb

A fitted BayesFBHborrow model, with borrowing

nb

The same fitted BayesFBHborrow model, without borrowing

G_compute

If G_compute is FALSE (default), conditional estimates are compared. If it is set to TRUE, marginal estimates are compared.

Value

A double precision numeric.

Author(s)

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

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

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

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)

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>

See Also

BayesFBHborrow,

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 <- trial_data(dat_lst)
    DAT_hst <- historical_data(dat_lst)

    my_bfbhb <- 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)

    my_bfbhb.s <- summary(my_bfbhb)
    my_bfbhb.s

Current trial data extractor for a BFBHBdat object

Description

Current trial data extractor for object of class BFBHBdat as returned by the simulation routine genBFBHBdat.

Usage

trial_data(x)

Arguments

x

An object of class BFBHdat as returned by the simulation routine genBFBHBdat

Value

The current trial data.frame with variables

tte

Time to event
evnet

Event indicator
X_trt

Treatment indicator
X_01 ... X_0n

Pre-treatment covariates as directed in the call to genBFBHBdat

Author(s)

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

See Also

historical_data, genBFBHBdat

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 <- trial_data(dat_lst)
    DAT_hst <- historical_data(dat_lst)

The Update Method for the BayesFBHborrow Class

Description

The Update Method for the BayesFBHborrow Class

Usage

## S3 method for class 'BayesFBHborrow'
update(
       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_haz_0 = "cnd_haz_0", fnm_cnd_cumHz_0 = "cnd_cumHz_0",
       fnm_lml_mgnl_surv_0 = "lml_mgnl_surv_0",
       fnm_lml_mgnl_surv_1 = "lml_mgnl_surv_1",
       fnm_mgnl_haz_0 =  "mgnl_haz_0",
       fnm_mgnl_haz_1 = "mgnl_haz_1", sfx = NULL, keep_bin_files= FALSE,
       n_chains = 1L, hpc_max_cores = 16, dbg = FALSE, evaluate = TRUE,
       ...)

Arguments

object

An object of class BayesFBHborrow

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_haz_0

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. These files are written to a hidden subdirectory named .xxxxxx (dot randome hex string) in the current working directory. Their complete paths are stored in the resulting object and are available to the user for computing any downstream functional of the posterior distribution. See the documentation for the read_haz_mcmc_smpls function. This file contains samples of the conditional baseline hazard. These are given default names so there's no need to specify them. Default behavior is to delete them unless the user specifies otherwise (see below).

fnm_cnd_cumHz_0

(see above) This file contains samples of the conditional baseline cumulative hazard.

fnm_lml_mgnl_surv_0

(see above) This file contains samples of the logged negative logged control arm marginal survival function.

fnm_lml_mgnl_surv_1

(see above) This file contains samples of the logged negative logged treated arm marginal survival function.

fnm_mgnl_haz_0

(see above) This file contains samples of the control arm marginal hazard which have been derived as the finite difference quotient of the exponentiated values in the lml_mgnl_surv_0 file.

fnm_mgnl_haz_1

(see above) This file contains samples of the treated arm marginal hazard which have been derived as the finite difference quotient of the exponentiated values in the lml_mgnl_surv_0 file.

sfx

The name of the subdirectory created in the current working directory to contain these binary files. Also used in the suffix of the file names. The default behavior is to give this a random 6 digit hex string so there's no need to specify this argument either.

keep_bin_files

Defaults to FALSE as the default behavior is to delete the entire temp binary file directory when the run concludes. If the user wishes to perform downstream calculation using the full set of MCMC/MH sampled functions snapped to the finely spaced grid then set this to TRUE and then use read_haz_mcmc_samples (see below).

n_chains

Number of chains to sample in parallel post warmup. This is determined automatically by the function depending on the capabilities of your machine and the OS you are using (unix alike [mac/WSL], HPC cluster, or windows). No need to set this

hpc_max_cores

If you use the HPC cluster either in the workbench or setting up an interactive node the command line you should request 'Rstudio large' and then set the number of cores to anything up to 32. You should request 16GB of ram so you might have to play with setting until you're given permission to open the session. At AZ I've had success with 16GB and 16 cores. In any case, set this to the number of cores you're able to get.

dbg

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

evaluate

controls whether the modified model call is executed immediately or just returned as an expressionaluate

...

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 D.A.V. 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 D.A.V., 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>

See Also

plot, summary, update methods for class "BayesFBHborrow" objects

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)

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>

See Also

plot, summary, update methods for class "BayesFBHborrow" objects

Examples

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