% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.welch.R
\name{test.welch}
\alias{test.welch}
\title{Welch's Test}
\usage{
test.welch(formula, data, alternative = c("two.sided", "less", "greater"),
           hypo = FALSE, descript = FALSE, effsize = FALSE, weighted = FALSE,
           ref = NULL, correct = FALSE, posthoc = FALSE, conf.level = 0.95,
           digits = 2, p.digits = 3, as.na = NULL, plot = FALSE, bar = TRUE,
           point = FALSE, ci = TRUE, jitter = FALSE, adjust = TRUE,
           filename = NULL, width = NA, height = NA, dpi = 600,
           write = NULL, append = TRUE, check = TRUE, output = TRUE)
}
\arguments{
\item{formula}{a formula of the form \code{y ~ group} where \code{y} is
a numeric variable giving the data values and \code{group}
a numeric variable, character variable or factor with two
or more than two values or factor levels giving the
corresponding groups.}

\item{data}{a matrix or data frame containing the variables in the
formula \code{formula}.}

\item{alternative}{a character string specifying the alternative hypothesis,
must be one of \code{"two.sided"} (default), \code{"greater"}
or \code{"less"}. Note that this argument is only used when
conducting Welch's two-sample t-test.}

\item{hypo}{logical: if \code{TRUE} (default), null and alternative
hypothesis are shown on the console.}

\item{descript}{logical: if \code{TRUE}, descriptive statistics are shown
on the console when conducting Welch's ANOVA.}

\item{effsize}{logical: if \code{TRUE}, effect size measure Cohen's d for
Welch's two-sample t-test (see \code{\link{cohens.d}}),
\eqn{\eta^2} and \eqn{\omega^2} for Welch's ANOVA and
Cohen's d for the post hoc tests are shown on the console.}

\item{weighted}{logical: if \code{TRUE}, the weighted pooled standard
deviation is used to compute Cohen's d.}

\item{ref}{a numeric value or character string indicating the reference
group. The standard deviation of the reference group is
used to standardized the mean difference to compute
Cohen's d.}

\item{correct}{logical: if \code{TRUE}, correction factor to remove
positive bias in small samples for is used to compute Cohen's d.}

\item{posthoc}{logical: if \code{TRUE}, Games-Howell post hoc test for
multiple comparison is conducted when performing Welch's ANOVA.}

\item{conf.level}{a numeric value between 0 and 1 indicating the confidence
level of the interval.}

\item{digits}{an integer value indicating the number of decimal places
to be used for displaying results.}

\item{p.digits}{an integer value indicating the number of decimal places
to be used for displaying the \emph{p}-value.}

\item{as.na}{a numeric vector indicating user-defined missing values,
i.e. these values are converted to \code{NA} before
conducting the analysis.}

\item{plot}{logical: if \code{TRUE}, a plot is drawn.}

\item{bar}{logical: if \code{TRUE} (default), bars representing means
for each groups are drawn.}

\item{point}{logical: if \code{TRUE}, points representing means for
each groups are drawn.}

\item{ci}{logical: if \code{TRUE} (default), error bars representing
confidence intervals are drawn.}

\item{jitter}{logical: if \code{TRUE}, jittered data points are drawn.}

\item{adjust}{logical: if \code{TRUE} (default), difference-adjustment
for the confidence intervals is applied.}

\item{filename}{a character string indicating the \code{filename}
argument including the file extension in the \code{ggsave}
function. Note that one of \code{".eps"}, \code{".ps"},
\code{".tex"}, \code{".pdf"} (default),
\code{".jpeg"}, \code{".tiff"}, \code{".png"},
\code{".bmp"}, \code{".svg"} or \code{".wmf"} needs
to be specified as file extension in the \code{filename}
argument. Note that plots can only be saved when
\code{plot = TRUE}.}

\item{width}{a numeric value indicating the \code{width} argument
(default is the size of the current graphics device)
in the \code{ggsave} function.}

\item{height}{a numeric value indicating the \code{height} argument
(default is the size of the current graphics device)
in the \code{ggsave} function.}

\item{dpi}{a numeric value indicating the \code{dpi} argument
(default: \code{600}) in the \code{ggsave} function.}

\item{write}{a character string naming a text file with file extension
\code{".txt"} (e.g., \code{"Output.txt"}) for writing the
output into a text file.}

\item{append}{logical: if \code{TRUE} (default), output will be appended
to an existing text file with extension \code{.txt} specified
in \code{write}, if \code{FALSE} existing text file will be
overwritten.}

\item{check}{logical: if \code{TRUE} (default), argument specification
is checked.}

\item{output}{logical: if \code{TRUE} (default), output is shown on the
console.}
}
\value{
Returns an object of class \code{misty.object}, which is a list with following
entries:
\item{\code{call}}{function call}
\item{\code{type}}{type of analysis}
\item{\code{sample}}{type of sample, i.e., one-, two-, or paired sample}
\item{\code{data}}{data frame with the outcome and grouping variable}
\item{\code{formula}}{formula}
\item{\code{args}}{specification of function arguments}
\item{\code{plot}}{ggplot2 object for plotting the results}
\item{\code{result}}{result table}
}
\description{
This function performs Welch's two-sample t-test and Welch's ANOVA including
Games-Howell post hoc test for multiple comparison and provides descriptive
statistics, effect size measures, and a plot showing bars representing means
for each group and error bars for difference-adjusted confidence intervals.
}
\details{
\describe{
\item{\strong{Effect Size Measure}}{By default, Cohen's d based on the non-weighted
standard deviation (i.e., \code{weighted = FALSE}) which does not assume homogeneity
of variance is computed (see Delacre et al., 2021) when requesting an effect size
measure (i.e., \code{effsize = TRUE}). Cohen's d based on the pooled standard
deviation assuming equality of variances between groups can be requested by
specifying \code{weighted = TRUE}.}
}
}
\examples{
#————————————————————————————————————————————————————————————————————————————
# Two-Sample Design

# Example 1a: Two-sided two-sample Welch-test
test.welch(hp ~ am, data = mtcars)

# Example 1b: One-sided two-sample Welch-test
test.welch(hp ~ am, data = mtcars, alternative = "less")

# Example 1c: Two-sided two-sample Welch-test,
# Print descriptive statistics and Cohen's d
test.welch(hp ~ am, data = mtcars, descript = TRUE, effsize = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Multiple-Sample Design

# Example 2a: Welch's ANOVA
test.welch(hp ~ gear, data = mtcars)

# Example 2b: Welch's ANOVA,
# Print descriptive statistics and Games-Howell post hoc test
test.welch(hp ~ gear, data = mtcars, descript = TRUE, posthoc = TRUE)

# Example 2c: Welch's ANOVA, print eta-squared and omega-squared
test.welch(hp ~ gear, data = mtcars, effsize = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Plot

# Example 3a: Plot results, default setting
test.welch(hp ~ gear, data = mtcars, plot = TRUE)

# Example 3b: Plot results
# No bars, draw points representing means and jittered data points
test.welch(hp ~ gear, data = mtcars, plot = TRUE, bar = FALSE, point = TRUE,
           jitter = TRUE)

# Example 3c: Plot results using the plot() function, use additional arguments
# see Details in the help page of the function plot.misty.object
object <- test.welch(hp ~ gear, data = mtcars)
plot(object, jitter = TRUE, jitter.alpha = 0.4, title = "Welch's Test")

#————————————————————————————————————————————————————————————————————————————
# Create Plot Manually

# Load ggplot2 package
library(ggplot2)

# Create misty object
object <- test.welch(hp ~ gear, data = mtcars)

# Example 4: Plot
ggplot(object$result$descript, aes(group, y)) +
  geom_bar(aes(group, m), stat = "summary", fun = "mean") +
  geom_jitter(data = object$data, aes(group, y), alpha = 0.1, width = 0.05,
             height = 0, size = 1.25) +
  geom_point(aes(group, m), stat = "identity", size = 3) +
  geom_errorbar(aes(group, m, ymin = low, ymax = upp), width = 0.1) +
  theme_bw()

#————————————————————————————————————————————————————————————————————————————
# Write Results and Save Plot

\dontrun{

# Example 5a: Write results into a text file
test.welch(hp ~ gear, data = mtcars, write = "Welch-Test.txt")

# Example 5a: Write results into an Excel file
test.welch(hp ~ gear, data = mtcars, write = "Welch-Test.xlsx")

# Example 5b: Save plot as PNG fine
test.welch(hp ~ gear, data = mtcars, plot = TRUE,
            filename = "Welch-Test.png", width = 6, height = 5)
}
}
\references{
Rasch, D., Kubinger, K. D., & Yanagida, T. (2011). \emph{Statistics in psychology
- Using R and SPSS}. John Wiley & Sons.

Delacre, M., Lakens, D., Ley, C., Liu, L., & Leys, C. (2021). Why Hedges' g*s
based on the non-pooled standard deviation should be reported with Welch's
t-test. https://doi.org/10.31234/osf.io/tu6mp
}
\seealso{
\code{\link{test.t}}, \code{\link{test.z}}, \code{\link{test.levene}},
\code{\link{aov.b}}, \code{\link{cohens.d}}, \code{\link{ci.mean.diff}},
\code{\link{ci.mean}}
}
\author{
Takuya Yanagida \email{takuya.yanagida@univie.ac.at}
}
