Type:	Package
Title:	Bayesian Dynamic Borrowing Analysis and Simulation
Version:	0.0.4.0
Description:	Bayesian dynamic borrowing is an approach to incorporating external data to supplement a randomized, controlled trial analysis in which external data are incorporated in a dynamic way (e.g., based on similarity of outcomes); see Viele 2013 <doi:10.1002/pst.1589> for an overview. This package implements the hierarchical commensurate prior approach to dynamic borrowing as described in Hobbes 2011 <doi:10.1111/j.1541-0420.2011.01564.x>. There are three main functionalities. First, 'psborrow2' provides a user-friendly interface for applying dynamic borrowing on the study results handles the Markov Chain Monte Carlo sampling on behalf of the user. Second, 'psborrow2' provides a simulation framework to compare different borrowing parameters (e.g. full borrowing, no borrowing, dynamic borrowing) and other trial and borrowing characteristics (e.g. sample size, covariates) in a unified way. Third, 'psborrow2' provides a set of functions to generate data for simulation studies, and also allows the user to specify their own data generation process. This package is designed to use the sampling functions from 'cmdstanr' which can be installed from https://stan-dev.r-universe.dev.
URL:	https://github.com/Genentech/psborrow2, https://genentech.github.io/psborrow2/index.html
BugReports:	https://github.com/Genentech/psborrow2/issues
License:	Apache License 2.0
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
RoxygenNote:	7.3.1
Config/testthat/edition:	3
Imports:	checkmate, glue, methods, graphics, posterior, generics, Matrix, mvtnorm, future, simsurv
Suggests:	cmdstanr, survival, flexsurv, eha, testthat (≥ 3.0), usethis (≥ 2.1.5), vdiffr, tibble, xml2, knitr, rmarkdown, bayesplot, matrixcalc, WeightIt, MatchIt, BayesPPD, ggsurvfit, gbm, ggplot2, cobalt, table1, gt, gtsummary
Additional_repositories:	https://stan-dev.r-universe.dev
Language:	en-US
SystemRequirements:	cmdstan
Collate:	'generics.R' 'prior_class.R' 'covariate_class.R' 'add_covariates.R' 'prior_normal.R' 'treatment_class.R' 'borrowing_class.R' 'outcome_class.R' 'analysis_class.R' 'borrowing_details.R' 'borrowing_full.R' 'borrowing_hierarchical_commensurate.R' 'borrowing_none.R' 'cast_mat_to_long_pem.R' 'check_data_matrix_has_columns.R' 'cmdstan.R' 'create_analysis_obj.R' 'create_data_matrix.R' 'treatment_details.R' 'sim_treatment_list.R' 'helpers.R' 'outcome_bin_logistic.R' 'prior_exponential.R' 'outcome_surv_weibull_ph.R' 'outcome_surv_exponential.R' 'sim_outcome_list.R' 'sim_borrowing_list.R' 'sim_covariate_list.R' 'sim_data_list.R' 'simulation_class.R' 'create_simulation_obj.R' 'data.R' 'get_prior_string_covariates.R' 'prior_half_cauchy.R' 'outcome_cont_normal.R' 'outcome_surv_pem.R' 'load_and_interpolate_stan_model.R' 'load_stan_file.R' 'make_analysis_object_list.R' 'mcmc_sample.R' 'mcmc_simulation_result.R' 'package.R' 'prepare_stan_data_inputs.R' 'prior_bernoulli.R' 'prior_beta.R' 'prior_cauchy.R' 'prior_gamma.R' 'prior_half_normal.R' 'prior_poisson.R' 'sim_covariates.R' 'sim_estimate_bias.R' 'sim_estimate_effect_variance.R' 'sim_estimate_mse.R' 'sim_is_null_effect_covered.R' 'sim_is_true_effect_covered.R' 'sim_samplesize.R' 'simulate_data_baseline.R' 'simulate_data.R' 'simvar_class.R' 'trim_data_matrix.R' 'uniform_prior.R' 'zzz.R'
LazyData:	true
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-02-11 19:34:44 UTC; secrestm
Author:	Matt Secrest [aut, cre], Isaac Gravestock [aut], Craig Gower-Page [ctb], Manoj Khanal [ctb], Mingyang Shan [ctb], Kexin Jin [ctb], Zhi Yang [ctb], Genentech, Inc. [cph, fnd]
Maintainer:	Matt Secrest <secrestm@gene.com>
Repository:	CRAN
Date/Publication:	2025-02-12 15:20:02 UTC

psborrow2: Bayesian Dynamic Borrowing Analysis and Simulation

Description

Bayesian dynamic borrowing is an approach to incorporating external data to supplement a randomized, controlled trial analysis in which external data are incorporated in a dynamic way (e.g., based on similarity of outcomes); see Viele 2013 doi:10.1002/pst.1589 for an overview. This package implements the hierarchical commensurate prior approach to dynamic borrowing as described in Hobbes 2011 doi:10.1111/j.1541-0420.2011.01564.x. There are three main functionalities. First, 'psborrow2' provides a user-friendly interface for applying dynamic borrowing on the study results handles the Markov Chain Monte Carlo sampling on behalf of the user. Second, 'psborrow2' provides a simulation framework to compare different borrowing parameters (e.g. full borrowing, no borrowing, dynamic borrowing) and other trial and borrowing characteristics (e.g. sample size, covariates) in a unified way. Third, 'psborrow2' provides a set of functions to generate data for simulation studies, and also allows the user to specify their own data generation process. This package is designed to use the sampling functions from 'cmdstanr' which can be installed from https://stan-dev.r-universe.dev.

Author(s)

Maintainer: Matt Secrest secrestm@gene.com (ORCID)

Authors:

• Isaac Gravestock isaac.gravestock@roche.com

Other contributors:

• Craig Gower-Page craig.gower-page@roche.com [contributor]

• Manoj Khanal khanal_manoj@lilly.com [contributor]

• Mingyang Shan mingyang.shan@lilly.com [contributor]

• Kexin Jin kexin.jin@bms.com [contributor]

• Zhi Yang zhi.yang@bms.com [contributor]

• Genentech, Inc. [copyright holder, funder]

See Also

Useful links:

• https://github.com/Genentech/psborrow2

• https://genentech.github.io/psborrow2/index.html

• Report bugs at https://github.com/Genentech/psborrow2/issues

Analysis Class

Description

A class for defining Analysis details. Objects of class Analysis should not be created directly but by the constructor create_analysis_obj().

Slots

data_matrix

matrix. The data matrix, including all covariates to be adjusted for, all relevant outcome variables, and treatment arm and external control arm flags.

covariates

Covariate. Object of class Covariate as output by the function covariate_details().

outcome

Outcome. Object of class Outcome as output by outcome_surv_exponential(), outcome_surv_weibull_ph(), or outcome_bin_logistic().

borrowing

Borrowing. Object of class Borrowing as output by borrowing_full(), borrowing_none(), or borrowing_hierarchical_commensurate().

treatment

Treatment. Object of class Treatment as output by treatment_details().

model_string

character. The string that contains the full Stan model code to be compiled.

model

CmdStanModel. The compiled Stan model as output by cmdstanr::cmdstan_model()

ready_to_sample

logical. Is the object ready to sample?

Baseline Data Frame Object

Description

Contains a generated baseline dataset for a single arm.

Value

A BaselineDataFrame

Slots

cov_names

character contains the names of covariates generated from the multivariate normal distribution

means

numeric contains the means of generating distribution for the covariates in cov_names

variances

numeric contains the marginal variances of generating distribution for the covariates in cov_names.

Baseline Data Frame List

Description

A named list of BaselineDataFrames with generated data for internal_treated/internal_control/ external_control groups

Value

A BaselineDataList

Slots

baseline_object

Simulated covariates definitions as BaselineObject. See create_baseline_object()

BaselineObject class for data simulation

Description

BaselineObject class for data simulation

Slots

n_trt_int

integer. Number of internal treated patients

n_ctrl_int

integer. Number of internal control patients

n_ctrl_ext

integer. Number of external control patients

covariates

list. List of correlated covariates objects, see baseline_covariates()

transformations

list. List of named transformation functions.

BinaryOutcome class

Description

BinaryOutcome class

Slots

n_param

integer. Number of ancillary parameters for the model to estimate.

param_priors

list. Named list of prior distributions on the ancillary parameters in the model.

binary_var

character. Variable used for outcome in BinaryOutcome objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

name_exp_trt.

Named vector for exponentiated beta_trt

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: ContinuousOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

Borrowing Class

Description

A class for defining borrowing details. Objects of class Borrowing should not be created directly but by the constructors borrowing_hierarchical_commensurate(), borrowing_none(), borrowing_full().

Slots

method_name

string. The name of the method.

ext_flag_col

character. Name of the external flag column in the matrix.

See Also

Prior constructor functions: borrowing_full(), borrowing_hierarchical_commensurate(), borrowing_none()

Other borrowing classes: BorrowingFull-class, BorrowingHierarchicalCommensurate-class, BorrowingNone-class

BorrowingFull class

Description

A class for defining details for "Full Borrowing" methods. Objects of class BorrowingFull should not be created directly but by the constructor borrowing_full().

Slots

method_name

string. The name of the method.

ext_flag_col

character. Name of the external flag column in the matrix.

name_tau

named vector for hierarchical commensurability parameter hyperprior.

See Also

Other borrowing classes: Borrowing-class, BorrowingHierarchicalCommensurate-class, BorrowingNone-class

BorrowingHierarchicalCommensurate class

Description

A class for defining details of dynamic borrowing using the hierarchical Bayesian model with a commensurability parameter. Objects of class BorrowingHierarchicalCommensurate should not be created directly but by the constructor borrowing_hierarchical_commensurate().

Slots

method_name

string. The name of the method.

ext_flag_col

character. Name of the external flag column in the matrix.

tau_prior

Prior. Prior for the commensurability parameter.

See Also

Other borrowing classes: Borrowing-class, BorrowingFull-class, BorrowingNone-class

BorrowingNone class

Description

A class for defining details for "No borrowing" methods. Objects of class BorrowingNone should not be created directly but by the constructor borrowing_none().

Slots

method_name

string. The name of the method.

ext_flag_col

character. Name of the external flag column in the matrix.

See Also

Other borrowing classes: Borrowing-class, BorrowingFull-class, BorrowingHierarchicalCommensurate-class

ContinuousOutcome class

Description

ContinuousOutcome class

Slots

n_param

integer. Number of ancillary parameters for the model to estimate.

param_priors

list. Named list of prior distributions on the ancillary parameters in the model.

continuous_var

character. Variable used for outcome in ContinuousOutcome objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: BinaryOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

Covariate Class

Description

A class for defining covariate details. Objects of class Covariate should not be created directly but by the constructor add_covariates().

Slots

covariates

character. Names of columns in the data matrix containing covariates to be adjusted for in the outcome model. Note: the external and treatment flags should not go here.

priors.

Either a single object of class Prior specifying the prior distribution to apply to all covariates or a named list of distributions of class Prior, one for each covariate

name_betas.

Names for the beta parameters in the STAN model.

Cut Off Object

Description

Cut Off Object

Slots

cut_off_fun

A function that takes a data.frame with columns of enrollment time, survival time and outcome. The function returns a modified data.frame after applied the cut-off rule.

Enrollment Object

Description

Enrollment Object

Slots

fun

A function that takes one argument n the number of enrollment times to observe and returns a vector of times.

label

A user-friendly label

Event Time Distribution Object

Description

Event Time Distribution Object

Slots

params

Parameters used for simulating event times with simsurv::simsurv().

label

Description of the distribution.

Fixed External Control Data Object

Description

Fixed External Control Data Object

Value

A FixedExternalData

Slots

data

data.frame containing external control data

n

Number of observations

Data Simulation Object Class

Description

Data Simulation Object Class

Value

A DataSimObject

Slots

baseline

BaselineObject from create_baseline_object

coefficients

Named numeric vector of beta coefficients for survival model. See beta at ?simsurv::simsurv

treatment_hr

numeric treatment effect as a hazard ration. log(treatment_hr) is included in beta with coefficients and log(drift_hr). This default is overridden by generate arguments

drift_hr

numeric hazard ratio between internal and external arms. Included as log(drift_hr).

fixed_external_data

data.frame for external data. Currently unused.

event_dist

DataSimEvent parameters for outcome distribution from create_event_dist()

enrollment

DataSimEnrollment object.

cut_off

DataSimCutOff

MCMCSimulationResult Class

Description

A class for defining Simulation study results. Objects of class MCMCSimulationResult should not be created directly but by mcmc_sample().

Slots

results

data.frame. The results of the simulation study summarized in a data.frame

cmd_stan_models

list. List of lists of CmdStanmodels corresponding to the different parameters in Simulation@guide and different datasets in Simulation@data_matrix_list.

Outcome class

Description

Outcome class

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

OutcomeBinaryLogistic class

Description

A class for defining a logistic regression with a binary outcome to be translated to Stan code. Objects of class OutcomeBinaryLogistic should not be created directly but by the constructor outcome_bin_logistic().

Slots

n_param

integer. Number of ancillary parameters for the model to estimate (0).

param_priors

list. Named list of prior distributions on the ancillary parameters in the model. Empty for OutcomeBinaryLogistic.

binary_var

character. Variable used for outcome in OutcomeBinaryLogistic objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

name_exp_trt.

Named vector for exponentiated beta_trt

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, Outcome-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

OutcomeContinuousNormal class

Description

A class for defining a regression with a normal outcome to be translated to Stan code. Objects of class OutcomeContinuousNormal should not be created directly but by the constructor outcome_cont_normal().

Slots

n_param

integer. Number of ancillary parameters for the model to estimate (0).

param_priors

list. Named list of prior distributions on the ancillary parameters in the model. Empty for OutcomeContinuousNormal.

continuous_var

character. Variable used for outcome in OutcomeContinuousNormal objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

OutcomeSurvExponential Class

Description

A class for defining a time-to-event survival analysis with an exponential survival distribution. Objects of class OutcomeSurvExponential should not be created directly but by the constructor outcome_surv_exponential().

Slots

n_param

integer. Number of ancillary parameters for the model to estimate (0).

param_priors

list. Named list of prior distributions on the ancillary parameters in the model. Empty for OutcomeSurvExponential.

time_var

character. Variable used for time in TimeToEvent objects.

cens_var

character. Variable used for censoring in TimeToEvent objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

name_exp_trt.

Named vector for exponentiated beta_trt

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

OutcomeSurvPEM Class

Description

A class for defining a time-to-event survival analysis with a piecewise survival distribution. Objects of class OutcomeSurvPEM should not be created directly but by the constructor outcome_surv_pem().

Slots

function_stan_code

character. stan function code block containing text to interpolate into stan model. Empty string for OutcomeSurvPEM.

param_stan_code

character. stan parameter code block containing text to interpolate into stan model. Empty string for OutcomeSurvPEM.

n_param

integer. Number of ancillary parameters for the model to estimate (0).

param_priors

list. Named list of prior distributions on the ancillary parameters in the model. Empty for OutcomeSurvPEM.

time_var

character. Variable used for time in TimeToEvent objects.

cens_var

character. Variable used for censoring in TimeToEvent objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

name_exp_trt.

Named vector for exponentiated beta_trt

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

n_periods.

Number of periods.

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvWeibullPH-class, TimeToEvent-class

OutcomeSurvWeibullPH Class

Description

A class for defining a time-to-event survival analysis with a Weibull proportional hazards survival distribution. Objects of class OutcomeSurvWeibullPH should not be created directly but by the constructor outcome_surv_weibull_ph().

Slots

n_param

integer. Number of ancillary parameters for the model to estimate (1).

param_priors

list. Named list of prior distributions on the ancillary parameters in the model.

time_var

character. Variable used for time in TimeToEvent objects.

cens_var

character. Variable used for censoring in TimeToEvent objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

name_exp_trt.

Named vector for exponentiated beta_trt

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, TimeToEvent-class

Prior Class

Description

A class for defining priors to be translated to Stan code. Objects of class Prior should not be created directly but by one of the specific prior class constructors.

Slots

stan_code

character. Stan implementation of the prior, with placeholders for parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters.

constraint

character. Support of prior distribution expressed as a Stan constraint, e.g. "<lower=0, upper=1>".

See Also

Prior constructor functions: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_half_cauchy(), prior_gamma(), prior_normal(), prior_poisson(), uniform_prior()

Other prior classes: PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorBernoulli Class

Description

A class for defining bernoulli priors to be translated to Stan code. Objects of class PriorBernoulli should not be created directly but by the constructor prior_bernoulli().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for bernoulli stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (1).

constraint

character. Support of prior distribution, "<lower=0, upper=1>".

theta

numeric. Probability (in [0, 1]).

See Also

Other prior classes: Prior-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorBeta Class

Description

A class for defining beta priors to be translated to Stan code. Objects of class PriorBeta should not be created directly but by the constructor prior_beta().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for beta stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution, "<lower=0, upper=1>".

alpha

numeric. Shape (>=0).

beta

numeric. Shape (>=0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorCauchy Class

Description

A class for defining the cauchy priors to be translated to Stan code. Objects of class PriorCauchy should not be created directly but by the constructor prior_cauchy().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for cauchy stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution, (all values allowed in cauchy distribution).

mu

numeric. Location.

sigma

numeric. Scale (>0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorExponential Class

Description

A class for defining exponential priors to be translated to Stan code. Objects of class PriorExponential should not be created directly but by the constructor prior_exponential().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for exponential Stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (1).

constraint

character. Support of prior distribution, "<lower=0>".

beta

numeric. Inverse scale (>0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorGamma Class

Description

A class for defining gamma priors to be translated to Stan code. Objects of class PriorGamma should not be created directly but by the constructor prior_gamma().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for gamma stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution, "<lower=0>".

alpha

numeric. Shape (>0).

beta

numeric. Inverse scale (>=0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorHalfCauchy Class

Description

A class for defining half cauchy priors to be translated to Stan code. Objects of class PriorHalfCauchy should not be created directly but by the constructor prior_half_cauchy().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for the half cauchy stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution. In a half cauchy prior, constraint is mu

mu

numeric. Location.

sigma

numeric. Scale (>0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorHalfNormal Class

Description

A class for defining half normal priors to be translated to Stan code. Objects of class PriorHalfNormal should not be created directly but by the constructor prior_half_normal().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for the half normal stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution. In a half normal prior, constraint is mu

mu

numeric. Location.

sigma

numeric. Scale (>0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorNormal-class, PriorPoisson-class, UniformPrior-class

PriorNormal Class

Description

A class for defining normal priors to be translated to Stan code. Objects of class PriorNormal should not be created directly but by the constructor prior_normal().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for normal stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution, (all values allowed in normal distribution).

mu

numeric. Location.

sigma

numeric. Scale (>0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorPoisson-class, UniformPrior-class

PriorPoisson Class

Description

A class for defining poisson priors to be translated to Stan code. Objects of class PriorPoisson should not be created directly but by the constructor prior_poisson().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for poisson stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (1).

constraint

character. Support of prior distribution, "<lower=0>".

lambda

numeric. Rate (>0).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, UniformPrior-class

SimBorrowingList Class

Description

A class for borrowing details as part of a simulation study. Objects of class SimBorrowingList should not be created directly but by the constructor sim_borrowing_list().

Slots

borrowing_list

named list of object of class Borrowing, one object for each parameter variation.

SimCovariateList Class

Description

A class for covariate details as part of a simulation study. Objects of class SimCovariateList should not be created directly but by the constructor sim_covariate_list().

Slots

covariate_list

named list of object of class Covariate, one object for each parameter variation.

SimCovariates Class

Description

A class for specifying covariate distributions and covariance for simulation studies.

Slots

covariates

list. List of covariate mean values or probabilities as generated through bin_var() (class SimVarBin or cont_var() (class SimVarCont).

covariance_internal

matrix. Covariance matrix before binarization for internal patients.

covariance_external

matrix. Covariance matrix before binarization for external patients.

SimDataList Class

Description

A class for defining generated data for use as part of a simulation study. Objects of class SimDataList should not be created directly but by the constructor sim_data_list().

Slots

data_list

list of lists of matrices. The lists at the highest level differ in that the parameters used to generate the data. The matrices at lowest level are different iterations of the same data generation parameters.

guide

data.frame. guide contains information on the parameters that differ at the highest level of data_list.

effect

character. The column in guide that corresponds to the true treatment effect estimate (hazard ratio or odds ratio).

drift

character. The column in guide that corresponds to the drift between external and internal control arms. A drift >1 means the external arm experiences greater effects.

index

character. The column in guide that corresponds to the index of the parameter situations in data_list.

SimOutcomeList Class

Description

A class for outcome details as part of a simulation study. Objects of class SimOutcomeList should not be created directly but by the constructor sim_outcome_list().

Slots

outcome_list

named list of object of class Outcome, one object for each parameter variation.

SimSampleSize Class

Description

A class for creating matrices for simulation studies containing flags specifying whether the patient is from the concurrent trial or not (ext = 0 for concurrent trial, ext = 1 for historical data) and whether the patient is on the experimental therapy or not (trt = 0 for no experimental therapy, trt = 1 for experimental therapy).

Slots

n_internal_control

integer. Number of patients to be simulated in the internal control arm.

n_external_control

integer. Number of patients to be simulated in the external control arm.

n_internal_experimental

integer. Number of patients to be simulated in the internal experimental arm.

mat

matrix. Matrix with two columns, ext (flag for being from external data source) and trt (flag for receiving experimental treatment)

SimTreatmentList Class

Description

A class for treatment details as part of a simulation study. Objects of class SimTreatmentList should not be created directly but by the constructor sim_treatment_list().

Slots

treatment_list

named list of object of class Treatment, one object for each parameter variation.

SimVar Class

Description

A parent class for defining covariates to be created in the simulation study calls to add_covariates().

SimVarBin class

Description

A constructor for making objects of class SimVarBin. Objects of class SimVarBin are used to hold proportions of binary variables specified in a simulation study.

Slots

prob_internal

numeric. Proportion for the internal arms.

prob_external

numeric. Proportion for the external arm.

mu_internal_before_bin

numeric. Mean value of covariate before binarization for the internal arms.

mu_external_before_bin

numeric. Mean value of covariate before binarization for the external arm.

printval_int

numeric. Value to print to summarize internal arms.

printval_ext

numeric. Value to print to summarize external arm.

type_string

character. 'binary'

See Also

Other simvar classes: SimVarCont-class

SimVarCont class

Description

A constructor for making objects of class SimVarCont. Objects of class SimVarCont are used to hold mean values of of continuous variables specified in a simulation study.

Slots

mu_internal

numeric. Mean covariate value for the internal arms.

mu_external

numeric. Mean covariate value for the external arm.

printval_int

numeric. Value to print to summarize internal arms.

printval_ext

numeric. Value to print to summarize external arm.

type_string

character. 'continuous'

See Also

Other simvar classes: SimVarBin-class

Simulation Class

Description

A class for defining Simulation study details. Objects of class Simulation should not be created directly but by the constructor create_simulation_obj().

Slots

data_matrix_list

SimDataList. The list of lists of data matrices created with sim_data_list().

outcome

SimOutcomeList. List of Outcome objects created with sim_outcome_list().

borrowing

SimBorrowingList. List of Borrowing objects created with sim_borrowing_list().

covariate

SimCovariateList or NULL. List of Covariate objects created with sim_covariate_list() or NULL (no covariate adjustment).

treatment

SimTreatmentList. List of Treatment objects created with sim_treatment_list().

guide

data.frame. Data.frame containing information on all combinations evaluated.

n_combos

integer. Number of combinations of parameters to be evaluated.

n_analyses

integer. Number of analyses (combos x datasets to be performed).

`analysis_obj_list`

list. List of analysis objects indexed according to guide.

TimeToEvent class

Description

TimeToEvent class

Slots

n_param

integer. Number of ancillary parameters for the model to estimate.

param_priors

list. Named list of prior distributions on the ancillary parameters in the model.

time_var

character. Variable used for time in TimeToEvent objects.

cens_var

character. Variable used for censoring in TimeToEvent objects.

baseline_prior

Prior. Object of class Prior specifying prior distribution for the baseline outcome.

name_beta_trt.

Named vector for beta_trt.

name_exp_trt.

Named vector for exponentiated beta_trt

alpha_type.

How to interpret alpha.

name_addnl_params.

Named vector for additional parameters.

See Also

Other outcome: BinaryOutcome-class, ContinuousOutcome-class, Outcome-class, OutcomeBinaryLogistic-class, OutcomeContinuousNormal-class, OutcomeSurvExponential-class, OutcomeSurvPEM-class, OutcomeSurvWeibullPH-class

Treatment Class

Description

A class for defining treatment details. Objects of class Treatment should not be created directly but by the constructor treatment_details().

Slots

trt_flag_col

character. Character specifying the name of the column in the model matrix that corresponds to the treatment flag (1/0 or TRUE/FALSE). This identifies patients as belonging to the experimental treatment arm.

trt_prior

Prior. Object of class Prior specifying the prior distribution of the log effect estimate (log hazard ratio for time to event endpoints and log odds ratio for binary endpoints).

UniformPrior Class

Description

A class for defining uniform priors to be translated to Stan code. Objects of class UniformPrior should not be created directly but by the constructor uniform_prior().

Slots

stan_code

character. Stan implementation of the prior, with placeholders for uniform stan function parameters surrounded with ⁠{{⁠ and ⁠}}⁠ to be replaced with glue::glue().

n_param

integer. Number of prior parameters (2).

constraint

character. Support of prior distribution, ⁠"<lower=⁠alpha⁠, upper=⁠beta⁠>"⁠.

alpha

numeric. Lower bound.

beta

numeric. Upper bound (>alpha).

See Also

Other prior classes: Prior-class, PriorBernoulli-class, PriorBeta-class, PriorCauchy-class, PriorExponential-class, PriorGamma-class, PriorHalfCauchy-class, PriorHalfNormal-class, PriorNormal-class, PriorPoisson-class

Add Covariates for Model Adjustment

Description

Specify column names for adjustment variables in model matrix and prior distributions for the model parameters for these covariates (i.e., betas)

Usage

add_covariates(covariates, priors)

Arguments

Value

Object of class Covariates.

Examples

add_covariates(
  covariates = c("a", "b"),
  priors = list(
    "a" = prior_normal(0, 1),
    "b" = prior_normal(0, 2)
  )
)

Coerce a psborrow2 object to a data frame

Description

Creates data.frame objects from various classes in psborrow2

Usage

## S3 method for class 'BaselineDataList'
as.data.frame(x, ...)

Arguments

Value

A data.frame

Specify Correlated Baseline Covariates

Description

Set parameters to generate correlated multivariate normal data for internal and external patients.

Usage

baseline_covariates(
  names,
  means_int,
  means_ext = means_int,
  covariance_int,
  covariance_ext = covariance_int
)

Arguments

Value

BaselineObject to build simulated dataset

Examples

corr_covs <- baseline_covariates(
  names = c("b1", "b2"),
  means_int = c(5, 25),
  covariance_int = covariance_matrix(diag = c(1, 1), upper_tri = 0.4)
)

Legacy function for the bernoulli prior

Description

Please use prior_bernoulli() instead.

Usage

bernoulli_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that bernoulli_prior() is deprecated and that prior_bernoulli() should be used instead.

Legacy function for the beta prior

Description

Please use prior_beta() instead.

Usage

beta_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that beta_prior() is deprecated and that prior_beta() should be used instead.

Create binary covariate

Description

Create an object of class SimVarBin to hold proportions of binary variables specified in a simulation study.

Usage

bin_var(
  prob_internal,
  prob_external,
  mu_internal_before_bin = 0,
  mu_external_before_bin = 0
)

Arguments

Details

This function contains information necessary to create binary covariates as part of a simulation study. The binary covariates are created by binarizing multivariate normal distributions to achieve the probabilities specified in prob_internal and prob_external. The user may choose to change the default mean value of each variable prior to binarization by specifying mu_internal_before_bin or mu_external_before_bin to ensure the correct scales are used in the covariance matrix, though the ultimate proportions will depend on prob_internal and prob_external. The default values for mu_internal_before_bin and mu_external_before_bin are 0, and it is not recommended to change these without good reason.

Value

Object of class SimVarBin.

See Also

Other simvar: cont_var()

Examples

cv1 <- bin_var(0.50, 0.80)
cv2 <- bin_var(.95, .92)

Binary Cut-Off Transformation

Description

Binary Cut-Off Transformation

Usage

binary_cutoff(name, int_cutoff, ext_cutoff)

Arguments

Value

Transformation function to be used in create_baseline_object(). Sets quantile values larger than cut-off value to TRUE otherwise FALSE.

Examples

# Creates a simple function, where `data` is a `BaselineDataFrame`:
function(data) {
  ext <- data$ext == 0
  q <- get_quantiles(data, name)
  ifelse(ext, q > int_cutoff, q > ext_cutoff)
}

Legacy function for specifying borrowing details

Description

Please use one of borrowing_hierarchical_commensurate(), borrowing_none(), or borrowing_full() instead.

Usage

borrowing_details(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that borrowing_details() is deprecated and that one of borrowing_hierarchical_commensurate(), borrowing_none(), or borrowing_full() should be used instead.

Full borrowing

Description

Full borrowing

Usage

borrowing_full(ext_flag_col)

Arguments

Details

Method

This method does not distinguish between internal and external arms, effectively pooling patients.

External Control

The ext_flag_col argument refers to the column in the data matrix that contains the flag indicating a patient is from the external control cohort.

Value

Object of class BorrowingFull.

See Also

Other borrowing: borrowing_none()

Examples

fb <- borrowing_full("ext")

Hierarchical commensurate borrowing

Description

Hierarchical commensurate borrowing

Usage

borrowing_hierarchical_commensurate(ext_flag_col, tau_prior)

Arguments

Details

Method

In Bayesian dynamic borrowing using the hierarchical commensurate prior approach, external control information is borrowed to the extent that the outcomes (i.e., log hazard rates or log odds) are similar between external and internal control populations. See Viele 2014 doi:10.1002/pst.1589 and Hobbs 2011 doi:10.1111/j.1541-0420.2011.01564.x for details.

External Control

The ext_flag_col argument refers to the column in the data matrix that contains the flag indicating a patient is from the external control cohort.

Tau Prior

The tau_prior argument specifies the hyperprior on the precision parameter commonly referred to as the commensurability parameter. See Viele 2014 doi:10.1002/pst.1589 for more details. This hyperprior determines (along with the comparability of the outcomes between internal and external controls) how much borrowing of the external control group will be performed. Example hyperpriors include largely uninformative inverse gamma distributions [e.g., prior_gamma(alpha = .001, beta = .001)] as well as more informative distributions [e.g., ⁠prior_gamma(alpha = 1, beta = .001⁠)], though any distribution x \in (0, \infty) can be used. Distributions with more density at higher values of x (i.e., higher precision) will lead to more borrowing.

Value

Object of class BorrowingHierarchicalCommensurate.

References

Viele, K., Berry, S., Neuenschwander, B., Amzal, B., Chen, F., Enas, N., Hobbs, B., Ibrahim, J.G., Kinnersley, N., Lindborg, S., Micallef, S., Roychoudhury, S. and Thompson, L. (2014), Use of historical control data for assessing treatment effects in clinical trials. Pharmaceut. Statist., 13: 41–54. doi:10.1002/pst.1589

Hobbes, B.P., Carlin, B.P., Mandrekar, S.J. and Sargent, D.J. (2011), Hierarchical commensurate and power prior models for adaptive incorporation of historical information in clinical trials. Biometrics, 67: 1047–1056. doi:10.1111/j.1541-0420.2011.01564.x

Examples

db <- borrowing_hierarchical_commensurate(
  ext_flag_col = "ext",
  tau_prior = prior_gamma(0.0001, 0.0001)
)

No borrowing

Description

No borrowing

Usage

borrowing_none(ext_flag_col)

Arguments

Details

Method

This method evaluates only the internal comparison, ignoring historical controls. Note that this method will filter the model matrix based on values in ext_flag_col.

External Control

The ext_flag_col argument refers to the column in the data matrix that contains the flag indicating a patient is from the external control cohort.

Value

Object of class BorrowingNone.

See Also

Other borrowing: borrowing_full()

Examples

db <- borrowing_none(
  ext_flag_col = "ext"
)

Build the model string by interpolating the Stan template

Description

Build the model string by interpolating the Stan template

Usage

build_model_string(
  template_domain,
  template_filename,
  outcome,
  borrowing,
  analysis_obj,
  ...
)

Arguments

Value

String containing the interpolated Stan model

Combine objects in psborrow2

Description

Creates data.frame objects from various classes in psborrow2

Usage

## S4 method for signature 'SimDataList'
c(x, ...)

Arguments

Value

A combined object

list of SimDataList objects.

Legacy function for the cauchy prior

Description

Please use prior_cauchy() instead.

Usage

cauchy_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that cauchy_prior() is deprecated and that prior_cauchy() should be used instead.

Check Stan

Description

Check whether cmdstanr is available and prints version and logistic example.

Usage

check_cmdstanr(check_sampling = FALSE)

check_cmdstan()

Arguments

Value

check_cmdstanr() prints results from checks.

check_cmdstan() returns TRUE if CmdStan seems to be installed, otherwise FALSE

Functions

• check_cmdstan(): Check if the CmdStan command line tools are available.

Examples

check_cmdstanr()

Check Data Matrix for Required Columns

Description

Check that an Analysis object's data_matrix has all the required variables.

Usage

check_data_matrix_has_columns(object)

Arguments

Value

stop() if some columns are missing.

Examples

anls <- create_analysis_obj(
  data_matrix = example_matrix,
  covariates = add_covariates(
    covariates = c("cov1", "cov2"),
    priors = prior_normal(0, 1000)
  ),
  outcome = outcome_surv_exponential(
    "time",
    "cnsr",
    baseline_prior = prior_normal(0, 1000)
  ),
  borrowing = borrowing_hierarchical_commensurate(
    "ext",
    prior_exponential(.001)
  ),
  treatment = treatment_details(
    "trt",
    prior_normal(0, 1000)
  )
)

check_data_matrix_has_columns(anls)

Create a Fixed External Data Object

Description

Create a Fixed External Data Object

Usage

check_fixed_external_data(data, req_cols)

Arguments

Value

A DataSimObject with updated enrollment_internal and enrollment_external slots.

Create continuous covariate

Description

Create an object of class SimVarCont to hold mean values of of continuous variables specified in a simulation study.

Usage

cont_var(mu_internal, mu_external)

Arguments

Value

Object of class SimVarCont.

See Also

Other simvar: bin_var()

Examples

cv1 <- cont_var(0.5, 1)
cv2 <- cont_var(10, 10)

Create Covariance Matrix

Description

Create Covariance Matrix

Usage

covariance_matrix(diag, upper_tri)

Arguments

Value

A symmetric matrix with diag values on the main diagonal and upper_tri values in the lower and upper triangles.

Examples

m1 <- covariance_matrix(c(1, 1, 1, 1), c(.8, .3, .8, 0, 0, 0))
m1
mvtnorm::rmvnorm(5, mean = c(0, 0, 0, 0), sigma = m1)

# No correlation
covariance_matrix(c(1, 2, 3))

Create alpha string

Description

Create alpha string

Usage

create_alpha_string(borrowing_object, outcome_object)

## S4 method for signature 'Borrowing'
create_alpha_string(borrowing_object, outcome_object)

## S4 method for signature 'BorrowingHierarchicalCommensurate'
create_alpha_string(borrowing_object, outcome_object)

Arguments

Compile MCMC sampler using STAN and create analysis object

Description

Compile MCMC sampler using STAN and create analysis object

Usage

create_analysis_obj(
  data_matrix,
  outcome,
  borrowing,
  treatment,
  covariates = NULL,
  quiet = FALSE
)

Arguments

Value

Object of class Analysis.

Examples

if (check_cmdstan()) {
  anls <- create_analysis_obj(
    data_matrix = example_matrix,
    outcome = outcome_surv_exponential(
      "time",
      "cnsr",
      baseline_prior = prior_normal(0, 1000)
    ),
    borrowing = borrowing_hierarchical_commensurate(
      "ext",
      prior_exponential(.001)
    ),
    treatment = treatment_details(
      "trt",
      prior_normal(0, 1000)
    ),
    covariates = add_covariates(
      covariates = c("cov1", "cov2"),
      priors = prior_normal(0, 1000)
    )
  )
}

Create Baseline Data Simulation Object

Description

Create Baseline Data Simulation Object

Usage

create_baseline_object(
  n_trt_int,
  n_ctrl_int,
  n_ctrl_ext,
  covariates,
  transformations
)

Arguments

Details

Transformation functions are evaluated in order and create or overwrite a column in the data.frame with that name. The function should take a data.frame (specifically a BaselineDataFrame object from generate(BaselineObject)) and return a vector with length identical to the total number of patients. The ⁠@BaselineObject⁠ slot may be accessed directly or with get_quantiles() to create transformations. See binary_cutoff()

Value

A BaselineObject

Examples

bl_no_covs <- create_baseline_object(
  n_trt_int = 100,
  n_ctrl_int = 50,
  n_ctrl_ext = 100
)


bl_biomarkers <- create_baseline_object(
  n_trt_int = 100,
  n_ctrl_int = 50,
  n_ctrl_ext = 100,
  covariates = baseline_covariates(
    c("b1", "b2", "b3"),
    means_int = c(0, 0, 0),
    covariance_int = covariance_matrix(c(1, 1, 1), c(.8, .3, .8))
  ),
  transformations = list(
    exp_b1 = function(data) exp(data$b1),
    b2 = binary_cutoff("b2", int_cutoff = 0.7, ext_cutoff = 0.5)
  )
)

Create Data Matrix

Description

Creates a matrix suitable for create_analysis_obj(). Creates dummy variables for factors and allows transformations of covariates specified with a formula.

Usage

create_data_matrix(
  data,
  outcome,
  trt_flag_col,
  ext_flag_col,
  covariates = NULL,
  weight_var = NULL
)

Arguments

Value

Invisibly returns a matrix containing all variables to pass to create_analysis_obj(). Prints names of covariates columns to use with add_covariates().

Examples

dat <- survival::diabetic
dat$ext <- dat$trt == 0 & dat$id > 1000
data_mat <- create_data_matrix(
  dat,
  outcome = c("time", "status"),
  trt_flag_col = "trt",
  ext_flag_col = "ext",
  covariates = ~ age + laser + log(risk)
)
data_mat

Data Simulation

Description

Data Simulation

Usage

create_data_simulation(
  baseline,
  coefficients = numeric(),
  treatment_hr = 1,
  drift_hr = 1,
  event_dist,
  fixed_external_data
)

Arguments

Value

DataSimObject

Examples

baseline_obj <- create_baseline_object(
  n_trt_int = 100,
  n_ctrl_int = 50,
  n_ctrl_ext = 10,
  covariates = baseline_covariates(
    names = c("age", "score"),
    means_int = c(55, 5),
    means_ext = c(60, 5),
    covariance_int = covariance_matrix(c(5, 1))
  )
)
sim_obj <- create_data_simulation(
  baseline_obj,
  coefficients = c(age = 0.001, score = 1.5),
  event_dist = create_event_dist(dist = "exponential", lambdas = 1 / 36)
)
data_sim_list <- generate(sim_obj, treatment_hr = c(0.5, 1), drift_hr = 0.5)

Specify a Time to Event Distribution

Description

Uses simsurv::simsurv to generate time to event data. See simsurv help for more details.

Usage

create_event_dist(
  dist = NULL,
  lambdas = NULL,
  gammas = NULL,
  mixture = FALSE,
  pmix = 0.5,
  hazard = NULL,
  loghazard = NULL,
  cumhazard = NULL,
  logcumhazard = NULL,
  ...
)

null_event_dist()

Arguments

Value

A SimDataEvent object

null_event_dist returns an object with no parameters specified that does not simulate event times.

Examples

weibull_surv <- create_event_dist(dist = "weibull", lambdas = 1 / 200, gammas = 1)
exp_event_dist <- create_event_dist(dist = "exponential", lambdas = 1 / 36)
null_event_dist()

Compile MCMC sampler using STAN and create simulation object

Description

Compile MCMC sampler using STAN and create simulation object

Usage

create_simulation_obj(
  data_matrix_list,
  covariate = NULL,
  outcome,
  borrowing,
  treatment,
  quiet = TRUE
)

Arguments

Value

Object of class Simulation.

Examples

base_mat <- matrix(
  c(
    rep(0, 200), rep(0, 200), rep(1, 200),
    rep(1, 200), rep(0, 200), rep(0, 200),
    rep(0, 600)
  ),
  ncol = 3,
  dimnames = list(NULL, c("ext", "trt", "driftOR"))
)

add_binary_endpoint <- function(odds_ratio,
                                base_matrix = base_mat) {
  linear_predictor <- base_matrix[, "trt"] * log(odds_ratio)
  prob <- 1 / (1 + exp(-linear_predictor))

  bin_endpoint <- rbinom(
    NROW(base_matrix),
    1,
    prob
  )

  cbind(base_matrix, matrix(bin_endpoint, ncol = 1, dimnames = list(NULL, "ep")))
}

data_list <- list(
  list(add_binary_endpoint(1.5), add_binary_endpoint(1.5)),
  list(add_binary_endpoint(2.5), add_binary_endpoint(2.5))
)

guide <- data.frame(
  trueOR = c(1.5, 2.5),
  driftOR = c(1.0, 1.0),
  index = 1:2
)

sdl <- sim_data_list(
  data_list = data_list,
  guide = guide,
  effect = "trueOR",
  drift = "driftOR",
  index = "index"
)

if (check_cmdstan()) {
  sim_object <- create_simulation_obj(
    data_matrix_list = sdl,
    outcome = outcome_bin_logistic("ep", prior_normal(0, 1000)),
    borrowing = sim_borrowing_list(list(
      full_borrowing = borrowing_full("ext"),
      bdb = borrowing_hierarchical_commensurate("ext", prior_exponential(0.0001))
    )),
    treatment = treatment_details("trt", prior_normal(0, 1000))
  )
}

Create tau string

Description

Create tau string

Usage

create_tau_string(borrowing_object)

## S4 method for signature 'Borrowing'
create_tau_string(borrowing_object)

## S4 method for signature 'BorrowingHierarchicalCommensurate'
create_tau_string(borrowing_object)

Arguments

Create a DataSimEnrollment Object

Description

Create a DataSimEnrollment Object

Usage

custom_enrollment(fun, label)

Arguments

Value

A DataSimEnrollment object

Examples

custom_enrollment(
  fun = function(n) rpois(n, lambda = 5),
  label = "Poisson enrollment distribution"
)

Cut Off Functions

Description

Cut Off Functions

Usage

cut_off_none()

cut_off_after_first(time)

cut_off_after_last(time)

cut_off_after_events(n)

Arguments

Value

A DataSimCutOff object containing a cut-off function

Functions

• cut_off_none(): No cut off is specified

• cut_off_after_first(): Cut off at time after first enrolled patient

• cut_off_after_last(): Cut off at time after last enrolled patient

• cut_off_after_events(): Cut off after the time of the n-th event

Examples

cut_off_none()
cut_off_after_first(time = 36)
cut_off_after_last(time = 36)
cut_off_after_events(n = 20)

Constant Enrollment Rates

Description

Constant Enrollment Rates

Usage

enrollment_constant(rate, for_time = rep(1, length(rate)))

Arguments

Value

An object of class DataSimEnrollment to be passed to create_data_simulation()

Examples

# 10 patients/month for 6 months, then 5/month for 6 months
enroll_obj <- enrollment_constant(rate = c(10, 5), for_time = c(6, 6))
enroll_obj@fun(n = 80)

Evaluate constraints

Description

Evaluate constraints when these are called

Usage

eval_constraints(object)

## S4 method for signature 'Prior'
eval_constraints(object)

Arguments

Example data matrix

Description

A matrix containing data from a clinical trial with a treatment arm and a control arm, as well as data from an external control. In this simulated dataset, the true hazard ratio (HR) for the time-to-event endpoint comparing the experimental treatment to the control treatment is 0.70. The true odds ratio (OR) for the binary response endpoint comparing the experimental treatment to the control treatment is 1.20.

Usage

example_matrix

Format

A data frame with 500 rows and 11 columns. The distributions of patients is: 50 internal control patients, 100 internal experimental patients, 350 external control patients.

id

patient identifier

ext

0/1, flag for external controls

trt

0/1, flag for treatment arm

cov1

0/1, baseline covariate

cov2

0/1, baseline covariate

cov3

0/1, baseline covariate

cov4

0/1, baseline covariate

time

numeric >0, survival time

status

0/1, indicator for event status (1 = had event, 0 = did not have event)

cnsr

0/1, censoring indicator (1 = was censored, 0 = was not censored)

. This value is 1 - status.

resp

0/1, indicator for response outcome (1 = had a response, 0 = did not have a response)

Simulated Survival Data

Description

A data frame containing simulated data from a clinical trial with a treatment arm (n=200) and a control arm (n=158), as well as data from an external control (n=242).

Usage

example_surv

Format

A data frame with 600 rows and 6 variables:

trt

0/1, flag for treatment arm

ext

0/1, flag for external controls

eventtime

numeric >0, survival time

status

0/1, event indicator

censor

0/1, censoring indicator

cov1

0/1, binary baseline covariate 1

cov2

integer in [0, 15], baseline covariate 2

cov3

continuous numeric, baseline covariate 3

Legacy function for the exponential survival distribution

Description

Please use outcome_surv_exponential() instead.

Usage

exp_surv_dist(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that exp_surv_dist() is deprecated and that outcome_surv_exponential() should be used instead.

Legacy function for the exponential prior

Description

Please use prior_exponential() instead.

Usage

exponential_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that exponential_prior() is deprecated and that prior_exponential() should be used instead.

Legacy function for the gamma prior

Description

Please use prior_gamma() instead.

Usage

gamma_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that gamma_prior() is deprecated and that prior_gamma() should be used instead.

Generate Data from Object

Description

Generate Data from Object

Usage

generate(x, ...)

Arguments

Value

Object of class SimDataList.

Generate Data for a BaselineObject

Description

Generate Data for a BaselineObject

Usage

## S4 method for signature 'BaselineObject'
generate(x, ...)

Arguments

Value

A BaselineDataFrame object

Examples

bl_biomarkers <- create_baseline_object(
  n_trt_int = 100,
  n_ctrl_int = 50,
  n_ctrl_ext = 100,
  covariates = baseline_covariates(
    c("b1", "b2", "b3"),
    means_int = c(0, 0, 0),
    covariance_int = covariance_matrix(c(1, 1, 1), c(.8, .3, .8))
  ),
  transformations = list(
    exp_b1 = function(data) exp(data$b1),
    b2 = binary_cutoff("b2", int_cutoff = 0.7, ext_cutoff = 0.5)
  )
)
generate(bl_biomarkers)

Generate Data for a DataSimObject

Description

Generate Data for a DataSimObject

Usage

## S4 method for signature 'DataSimObject'
generate(x, n = 1, treatment_hr = NULL, drift_hr = NULL)

Arguments

Value

A SimDataList object for use with create_simulation_obj().

Examples

baseline_obj <- create_baseline_object(
  n_trt_int = 100,
  n_ctrl_int = 50,
  n_ctrl_ext = 10,
  covariates = baseline_covariates(
    names = c("age", "score"),
    means_int = c(55, 5),
    means_ext = c(60, 5),
    covariance_int = covariance_matrix(c(5, 1))
  )
)
sim_obj <- create_data_simulation(
  baseline_obj,
  coefficients = c(age = 0.001, score = 1.5),
  event_dist = create_event_dist(dist = "exponential", lambdas = 1 / 36)
)
data_sim_list <- generate(sim_obj, treatment_hr = c(0, 1), drift_hr = 0.5)

Get CmdStanModel objects for MCMCSimulationResults

Description

Show the CmdStanModel objects from MCMCSimulationResults objects.

Usage

get_cmd_stan_models(object)

## S4 method for signature 'MCMCSimulationResult'
get_cmd_stan_models(object)

Arguments

Value

List of lists of CmdStanModel objects for each model.

Get Simulated Data from SimDataList object

Description

Retrieves the simulated data from a SimDataList object by index.

Usage

get_data(object, index = 1, dataset = 1)

## S4 method for signature 'SimDataList'
get_data(object, index = NULL, dataset = NULL)

Arguments

Value

Simulated data as a data frame if the index is specified, else as a list

Get prior string for all covariates

Description

Get prior string for all covariates

Usage

get_prior_string_covariates(covariates)

Arguments

Get Quantiles of Random Data

Description

Helper for use within transformation functions for create_baseline_object().

Usage

get_quantiles(object, var)

Arguments

Value

A numeric vector containing quantiles based on the data generating distribution.

Get results for MCMCSimulationResults objects

Description

Get the results data.frame from MCMCSimulationResults objects.

Usage

get_results(object)

## S4 method for signature 'MCMCSimulationResult'
get_results(object)

Arguments

Value

data.frame with simulation results.

Get method for Stan model

Description

Get method for Stan model

Usage

get_stan_code(object)

## S4 method for signature 'Analysis'
get_stan_code(object)

Arguments

Value

String containing the Stan model

Get Variables

Description

Gets the data variable names from an object.

Usage

get_vars(object)

## S4 method for signature 'Covariates'
get_vars(object)

## S4 method for signature 'Treatment'
get_vars(object)

## S4 method for signature 'Borrowing'
get_vars(object)

## S4 method for signature 'TimeToEvent'
get_vars(object)

## S4 method for signature 'BinaryOutcome'
get_vars(object)

## S4 method for signature 'ContinuousOutcome'
get_vars(object)

## S4 method for signature 'Analysis'
get_vars(object)

## S4 method for signature 'NULL'
get_vars(object)

## S4 method for signature 'SimTreatmentList'
get_vars(object)

## S4 method for signature 'SimOutcomeList'
get_vars(object)

## S4 method for signature 'SimBorrowingList'
get_vars(object)

## S4 method for signature 'SimCovariateList'
get_vars(object)

## S4 method for signature 'Simulation'
get_vars(object)

## S4 method for signature 'BaselineObject'
get_vars(object)

Arguments

Value

A character vector containing variable names

Examples

get_vars(treatment_details(
  trt_flag_col = "treat_fl",
  trt_prior = prior_normal(0, 1000)
))

Legacy function for the half-cauchy prior

Description

Please use prior_half_cauchy() instead.

Usage

half_cauchy_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that half_cauchy_prior() is deprecated and that prior_half_cauchy() should be used instead.

Legacy function for the normal half prior

Description

Please use prior_half_normal() instead.

Usage

half_normal_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that half_normal_prior() is deprecated and that prior_half_normal() should be used instead.

Load and interpolate Stan model

Description

Load and interpolate Stan model

Usage

load_and_interpolate_stan_model(outcome, borrowing, analysis_obj)

Arguments

Value

String containing the interpolated Stan model

Load a Stan psborrow2 template

Description

This function loads a Stan template file from the package's 'inst/stan' directory.

Usage

load_stan_file(...)

Arguments

Value

template string

Legacy function for binary logistic regression

Description

Please use outcome_bin_logistic() instead.

Usage

logistic_bin_outcome(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that logistic_bin_outcome() is deprecated and that outcome_bin_logistic() should be used instead.

Sample from Stan model

Description

Method to sample from compiled Stan model and return a CmdStanMCMC object with draws.

Usage

mcmc_sample(x, ...)

## S4 method for signature 'ANY'
mcmc_sample(x, ...)

## S4 method for signature 'Analysis'
mcmc_sample(
  x,
  iter_warmup = 1000L,
  iter_sampling = 10000L,
  chains = 4L,
  verbose = FALSE,
  ...
)

## S4 method for signature 'Simulation'
mcmc_sample(
  x,
  posterior_quantiles = c(0.025, 0.975),
  iter_warmup = 1000L,
  iter_sampling = 10000L,
  chains = 4L,
  verbose = FALSE,
  keep_cmd_stan_models = FALSE,
  ...
)

Arguments

Details

Simulation objects

This function takes draws from an MCMC sampler and summarizes results.

Value

An object of class CmdStanMCMC

An object of class MCMCSimulationResult

Examples

## Analysis objects
if (check_cmdstan()) {
  anls <- create_analysis_obj(
    data_matrix = example_matrix,
    covariates = add_covariates(
      covariates = c("cov1", "cov2"),
      priors = prior_normal(0, 1000)
    ),
    outcome = outcome_surv_weibull_ph(
      "time",
      "cnsr",
      shape_prior = prior_normal(0, 1000),
      baseline_prior = prior_normal(0, 1000)
    ),
    borrowing = borrowing_hierarchical_commensurate(
      "ext",
      prior_exponential(.001)
    ),
    treatment = treatment_details("trt", prior_normal(0, 1000))
  )

  mcmc_results <- mcmc_sample(anls, chains = 1, iter_warmup = 500L, iter_sampling = 1000L)
}

## Simulation objects
base_mat <- matrix(
  c(
    rep(0, 200), rep(0, 200), rep(1, 200),
    rep(1, 200), rep(0, 200), rep(0, 200),
    rep(0, 600)
  ),
  ncol = 3,
  dimnames = list(NULL, c("ext", "trt", "driftOR"))
)

add_binary_endpoint <- function(odds_ratio,
                                base_matrix = base_mat) {
  linear_predictor <- base_matrix[, "trt"] * log(odds_ratio)
  prob <- 1 / (1 + exp(-linear_predictor))

  bin_endpoint <- rbinom(
    NROW(base_matrix),
    1,
    prob
  )

  cbind(base_matrix, matrix(bin_endpoint, ncol = 1, dimnames = list(NULL, "ep")))
}

data_list <- list(
  list(add_binary_endpoint(1.5), add_binary_endpoint(1.5)),
  list(add_binary_endpoint(2.5), add_binary_endpoint(2.5))
)

guide <- data.frame(
  trueOR = c(1.5, 2.5),
  driftOR = c(1.0, 1.0),
  index = 1:2
)

sdl <- sim_data_list(
  data_list = data_list,
  guide = guide,
  effect = "trueOR",
  drift = "driftOR",
  index = "index"
)

if (check_cmdstan()) {
  sim_object <- create_simulation_obj(
    data_matrix_list = sdl,
    outcome = outcome_bin_logistic("ep", prior_normal(0, 1000)),
    borrowing = sim_borrowing_list(list(
      full_borrowing = borrowing_full("ext"),
      bdb = borrowing_hierarchical_commensurate("ext", prior_exponential(0.0001))
    )),
    treatment = treatment_details("trt", prior_normal(0, 1000))
  )

  mcmc_sample(sim_object, chains = 1, iter_warmup = 500L, iter_sampling = 1000L)
}
## Not run: 
library(future)
# Use two separate R processes
plan("multisession", workers = 2)

# and two parallel threads in each.
mcmc_sample(sim_object, chains = 1, iter_warmup = 500L, iter_sampling = 1000L, parallel_chains = 2)

# Tidy up processes when finished
plan("sequential")

## End(Not run)

Legacy function for the normal prior

Description

Please use prior_normal() instead.

Usage

normal_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that normal_prior() is deprecated and that prior_normal() should be used instead.

Bernoulli distribution with logit parametrization

Description

Bernoulli distribution with logit parametrization

Usage

outcome_bin_logistic(binary_var, baseline_prior, weight_var = "")

Arguments

Details

Baseline Prior

The baseline_prior argument specifies the prior distribution for the baseline log odds. The interpretation of the baseline_prior differs slightly between borrowing methods selected.

• Dynamic borrowing using borrowing_hierarchical_commensurate(): the baseline_prior for Bayesian Dynamic Borrowing refers to the log odds of the external control arm.

• Full borrowing or No borrowing using borrowing_full() or borrowing_none(): the baseline_prior for these borrowing methods refers to the log odds for the internal control arm.

Value

Object of class OutcomeBinaryLogistic.

See Also

Other outcome models: outcome_cont_normal(), outcome_surv_exponential(), outcome_surv_pem(), outcome_surv_weibull_ph()

Examples

lg <- outcome_bin_logistic(
  binary_var = "response",
  baseline_prior = prior_normal(0, 1000)
)

Normal Outcome Distribution

Description

Normal Outcome Distribution

Usage

outcome_cont_normal(
  continuous_var,
  baseline_prior,
  std_dev_prior,
  weight_var = ""
)

Arguments

Details

Baseline Prior

The baseline_prior argument specifies the prior distribution for the intercept of the linear model. The interpretation of the baseline_prior differs slightly between borrowing methods selected.

• Dynamic borrowing using borrowing_hierarchical_commensurate(): the baseline_prior for Bayesian Dynamic Borrowing refers to the intercept of the external control arm.

• Full borrowing or No borrowing using borrowing_full() or borrowing_none(): the baseline_prior for these borrowing methods refers to the intercept for the internal control arm.

Value

Object of class OutcomeContinuousNormal.

See Also

Other outcome models: outcome_bin_logistic(), outcome_surv_exponential(), outcome_surv_pem(), outcome_surv_weibull_ph()

Examples

norm <- outcome_cont_normal(
  continuous_var = "tumor_size",
  baseline_prior = prior_normal(0, 100),
  std_dev_prior = prior_half_cauchy(1, 5)
)

Exponential survival distribution

Description

Exponential survival distribution

Usage

outcome_surv_exponential(time_var, cens_var, baseline_prior, weight_var = "")

Arguments

Details

Baseline Prior

The baseline_prior argument specifies the prior distribution for the baseline log hazard rate. The interpretation of the baseline_prior differs slightly between borrowing methods selected.

• Dynamic borrowing using borrowing_hierarchical_commensurate(): the baseline_prior for Bayesian Dynamic Borrowing refers to the log hazard rate of the external control arm.

• Full borrowing or No borrowing using borrowing_full() or borrowing_none(): the baseline_prior for these borrowing methods refers to the log hazard rate for the internal control arm.

Value

Object of class OutcomeSurvExponential.

See Also

Other outcome models: outcome_bin_logistic(), outcome_cont_normal(), outcome_surv_pem(), outcome_surv_weibull_ph()

Examples

es <- outcome_surv_exponential(
  time_var = "time",
  cens_var = "cens",
  baseline_prior = prior_normal(0, 1000)
)

Piecewise exponential survival distribution

Description

Piecewise exponential survival distribution

Usage

outcome_surv_pem(
  time_var,
  cens_var,
  baseline_prior,
  weight_var = "",
  cut_points
)

Arguments

Details

Baseline Prior

The baseline_prior argument specifies the prior distribution for the baseline log hazard rate within each cutpoint. Currently, there is no option to consider different baseline priors within each cut point. The interpretation of the baseline_prior differs slightly between borrowing methods selected.

• Dynamic borrowing using borrowing_hierarchical_commensurate(): the baseline_prior for Bayesian Dynamic Borrowing refers to the log hazard rate of the external control arm.

• Full borrowing or No borrowing using borrowing_full() or borrowing_none(): the baseline_prior for these borrowing methods refers to the log hazard rate for the internal control arm.

Value

Object of class OutcomeSurvPEM.

See Also

Other outcome models: outcome_bin_logistic(), outcome_cont_normal(), outcome_surv_exponential(), outcome_surv_weibull_ph()

Examples

es <- outcome_surv_pem(
  time_var = "time",
  cens_var = "cens",
  baseline_prior = prior_normal(0, 1000),
  cut_points = c(10, 15, 30)
)

Weibull survival distribution (proportional hazards formulation)

Description

Weibull survival distribution (proportional hazards formulation)

Usage

outcome_surv_weibull_ph(
  time_var,
  cens_var,
  shape_prior,
  baseline_prior,
  weight_var = ""
)

Arguments

Details

Baseline Prior

The baseline_prior argument specifies the prior distribution for the baseline log hazard rate. The interpretation of the baseline_prior differs slightly between borrowing methods selected.

• Dynamic borrowing using borrowing_hierarchical_commensurate(): the baseline_prior for Bayesian Dynamic Borrowing refers to the log hazard rate of the external control arm.

• Full borrowing or No borrowing using borrowing_full() or borrowing_none(): the baseline_prior for these borrowing methods refers to the log hazard rate for the internal control arm.

Value

Object of class OutcomeSurvWeibullPH.

See Also

Other outcome models: outcome_bin_logistic(), outcome_cont_normal(), outcome_surv_exponential(), outcome_surv_pem()

Examples

ws <- outcome_surv_weibull_ph(
  time_var = "time",
  cens_var = "cens",
  shape_prior = prior_exponential(1),
  baseline_prior = prior_normal(0, 1000)
)

Plot Prior Objects

Description

Plot prior distributions as densities. Continuous distributions are plotted as curves and discrete distributions as bar plots.

Usage

## S4 method for signature 'Prior,missing'
plot(
  x,
  y,
  default_limits,
  dist_type = c("continuous", "discrete"),
  density_fun,
  add,
  ...
)

## S4 method for signature 'PriorNormal,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorExponential,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorHalfCauchy,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorBernoulli,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorBeta,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorCauchy,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorGamma,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorHalfNormal,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'PriorPoisson,missing'
plot(x, y, add = FALSE, ...)

## S4 method for signature 'UniformPrior,missing'
plot(x, y, add = FALSE, ...)

Arguments

Details

Plot ranges are selected by default to show 99% of the density for unbounded distributions. The limits can be changed by specifying xlim = c(lower, upper).

Colors, line types, and other typical par() parameters can be used.

Value

No return value, this function generates a plot in the current graphics device.

Examples

plot(prior_normal(1, 2))
plot(prior_exponential(0.1))
plot(prior_half_cauchy(0, 1), xlim = c(-20, 20))
plot(prior_half_cauchy(0, 2), xlim = c(-20, 20), col = 2, add = TRUE)
plot(prior_bernoulli(0.4), xlim = c(0, 15))
plot(prior_beta(2, 2))
plot(prior_cauchy(0, 1), xlim = c(-20, 20))
plot(prior_cauchy(0, 2), xlim = c(-20, 20), col = 2, add = TRUE)
plot(prior_gamma(0.1, 0.1))
plot(prior_half_normal(0, 1), xlim = c(-20, 20))
plot(prior_half_normal(0, 2), xlim = c(-20, 20), col = 2, add = TRUE)
plot(prior_poisson(5), xlim = c(0, 15))
plot(uniform_prior(1, 2), xlim = c(0, 3))

Plot Probability Density Function Values

Description

Plot Probability Density Function Values

Usage

plot_pdf(x, y, ...)

Arguments

Value

No return value, this function generates a plot in the current graphics device.

Examples

x <- seq(-2, 2, len = 100)
y <- dnorm(x)
plot_pdf(x, y)

Plot Probability Mass Function Values

Description

Plot Probability Mass Function Values

Usage

plot_pmf(x, y, ..., col = "grey", add = FALSE)

Arguments

Value

No return value, this function generates a plot in the current graphics device.

Examples

x <- seq(0, 5)
y <- dpois(x, lambda = 2)
plot_pmf(x, y)

Legacy function for the poisson prior

Description

Please use prior_poisson() instead.

Usage

poisson_prior(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that poisson_prior() is deprecated and that prior_poisson() should be used instead.

Get All Variable Names in Simulated Data Model Matrix

Description

Get All Variable Names in Simulated Data Model Matrix

Usage

possible_data_sim_vars(object)

Arguments

Value

A vector of variable names

Prior bernoulli distribution

Description

Prior bernoulli distribution

Usage

prior_bernoulli(theta)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/bernoulli-distribution.html

Value

Object of class PriorBernoulli.

See Also

Other priors: prior_beta(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_normal(), prior_poisson(), uniform_prior()

Examples

bp <- prior_bernoulli(0.23)

Prior beta distribution

Description

Prior beta distribution

Usage

prior_beta(alpha, beta)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/beta-distribution.html

Value

Object of class PriorBeta

See Also

Other priors: prior_bernoulli(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_normal(), prior_poisson(), uniform_prior()

Examples

bp <- prior_beta(9, 235)

Prior cauchy distribution

Description

Prior cauchy distribution

Usage

prior_cauchy(mu, sigma)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/cauchy-distribution.html

Value

Object of class PriorCauchy.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_normal(), prior_poisson(), uniform_prior()

Examples

cp <- prior_cauchy(1, 1)

Prior exponential distribution

Description

Prior exponential distribution

Usage

prior_exponential(beta)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/exponential-distribution.html

Value

Object of class PriorExponential.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_normal(), prior_poisson(), uniform_prior()

Examples

ep <- prior_exponential(1)

Prior gamma distribution

Description

Prior gamma distribution

Usage

prior_gamma(alpha, beta)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/gamma-distribution.html

Value

Object of class PriorGamma.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_exponential(), prior_half_cauchy(), prior_half_normal(), prior_normal(), prior_poisson(), uniform_prior()

Examples

gp <- prior_gamma(0.001, 0.001)

Prior half-cauchy distribution

Description

Prior half-cauchy distribution

Usage

prior_half_cauchy(mu, sigma)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/cauchy-distribution.html

Value

Object of class PriorHalfCauchy.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_normal(), prior_normal(), prior_poisson(), uniform_prior()

Examples

hcp <- prior_half_cauchy(1, 1)

Prior half-normal distribution

Description

Prior half-normal distribution

Usage

prior_half_normal(mu, sigma)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/normal-distribution.html

Value

Object of class PriorHalfNormal.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_normal(), prior_poisson(), uniform_prior()

Examples

hcp <- prior_half_normal(1, 1)

Prior normal distribution

Description

Prior normal distribution

Usage

prior_normal(mu, sigma)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/normal-distribution.html

Value

Object of class PriorNormal.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_poisson(), uniform_prior()

Examples

np <- prior_normal(1, 1)

Prior poisson distribution

Description

Prior poisson distribution

Usage

prior_poisson(lambda)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/poisson.html

Value

Object of class PriorPoisson.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_normal(), uniform_prior()

Examples

pp <- prior_poisson(100)

Rename Covariates in draws Object

Description

Rename Covariates in draws Object

Usage

rename_draws_covariates(draws, analysis)

Arguments

Value

A draws[posterior::draws] object with covariate names.

Examples

if (check_cmdstan()) {
  analysis_object <- create_analysis_obj(
    data_matrix = example_matrix,
    covariates = add_covariates(
      covariates = c("cov1", "cov2"),
      priors = prior_normal(0, 1000)
    ),
    outcome = outcome_surv_exponential(
      "time",
      "cnsr",
      baseline_prior = prior_normal(0, 1000)
    ),
    borrowing = borrowing_hierarchical_commensurate(
      "ext",
      prior_exponential(.001)
    ),
    treatment = treatment_details(
      "trt",
      prior_normal(0, 1000)
    )
  )
  samples <- mcmc_sample(analysis_object, 200, 400, 1)
  draws <- samples$draws()
  renamed_draws <- rename_draws_covariates(draws, analysis_object)
  summary(renamed_draws)
}

Set Clinical Cut Off Rule

Description

Set Clinical Cut Off Rule

Usage

set_cut_off(object, internal = cut_off_none(), external = cut_off_none())

Arguments

Value

A DataSimObject with updated cut_off_internal and cut_off_external slots.

Examples

data_sim <- create_data_simulation(
  create_baseline_object(10, 10, 10),
  event_dist = create_event_dist(dist = "exponential", lambdas = 1 / 36)
)
set_cut_off(
  data_sim,
  cut_off_after_events(n = 10),
  cut_off_after_first(time = 30)
)

Set Drop Out Distribution

Description

Set Drop Out Distribution

Usage

set_dropout(object, internal_treated, internal_control, external_control)

Arguments

Details

DataSimEvent objects can be specified with create_event_dist(). Currently no beta parameters can be used in drop out distributions (unlike for the survival outcome).

Value

A DataSimObject with updated internal_treated, internal_control and external_control slots.

Examples

data_sim <- create_data_simulation(
  create_baseline_object(10, 10, 10),
  event_dist = create_event_dist(dist = "exponential", lambdas = 1 / 36)
)
set_dropout(
  data_sim,
  internal_treated = create_event_dist(dist = "exponential", lambdas = 1 / 55),
  internal_control = create_event_dist(dist = "exponential", lambdas = 1 / 50),
  external_control = create_event_dist(dist = "exponential", lambdas = 1 / 40)
)

Set Enrollment Rates for Internal and External Trials

Description

Set Enrollment Rates for Internal and External Trials

Usage

set_enrollment(object, internal, external = internal)

Arguments

Value

A DataSimObject with updated enrollment_internal and enrollment_external slots.

Examples

data_sim <- create_data_simulation(
  create_baseline_object(10, 10, 10),
  event_dist = create_event_dist(dist = "exponential", lambdas = 1 / 36)
)
set_enrollment(
  data_sim,
  internal = enrollment_constant(rate = c(10, 5), for_time = c(6, 6)),
  external = enrollment_constant(rate = c(5), for_time = c(20))
)

Set transformations in BaselineObject objects

Description

Set transformations in BaselineObject objects

Usage

set_transformations(object, ..., overwrite = FALSE)

Arguments

Value

BaselineObject object with transformations

Set Transformations in Baseline Objects

Description

Set Transformations in Baseline Objects

Usage

## S4 method for signature 'BaselineObject'
set_transformations(object, ..., overwrite = FALSE)

Arguments

Details

Transformation functions are evaluated in order and create or overwrite a column in the data.frame with that name. The function should have signature ⁠function(data)⁠, taking a data.frame (specifically a BaselineDataFrame object from generate(BaselineObject)) and return a vector with length identical to the total number of patients. The ⁠@BaselineObject⁠ slot of the BaselineDataFrame may be accessed directly or with get_quantiles() to create transformations. See binary_cutoff().

Value

An updated BaselineObject

Examples

baseline <- create_baseline_object(
  100, 50, 100,
  covariates = baseline_covariates(
    names = "age", means_int = 55,
    covariance_int = covariance_matrix(5)
  )
)
set_transformations(baseline, age_scaled = function(data) scale(data$age))

Show guide for objects with guides

Description

Show the guide in Simulation objects.

Usage

show_guide(object)

## S4 method for signature 'Simulation'
show_guide(object)

Arguments

Value

A data.frame showing all simulation scenarios.

Input borrowing details for a simulation study

Description

A function for defining which borrowing scenarios should be evaluated as part of a simulation study.

Usage

sim_borrowing_list(borrowing_list)

Arguments

Value

Object of class SimBorrowingList.

See Also

Other simulation classes: sim_covariate_list(), sim_data_list(), sim_outcome_list(), sim_treatment_list()

Examples

borrow_scenarios <- sim_borrowing_list(
  list(
    "No borrowing" = borrowing_none("ext"),
    "Full borrowing" = borrowing_full("ext"),
    "BDB, uninformative prior" = borrowing_hierarchical_commensurate(
      "ext",
      prior_gamma(0.001, 0.001)
    ),
    "BDB, informative prior" = borrowing_hierarchical_commensurate(
      "ext",
      prior_gamma(1, 0.001)
    )
  )
)

Input covariate adjustment details for a simulation study

Description

A function for defining which covariate adjustment scenarios should be evaluated as part of a simulation study.

Usage

sim_covariate_list(covariate_list)

Arguments

Details

This function allows the user to specify covariate adjustment details that will be included as part of a simulation study. It is often of interest to compare several adjustment methods to no adjustment. To specify no adjustment, pass NULL as a list item to covariate_list.

Value

Object of class SimCovariateList.

See Also

Other simulation classes: sim_borrowing_list(), sim_data_list(), sim_outcome_list(), sim_treatment_list()

Examples

covariates <- sim_covariate_list(
  list(
    "No adjustment" = NULL,
    "Covariates 1 and 2" = add_covariates(c("cov1", "cov2"), prior_normal(0, 1000))
  )
)

Specify covariates for simulation study

Description

Provide details on the desired covariate distributions and covariance for for a simulation study.

Usage

sim_covariates(
  covariates,
  covariance_internal,
  covariance_external = covariance_internal
)

Arguments

Details

This function is intended to specify the number of covariates and relationships between them for the purposes of designing a simulation study in psborrow2. Because the outcome model does not necessarily need to adjust for covariates, this function is not necessary in create_simulation_obj(). The relationship between the treatment and the outcome is specified elsewhere (i.e, in sim_survival() or sim_binary_event()).

We need a few things to

Value

Object of class SimCovariates

See Also

Other simulation: sim_samplesize()

Examples

set.seed(123)
covmat <- matrix(rWishart(1, 2, diag(2)), ncol = 2)

covset1 <- sim_covariates(
  covariates = list(
    cov1 = bin_var(0.5, 0.5),
    cov2 = cont_var(100, 130)
  ),
  covariance_internal = covmat
)

Summarize the number of continuous and binary covariates in a SimCovariates object created by sim_covariates()

Description

Summarize the number of continuous and binary covariates in a SimCovariates object created by sim_covariates()

Usage

sim_covariates_summ(sim_covariates_obj)

Arguments

Value

data.frame showing covariate names and types as well as counts of binary and continuous covariates.

Input generated data for a simulation study

Description

A function for defining generated data for use as part of a simulation study.

Usage

sim_data_list(data_list, guide, effect, drift, index)

Arguments

Details

In this function, you are providing generated data for analysis in a simulation study in psborrow2. Note that this function does not do any data generation on your behalf; it assumes that you have generated the data already. For a full working example, refer to the relevant vignette: vignette('simulation_study', package = 'psborrow2').

More information on the inputs is provided below.

Matrix requirements in data_list

Each matrix embedded in data_list must have:

1. a flag for whether the patient is an external control

2. a flag for whether the patient is in the experimental treatment arm

3. outcome information (time and censorship for survival, flag for outcome in binary endpoints)

Optionally, the matrices may also contain covariates. See examples.

data_list

Each set of distinct data generation parameters should be represented by a single list of matrices. Because multiple scenarios may want to be compared, a list of list of matrices is preferred. See examples.

guide

The guide should be a data.frame with one row per scenario. As a consquence of this, the length of the list should equal the number of rows in the guide. See examples.

Value

Object of class SimDataList.

See Also

Other simulation classes: sim_borrowing_list(), sim_covariate_list(), sim_outcome_list(), sim_treatment_list()

Examples

base_mat <- matrix(
  c(
    rep(0, 200), rep(0, 200), rep(1, 200),
    rep(1, 200), rep(0, 200), rep(0, 200),
    rep(0, 600)
  ),
  ncol = 3,
  dimnames = list(NULL, c("ext", "trt", "driftOR"))
)

add_binary_endpoint <- function(odds_ratio,
                                base_matrix = base_mat) {
  linear_predictor <- base_matrix[, "trt"] * log(odds_ratio)
  prob <- 1 / (1 + exp(-linear_predictor))

  bin_endpoint <- rbinom(
    NROW(base_matrix),
    1,
    prob
  )

  cbind(base_matrix, matrix(bin_endpoint, ncol = 1, dimnames = list(NULL, "ep")))
}

data_list <- list(
  list(add_binary_endpoint(1.5), add_binary_endpoint(1.5)),
  list(add_binary_endpoint(2.5), add_binary_endpoint(2.5))
)

guide <- data.frame(
  trueOR = c(1.5, 2.5),
  driftOR = c(1.0, 1.0),
  ind = c(1, 2)
)

sdl <- sim_data_list(
  data_list = data_list,
  guide = guide,
  effect = "trueOR",
  drift = "driftOR",
  index = "ind"
)

Input outcome details for a simulation study

Description

A function for defining which outcome scenarios should be evaluated as part of a simulation study.

Usage

sim_outcome_list(outcome_list)

Arguments

Value

Object of class SimOutcomeList.

See Also

Other simulation classes: sim_borrowing_list(), sim_covariate_list(), sim_data_list(), sim_treatment_list()

Examples

outcome_scenarios <- sim_outcome_list(
  list(
    "Exponential" = outcome_surv_exponential("time", "cnsr", prior_normal(0, 10000))
  )
)

Set simulation study parameters for sample size

Description

Set simulation study parameters for sample size

Usage

sim_samplesize(n_internal_control, n_external_control, n_internal_experimental)

Arguments

Value

Object of class SimSampleSize

See Also

Other simulation: sim_covariates()

Examples

ss <- sim_samplesize(200, 200, 500)

Input treatment details for a simulation study

Description

A function for defining which treatment scenarios should be evaluated as part of a simulation study.

Usage

sim_treatment_list(treatment_list)

Arguments

Value

Object of class SimTreatmentList.

See Also

Other simulation classes: sim_borrowing_list(), sim_covariate_list(), sim_data_list(), sim_outcome_list()

Examples

treatment_scenarios <- sim_treatment_list(
  list(
    "Standard" = treatment_details("trt", prior_normal(0, 1000))
  )
)

Specify Treatment Details

Description

Specify the treatment arm column name in the model matrix and set a prior distribution for the treatment effect (log hazard ratio or log odds ratio)

Usage

treatment_details(trt_flag_col, trt_prior)

Arguments

Value

Object of class Treatment.

Examples

sta <- treatment_details(
  trt_flag_col = "trt",
  trt_prior = prior_normal(0, 1000)
)

Trim columns from Data Matrix Based on Borrowing object type

Description

Trim columns from Data Matrix Based on Borrowing object type

Usage

trim_cols(borrowing_object, analysis_object)

## S4 method for signature 'Borrowing'
trim_cols(borrowing_object, analysis_object)

## S4 method for signature 'BorrowingHierarchicalCommensurate'
trim_cols(borrowing_object, analysis_object)

Arguments

Trim Rows from Data Matrix Based on Borrowing object type

Description

Trim Rows from Data Matrix Based on Borrowing object type

Usage

trim_rows(borrowing_object, analysis_object)

## S4 method for signature 'Borrowing'
trim_rows(borrowing_object, analysis_object)

## S4 method for signature 'BorrowingNone'
trim_rows(borrowing_object, analysis_object)

Arguments

Prior uniform distribution

Description

Prior uniform distribution

Usage

uniform_prior(alpha, beta)

Arguments

Details

Stan reference https://mc-stan.org/docs/functions-reference/uniform-distribution.html

Value

Object of class UniformPrior.

See Also

Other priors: prior_bernoulli(), prior_beta(), prior_cauchy(), prior_exponential(), prior_gamma(), prior_half_cauchy(), prior_half_normal(), prior_normal(), prior_poisson()

Examples

up <- uniform_prior(0, 1)

Create Variable Dictionary

Description

Create Variable Dictionary

Usage

variable_dictionary(analysis_obj)

Arguments

Value

A data.frame with the names of Stan variables and the descriptions.

Legacy function for the Weibull proportional Hazards survival distribution

Description

Please use outcome_surv_weibull_ph() instead.

Usage

weib_ph_surv_dist(...)

Arguments

Value

This function does not return a value. When called, it triggers an error message indicating that weib_ph_surv_dist() is deprecated and that outcome_surv_weibull_ph() should be used instead.