% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aov.b.R
\name{aov.b}
\alias{aov.b}
\title{Between-Subject Analysis of Variance}
\usage{
aov.b(formula, data, hypo = FALSE, descript = FALSE, effsize = FALSE,
      weighted = TRUE, 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 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{hypo}{logical: if \code{TRUE} (default), null and alternative
hypothesis are shown on the console.}

\item{descript}{logical: if \code{TRUE} (default), descriptive statistics
are shown on the console.}

\item{effsize}{logical: if \code{TRUE}, effect size measures \eqn{\eta^2}
and \eqn{\omega^2} for the ANOVA and Cohen's d for the post
hoc tests are shown on the console.}

\item{weighted}{logical: if \code{TRUE} (default), the weighted pooled standard
deviation is used 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}, Tukey HSD post hoc test for
multiple comparison is conducted.}

\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 descriptive statistics and
confidence interval.}

\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 is \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{data}}{data frame with variables used in the current analysis}
\item{\code{formula}}{formula of the current analysis}
\item{\code{args}}{specification of function arguments}
\item{\code{plot}}{ggplot2 object for plotting the results}
\item{\code{result}}{result tables}
}
\description{
This function performs an one-way between-subject analysis of variance (ANOVA)
including Tukey HSD post hoc tests 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{Confidence Intervals}}{Cumming and Finch (2005) pointed out that
when 95\% confidence intervals (CI) for two separately plotted means overlap,
it is still possible that the CI for the difference would not include zero.
Baguley (2012) proposed to adjust the width of the CIs by the factor of
\eqn{\sqrt{2}} to reflect the correct width of the CI for a mean difference:

\deqn{\hat{\mu}_{j} \pm t_{n - 1, 1 - \alpha/2} \frac{\sqrt{2}}{2} \hat{\sigma}_{{\hat{\mu}}_j}}}

These difference-adjusted CIs around the individual means can be interpreted
as if it were a CI for their difference. Note that the width of these intervals
is sensitive to differences in the variance and sample size of each sample,
i.e., unequal population variances and unequal \eqn{n} alter the interpretation
of difference-adjusted CIs.
}
}
\examples{
#————————————————————————————————————————————————————————————————————————————
# Between-Subject Analysis of Variance

# Example 1a: Between-Subject ANOVA
aov.b(hp ~ gear, data = mtcars)

# Example 1b: Between-Subject ANOVA
# Print descriptive statistics and Tukey HSD post hoc test
aov.b(hp ~ gear, data = mtcars, descript = TRUE, posthoc = TRUE)

# Example 1c: Between-Subject ANOVA, print eta-squared and omega-squared
aov.b(hp ~ gear, data = mtcars, effsize = TRUE)

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

# Example 2a: Plot results, default setting
aov.b(hp ~ gear, data = mtcars, plot = TRUE)

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

# Example 2c: Plot results using the plot() function, use additional arguments
# see Details in the help page of the function plot.misty.object
object <- aov.b(hp ~ gear, data = mtcars)
plot(object, jitter = TRUE, jitter.alpha = 0.4, title = "Between-Subject ANOVA")

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

# Load ggplot2 package
library(ggplot2)

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

# Example 3: 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 4a: Write results into a text file
aov.b(hp ~ gear, data = mtcars, write = "ANOVA.txt")

# Example 4b: Write results into an Excel file
aov.b(hp ~ gear, data = mtcars, write = "ANOVA.xlsx")

# Example 4c: Save plot as PNG fine
aov.b(hp ~ gear, data = mtcars, plot = TRUE, filename = "ANOVA.png",
      width = 6, height = 5)
}
}
\references{
Baguley, T. S. (2012a). \emph{Serious stats: A guide to advanced statistics for
the behavioral sciences}. Palgrave Macmillan.

Cumming, G., and Finch, S. (2005) Inference by eye: Confidence intervals, and
how to read pictures of data. \emph{American Psychologist, 60}, 170–80.

Rasch, D., Kubinger, K. D., & Yanagida, T. (2011). \emph{Statistics in psychology
- Using R and SPSS}. John Wiley & Sons.
}
\seealso{
\code{\link{aov.w}}, \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}
}
