Package {anovapowersim}

anovapowersim: Design-Based Power Simulation for Factorial ANOVA

Description

Simulation-based power analysis for balanced factorial ANOVA designs. Given between- and within-subject factor structures, a target partial eta squared, and sample sizes, anovapowersim generates default term-specific cell means, simulates datasets under sphericity, refits the ANOVA with stats, and returns tidy power estimates and a ggplot2 power curve.

Details

The primary entry point is power_curve(). It accepts a design specification, a term name, a target partial eta squared, and sample sizes. It returns an object of class anovapowersim_curve that can be printed, summarised, or plotted with plot_power_curve().

The lower-level building blocks are also exported so users can compose custom simulations:

• balanced_anova_design()

• design_term_means()

• simulate_design_dataset()

• compute_scale_factor()

Author(s)

Maintainer: Shaheed Azaad sazaad@uni-muenster.de

See Also

Useful links:

• https://shaheedazaad.github.io/anovapowersim/

• https://github.com/shaheedazaad/anovapowersim

• Report bugs at https://github.com/shaheedazaad/anovapowersim/issues

Create a balanced factorial ANOVA design specification

Description

Builds the design object used by power_curve(), design_term_means(), and simulate_design_dataset(). This object stores factor names, level counts, generated factor levels, and the between/within cell grids.

Usage

balanced_anova_design(between = NULL, within = NULL)

Arguments

Value

An object of class anovapowersim_design_spec.

Examples

d <- balanced_anova_design(between = c(group = 2), within = c(time = 3))
d$between_cells
d$within_cells

Compute the mean-deviation scaling factor from a change in partial eta squared

Description

Given an existing partial eta squared for a term and a target partial eta squared, returns the multiplier k that must be applied to that term's additive contribution to the cell means in order to obtain the target effect size under the same residual structure.

Usage

compute_scale_factor(old_pes, new_pes)

Arguments

Details

The derivation is straightforward: partial eta squared can be written as pes = SS_effect / (SS_effect + C), where C is the part of the denominator held fixed by this package's rescaling. Thus pes / (1 - pes) scales as the target effect's sum of squares. Scaling the term's deviations by k scales the target effect's sum of squares by k^2, so the required multiplier is

k = \sqrt{\frac{p_{\mathrm{new}} / (1 - p_{\mathrm{new}})} {p_{\mathrm{old}} / (1 - p_{\mathrm{old}})}}.

Value

A single positive numeric value k. k > 1 amplifies the effect, k < 1 shrinks it, and k == 1 leaves it unchanged.

See Also

design_term_means(), power_curve()

Examples

compute_scale_factor(0.10, 0.05)   # shrink
compute_scale_factor(0.05, 0.10)   # amplify

Build calibrated default means for a design term

Description

Creates the default contrast pattern for one ANOVA term and scales it so an exact reference dataset has the requested partial eta squared under the supplied balanced design assumptions.

Usage

design_term_means(
  design,
  term,
  target_pes,
  n,
  sd = 1,
  r = 0.5,
  gpower = FALSE,
  ss_type = "III"
)

Arguments

Value

A numeric matrix of cell means, with rows indexing between cells and columns indexing within cells.

Examples

d <- balanced_anova_design(between = c(group = 2), within = c(time = 2))
design_term_means(d, term = "group:time", target_pes = 0.2, n = 20)

Plot a simulation-based power curve

Description

Renders an anovapowersim_curve as a ggplot2 line + ribbon with a horizontal reference at requested power values and, when auto-search was used, a vertical marker at the estimated required total sample size.

Usage

plot_power_curve(
  x,
  show_target = TRUE,
  power_lines = NULL,
  show_n_needed = TRUE,
  ...
)

Arguments

Value

A ggplot object.

See Also

power_curve()

Examples

pc <- power_curve(
  between = c(group = 2),
  within = c(time = 2),
  term = "group:time",
  target_pes = 0.2,
  n_range = c(20, 30),
  n_sims = 1000,
  seed = 123
)
plot_power_curve(pc)

Simulate ANOVA power from a balanced factorial design

Description

Simulation-based power estimation for balanced factorial designs under sphericity. Users specify the between- and within-subject factors, the ANOVA term to test, a target partial eta squared, and explicit sample sizes. The function creates a default contrast pattern for the target term, scales it to the requested partial eta squared, simulates datasets, refits stats::aov(), and estimates power by counting p < alpha.

Usage

power_curve(
  between = NULL,
  within = NULL,
  term,
  target_pes,
  n_range,
  n_sims = 10000,
  alpha = 0.05,
  ss_type = "III",
  gpower = FALSE,
  progress = interactive(),
  parallel = FALSE,
  cores = NULL,
  seed = NULL
)

Arguments

Value

An anovapowersim_curve object. The ⁠$results⁠ tibble contains n_per_cell, total_n, n_sims, numerator and denominator degrees of freedom (num_df, den_df), the noncentrality parameter (ncp), calculated power (power_calc), and simulated power (power_sim).

Examples

power_curve(
  between = c(cond = 2),
  within = c(stim = 2),
  term = "cond:stim",
  target_pes = 0.14,
  n_range = c(16, 20, 23, 28), # n per between-subject cell
  n_sims = 1000,
  seed = 123
)

power_curve(
  between = c(group = 2),
  within = c(time = 2),
  term = "group:time",
  target_pes = 0.14,
  n_range = c(12, 16, 20),
  n_sims = 5000,
  parallel = TRUE,
  cores = 4,
  seed = 123
)

Search for the sample size needed for target ANOVA power

Description

Adaptive simulation search for the per-between-cell sample size needed to reach a requested power for a balanced factorial ANOVA design. The search doubles upward from n_start until it brackets the target or reaches n_max, then bisects the bracket.

Usage

power_n(
  between = NULL,
  within = NULL,
  term,
  target_pes,
  power = 0.8,
  n_sims = 10000,
  alpha = 0.05,
  ss_type = "III",
  n_start = NULL,
  n_max = 1000,
  tol = 0.01,
  gpower = FALSE,
  progress = interactive(),
  parallel = FALSE,
  cores = NULL,
  seed = NULL
)

Arguments

Value

An anovapowersim_curve object with n_needed and total_n_needed.

Examples

power_n(
  between = c(cond = 2),
  within = c(stim = 4),
  term = "cond:stim",
  target_pes = 0.14,
  alpha = 0.05,
  power = 0.80,
  n_sims = 1000, # use 5000+ for a more precise estimate
  seed = 123 # for reproducibility
)

Print an anovapowersim power curve

Description

Compact one-screen summary: target, term, effective effect size, estimated per-cell and total sample sizes, and the first and last rows of the power curve.

Usage

## S3 method for class 'anovapowersim_curve'
print(x, ...)

Arguments

Value

Invisibly returns x.

Simulate data from a balanced ANOVA design

Description

Generates one long-format dataset from a balanced design. Supply means from design_term_means() or any conformable matrix with one row per between-subject cell and one column per within-subject cell.

Usage

simulate_design_dataset(design, n, means, sd = 1, r = 0.5, empirical = FALSE)

Arguments

Value

A tibble ready for stats::aov() with columns id, factor columns, and value.

Examples

d <- balanced_anova_design(between = c(group = 2), within = c(time = 2))
m <- design_term_means(d, term = "group:time", target_pes = 0.2, n = 20)
sim <- simulate_design_dataset(d, n = 20, means = m)
head(sim)

Summarise an anovapowersim power curve

Description

Returns the full ⁠$results⁠ tibble along with a small header containing the target, effective effect size, and estimated n_needed.

Usage

## S3 method for class 'anovapowersim_curve'
summary(object, ...)

Arguments

Value

A list with elements header (named character) and curve (tibble), invisibly; printed to console as well.