Package 'anovapowersim'

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

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

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)

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)

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
)

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 refines the bracket using interpolation with midpoint bisection as a fallback.

Usage

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

Arguments

Value

An anovapowersim_curve object with n_needed and total_n_needed. For power_n(), n_needed is always an explicitly simulated n_per_cell value, never an interpolated sample size. If the search reaches target power but no simulated value lands inside ⁠[power, power + tol]⁠, power_n() reports the smallest explicitly simulated value at or above target power and warns that the requested precision band was not reached.

Examples

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

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.

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)

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.