This class represents a statistical model for Bayesian borrowing analysis. It provides methods for creating the model, performing inference, and calculating posterior moments.
Public fields
empirical_bayesLogical indicating if empirical Bayes method is used.
analytic_ocsResults of the analytic operating characteristics simulation.
posterior_parametersParameters of the posterior distribution.
quantile_summary_columnsNames of
posterior_parameterscolumns that are also summarised by their quantiles. A mean describes a quantity the model reports, but not the spread of one it selects per replicate. Empty for every method that does not select anything.post_meanMean of the posterior distribution.
post_medianMedian of the posterior distribution.
prior_meanMean of the prior distribution.
prior_varVariance of the prior distribution.
post_varVariance of the posterior distribution.
parametersList of model parameters.
RBesT_priorPrior distribution from RBesT package.
RBesT_posteriorPosterior distribution from RBesT package.
ess_moritaEffective sample size calculated using Morita's method.
ess_elirEffective sample size calculated using ELIR method.
ess_momentEffective sample size calculated using moment matching.
priorPrior distribution used in the model.
methodMethod used for the analysis.
mcmcLogical indicating if MCMC is used.
RBesT_posterior_normixNormal mixture approximation to the posterior distribution
RBesT_prior_normixNormal mixture approximation to the prior distribution
summary_measure_likelihoodLikelihood familly, that is, the distribution used to model the summary measure of the treatment effect.
n_components_mixture_approxNumber of mixture components used for the mixture approximation
aic_penalty_parameter_mixture_approxAIC penalty parameter used for the mixture approximation
empirical_bayes_from_sampleWhether the empirical Bayes quantities are a function of the replicate's sample alone, so that a deterministic model may still share an analysis between replicates with equal samples.
n_nonestimable_replicatesReplicates dropped by the last simulation because their target summary measure was undefined.
estimable_replicatesWhich rows of the last simulation's replicates were kept for analysis, in the order they were generated.
analysis_critical_valuePosterior probability threshold the analysis decides at, recorded when a simulation starts. Methods whose tuning depends on the decision rule read it, so that they are tuned for the test that is actually performed.
null_spaceNull hypothesis space,
"left"or"right"ofparameters$theta_0. Set by the methods that callhypothesis_space_transformation().
Methods
Model$hypothesis_space_transformation()
Express treatment effects relative to the null hypothesis
Translates the source estimate and the given target estimates by
parameters$theta_0 and, for a right null space, mirrors them, so that
the null hypothesis is the half line below 0 whatever the case study's
theta_0 and null_space. Methods defined only for that case can then
work on the result directly.
Model$create()
This method creates a Model object based on the specified configuration and method.
Model$vectorised_replicate_inference()
Run every replicate at once, when the method allows it
Methods with a closed-form posterior can produce the whole simulation
output with vector arithmetic instead of one inference per replicate.
Subclasses that can do so override this method; returning NULL means
"no fast path available", and
Model$simulation_for_given_treatment_effect() falls back to the
replicate loop.
Model$calibrate_for_design()
Fix any hyperparameter that the scenario's design decides
Most methods take their hyperparameters from the configuration grid, and for them this does nothing. A method that instead derives them from the target design - its sample size, and so the standard error it can expect - overrides this, and the drivers call it once per scenario, before any replicate is generated. Deriving them inside the replicate loop instead would make the prior a function of the data.
Model$inference_cache_scope()
Scenario identity under which replicate analyses may be shared
Two replicates may share an analysis only when everything the analysis reads, apart from the observed data, is the same. That is what this identifies. The drift is deliberately absent: it moves the sampling distribution of the data rather than the posterior any particular data set implies, so scenarios differing only in drift share this scope and meet in the cache.
Returning NULL means "do not cache", which is the default. Opting in is
left to subclasses because it is only sound for a model whose reported
results are a deterministic function of the data: a model that samples,
as the Stan backed ones and the empirical Bayes prior refits do, would
otherwise have one replicate's Monte Carlo error stand in for another's.
Usage
Model$inference_cache_scope(
target_data,
critical_value,
theta_0,
confidence_level,
null_space,
n_samples_quantiles_estimation,
simulation_config
)Arguments
target_dataTarget study data.
critical_valueCritical value for hypothesis testing.
theta_0Null hypothesis value.
confidence_levelConfidence level for the credible interval.
null_spaceThe null space for hypothesis testing.
n_samples_quantiles_estimationNumber of samples used for quantiles.
simulation_configConfiguration of simulation study.
Model$posterior_mean()
Method to calculate the mean of the posterior distribution
Model$posterior_quantile()
Method to compute quantiles of the posterior distribution
Model$posterior_median()
Method to calculate the median of the posterior distribution
Model$credible_interval()
Model$test_decision()
This function returns the test decision for a fitted model.
Model$simulation_for_given_treatment_effect()
Method to simulate for a given treatment effect
Usage
Model$simulation_for_given_treatment_effect(
target_data,
n_replicates,
critical_value,
theta_0,
confidence_level,
null_space,
case_study,
method,
to_return = c("credible_interval", "test_decision", "posterior_mean",
"posterior_median", "posterior_parameters", "ess_moment", "ess_precision",
"ess_elir", "fit_success", "mcmc_diagnostics"),
verbose = 0,
n_samples_quantiles_estimation,
simulation_config = NULL,
samples = NULL
)Arguments
target_dataData for the target treatment effect
n_replicatesNumber of replicates to simulate
critical_valueCritical value for hypothesis testing
theta_0Null hypothesis value
confidence_levelConfidence level for the credible interval
null_spaceThe null space for hypothesis testing
case_studyCase study name
methodMethod name
to_returnList of OCs to return
verboseVerbosity level (0 or 1)
n_samples_quantiles_estimationNumber of samples used to estimate distributions quantiles.
simulation_configSimulation configuration. Only required when
to_returnincludes"ess_moment","ess_precision"or"ess_elir"and the method has no vectorised fast path, since those outputs are computed viaposterior_to_RBesT()/prior_to_RBesT(), which needsimulation_config$n_samples_mixture_approx.samplesOptional replicate rows to analyse instead of generating
n_replicatesof them, such as the trials ofBinaryTargetData$enumerate_support().n_replicatesmust then be their number.
Model$estimate_frequentist_operating_characteristics()
Method to estimate frequentist operating characteristics
Usage
Model$estimate_frequentist_operating_characteristics(
theta_0,
target_data,
n_replicates,
critical_value,
confidence_level,
null_space,
n_samples_quantiles_estimation,
case_study,
method,
verbose = 0,
simulation_config = NULL,
exact_enumeration = FALSE,
enumeration_tail_mass = 1e-10
)Arguments
theta_0Null hypothesis value
target_dataData for the target treatment effect
n_replicatesNumber of replicates to simulate
critical_valueCritical value for hypothesis testing
confidence_levelConfidence level for the credible interval
null_spaceThe null space for hypothesis testing
n_samples_quantiles_estimationNumber of samples used to estimate distributions quantiles.
case_studyCase study name
methodMethod name
verboseVerbosity level (0 or 1)
simulation_configSimulation configuration, needed by
simulation_for_given_treatment_effect()foress_moment,ess_precisionandess_eliron methods without a vectorised fast path.exact_enumerationWhether to compute the operating characteristics exactly, as sums over every trial outcome weighted by its probability (see
BinaryTargetData$enumerate_support()), instead of averages overn_replicatessimulated trials. The intervals then collapse onto the point estimates, since there is no Monte Carlo error.enumeration_tail_massUpper bound on the probability of the trial outcomes the enumeration leaves out.
Model$estimate_bayesian_operating_characteristics()
Method to estimate Bayesian operating characteristics
Usage
Model$estimate_bayesian_operating_characteristics(
design_prior,
theta_0,
source_data,
n_replicates,
critical_value,
confidence_level,
null_space,
n_samples_design_prior,
target_sample_size_per_arm,
case_study_config,
target_to_source_std_ratio,
dropout_probability = 0,
event_time_distribution = "exponential",
treatment_delay = 0,
simulation_config,
case_study,
method,
n_samples_quantiles_estimation
)Arguments
design_priorDesign prior
theta_0Null hypothesis value
source_dataSource data
n_replicatesNumber of replicates to simulate
critical_valueCritical value for hypothesis testing
confidence_levelConfidence level for the credible interval
null_spaceThe null space for hypothesis testing
n_samples_design_priorNumber of samples from the design prior
target_sample_size_per_armSample size per arm in the target study
case_study_configConfiguration of the case study
target_to_source_std_ratioRatio between the target and source study standard deviation
dropout_probabilityProbability of loss to follow-up over the maximum follow-up time. Only used for the time-to-event endpoint.
event_time_distributionDistribution of the event times, either "exponential" or "weibull". Only used for the time-to-event endpoint.
treatment_delayTime before the treatment effect starts, in years. Only used for the time-to-event endpoint.
simulation_configSimulation configuration
case_studyCase study name
methodMethod name
n_samples_quantiles_estimationNumber of samples used to estimate distribution quantiles
Model$prior_elir_ess()
ELIR effective sample size of the current prior
The default route approximates the prior by a mixture fitted to samples drawn from it, and refits between replicates only when the prior is data dependent. Subclasses whose prior has a closed form override this.
Model$posterior_ess()
Effective sample sizes of the current posterior
Returns the moment-based and precision-based effective sample sizes the simulation reports per replicate. The default route approximates the posterior by a mixture fitted to samples drawn from it, which is the only option when neither the posterior summary nor draws from it are available. Subclasses that know their posterior standard deviation and credible interval override this and evaluate the definitions directly.
Model$posterior_beta_mixture()
Beta mixture approximation to the posterior response rate
The unit information design prior rescales the shape parameters of a Beta
mixture, so it needs the fit on the \([0, 1]\) rate scale rather than the one
on the treatment effect scale that posterior_to_RBesT() produces. It is
built here on request because that construction runs once per case study,
whereas posterior_to_RBesT() runs once per replicate.
Model$plot_pdfs()
Plot prior and posterior probability density functions (PDF).
Model$plot_prior_pdf()
Plot prior probability density function (PDF).
Model$plot_posterior_pdf()
Plot posterior probability density function (PDF).
Model$summary_rows()
Rows of the model summary
The rows shared by every model: the method name and the moments of the
prior and of the posterior, then each method-specific entry of
posterior_parameters. A quantity the model has not set, because
inference has not run or the method does not compute it, gets no row.
Subclasses add their own parameters by extending
super$summary_rows().
Model$print_model_summary()
Print a summary of the model attributes
Prints the table returned by summary_rows(), numeric values formatted
to 6 decimal places.