Simulate a single outcome per patient (continuous or binary)

This function simulates an endpoint (e.g., a final outcome or response) for each patient, which could be continuous (e.g., a lab measurement) or binary (e.g., responder yes/no). It supports a treatment effect and optional cluster-level variability for continuous outcomes.

Usage

simulate_outcomes(
  data,
  outcome_type = c("continuous", "binary"),
  outcome_mean_control = 0,
  outcome_diff = 0,
  outcome_sd = 1,
  outcome_prob_control = 0.5,
  outcome_prob_treatment = 0.5,
  outcome_means = NULL,
  outcome_probs = NULL,
  cluster_var = NULL,
  cluster_effect_sd = 0
)

Arguments

data

A data frame of patients that should include a treatment group column Arm (optional if only one group).

outcome_type

Character, either "continuous" or "binary" (default = "continuous").

outcome_mean_control

Numeric, mean of the continuous outcome for the control group (used if outcome_type = "continuous", default = 0).

outcome_diff

Numeric, treatment effect on the outcome. For continuous outcomes, this is added to the control mean for treatment group(s). For binary outcomes, this is ignored (use probabilities instead). Default = 0 (no treatment effect).

outcome_sd

Numeric, standard deviation for the continuous outcome (default = 1). Ignored for binary outcomes.

outcome_prob_control

Numeric, probability of outcome = "Yes" for control group (used if outcome_type = "binary", default = 0.5).

outcome_prob_treatment

Numeric, probability of outcome = "Yes" for treatment group (used if outcome_type = "binary" and exactly two arms, default = 0.5).

outcome_means

Named numeric vector of outcome means by arm (optional alternative to using outcome_mean_control and outcome_diff).

outcome_probs

Named numeric vector of outcome "Yes" probabilities by arm (optional alternative to using outcome_prob_control and outcome_prob_treatment).

cluster_var

Character, name of cluster variable in data for random effect (only used for continuous outcomes; e.g., "Site" for site-level effect).

cluster_effect_sd

Numeric, standard deviation of random effect for clusters (only for continuous outcomes, default = 0).

Value

The input data frame with a new column Outcome. For continuous outcomes, this is numeric. For binary outcomes, this is a factor with levels "No" and "Yes". Patients who dropped out or had an event before the outcome measurement are assigned NA for the outcome.

Details

For continuous outcomes, if multiple arms are present and outcome_means is provided, those values are used for each arm's mean. Otherwise, outcome_mean_control is used for the first arm (assumed control) and outcome_diff is added for other arms. A random normal error with SD outcome_sd is added for each patient. If cluster_var is given (and cluster_effect_sd > 0), a random intercept per cluster is added to the outcome to simulate cluster-level variability.

For binary outcomes, if two arms are present, outcome_prob_control and outcome_prob_treatment define the success probabilities for control and treatment respectively (or use outcome_probs for multiple arms). The outcome is generated as "Yes"/"No" for each patient. If a patient dropped out or had a terminal event prior to the endpoint, their outcome is set to NA (assuming missing data due to dropout/death).

Examples

df <- simulate_patients(5)
df <- simulate_allocation(df)
# Continuous outcome: mean 50 in control, treatment +5 difference
df <- simulate_outcomes(df, outcome_type = "continuous",
                        outcome_mean_control = 50, outcome_diff = 5, outcome_sd = 10)
# Binary outcome: 30% responders in control vs 60% in treatment
df <- simulate_outcomes(df, outcome_type = "binary",
                        outcome_prob_control = 0.3, outcome_prob_treatment = 0.6)
head(df$Outcome)
#> [1] No  Yes Yes Yes No 
#> Levels: No Yes