% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.levene.R
\name{test.levene}
\alias{test.levene}
\title{Levene's Test for Homogeneity of Variance}
\usage{
test.levene(formula, data, method = c("median", "mean"), hypo = FALSE,
            descript = FALSE, conf.level = 0.95, digits = 2, p.digits = 3,
            as.na = NULL, plot = FALSE, violin = TRUE, box = TRUE, jitter = FALSE,
            gray = FALSE, 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{method}{a character string specifying the method to compute the
center of each group, i.e. \code{method = "median"} (default)
to compute the Levene's test based on the median (aka
Brown-Forsythe test) or \code{method = "mean"} to compute
the Levene's test based on the arithmetic mean.}

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

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

\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 showing violins with
boxplots is drawn.}

\item{violin}{logical: if \code{TRUE} (default), violins are drawn.}

\item{box}{logical: if \code{TRUE} (default), boxplots are drawn.}

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

\item{gray}{logical: if \code{TRUE}, the plot is drawn in gray scale.}

\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{file} argument. Note that plots can only be
saved when specifying \code{plot = TRUE}.}

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

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

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

\item{write}{a character string naming a file for writing the output into
either a text file with file extension \code{".txt"} (e.g.,
\code{"Output.txt"}) or Excel file with file extension
\code{".xlsx"} (e.g., \code{"Output.xlsx"}). If the file name
does not contain any file extension, an Excel file will be
written.}

\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.}
}
\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 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 Levene's test for homogeneity of variance across two
or more independent groups including a plot showing violin plots and boxplots
representing the distribution of the outcome variable for each group.
}
\details{
\describe{
\item{\strong{Levene's Test}}{The Levene's test is equivalent to a one-way analysis
of variance (ANOVA) with the absolute deviations of observations from the mean
of each group as dependent variable (\code{center = "mean"}). Brown and Forsythe
(1974) modified the Levene's test by using the absolute deviations of observations
from the median (\code{center = "median"}). By default, the Levene's test uses
the absolute deviations of observations from the median.}
}
}
\examples{
#————————————————————————————————————————————————————————————————————————————
# Levene's Test

# Example 1a: Levene's test based on the median
test.levene(mpg ~ gear, data = mtcars)

# Example 1b: Levene's test based on the arithmetic mean
test.levene(mpg ~ gear, data = mtcars, method = "mean")

# Example 1c: Levene's test, print descriptive statistics
test.levene(mpg ~ gear, data = mtcars, descript = TRUE)

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

# Example 2a: Plot results, default setting
test.levene(mpg ~ gear, data = mtcars, plot = TRUE)

# Example 2b: Plot results, no violin plots, draw jittered data points
test.levene(mpg ~ gear, data = mtcars, plot = TRUE, violin = FALSE, 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 <- test.levene(mpg ~ gear, data = mtcars)
plot(object, violin.alpha = 0.1, box.width = 0.1, title = "Levene's Test")

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

# Load ggplot2 package
library(ggplot2)

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

# Example 3: Plot
ggplot(object$data, aes(group, y, fill = group)) +
  geom_violin(alpha = 0.3, trim = FALSE) +
  geom_boxplot(alpha = 0.2, width = 0.2) +
  geom_jitter(alpha = 0.2, width = 0.05, height = 0, size = 1.25) +
  theme_bw() +
   ggplot2::guides(fill = "none")

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

\dontrun{

# Example 4a: Write results into a text file
test.levene(mpg ~ gear, data = mtcars, write = "Levene.txt")

# Example 4b: Write results into an Excel file
test.levene(mpg ~ gear, data = mtcars, write = "Levene.xlsx")

# Example 4c: Save plot as PNG fine
test.levene(mpg ~ gear, data = mtcars, plot = TRUE,
            filename = "Levene-Test.png", width = 6, height = 5)
}
}
\references{
Brown, M. B., & Forsythe, A. B. (1974). Robust tests for the equality of
variances. \emph{Journal of the American  Statistical Association, 69},
364-367.

Rasch, D., Kubinger, K. D., & Yanagida, T. (2011). \emph{Statistics in psychology
- Using R and SPSS}. John Wiley & Sons.
}
\seealso{
\code{\link{aov.b}}, \code{\link{test.t}}, \code{\link{test.welch}}
}
\author{
Takuya Yanagida \email{takuya.yanagida@univie.ac.at}
}
