Create General ANCOVA Model with Flexible Specifications

Creates a build_model object for ANCOVA (Analysis of Covariance) with flexible specifications for number of arms, contrasts, allocation ratios, and parameters. This is the general function that underlies all ANCOVA model variants in the package.

Usage

build_model_ancova(
  prior_intercept = NULL,
  prior_sigma = NULL,
  prior_covariate = NULL,
  prior_treatment = NULL,
  link_sigma = "identity",
  n_arms = NULL,
  contrasts = NULL,
  p_alloc = NULL,
  intercept = NULL,
  b_arm_treat = NULL,
  b_covariate,
  sigma = NULL
)

Arguments

prior_intercept

Prior for the intercept parameter. If NULL (default), uses normal(0, 10). Must be a brmsprior object created with brms::set_prior().

prior_sigma

Prior for the residual standard deviation. If NULL (default), uses normal(0, 10). Must be a brmsprior object created with brms::set_prior().

prior_covariate

Prior for the covariate effect. If NULL (default), uses student_t(3, 0, 1). Must be a brmsprior object created with brms::set_prior().

prior_treatment

Prior for the treatment effect. If NULL (default), uses student_t(3, 0, 1). Must be a brmsprior object created with brms::set_prior().

link_sigma

Link function for the residual standard deviation. Default is "identity".

n_arms

Number of arms in the trial (must be >= 2). Required parameter.

contrasts

Contrast method for treatment arms. Either a character string (e.g., "contr.treatment", "contr.sum") or a contrast matrix. Required parameter.

p_alloc

Numeric vector of allocation probabilities summing to 1. Length must equal n_arms. Required parameter.

intercept

Intercept value for data generation. Required parameter.

b_arm_treat

Treatment effect coefficients for data generation. Vector length must equal n_arms - 1. Required parameter.

b_covariate

Covariate effect coefficient for data generation. Required parameter.

sigma

Residual standard deviation for data generation (must be > 0). Required parameter.

Value

An S7 object of class "rctbp_model_ancova" ready for use with build_design() and power analysis functions.

Details

This function creates a complete ANCOVA model with the following structure:

Model Formula: outcome ~ 1 + covariate + arm

Data Structure: The generated data includes:

• covariate: Standardized normal covariate

• arm: Factor with levels "ctrl" and treatment arms ("treat_1", "treat_2", etc.)

• outcome: Continuous outcome generated from the linear model

Parameters: The model includes parameters for intercept, covariate effect, treatment effects, and residual standard deviation (sigma).

Model Compilation: The function compiles the brms model during creation, which may take some time but enables efficient power analysis later.

Convenience Functions: For common use cases, consider the wrapper functions that can be called via the 'predefined_model' argument in build_model():

• build_model_ancova_cont_2arms() - 2-arm continuous ANCOVA

• build_model_ancova_cont_3arms() - 3-arm continuous ANCOVA

See also

build_model(), build_design(), build_model_ancova_cont_2arms(), build_model_ancova_cont_3arms()

Examples

if (FALSE) { # \dontrun{
# Create 2-arm ANCOVA model
model_2arm <- build_model_ancova(
  n_arms = 2,
  contrasts = "contr.treatment",
  p_alloc = c(0.5, 0.5),
  intercept = 0,
  b_arm_treat = 0.5,
  b_covariate = 0.3,
  sigma = 1
)
} # }