test.z: z-Test

In misty: Miscellaneous Functions 'T. Yanagida'

z-Test

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.

Usage

test.z(x, ...)

## Default S3 method:
test.z(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, ...)

## S3 method for class 'formula'
test.z(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

x	a numeric vector of data values.
...	further arguments to be passed to or from methods.
y	a numeric vector of data values.
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 sigma; when specifying two values for the argument sigma, unequal standard deviations are assumed. Note that either argument sigma or argument sigma2 is specified.
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 sigma2; when specifying two values for the argument sigma, unequal variance are assumed. Note that either argument sigma or argument sigma2 is specified.
mu	a numeric value indicating the population mean under the null hypothesis. Note that the argument mu is only used when computing a one-sample z-test.
paired	logical: if TRUE, paired-sample z-test is computed.
alternative	a character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater" or "less".
hypo	logical: if TRUE (default), null and alternative hypothesis are shown on the console.
descript	logical: if TRUE (default), descriptive statistics are shown on the console.
effsize	logical: if TRUE, effect size measure Cohen's d is shown on the console.
conf.level	a numeric value between 0 and 1 indicating the confidence level of the interval.
digits	an integer value indicating the number of decimal places to be used for displaying descriptive statistics and confidence interval.
p.digits	an integer value indicating the number of decimal places to be used for displaying the p-value.
as.na	a numeric vector indicating user-defined missing values, i.e. these values are converted to NA before conducting the analysis.
plot	logical: if TRUE, a plot showing bar plots with error bars for confidence intervals is drawn. For additional plotting arguments, see Details in the help page of the function plot.misty.object.
bar	logical: if TRUE (default), bars representing means for each groups are drawn.
point	logical: if TRUE, points representing means for each groups are drawn.
ci	logical: if TRUE (default), error bars representing confidence intervals are drawn.
jitter	logical: if TRUE, jittered data points are drawn.
line	logical: if TRUE (default), a horizontal line is drawn at mu for the one-sample z-test or at 0 for the paired-sample z-test.
adjust	logical: if TRUE (default), difference-adjustment for the confidence intervals in a two-sample design is applied.
filename	a character string indicating the filename argument including the file extension in the ggsave function. Note that one of ".eps", ".ps", ".tex", ".pdf" (default), ".jpeg", ".tiff", ".png", ".bmp", ".svg" or ".wmf" needs to be specified as file extension in the file argument. Note that plots can only be saved when plot = TRUE.
width	a numeric value indicating the width argument (default is the size of the current graphics device) for the ggsave function.
height	a numeric value indicating the height argument (default is the size of the current graphics device) for the ggsave function.
dpi	a numeric value indicating the dpi argument (default is 600) for the ggsave function.
write	a character string naming a text file with file extension ".txt" (e.g., "Output.txt") for writing the output into a text file.
append	logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.
check	logical: if TRUE (default), argument specification is checked.
output	logical: if TRUE (default), output is shown on the console.
formula	in case of two sample z-test (i.e., paired = FALSE), a formula of the form y ~ group where group is a numeric variable, character variable or factor with two values or factor levels giving the corresponding groups.
data	a matrix or data frame containing the variables in the formula formula.

Details

Effect Size

The Cohen's d reported when the argument effsize is set to TRUE is based on the population standard deviation specified in the argument sigma or the square root of the population variance specified in the argument sigma2.

• 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 d_z (Lakens, 2013).

• 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.

Value

Returns an object of class misty.object, which is a list with following entries:

call	function call
type	type of analysis
sample	type of sample, i.e., one-, two-, or paired sample
formula	formula
data	data frame with the outcome and grouping variable
args	specification of function arguments
plot	ggplot2 object for plotting the results
result	result table

Author(s)

Takuya Yanagida [e-mail]

References

Lakens, D. (2013). Calculating and reporting effect sizes to facilitate cumulative science: A practical primer for t-tests and ANOVAs. Frontiers in Psychology, 4, 1-12. https://doi.org/10.3389/fpsyg.2013.00863

Rasch, D., Kubinger, K. D., & Yanagida, T. (2011). Statistics in psychology - Using R and SPSS. John Wiley & Sons.

See Also

test.t, aov.b, aov.w, test.welch, cohens.d, ci.mean.diff, ci.mean

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

## Not run: 

# 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)

## End(Not run)

misty documentation built on Aug. 2, 2026, 9:06 a.m.