Creates an S7 rctbp_design object that combines a rctbp_model with analysis configuration parameters for Bayesian power analysis. This constructor function provides a user-friendly interface to the S7 class constructor.
Usage
build_design(
model,
target_params,
thresholds_success,
thresholds_futility,
p_sig_success,
p_sig_futility,
n_interim_analyses = 0,
interim_function = NULL,
design_name = NULL
)Arguments
- model
An S7 object of class "rctbp_model" created by
build_model()- target_params
Character vector specifying which model parameters to analyze for power. Must be valid parameter names from the brms model (e.g., "b_arms_treat" for treatment effect). Required.
- thresholds_success
Numeric vector of success thresholds for each target parameter. Length must match target_params. These represent the minimum clinically meaningful effect sizes. Required.
- thresholds_futility
Numeric vector of futility thresholds for each target parameter. Length must match target_params. These represent effect sizes below which the treatment is considered ineffective. Required.
- p_sig_success
Probability threshold for declaring success. The posterior probability that the effect exceeds the success threshold must be greater than this value to declare success (typically 0.975 or 0.95). Required.
- p_sig_futility
Probability threshold for declaring futility. The posterior probability that the effect is below the futility threshold must be greater than this value to declare futility (typically 0.5). Required.
- n_interim_analyses
Number of interim analyses planned during the study. Defaults to 0 for studies with only final analysis. Must be non-negative integer.
- interim_function
Optional function for adaptive interim analyses. If provided, must accept an interim_parameters argument defined as a call to list(). Currently not fully implemented. Defaults to NULL.
- design_name
Optional character string providing a descriptive name for the design. Defaults to NULL.
Value
An S7 object of class "rctbp_design" containing all elements from the model plus the analysis configuration. Key components include:
- data_simulation_fn
Data simulation function from the model
- brms_model
Compiled brms model template
- target_params
Target parameters for analysis
- thresholds_success
Success thresholds
- thresholds_futility
Futility thresholds
- p_sig_success
Success probability threshold
- p_sig_futility
Futility probability threshold
Details
The rctbp_design class combines model specifications with analysis decision criteria:
Model Integration: Inherits the data simulation function, compiled brms model, and metadata from the model object.
Decision Thresholds: Success and futility thresholds define the regions of practical equivalence (ROPE) for decision making. Effects above the success threshold are considered clinically meaningful, while effects below the futility threshold suggest treatment ineffectiveness.
Probability Thresholds: The p_sig_success and p_sig_futility parameters control the certainty required for decisions. Higher values require stronger evidence.
Validation: All parameters are validated for consistency with the underlying model structure and each other.
Examples
if (FALSE) { # \dontrun{
# Create an ANCOVA model
ancova_model <- build_model_ancova_cont()
# Create a design for analyzing treatment effect
my_design <- build_design(
model = ancova_model,
target_params = "b_arms_treat",
n_interim_analyses = 0,
thresholds_success = 0.2,
thresholds_futility = 0,
p_sig_success = 0.975,
p_sig_futility = 0.5,
design_name = "ANCOVA Treatment Effect Analysis"
)
} # }