define_design: Define the Structure of a Planned Experimental Design

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

Define the Structure of a Planned Experimental Design

Description

This is the primary setup function for any power simulation in PowRPriori. It creates a special PowRPriori_design object that contains all the necessary information about the variables, the hierarchical structure, and the sample size of a planned study.

Usage

define_design(sample_size, between = NULL, within = NULL)

Arguments

sample_size	A named list specifying the building blocks and dimensions of the planned study sample (e.g. list(class = 10, pupil = 20)). This dictates which analysis units exist and the number of elements within each unit.
between	A list of between-subject variables. These are variables where a given unit is assigned to exactly one level of the variable (e.g., participants or entire clusters being assigned to either an intervention or a control group).
within	A list of within-subject variables. These are variables where all levels are observed within the same unit (e.g., repeated pre- and post-measurements within participants).

Details

Variable Specification: Variables can be specified in different formats depending on their scale: Nominal variables (e.g. a group variable with levels "control" and "treatment") can be specified as factors (group = factor(c("control", "treatment"))) or as character vectors (group = c("control", "treatment")), which are automatically converted to factors. Continuous variables can be specified via their expected mean and standard deviation (test_score = list(mean = 10, sd = 5)). Additionally, variables can be defined as fixed numerical vectors (predictor = 1:4).

Assignment of Variables: By default, if between variables are specified directly as a simple list (e.g., between = list(treatment = c("A", "B"))), they are randomized at the lowest level of the design (individual assignment). If a between variable should be assigned at a higher cluster level (e.g., cluster-randomization at the class level), it must be wrapped in a named list corresponding to that specific analysis unit. You do not need to mimic the full hierarchical structure of your design here (e.g., no need to write school = list(class = list(...))). Simply wrap the predictor in a single list named after the exact cluster level it belongs to (see the nested design example below).

within variables, on the other hand, are always crossed with the level-1 analysis units, effectively creating repeated measures for the lowest level.

For a full tutorial and more complex design structures, see the package vignette: vignette("Workflow-Example", package = "PowRPriori").

Value

A PowRPriori_design object containing the parsed design specifications.

Examples

# Simple 2x2 mixed design
simple_design <- define_design(
  sample_size = list(subject = 20),
  between = list(group = c("Control", "Treatment")),
  within = list(time = c("pre", "post"))
)

# A nested (cluster-randomized) design where the intervention
# is assigned at the class level.
nested_design <- define_design(
  sample_size = list(class = 10,
                      pupil = 20),
  between = list(
    class = list(intervention = c("yes", "no")),
    pupil = list(support = c("yes", "no"))
  )
)

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