% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fttest.R
\name{f_t_test}
\alias{f_t_test}
\alias{f_t_test.formula}
\alias{f_t_test.default}
\title{Perform multiple t-tests with optional data transformation, inspection and visualization.}
\usage{
f_t_test(x, ...)

\method{f_t_test}{formula}(
  formula,
  data = NULL,
  paired = FALSE,
  var.equal = NULL,
  conf.level = NULL,
  mu = 0,
  alternative = "two.sided",
  norm_plots = TRUE,
  transformation = TRUE,
  force_transformation = NULL,
  alpha = 0.05,
  intro_text = TRUE,
  close_generated_files = FALSE,
  open_generated_files = interactive(),
  output_type = "default",
  save_as = NULL,
  save_in_wdir = FALSE,
  ...
)

\method{f_t_test}{default}(
  x,
  y = NULL,
  paired = FALSE,
  var.equal = NULL,
  conf.level = NULL,
  mu = 0,
  alternative = "two.sided",
  norm_plots = TRUE,
  transformation = TRUE,
  force_transformation = NULL,
  alpha = 0.05,
  intro_text = TRUE,
  close_generated_files = FALSE,
  open_generated_files = interactive(),
  output_type = "default",
  save_as = NULL,
  save_in_wdir = FALSE,
  ...
)
}
\arguments{
\item{x}{Numeric vector of data values (one-sample or first group for two-sample),
or a formula of the form \code{response ~ group} or \code{response ~ 1}.}

\item{...}{For the formula method: additional arguments forwarded to
the row-filtering step. The arguments \code{subset} and
\code{na.action} are honored: when supplied, they are spliced
(still unevaluated) into a \code{\link[stats]{model.frame}} call
built once before the per-response loop, so the \code{subset}
expression is evaluated in the data's column scope (e.g.
\code{subset = cyl == 6} works). All responses in a
multi-response call (\code{y1 + y2 ~ group}) are then tested on
the identical row set. For the default (vector) method, \code{...}
is currently unused.}

\item{formula}{A formula specifying the model (alternative to using x/y).
\itemize{
  \item \strong{Two-sample (Independent/Paired):} \code{response ~ group}
        (where group has exactly 2 levels).
  \item \strong{One-sample:} \code{response ~ 1} or \code{response ~ NULL}.
}
More response variables can be added using \code{+} (e.g., \code{y1 + y2 ~ group}).}

\item{data}{A data frame containing the variables when using the formula interface.}

\item{paired}{Logical. If \code{TRUE}, performs a paired t-test.
\strong{Note:} For the formula interface, data must be sorted so that all
observations of group 1 appear before group 2 (AABB order). For the vector
interface, \code{x} and \code{y} must have the same length.}

\item{var.equal}{Logical or \code{NULL}. If \code{TRUE}, forces Student's t-test
(equal variances). If \code{FALSE} or \code{NULL} (default), Welch's t-test is
used. Bartlett's and Levene's tests are always reported as diagnostics but do
\strong{not} affect this choice. See Delacre, Lakens & Leys (2017).}

\item{conf.level}{Numeric. Confidence level. Default is \code{1 - alpha}.
If \code{conf.level} is specified, \code{alpha} is set to \code{1 - conf.level}.}

\item{mu}{Numeric. The true value to test against: the mean (one-sample), the mean
of differences (paired), or the difference in means (two-sample). Default is 0.
For transformed analyses, \code{mu} is forward-transformed for one-sample and
paired tests. For two-sample tests with \code{mu != 0} a warning is issued.}

\item{alternative}{Character string. \code{"two.sided"} (default),
\code{"greater"}, or \code{"less"}.}

\item{norm_plots}{Logical. If \code{TRUE}, diagnostic plots are included in the
output. Default is \code{TRUE}.}

\item{transformation}{Logical or character string. If \code{TRUE} or
\code{"boxcox"}, applies \code{f_boxcox()} when Shapiro-Wilk indicates
non-normality. If \code{"bestnormalize"}, applies \code{f_bestNormalize()}.
If \code{FALSE} or \code{"none"}, no transformation is applied.
\strong{Note:} For paired tests, \code{bestNormalize} (Yeo-Johnson) is always
used on the differences, since Box-Cox requires strictly positive values.
Default is \code{TRUE}.}

\item{force_transformation}{Character vector. Names of variables to transform
regardless of normality results.}

\item{alpha}{Numeric. Significance level. Default is \code{0.05}.}

\item{intro_text}{Logical. If \code{TRUE}, includes explanation of t-test
assumptions. Default is \code{TRUE}.}

\item{close_generated_files}{Logical. Closes open Excel/Word files before writing.
Default \code{FALSE}. \strong{Windows only.}}

\item{open_generated_files}{Logical. Whether to open the generated output
files after creation. Defaults to \code{TRUE} in an interactive R session
and \code{FALSE} otherwise (e.g. in scripts or automated pipelines).
Set to \code{TRUE} or \code{FALSE} to override this behaviour explicitly.}

\item{output_type}{Character string specifying the output format. Default is \code{"default"}.
\itemize{
  \item \code{"default"}: Returns the object and lets R decide whether
    to print; auto-prints if unassigned, silent if assigned to a variable.
    Use \code{print(result)} or \code{plot(result)} to display the
    returned object.
  \item \code{"console"}: Forces immediate printing to the console
    regardless of object assignment.
  \item \code{"pdf"}, \code{"word"}, \code{"excel"}: Saves results to a
    file of the corresponding format. See \code{save_as},
    \code{save_in_wdir}, and \code{open_generated_files} for file
    path and opening behavior.
  \item \code{"rmd"}: Stores the raw markdown string inside the returned
    object for use in R Markdown documents.
}}

\item{save_as}{Character. Specific path/filename for output.}

\item{save_in_wdir}{Logical. Save in working directory. Default \code{FALSE}.}

\item{y}{Optional numeric vector (second group) for two-sample tests if using
the vector interface. Ignored when a formula is supplied.}
}
\value{
An object of class \code{'f_t_test'}, a named list with one element per
  response variable. Each element contains the t-test result, normality test
  results, variance diagnostic results, transformation object (if applied),
  and back-transformed confidence interval (if applicable).
}
\description{
Performs One-sample, Two-sample (Independent), or Paired t-tests on a given dataset
with options for (Box-Cox/BestNormalize) transformations, normality tests, and
visualization. Several response parameters can be analysed in sequence
(formula interface). Additionally, a vector interface similar to \code{stats::t.test()}
is supported.
}
\examples{
\donttest{
# 1. Two-sample independent Welch's t-test (default)
f_t_test(mpg ~ am, data = mtcars, output_type = "console", norm_plots = FALSE)

# 2. Multiple response variables in one call
f_t_test(mpg + hp ~ am, data = mtcars, output_type = "console", norm_plots = FALSE)

# 3. One-sample t-test: test if mean mpg equals 20
f_t_test(mpg ~ 1, data = mtcars, mu = 20,
         output_type = "console", norm_plots = FALSE)

# 4. Paired t-test (sleep dataset is already in AABB order)
f_t_test(extra ~ group, data = sleep, paired = TRUE,
         output_type = "console", norm_plots = FALSE)

# 5. Vector interface: two-sample independent
group_auto   <- mtcars$mpg[mtcars$am == 0]
group_manual <- mtcars$mpg[mtcars$am == 1]
f_t_test(group_auto, group_manual, output_type = "console", norm_plots = FALSE)

# 6. Vector interface: one-sample
f_t_test(mtcars$mpg, mu = 20, output_type = "console", norm_plots = FALSE)

# 7. Force Student's t-test (equal variances assumed)
f_t_test(mpg ~ am, data = mtcars, var.equal = TRUE,
         output_type = "console", norm_plots = FALSE)

# 8. One-sided test
f_t_test(mpg ~ am, data = mtcars, alternative = "greater",
         output_type = "console", norm_plots = FALSE)

# 9. Custom significance level (alpha = 0.01 is equivalent to conf.level = 0.99)
f_t_test(mpg ~ am, data = mtcars, alpha = 0.01,
         output_type = "console", norm_plots = FALSE)

# 10. Box-Cox transformation with back-transformed CI
# The back-transformed CI estimates the MEDIAN, not the arithmetic mean.
result <- f_t_test(hp ~ am, data = mtcars, transformation = TRUE,
                   output_type = "console", norm_plots = FALSE)
result[["hp"]]$ci_backtransformed

# 11. One-sample with non-zero mu and back-transformation
f_t_test(hp ~ 1, data = mtcars, mu = 100, transformation = TRUE,
         output_type = "console", norm_plots = FALSE)

# 12. BestNormalize transformation (set seed for reproducibility)
set.seed(123)
f_t_test(hp ~ am, data = mtcars, transformation = "bestnormalize",
         output_type = "console", norm_plots = FALSE)

# 13. Force transformation regardless of normality
f_t_test(mpg + hp ~ am, data = mtcars, force_transformation = "mpg",
         output_type = "console", norm_plots = FALSE)

# 14. Suppress transformation (diagnostic mode)
f_t_test(hp ~ am, data = mtcars, transformation = FALSE,
         output_type = "console", norm_plots = FALSE)

# 15. Access return object fields directly
result <- f_t_test(mpg + hp ~ am, data = mtcars,
                   output_type = "default", norm_plots = FALSE, intro_text = FALSE)
result[["mpg"]]$t_test          # standard htest object
result[["hp"]]$shapiro_res      # Shapiro-Wilk result
result[["hp"]]$homog_p_bartlett # Bartlett p-value (diagnostic only)
result[["hp"]]$homog_p_levene   # Levene p-value (diagnostic only)
result[["hp"]]$ci_backtransformed # back-transformed CI if transformed
}
}
\references{
Delacre, M., Lakens, D., & Leys, C. (2017). Why psychologists should by default
use Welch's t-test instead of Student's t-test.
\emph{International Review of Social Psychology}, 30(1), 92-101.
\doi{10.5334/irsp.82}
}
\author{
Sander H. van Delden  \email{plantmind@proton.me} \cr
}
