% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.z.R
\name{test.z}
\alias{test.z}
\alias{test.z.default}
\alias{test.z.formula}
\title{z-Test}
\usage{
test.z(x, ...)

\method{test.z}{default}(x, y = NULL, sigma = NULL, sigma2 = NULL, mu = 0,
       paired = FALSE, alternative = c("two.sided", "less", "greater"),
       hypo = FALSE, descript = TRUE, effsize = FALSE, conf.level = 0.95,
       digits = 2, p.digits = 3, as.na = NULL, plot = FALSE, bar = TRUE,
       point = FALSE, ci = TRUE, line = TRUE, jitter = FALSE, adjust = TRUE,
       filename = NULL, width = NA, height = NA, dpi = 600, write = NULL,
       append = TRUE, check = TRUE, output = TRUE, ...)

\method{test.z}{formula}(formula, data, sigma = NULL, sigma2 = NULL,
       alternative = c("two.sided", "less", "greater"), hypo = FALSE,
       descript = TRUE, effsize = FALSE, conf.level = 0.95, digits = 2,
       p.digits = 3, as.na = NULL, plot = FALSE, bar = TRUE, point = FALSE,
       ci = TRUE, line = TRUE, jitter = FALSE, adjust = TRUE, filename = NULL,
       width = NA, height = NA, dpi = 600, write = NULL, append = TRUE,
       check = TRUE, output = TRUE, ...)
}
\arguments{
\item{x}{a numeric vector of data values.}

\item{...}{further arguments to be passed to or from methods.}

\item{y}{a numeric vector of data values.}

\item{sigma}{a numeric vector indicating the population standard deviation(s).
In case of two-sample z-test, equal standard deviations are
assumed when specifying one value for the argument \code{sigma};
when specifying two values for the argument \code{sigma},
unequal standard deviations are assumed. Note that either
argument \code{sigma} or argument \code{sigma2} is specified.}

\item{sigma2}{a numeric vector indicating the population variance(s). In
case of two-sample z-test, equal variances are assumed when
specifying one value for the argument \code{sigma2}; when
specifying two values for the argument \code{sigma}, unequal
variance are assumed. Note that either argument \code{sigma}
or argument \code{sigma2} is specified.}

\item{mu}{a numeric value indicating the population mean under the null
hypothesis. Note that the argument \code{mu} is only used
when computing a one-sample z-test.}

\item{paired}{logical: if \code{TRUE}, paired-sample z-test is computed.}

\item{alternative}{a character string specifying the alternative hypothesis,
must be one of \code{"two.sided"} (default), \code{"greater"}
or \code{"less"}.}

\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 measure Cohen's d is
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 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 showing bar plots with
error bars for confidence intervals is drawn. For additional plotting arguments,
see \code{Details} in the help page of the function \code{plot.misty.object}.}

\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{line}{logical: if \code{TRUE} (default), a horizontal line
is drawn at \code{mu} for the one-sample z-test or at
0 for the paired-sample z-test.}

\item{adjust}{logical: if \code{TRUE} (default), difference-adjustment
for the confidence intervals in a two-sample design 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{file}
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)
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 is \code{600}) for 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.}

\item{formula}{in case of two sample z-test (i.e., \code{paired = FALSE}),
a formula of the form \code{y ~ group} where \code{group}
is a numeric variable, character variable or factor with
two values or factor levels giving the corresponding
groups.}

\item{data}{a matrix or data frame containing the variables in the
formula \code{formula}.}
}
\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{formula}}{formula}
\item{\code{data}}{data frame with the outcome and grouping variable}
\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 the one-sample, two-sample, and paired-sample z-test
and provides descriptive statistics, effect size measure, and a plot showing
error bars for (difference-adjusted) confidence intervals with jittered data
points.
}
\details{
\describe{
\item{\strong{Effect Size}}{The Cohen's d reported when the argument \code{effsize}
is set to \code{TRUE} is based on the population standard deviation specified
in the argument \code{sigma} or the square root of the population variance specified
in the argument \code{sigma2}.
  \itemize{
   \item{\strong{One-Sample and Paired-Sample Design}} In a one-sample and paired-sample
   design, Cohen's d is the mean of the difference scores divided by the population
   standard deviation of the (difference) scores equivalent to Cohen's \eqn{d_z}
    (Lakens, 2013).
    \item{\strong{Two-Sample Design}} In a two-sample design, Cohen's d is the difference
    between means of the two groups of observations divided by either the population
    standard deviation when assuming and specifying equal standard deviations or
    the unweighted pooled population standard deviation when assuming and specifying
    unequal standard deviations.
  }
}
}
}
\examples{
#————————————————————————————————————————————————————————————————————————————
# One-Sample Design

# Example 1a: Two-sided one-sample z-test, population mean = 20, population SD = 6
test.z(mtcars$mpg, sigma = 6, mu = 20)

# Example 1b: One-sided one-sample z-test, population mean = 20, population SD = 6,
# print Cohen's d
test.z(mtcars$mpg, sigma = 6, mu = 20, alternative = "greater", effsize = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Two-Sample Design

# Example 2a: Two-sided two-sample z-test, population SD = 6, equal SD assumption
test.z(mpg ~ vs, data = mtcars, sigma = 6)

# Example 2b: Two-sided two-sample z-test, alternative specification
test.z(c(3, 1, 4, 2, 5, 3, 6, 7), c(5, 2, 4, 3, 1), sigma = 1.2)

# Example 2c: Two-sided two-sample z-test, population SD = 4 and 6, unequal SD assumption
test.z(mpg ~ vs, data = mtcars, sigma = c(4, 6))

# Example 2d: One-sided two-sample z-test, population SD = 4 and 6, unequal SD assumption
# print Cohen's d
test.z(mpg ~ vs, data = mtcars, sigma = c(4, 6), alternative = "greater", effsize = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Paired-Sample Design

# Example 3a: Two-sided paired-sample z-test, population SD of difference score = 1.2
test.z(mtcars$drat, mtcars$wt, sigma = 1.2, paired = TRUE)

# Example 3b: One-sided paired-sample z-test, population SD of difference score = 1.2,
# print Cohen's d
test.z(mtcars$drat, mtcars$wt, sigma = 1.2, paired = TRUE, alternative = "greater",
       effsize = TRUE)

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

# Example 4a: One-Sample Design
test.z(mtcars$mpg, sigma = 6, mu = 20, plot = TRUE)

# Example 4b: Two-Sample Design
test.z(mpg ~ vs, data = mtcars, sigma = 6, plot = TRUE)

# Example 4c: Paired-Sample Design
test.z(mtcars$drat, mtcars$wt, sigma = 1.2, paired = TRUE, plot = TRUE)

# Example 4d: Plot results using the plot() function, use additional arguments
# see Details in the help page of the function plot.misty.object
object <- test.z(mpg ~ vs, data = mtcars, sigma = 6)
plot(object, jitter = TRUE, jitter.alpha = 0.4, title = "Two-Sample z-Test")

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

# Load ggplot2 package
library(ggplot2)

# Example 4a: Two-sample z-test
ci.table <- ci.mean(mtcars, mpg, group = "vs", adjust = TRUE, output = FALSE)$result

ggplot(ci.table, aes(group, m), stat = "identity", size = 3) +
  geom_bar(aes(group, m), stat = "summary", fun = "mean") +
  geom_errorbar(aes(group, m, ymin = low, ymax = upp), width = 0.1) +
  theme_bw()

# Example 4b: Paired-sample z-test
object <- test.z(mtcars$drat, mtcars$wt, sigma = 1.2, paired = TRUE)

ggplot(data.frame(x = object$data$y - object$data$x), aes(x = 0L, y = x)) +
 geom_bar(data = object$result, aes(0, m.diff), stat = "summary", fun = "mean") +
 geom_errorbar(data = object$result, aes(0, m.diff, ymin = m.low, ymax = m.upp), width = 0.1) +
 geom_hline(yintercept = 0L, linetype = 3, linewidth = 0.8) +
 scale_x_continuous(name = "", limits = c(-2, 2)) +
 theme_bw()  +
 theme(axis.text.x = element_blank(), axis.ticks.x = element_blank())

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

\dontrun{

# Example 6a: Write results into a text file
test.z(mpg ~ vs, data = mtcars, sigma = 6, write = "z-Test.txt")

# Example 6b:  Write results into an Excel file
test.z(mpg ~ vs, data = mtcars, sigma = 6, write = "z-Test.xlsx")

# Example 4c: Two-Sample Design
test.z(mpg ~ vs, data = mtcars, sigma = 6, plot = TRUE, filename = "z-Test.png",
       width = 6, height = 5)
}
}
\references{
Lakens, D. (2013). Calculating and reporting effect sizes to facilitate cumulative
science: A practical primer for t-tests and ANOVAs. \emph{Frontiers in Psychology, 4},
1-12. https://doi.org/10.3389/fpsyg.2013.00863

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