plot_sim_model: Visualize Simulation Data or Power Simulation Results

In PowRPriori: Power Analysis via Data Simulation for (Generalized) Linear Mixed Effects Models

Visualize Simulation Data or Power Simulation Results

Description

Generic plotting function with methods for different objects.

• When used on an lme4-style formula, it simulates and plots a single plausible dataset.

• When used on a PowRPriori object, it plots either a power curve from the object or a dataset from the simulation.

The plotting of the dataset is designed to aid in evaluating whether the simulated data is plausible in the context of the desired study design and model specifications. It can help determine whether the chosen parameters are sensible or might need some adapting. The power curve, plotted from the resulting PowRPriori object of the power_sim function visualizes the iterations of the simulation across the different sample sizes for which the power was calculated during simulation.

Usage

plot_sim_model(
  object,
  type,
  design,
  fixed_effects,
  random_effects,
  family,
  center,
  n,
  x_var,
  group_var,
  color_var,
  facet_var,
  n_data_points,
  ...
)

## S3 method for class 'formula'
plot_sim_model(
  object,
  type = "data",
  design,
  fixed_effects,
  random_effects,
  family = "gaussian",
  center = "auto",
  n = NULL,
  x_var = NULL,
  group_var = NULL,
  color_var = NULL,
  facet_var = NULL,
  n_data_points = 10,
  ...
)

## S3 method for class 'PowRPriori'
plot_sim_model(
  object,
  type = "power_curve",
  design = NULL,
  fixed_effects = NULL,
  random_effects = NULL,
  family = NULL,
  center = NULL,
  n = NULL,
  x_var = NULL,
  group_var = NULL,
  color_var = NULL,
  facet_var = NULL,
  n_data_points = 10,
  ...
)

Arguments

object	The object to base the plot on. Can be either a PowRPriori object or an lme4-style formula
type	The type of plot to create: "power_curve" (default) or "data" (to visualize the sample data from the simulation).
design	A PowRPriori_design object.
fixed_effects, random_effects	Lists of effect parameters.
family	The model family. Defaults to "gaussian", other possible values are "binomial" or "poisson".
center	Controls if centering is applied to the predictors prior to plotting. Defaults to "auto".
n	The total sample size to simulate for the plot (overwrites the lowest design level).
x_var, group_var, color_var, facet_var	Strings specifying variables for plot aesthetics.
n_data_points	The maximum number of trajectories in spaghetti plots.
...	Additional arguments (not used).

Details

The parameters ⁠x_var, group_var, color_var and facet_var⁠ are NULL by default. If left NULL, they are automatically extracted from the PowRPriori object or the design object.

Value

A ggplot object.

Examples

# 1. Plot prior to simulation to check data plausibility
design <- define_design(
  sample_size = list(subject = 30),
  between = list(group = c("Control", "Treatment")),
  within = list(time = c("pre", "post"))
)

fixed_effects <- list(
  `(Intercept)` = 10,
  groupTreatment = 2,
  timepost = 1,
  `groupTreatment:timepost` = 3
)

random_effects <- list(
  subject = list(`(Intercept)` = 3),
  sd_resid = 3
)

plot_sim_model(
  y ~ group * time + (1|subject),
  design = design,
  fixed_effects = fixed_effects,
  random_effects = random_effects
)

# 2. Plot from PowRPriori object after simulation
  power_results <- power_sim(
    formula = y ~ group * time + (1|subject),
    design = design,
    fixed_effects = fixed_effects,
    random_effects = random_effects,
    test_parameter = "groupTreatment:timepost",
    center = TRUE,
    n_start = 100,
    n_increment = 5,
    # The parameters defined in this example are to ensure low runtime.
    # Adapt these parameters!
    n_sims = 10,
    max_simulation_steps = 1,
    parallel_plan = "sequential"
  )

  # Power curve
  plot_sim_model(power_results, type = "power_curve")

  # Plot sample data with automated aesthetics extraction
  plot_sim_model(power_results, type = "data")

PowRPriori documentation built on May 12, 2026, 5:06 p.m.