---
title: "Fixed-sample power and sensitivity"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Fixed-sample power and sensitivity}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, message=FALSE}
library(anovapowersim)
```

`power_achieved()` and `power_sensitivity()` are experimental and available
only in the development version of `anovapowersim`. They use the same balanced
design construction, ANOVA fitting, covariance handling, and simulation
controls as `power_n()`.

## Achieved power

Use `power_achieved()` when the sample size and partial eta squared are fixed.
The `n` argument is the number of subjects per between-subject cell, or total N
for a purely within-subject design.

```{r achieved-power, eval=FALSE}
power_achieved(
  between = c(group = 2),
  within = c(time = 2),
  term = "group:time",
  target_pes = 0.14,
  n = 20,
  n_sims = 5000,
  parallel = TRUE,
  seed = 123
)
```

The result reports simulated achieved power as the primary estimate and
calculated power as a diagnostic.

## Sensitivity

Use `power_sensitivity()` when the sample size is fixed and the minimum
detectable partial eta squared is unknown. It simulates effect sizes until it
finds a bracket around the requested power, then reports an explicitly
simulated upper bracket as `pes_needed`.

```{r sensitivity, eval=FALSE}
power_sensitivity(
  between = c(group = 2),
  within = c(time = 2),
  term = "group:time",
  n = 20,
  power = 0.90,
  n_sims = 5000,
  pes_tol = 0.001,
  parallel = TRUE,
  seed = 123
)
```

Because simulated power has Monte Carlo variability, use enough simulations
for the precision you need and inspect all visited effect sizes in `$results`.

## Covariance and calculated-power alternatives

Both functions accept a `within_covariance()` object for repeated-measures
designs. See [Covariance and nonsphericity](covariance.html) for cell naming,
custom standard deviations and correlations, and Greenhouse--Geisser handling.

To skip simulations, use `power_achieved_calc()` or
`power_sensitivity_calc()`. These are covered in the
[Calculated power](calculated-power.html) guide.