% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plan_sample_size.R
\name{plan_sample_size}
\alias{plan_sample_size}
\title{Generates HTML reports for sample size planning for sequential ANOVAs.}
\usage{
plan_sample_size(
  f_expected,
  k_groups,
  beta = 0.05,
  decision_rate = 0.85,
  output_dir = tempdir(),
  output_file = "sprtt-report-sample-size-planning.html",
  open = interactive(),
  overwrite = FALSE
)
}
\arguments{
\item{f_expected}{Numeric scalar. The expected standardized effect size (e.g., Cohen's f).
Must be between 0.1 and 0.4 (increments of 0.05).}

\item{k_groups}{Integer scalar. The number of groups to compare. Must be between 2 and 4.}

\item{beta}{Numeric scalar (default = 0.05). Desired beta error rate (Type II error).
Possible values are 0.20, 0.10, and 0.05.}

\item{decision_rate}{Numeric scalar (default = 0.85). Desired chance to reach a decision.
Must be between 0.75 and 0.95 (increments of 0.05).}

\item{output_dir}{Character string. Directory in which to save the rendered HTML report.
Defaults to a temporary directory (\code{tempdir()}).}

\item{output_file}{Character string. File name of the generated HTML report.
Defaults to \code{"sprtt-report-sample-size-planning.html"}.}

\item{open}{Logical (default = \code{interactive()}). If \code{TRUE}, the generated report is opened
in the system's default web browser after rendering.}

\item{overwrite}{Logical (default = \code{FALSE}). If \code{FALSE} and the target file already exists,
the user is prompted interactively whether to overwrite it. In non-interactive sessions,
an error is raised unless \code{overwrite = TRUE}.}
}
\value{
Invisibly returns the path to the rendered HTML file (character string).
The report is optionally opened in the default browser.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

Renders a parameterized R Markdown report that helps plan sample size for the sequential ANOVA.
The function takes expected effect size (\code{f_expected}), number of groups (\code{k_groups}),
the power, and decision rate, then generates a reproducible HTML report summarizing the simulation-based
sample size recommendations. The alpha level is always 0.05.

The template is located under:
\code{inst/rmarkdown/templates/report_sample_size/skeleton/skeleton.Rmd}.
}
\details{
This function is a front-end utility for rendering a pre-defined R Markdown report using
\code{rmarkdown::render()}.
}
\section{File Overwrite Behavior}{

\itemize{
\item If the specified output file already exists:
\itemize{
\item and \code{overwrite = FALSE}, the user is asked whether to overwrite (in interactive sessions);
otherwise, an error is thrown.
\item If \code{overwrite = TRUE}, the file is replaced silently.
}
}
}

\examples{
\dontrun{
# Generate and open an SPRT sample size planning report:
plan_sample_size(
  f_expected = 0.25,
  k_groups = 3,
  decision_rate = 0.9
)

# Prevent overwriting an existing file:
plan_sample_size(0.25, 3, overwrite = FALSE)
}
}
