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

Creates the complete cell table used by power_unbalanced(). Each cell is defined by its factor levels, sample size (n), and population mean (m). End each cell after both reserved values have been supplied. The common population standard deviation belongs in unbalanced_covariance().

Usage

cell_design(..., within = NULL, default_n = NULL, default_m = NULL)

Arguments

Details

The m values are literal population cell means: their magnitudes and all effects they contain are used as supplied. This differs from means_pattern(), whose values specify only a relative shape that balanced simulation functions project onto the tested term, normalize, and rescale to target_pes.

Value

An anovapowersim_cell_design tibble with one row per design cell.

Lifecycle

cell_design() is experimental and is available only in the development version of anovapowersim. Its API may change.

See Also

means_pattern() for shape-only patterns used by balanced simulation functions.

Examples

design <- cell_design(
  group = "control", time = "pre",  n = 22, m = 10.0,
  group = "control", time = "post", n = 22, m = 11.0,
  group = "treatment", time = "pre",  n = 31, m = 10.1,
  group = "treatment", time = "post", n = 31, m = 12.4,
  within = "time"
)
design

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

Projects a supplied relative pattern (or uses the documented linear/Kronecker default) 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",
  means_pattern = NULL
)

Arguments

Value

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

Covariance limitation

This manual helper does not accept within_covariance() specifications. Calibration always uses the compound-symmetric covariance defined by sd and r. Consequently, its calibrated means can differ from those used by power_curve(), power_n(), or power_achieved() with a custom covariance, because the covariance affects the reference residual sum of squares and therefore the mean scale factor.

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

Creates a sparse mean-shape specification for the balanced simulation functions. End each cell definition with value. Unlisted cells have raw value zero, and factors in the tested term that are omitted from every row are broadcast when the pattern is resolved against a design.

Usage

means_pattern(...)

Arguments

Details

Pattern values describe relative shape, not effect magnitude. The selected power function projects the raw values onto the requested ANOVA term, normalizes that component, and rescales it uniformly to reach target_pes. Multiplying all values by one positive constant, adding an intercept or a lower-order component, or reversing every sign therefore leaves the same target-term direction (up to sign). Under nonsphericity, different directions within a multi-df term can nevertheless produce different simulated power.

This differs from cell_design(), where each m is a literal population mean whose magnitude directly determines the simulated effect.

Value

An object of class anovapowersim_means_pattern, retaining the sparse definitions until a balanced simulation function resolves them against its design and tested term.

Default direction

When no pattern is supplied, balanced simulations use centered scores in generated level order, i - (L + 1) / 2 for levels ⁠i = 1, ..., L⁠, normalized to unit length. Interactions use the Kronecker product of their factors' normalized score vectors, followed by one final normalization after broadcasting. This is an ordered, reproducible convention rather than a neutral scientific assumption; an explicit pattern is recommended whenever the expected shape is known.

See Also

cell_design() for unbalanced designs with literal cell means.

Examples

trend <- means_pattern(
  time = 1, value = 0,
  time = 2, value = 0.3,
  time = 3, value = 0.5,
  time = 4, value = 0.6
)

interaction_shape <- means_pattern(
  group = "group1", time = "time3", value = 1,
  group = "group2", time = "time3", value = -1
)

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

Simulates one balanced factorial ANOVA design point for a fixed partial eta squared and sample size. The simulation estimate is the primary achieved power result; noncentral-F calculated power is retained as a diagnostic.

Usage

power_achieved(
  between = NULL,
  within = NULL,
  term,
  target_pes,
  n,
  n_sims = 10000,
  alpha = 0.05,
  ss_type = "III",
  gpower = FALSE,
  progress = interactive(),
  parallel = FALSE,
  cores = NULL,
  seed = NULL,
  covariance = NULL,
  means_pattern = NULL,
  sim_correction = c("auto", "GG", "none")
)

Arguments

Value

An anovapowersim_achieved_power object. ⁠$results⁠ contains the standard one-row power diagnostics. ⁠$achieved_power⁠ is the simulated power estimate and ⁠$calculated_power⁠ is the calculated-power diagnostic.

Lifecycle

power_achieved() is experimental and is available only in the development version of anovapowersim. Its API and reporting format may change.

Examples

power_achieved(
  between = c(group = 2),
  within = c(time = 2),
  term = "group:time",
  target_pes = 0.14,
  n = 20,
  n_sims = 100,
  seed = 123
)

Description

Calculation-only counterpart to power_achieved(). Numerator and denominator degrees of freedom, noncentrality, and achieved power are calculated directly without simulating data or fitting ANOVA models.

Usage

power_achieved_calc(
  between = NULL,
  within = NULL,
  term,
  target_pes,
  n,
  alpha = 0.05,
  gpower = FALSE,
  epsilon = 1
)

Arguments

Value

An anovapowersim_achieved_power object. ⁠$achieved_power⁠ and ⁠$calculated_power⁠ contain the calculated-power estimate. In ⁠$results⁠, simulation-specific result columns are NA because no simulations are run.

Lifecycle

power_achieved_calc() is experimental and is available only in the development version of anovapowersim. Its API and reporting format may change.

Examples

power_achieved_calc(
  between = c(group = 2),
  within = c(time = 3),
  term = "group:time",
  target_pes = 0.08,
  n = 30,
  gpower = TRUE,
  epsilon = 0.80
)

Description

Simulation-based power estimation for balanced factorial designs. Users specify the between- and within-subject factors, the ANOVA term to test, a target partial eta squared, and explicit sample sizes. The function projects an explicit relative means pattern (or uses the documented linear/Kronecker default), scales it to the requested partial eta squared, simulates datasets, refits the ANOVA, 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,
  covariance = NULL,
  means_pattern = NULL,
  sim_correction = c("auto", "GG", "none")
)

Arguments

Value

An anovapowersim_curve object. The ⁠$results⁠ tibble contains n_per_cell, total_n, n_sims, successful and failed simulation counts (valid_sims, failed_sims), the population nonsphericity correction (epsilon), numerator and denominator degrees of freedom (num_df, den_df), the noncentrality parameter (ncp), calculated power (power_calc), and simulated power (power_sim). The full-precision power_sim value, not its printed three-decimal representation, is used by adaptive searches. When epsilon < 1, the reported degrees of freedom and noncentrality are the corrected values used for power_calc. With the default sim_correction = "auto", power_sim uses the Greenhouse–Geisser-corrected simulated p-value when epsilon < 1 - 1e-8 and ss_type is "III" or "II"; otherwise it uses the uncorrected univariate test. Balanced simulation result objects also include custom_means_pattern, indicating whether the relative direction was supplied explicitly, plus sim_correction and sim_correction_resolved for the requested and applied simulated-test correction.

Simulated sphericity correction

sim_correction changes only power_sim. When Greenhouse–Geisser correction is selected, each simulated dataset is tested using its own sample-estimated epsilon from car::Anova(). power_calc is unchanged and always models the population-epsilon-adjusted test. Consequently, forcing sim_correction = "GG" under a truly spherical population can make power_sim slightly smaller than power_calc, because sample-epsilon GG correction is mildly conservative under sphericity.

Power is estimated for the prespecified corrected or uncorrected test. Conditional procedures that first run Mauchly's test and then decide whether to correct are not simulated.

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
)

power_curve(
  within = c(time = 4),
  term = "time",
  target_pes = 0.15,
  n_range = 30,
  means_pattern = means_pattern(
    time = 1, value = 0,
    time = 2, value = 0.3,
    time = 3, value = 0.5,
    time = 4, value = 0.6
  ),
  n_sims = 1000,
  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 searches upward from n_start until it brackets the target or reaches n_max. If n_start already reaches the target, the search probes the smallest sample size supported by the design to establish a lower bracket. It 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 = 5000,
  tol = 0.03,
  gpower = FALSE,
  progress = interactive(),
  parallel = FALSE,
  cores = NULL,
  seed = NULL,
  covariance = NULL,
  means_pattern = NULL,
  sim_correction = c("auto", "GG", "none")
)

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

Calculation-only search for the per-between-cell sample size needed to reach a requested power for a balanced factorial ANOVA design. Unlike power_n(), this function does not run simulations, fit ANOVA models, or call car; numerator degrees of freedom, denominator degrees of freedom, noncentrality, and calculated power are obtained directly from the balanced design.

Usage

power_n_calc(
  between = NULL,
  within = NULL,
  term,
  target_pes,
  power = 0.9,
  alpha = 0.05,
  n_start = NULL,
  n_max = 5000,
  gpower = FALSE,
  epsilon = 1
)

Arguments

Value

An anovapowersim_curve object with n_needed and total_n_needed. The ⁠$results⁠ tibble contains n_per_cell, total_n, n_sims, valid_sims, failed_sims, numerator and denominator degrees of freedom (num_df, den_df), the nonsphericity correction (epsilon), the noncentrality parameter (ncp), calculated power (power_calc), and simulated power (power_sim). For power_n_calc(), the simulation-specific columns are always NA. When epsilon < 1, num_df and den_df are the corrected degrees of freedom used in the power calculation.

Lifecycle

power_n_calc() is experimental while the calculated-power search API and reporting format are refined.

Examples

power_n_calc(
  between = c(cond = 2),
  within = c(stim = 4),
  term = "cond:stim",
  target_pes = 0.14,
  power = 0.90,
  epsilon = 0.70
)

Description

Searches for the minimum detectable partial eta squared at a fixed sample size and target power. Calculated power supplies an efficient initial estimate. Explicit simulations then bracket the target and refine the effect-size bracket using interpolation with midpoint fallback.

Usage

power_sensitivity(
  between = NULL,
  within = NULL,
  term,
  n,
  power = 0.9,
  n_sims = 10000,
  alpha = 0.05,
  ss_type = "III",
  pes_min = 1e-06,
  pes_max = 0.99,
  pes_tol = 0.001,
  gpower = FALSE,
  progress = interactive(),
  parallel = FALSE,
  cores = NULL,
  seed = NULL,
  covariance = NULL,
  means_pattern = NULL,
  sim_correction = c("auto", "GG", "none")
)

Arguments

Value

An anovapowersim_sensitivity object. ⁠$pes_needed⁠ is the explicitly simulated upper effect-size bracket, or NA when pes_max does not achieve target power. ⁠$results⁠ contains every explicitly simulated effect size and its standard power diagnostics.

Lifecycle

power_sensitivity() is experimental and is available only in the development version of anovapowersim. Its API and reporting format may change.

Examples

power_sensitivity(
  between = c(group = 2),
  within = c(time = 2),
  term = "group:time",
  n = 20,
  power = 0.90,
  n_sims = 100,
  pes_tol = 0.01,
  seed = 123
)

Description

Calculation-only counterpart to power_sensitivity(). The function searches for the minimum partial eta squared that reaches target power using calculated noncentral-F power, without simulating data or fitting ANOVA models.

Usage

power_sensitivity_calc(
  between = NULL,
  within = NULL,
  term,
  n,
  power = 0.9,
  alpha = 0.05,
  pes_min = 1e-06,
  pes_max = 0.99,
  pes_tol = 0.001,
  gpower = FALSE,
  epsilon = 1
)

Arguments

Value

An anovapowersim_sensitivity object. ⁠$pes_needed⁠ is the calculated upper effect-size bracket, or NA when pes_max does not achieve target power. ⁠$results⁠ contains every effect size evaluated by the calculated-power search; simulation-specific result columns are always NA.

Lifecycle

power_sensitivity_calc() is experimental and is available only in the development version of anovapowersim. Its API and reporting format may change.

Examples

power_sensitivity_calc(
  between = c(group = 2),
  within = c(time = 3),
  term = "group:time",
  n = 30,
  power = 0.90,
  pes_tol = 0.001,
  gpower = TRUE,
  epsilon = 0.80
)

Description

Estimates achieved power for exact, potentially unequal cell sizes and user-supplied population means under one common standard deviation. This function is simulation-only: it does not calculate power from a noncentral F distribution and does not scale the supplied sample sizes. A warning is issued when the deterministic reference data imply essentially zero effect for the tested term, which often indicates a typo, a wrong term, or means that contain only other effects.

Usage

power_unbalanced(
  design,
  term,
  covariance = NULL,
  n_sims = 10000,
  alpha = 0.05,
  ss_type = "III",
  progress = interactive(),
  parallel = FALSE,
  cores = NULL,
  seed = NULL,
  sim_correction = c("auto", "GG", "none")
)

Arguments

Value

An anovapowersim_unbalanced_power object. ⁠$power⁠ and ⁠$achieved_power⁠ contain simulated power. ⁠$partial_eta_squared⁠ is the term effect size in a deterministic reference dataset. ⁠$epsilon⁠ is the population Greenhouse–Geisser epsilon for the tested term. ⁠$results⁠ also reports the common SD, simulated partial eta-squared distribution, and failed fits. Sample partial eta squared is upward-biased in finite samples, so mean_pes_sim, median_pes_sim, and the simulated interval are sampling diagnostics rather than estimates of the supplied population effect; use ⁠$partial_eta_squared⁠ as the reference effect. The object stores the requested sim_correction and applied sim_correction_resolved values.

Lifecycle

power_unbalanced() is experimental and is available only in the development version of anovapowersim. Its API and reporting format may change.

Simulated sphericity correction

sim_correction governs only the simulated test. With "GG", each dataset uses its own sample-estimated Greenhouse–Geisser epsilon from car::Anova(). Under a truly spherical population, that sample correction is mildly conservative. Power is estimated for the prespecified corrected or uncorrected test; conditional Mauchly-then-correct procedures are not simulated. Unlike the balanced simulation functions, power_unbalanced() does not report a power_calc diagnostic.

Examples

design <- cell_design(
  group = "control", time = "pre",  n = 12, m = 10,
  group = "control", time = "post", n = 12, m = 11,
  group = "treatment", time = "pre",  n = 18, m = 10,
  group = "treatment", time = "post", n = 18, m = 13,
  within = "time"
)
power_unbalanced(
  design = design,
  term = "group:time",
  covariance = unbalanced_covariance(
    sd = 2,
    correlations = c("pre:post" = 0.7)
  ),
  n_sims = 100,
  seed = 123
)

Description

Print a fixed-sample achieved-power result

Usage

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

Arguments

Value

Invisibly returns x.

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

Print a fixed-sample sensitivity result

Usage

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

Arguments

Value

Invisibly returns x.

Description

Print simulated power for an unbalanced design

Usage

## S3 method for class 'anovapowersim_unbalanced_power'
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.

Covariance limitation

This manual helper does not accept within_covariance() specifications. It always simulates from the compound-symmetric covariance defined by sd and r. It therefore cannot reproduce a balanced power-function call that uses a custom covariance; use the power functions directly for that workflow.

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

Summarise a fixed-sample achieved-power result

Usage

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

Arguments

Value

A list with header and results, invisibly; printed to the console as well.

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.

Description

Summarise a fixed-sample sensitivity result

Usage

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

Arguments

Value

A list with header and results, invisibly; printed to the console as well.

Description

Summarise simulated power for an unbalanced design

Usage

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

Arguments

Value

A list with header, design, and results, invisibly; printed to the console as well.

Description

Defines the common marginal standard deviation and within-subject correlation structure used by power_unbalanced(). The resulting covariance is shared by every between-subject cell.

Usage

unbalanced_covariance(sd = 1, default_correlation = 0.5, correlations = NULL)

Arguments

Value

An anovapowersim_unbalanced_covariance_spec object.

Lifecycle

unbalanced_covariance() is experimental and is available only in the development version of anovapowersim. Its API may change.

Examples

unbalanced_covariance(
  sd = 2,
  default_correlation = 0.5,
  correlations = c("pre:post" = 0.7)
)

Description

Creates a readable covariance specification for power_n() and power_curve(). Supply one common standard deviation and default correlation, then override only the individual correlation pairs that differ. Measurement names are generated from the within design; for example, within = c(time = 2, condition = 2) creates time1_condition1, time1_condition2, time2_condition1, and time2_condition2.

Usage

within_covariance(sd = 1, default_correlation = 0.5, correlations = NULL)

Arguments

Value

An anovapowersim_covariance_spec object. power_n() and power_curve() resolve it against their within design and construct the covariance matrix as sd^2 * R, where R is the correlation matrix. They also derive the tested term's population Greenhouse–Geisser epsilon from the resolved matrix and apply it to power_calc.

Examples

covariance <- within_covariance(
  sd = 1,
  default_correlation = 0.5,
  correlations = c(
    "time1_condition1:time1_condition2" = 0.6,
    "time2_condition1:time2_condition2" = 0.7
  )
)


power_n(
  within = c(time = 3, condition = 2),
  term = "time:condition",
  target_pes = 0.14,
  power = 0.90,
  n_sims = 100,
  covariance = covariance,
  seed = 123
)