---
title: "Getting started with anovapowersim"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with anovapowersim}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4
)
```

`anovapowersim` simulates power for balanced factorial ANOVA designs. Specify
the factors and levels, the term of interest, and a target partial eta squared.
The package generates default term-specific cell means, simulates datasets,
refits the ANOVA, and estimates power.

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

```{r load-precomputed-results, include=FALSE}
vignette_results_path <- system.file(
  "extdata",
  "anovapowersim-vignette-results.rds",
  package = "anovapowersim"
)
if (!nzchar(vignette_results_path)) {
  vignette_results_path <- file.path(
    "..",
    "inst",
    "extdata",
    "anovapowersim-vignette-results.rds"
  )
}
vignette_results <- readRDS(vignette_results_path)
```

## Search for the required sample size

Use `power_n()` to search for the sample size needed to reach the requested
power. This example is a mixed design with one two-level between-subject factor
(`cond`) and one four-level within-subject factor (`stim`). It tests the
`cond:stim` interaction with 90% power to detect a partial eta squared of 0.14.

```{r adaptive-code, eval=FALSE}
power_n(
  between = c(cond = 2), # cond has 2 levels
  within = c(stim = 4), # stim has 4 levels
  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
)
```

```{r adaptive-output, echo=FALSE}
vignette_results$adaptive
```

`power_n()` reports the required number of subjects per between-subject cell
and the corresponding total N. For a purely within-subject design, the reported
`n_per_cell` is the total sample size.

The output table uses compact column names: `num_df` and `den_df` are the ANOVA
degrees of freedom, `ncp` is the noncentrality parameter, `power_calc` is the
calculated noncentral-F power, and `power_sim` is the simulation estimate.

The example uses 1000 simulations for speed. Use at least 5000 simulations for
a more stable estimate; the package default is 10000.

### Adding factors and levels

Add as many factors and levels as required and name the term to test. For
example, this design includes a three-level between-subject factor and tests a
three-way interaction:

```{r complex, eval=FALSE}
power_n(
  between = c(cond = 2, age = 3),
  within = c(stim = 4),
  term = "cond:stim:age",
  target_pes = f_to_pes(0.50)
  power = 0.90,
  n_sims = 5000,
  seed = 123
)
```

## Simulate a power curve

Use `power_curve()` to estimate power across explicitly chosen sample sizes.
The result is a tidy table that can be passed to `plot_power_curve()`.

```{r curve-fixed-code, eval=FALSE}
pc <- 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_sims = 1000,
  seed = 123
)
pc
```

```{r curve-fixed-output, echo=FALSE}
pc <- vignette_results$curve
pc
```

```{r plot-fixed}
plot_power_curve(
  pc,
  power_lines = c(0.80, 0.90)
)
```

## Run simulations in parallel

For larger simulation runs, set `parallel = TRUE`. If `cores` is omitted,
`anovapowersim` uses one fewer than the available cores and reports the number
selected. Set `cores` explicitly when a fixed number of workers is required.

```{r parallel, eval=FALSE}
power_n(
  between = c(cond = 2),
  within = c(stim = 2),
  term = "cond:stim",
  target_pes = 0.14,
  power = 0.90,
  n_sims = 5000,
  parallel = TRUE,
  cores = 4,
  seed = 123
)
```

## Next steps

- [Fixed-sample power and sensitivity](fixed-sample-power.html)
- [Calculated power without simulations](calculated-power.html)
- [Power for unbalanced designs](unbalanced-designs.html)
- [Covariance and nonsphericity](covariance.html)
- [Comparison with G\*Power](comparison-with-gpower.html)