Skip to contents

Create a Build Model Object

Source: R/class_model.R
build_model.Rd

Constructs a build_model object that encapsulates a data simulation function, a compiled brms model, and associated metadata for power analysis. This object serves as the foundation for Bayesian power analysis in RCTs.

Usage

build_model(
  predefined_model = NULL,
  data_simulation_fn,
  brms_model,
  n_endpoints = NULL,
  endpoint_types = NULL,
  n_arms = NULL,
  n_repeated_measures = NULL,
  model_name = NULL
)

Arguments

predefined_model

Optional character string specifying a predefined model to use instead of creating a custom model. Currently supported values:

  • "ancova_cont_2arms" - ANCOVA model for continuous outcomes with baseline covariate and 2 arms

  • "ancova_cont_3arms" - ANCOVA model for continuous outcomes with baseline covariate and 3 arms

When specified, other parameters are ignored and the predefined model is returned. Use list_predefined_models() to see all available models.

data_simulation_fn

A function that simulates data for the RCT. Must take parameters n_total, p_alloc, and further parameters needed for data simulation.

brms_model

A fitted brmsfit object that serves as the template model. This should be compiled without posterior draws (chains = 0) for efficiency.

n_endpoints

Number of endpoints in the study (must be positive integer)

endpoint_types

Character vector specifying the type of each endpoint. Valid types are "continuous", "binary", "count". Length must match n_endpoints.

n_arms

Number of arms in the study including control arm (must be positive integer)

n_repeated_measures

Number of repeated measures per participant. Use NULL or 0 for single time point studies.

model_name

Optional character string providing a descriptive name for the model

Value

An S7 object of class "rctbp_model" containing the specified properties

Details

The build_model class encapsulates all components needed for power analysis simulation:

Predefined Models: For convenience, users can specify predefined_model to use ready-made model configurations. This is the recommended approach for standard analyses. When using predefined models, other parameters are ignored.

Custom Models: For advanced users, custom models can be created by providing all required parameters:

Data Simulation Function: Must accept n_total (total sample size), p_alloc (vector of allocation probabilities), and true_parameter_values (named list of parameter values). The function should return a data.frame with simulated baseline data ready for outcome generation.

BRMS Model: A compiled brms model that will be used as a template. The model should be fitted with minimal chains (e.g., chains = 0) to serve as a compilation template only.

Validation: The function validates that the data simulation function has the required parameter structure and that the brms model is properly fitted.

See also

build_design(), build_model_ancova()

Examples

if (FALSE) { # \dontrun{
# Method 1: Use predefined model (recommended)
ancova_model <- build_model(predefined_model = "ancova_cont")
} # }