PowRPriori (version 0.1.2)

plot_sim_model: 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,
  n,
  x_var,
  group_var,
  color_var,
  facet_var,
  n_data_points,
  ...
)
# S3 method for formula
plot_sim_model(
  object,
  type = "data",
  design,
  fixed_effects,
  random_effects,
  family = "gaussian",
  n,
  x_var = NULL,
  group_var = NULL,
  color_var = NULL,
  facet_var = NULL,
  n_data_points = 10,
  ...
)
# S3 method for PowRPriori
plot_sim_model(
  object,
  type = "power_curve",
  design = NULL,
  fixed_effects = NULL,
  random_effects = NULL,
  family = NULL,
  n = NULL,
  x_var = NULL,
  group_var = NULL,
  color_var = NULL,
  facet_var = NULL,
  n_data_points = 10,
  ...
)

Value

A ggplot object.

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".

n

The total sample size to simulate for the plot.

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.

Examples

# 1. Plot prior to simulation to check data plausibility
design <- define_design(
  id = "subject",
  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,
  n = 30
)
# \donttest{
# 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",
    n_start = 20,
    n_increment = 5,
    n_sims = 100, # Using a smaller n_sims for a quick example
    parallel_plan = "multisession"
  )

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

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