Package 'nhstplot' reference manual

Title:	Plot Null Hypothesis Significance Tests
Description:	Illustrate graphically the most common Null Hypothesis Significance Testing procedures. More specifically, this package provides functions to plot Chi-Squared, F, t (one- and two-tailed) and z (one- and two-tailed) tests, by plotting the probability density under the null hypothesis as a function of the different test statistic values. Although highly flexible (color theme, fonts, etc.), only the minimal number of arguments (observed test statistic, degrees of freedom) are necessary for a clear and useful graph to be plotted, with the observed test statistic and the p value, as well as their corresponding value labels. The axes are automatically scaled to present the relevant part and the overall shape of the probability density function. This package is especially intended for education purposes, as it provides a helpful support to help explain the Null Hypothesis Significance Testing process, its use and/or shortcomings.
Authors:	Nils Myszkowski [aut, cre]
Maintainer:	Nils Myszkowski <[email protected]>
License:	GPL-3
Version:	1.3.0
Built:	2024-10-30 04:45:35 UTC
Source:	https://github.com/cran/nhstplot

Illustrate a $\chi^2$ test graphically.

Description

This function plots the density probability distribution of a $\chi^2$ statistic, with a vertical cutline at the observed $\chi^2$ value specified. The p-value and the observed $\chi^2$ value are plotted. Although largely customizable, only two arguments are required (the observed $\chi^2$ and the degrees of freedom).

Usage

plotchisqtest(
  chisq,
  df = chisq$parameter,
  blank = FALSE,
  xmax = "auto",
  title = parse(text = expression(chi^2 ~ "Test")),
  xlabel = parse(text = expression(chi^2)),
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colorleft = "aliceblue",
  colorright = "firebrick3",
  colorleftcurve = "black",
  colorrightcurve = "black",
  colorcut = "black",
  colorplabel = colorright,
  theme = "default",
  signifdigitschisq = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)
plotchisqtest(
  chisq,
  df = chisq$parameter,
  blank = FALSE,
  xmax = "auto",
  title = parse(text = expression(chi^2 ~ "Test")),
  xlabel = parse(text = expression(chi^2)),
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colorleft = "aliceblue",
  colorright = "firebrick3",
  colorleftcurve = "black",
  colorrightcurve = "black",
  colorcut = "black",
  colorplabel = colorright,
  theme = "default",
  signifdigitschisq = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)

Arguments

`chisq`	A numeric value indicating the observed $\chi^2$ statistic. Alternatively, you can use an object of class `htest` created by the function `chisq.test()`.
`df`	A numeric value indicating the degrees of freedom. This argument is optional if you are using an `htest` object as the `chisq` argument.
`blank`	A logical that indicates whether to hide (`blank = TRUE`) the test statistic value, p value and cutline. The corresponding colors are actually only made transparent when `blank = TRUE`, so that the output is scaled exactly the same (this is useful and especially intended for step-by-step explanations).
`xmax`	A numeric including the maximum for the x-axis. Defaults to `"auto"`, which scales the plot automatically (optional).
`title`	A character or expression indicating a custom title for the plot (optional).
`xlabel`	A character or expression indicating a custom title for the x axis (optional).
`ylabel`	A character or expression indicating a custom title for the y axis (optional).
`fontfamily`	A character indicating the font family of all the titles and labels (e.g. `"serif"` (default), `"sans"`, `"Helvetica"`, `"Palatino"`, etc.) (optional).
`colorleft`	A character indicating the color for the "left" area under the curve (optional).
`colorright`	A character indicating the color for the "right" area under the curve (optional).
`colorleftcurve`	A character indicating the color for the "left" part of the curve (optional).
`colorrightcurve`	A character indicating the color for the "right" part of the curve (optional). By default, for color consistency, this color is also passed to the label, but this can be changed by providing an argument for the `colorlabel` parameter.
`colorcut`	A character indicating the color for the cut line at the observed test statistic (optional).
`colorplabel`	A character indicating the color for the label of the p-value (optional). By default, for color consistency, this color is the same as color of `colorright`.
`theme`	A character indicating one of the predefined color themes. The themes are `"default"` (light blue and red), `"blackandwhite"`, `"whiteandred"`, `"blueandred"`, `"greenandred"` and `"goldandblue"`) (optional). Supersedes `colorleft` and `colorright` if another argument than `"default"` is provided.
`signifdigitschisq`	A numeric indicating the number of desired significant figures reported for the $\chi^2$ label (optional).
`curvelinesize`	A numeric indicating the size of the curve line (optional).
`cutlinesize`	A numeric indicating the size of the cut line (optional). By default, the size of the curve line is used.
`p_value_position`	A numeric vector of length 2, indicating the x and y coordinates of the p-value label. By default, the position is set to `"auto"`. Note that the absolute value is used, and the sign is ignored.

Value

A plot with the density of probability of $\chi^2$ under the null hypothesis, annotated with the observed test statistic and the p-value.

Author(s)

Nils Myszkowski <[email protected]>

Examples

#Making a chi-squared plot with Chi-squared of 8 and df of 4
plotchisqtest(chisq = 8, df = 4)

#The same plot without the Chi-Squared or p value
plotchisqtest(8,4, blank = TRUE)

#Plot using a chisq.test()
test <- chisq.test(c(A = 37, B = 18, C = 25))
plotchisqtest(test)

#Plot from anova() model comparison
set.seed(1)
y <- rbinom(10, 1, .4) ; x <- 2*y + rnorm(10)
fit1 <- glm(y ~ 1, family = binomial)
fit2 <- glm(y ~ x, family = binomial)
comp <- anova(fit1, fit2, test = "Chisq")
plotchisqtest(comp)

#Making a chi-squared plot with Chi-squared of 8 and df of 4
plotchisqtest(chisq = 8, df = 4)

#The same plot without the Chi-Squared or p value
plotchisqtest(8,4, blank = TRUE)

#Plot using a chisq.test()
test <- chisq.test(c(A = 37, B = 18, C = 25))
plotchisqtest(test)

#Plot from anova() model comparison
set.seed(1)
y <- rbinom(10, 1, .4) ; x <- 2*y + rnorm(10)
fit1 <- glm(y ~ 1, family = binomial)
fit2 <- glm(y ~ x, family = binomial)
comp <- anova(fit1, fit2, test = "Chisq")
plotchisqtest(comp)

Illustrate an F Test graphically.

Description

This function plots the density probability distribution of an F statistic, with a vertical cutline at the observed F value specified. A p-value and the observed F value are plotted. Although largely customizable, only three arguments are required (the observed F and the degrees of freedom).

Usage

plotftest(
  f,
  dfnum = f$fstatistic[2],
  dfdenom = f$fstatistic[3],
  blank = FALSE,
  xmax = "auto",
  title = "F Test",
  xlabel = "F",
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colorleft = "aliceblue",
  colorright = "firebrick3",
  colorleftcurve = "black",
  colorrightcurve = "black",
  colorcut = "black",
  colorplabel = colorright,
  theme = "default",
  signifdigitsf = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)
plotftest(
  f,
  dfnum = f$fstatistic[2],
  dfdenom = f$fstatistic[3],
  blank = FALSE,
  xmax = "auto",
  title = "F Test",
  xlabel = "F",
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colorleft = "aliceblue",
  colorright = "firebrick3",
  colorleftcurve = "black",
  colorrightcurve = "black",
  colorcut = "black",
  colorplabel = colorright,
  theme = "default",
  signifdigitsf = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)

Arguments

`f`	A numeric value indicating the observed F statistic. Alternatively, you can pass an object of class `lm` created by the function `lm()`.
`dfnum`	A numeric value indicating the degrees of freedom of the numerator. This argument is optional if you are using an `lm` object as the `f` argument.
`dfdenom`	A numeric value indicating the degrees of freedom of the denominator. This argument is optional if you are using an `lm` object as the `f` argument.
`blank`	A logical that indicates whether to hide (`blank = TRUE`) the test statistic value, p value and cutline. The corresponding colors are actually only made transparent when `blank = TRUE`, so that the output is scaled exactly the same (this is useful and especially intended for step-by-step explanations).
`xmax`	A numeric including the maximum for the x-axis. Defaults to `"auto"`, which scales the plot automatically (optional).
`title`	A character or expression indicating a custom title for the plot (optional).
`xlabel`	A character or expression indicating a custom title for the x axis (optional).
`ylabel`	A character or expression indicating a custom title for the y axis (optional).
`fontfamily`	A character indicating the font family of all the titles and labels (e.g. `"serif"` (default), `"sans"`, `"Helvetica"`, `"Palatino"`, etc.) (optional).
`colorleft`	A character indicating the color for the "left" area under the curve (optional).
`colorright`	A character indicating the color for the "right" area under the curve (optional).
`colorleftcurve`	A character indicating the color for the "left" part of the curve (optional).
`colorrightcurve`	A character indicating the color for the "right" part of the curve (optional). By default, for color consistency, this color is also passed to the label, but this can be changed by providing an argument for the `colorlabel` parameter.
`colorcut`	A character indicating the color for the cut line at the observed test statistic (optional).
`colorplabel`	A character indicating the color for the label of the p-value (optional). By default, for color consistency, this color is the same as color of `colorright`.
`theme`	A character indicating one of the predefined color themes. The themes are `"default"` (light blue and red), `"blackandwhite"`, `"whiteandred"`, `"blueandred"`, `"greenandred"` and `"goldandblue"`) (optional). Supersedes `colorleft` and `colorright` if another argument than `"default"` is provided.
`signifdigitsf`	A numeric indicating the number of desired significant figures reported for the F (optional).
`curvelinesize`	A numeric indicating the size of the curve line (optional).
`cutlinesize`	A numeric indicating the size of the cut line (optional). By default, the size of the curve line is used.
`p_value_position`	A numeric vector of length 2, indicating the x and y coordinates of the p-value label. By default, the position is set to `"auto"`. Note that the absolute value is used, and the sign is ignored.

Value

A plot with the density of probability of F under the null hypothesis, annotated with the observed test statistic and the p-value.

Author(s)

Nils Myszkowski <[email protected]>

Examples

#Making an F plot with an F of 3, and degrees of freedom of 1 and 5.
plotftest(f = 4, dfnum = 3, dfdenom = 5)

#The same plot without the f or p value
plotftest(4,3,5, blank = TRUE)

#Passing an "lm" object
set.seed(1)
x <- rnorm(10) ; y <- x + rnorm(10)
fit <- lm(y ~ x)
plotftest(fit)
plotftest(summary(fit)) # also works

#Passing an "anova" F-change test
set.seed(1)
x <- rnorm(10) ; y <- x + rnorm(10)
fit1 <- lm(y ~ x)
fit2 <- lm(y ~ poly(x, 2))
comp <- anova(fit1, fit2)
plotftest(comp)

#Making an F plot with an F of 3, and degrees of freedom of 1 and 5.
plotftest(f = 4, dfnum = 3, dfdenom = 5)

#The same plot without the f or p value
plotftest(4,3,5, blank = TRUE)

#Passing an "lm" object
set.seed(1)
x <- rnorm(10) ; y <- x + rnorm(10)
fit <- lm(y ~ x)
plotftest(fit)
plotftest(summary(fit)) # also works

#Passing an "anova" F-change test
set.seed(1)
x <- rnorm(10) ; y <- x + rnorm(10)
fit1 <- lm(y ~ x)
fit2 <- lm(y ~ poly(x, 2))
comp <- anova(fit1, fit2)
plotftest(comp)

Illustrate a one- or two-tailed t test graphically.

Description

This function plots the density probability distribution of a t statistic, with appropriate vertical cutlines at the t value. The p-value and the observed t value are plotted. Although largely customizable, only two arguments are required (the observed t statistic and the degrees of freedom) for a two-tailed t test. The optional argument tails = "one" plots a one-tailed test plot (the tail is on the left or right, depending on the sign of the t statistic).

Usage

plotttest(
  t,
  df = t$parameter,
  tails = "two",
  blank = FALSE,
  xmax = "auto",
  title = "t Test",
  xlabel = "t",
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colormiddle = "aliceblue",
  colorsides = "firebrick3",
  colormiddlecurve = "black",
  colorsidescurve = "black",
  colorcut = "black",
  colorplabel = colorsides,
  theme = "default",
  signifdigitst = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)
plotttest(
  t,
  df = t$parameter,
  tails = "two",
  blank = FALSE,
  xmax = "auto",
  title = "t Test",
  xlabel = "t",
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colormiddle = "aliceblue",
  colorsides = "firebrick3",
  colormiddlecurve = "black",
  colorsidescurve = "black",
  colorcut = "black",
  colorplabel = colorsides,
  theme = "default",
  signifdigitst = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)

Arguments

`t`	A numeric value indicating the observed t statistic. Alternatively, you can pass an object of class `htest` created by the function `t.test()` or `cor.test()`.
`df`	A numeric value indicating the degrees of freedom. This argument is optional if you are using an `htest` object as the `t` argument.
`tails`	A character that indicates whether to plot a one (`"one"`) or two (`"two"`) tailed t-test (optional). By default, a two-tailed test is plotted.
`blank`	A logical that indicates whether to hide (`blank = TRUE`) the test statistic value, p value and cutline. The corresponding colors are actually only made transparent when `blank = TRUE`, so that the output is scaled exactly the same (this is useful and especially intended for step-by-step explanations).
`xmax`	A numeric including the maximum for the x-axis. Defaults to `"auto"`, which scales the plot automatically (optional).
`title`	A character or expression indicating a custom title for the plot (optional).
`xlabel`	A character or expression indicating a custom title for the x axis (optional).
`ylabel`	A character or expression indicating a custom title for the y axis (optional).
`fontfamily`	A character indicating the font family of all the titles and labels (e.g. `"serif"` (default), `"sans"`, `"Helvetica"`, `"Palatino"`, etc.) (optional).
`colormiddle`	A character indicating the color for the "middle" area under the curve (optional).
`colorsides`	A character indicating the color for the "side(s)" area(s) under the curve (optional).
`colormiddlecurve`	A character indicating the color for the "middle" part of the curve (optional).
`colorsidescurve`	A character indicating the color for the "side(s)" part of the curve (optional).
`colorcut`	A character indicating the color for the cut line at the observed test statistic (optional).
`colorplabel`	A character indicating the color for the label of the p-value (optional). By default, for color consistency, this color is the same as color of `colorright`.
`theme`	A character indicating one of the predefined color themes. The themes are `"default"` (light blue and red), `"blackandwhite"`, `"whiteandred"`, `"blueandred"`, `"greenandred"` and `"goldandblue"`) (optional). Supersedes `colormiddle` and `colorsides` if another argument than `"default"` is provided.
`signifdigitst`	A numeric indicating the number of desired significant figures reported for the t label (optional).
`curvelinesize`	A numeric indicating the size of the curve line (optional).
`cutlinesize`	A numeric indicating the size of the cut line(s) (optional). By default, the size of the curve line is used.
`p_value_position`	A numeric vector of length 2, indicating the x and y coordinates of the p-value label. By default, the position is set to `"auto"`. Note that the absolute value is used, and the sign is ignored. The position is set to the right if the test statistic value is positive, to the left if the test statistic value is negative, and on both sides if a two tailed test is plotted.

Value

A plot with the density of probability of t under the null hypothesis, annotated with the observed test statistic and the p-value.

Author(s)

Nils Myszkowski <[email protected]>

Examples

#Making a t test plot with a t value of 2 and df of 10
plotttest(t = 2, df = 10)

#The same plot without the t or p value
plotttest(2,10, blank = TRUE)

#Plotting a one-tailed test using the "tails" parameter.
plotttest(t = 2, df = 10, tails = "one")

#Using t.test() as an input
test <- t.test(rnorm(10), rnorm(10))
plotttest(test)

#Using cor.test() as an input
test <- cor.test(rnorm(10), rnorm(10))
plotttest(test)

#Making a t test plot with a t value of 2 and df of 10
plotttest(t = 2, df = 10)

#The same plot without the t or p value
plotttest(2,10, blank = TRUE)

#Plotting a one-tailed test using the "tails" parameter.
plotttest(t = 2, df = 10, tails = "one")

#Using t.test() as an input
test <- t.test(rnorm(10), rnorm(10))
plotttest(test)

#Using cor.test() as an input
test <- cor.test(rnorm(10), rnorm(10))
plotttest(test)

Illustrate a one- or two-tailed z test graphically.

Description

This function plots the density probability distribution of a z statistic, with appropriate vertical cutlines at the z value. The p-value and the observed z value are plotted. Although largely customizable, only one argument is required (the observed z statistic) for a two-tailed z test. The optional argument tails = "one" plots a one-tailed test plot (the tail is on the left or right, depending on the sign of the z statistic).

Usage

plotztest(
  z,
  tails = "two",
  blank = FALSE,
  xmax = "auto",
  title = "z test",
  xlabel = "z",
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colormiddle = "aliceblue",
  colorsides = "firebrick3",
  colormiddlecurve = "black",
  colorsidescurve = "black",
  colorcut = "black",
  colorplabel = colorsides,
  theme = "default",
  signifdigitsz = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)
plotztest(
  z,
  tails = "two",
  blank = FALSE,
  xmax = "auto",
  title = "z test",
  xlabel = "z",
  ylabel = "Density of probability\nunder the null hypothesis",
  fontfamily = "serif",
  colormiddle = "aliceblue",
  colorsides = "firebrick3",
  colormiddlecurve = "black",
  colorsidescurve = "black",
  colorcut = "black",
  colorplabel = colorsides,
  theme = "default",
  signifdigitsz = 3,
  curvelinesize = 0.4,
  cutlinesize = curvelinesize,
  p_value_position = "auto"
)

Arguments

`z`	A numeric value indicating the observed z statistic.
`tails`	A character that indicates whether to plot a one (`"one"`) or two (`"two"`) tailed z-test (optional). By default, a two-tailed test is plotted.
`blank`	A logical that indicates whether to hide (`blank = TRUE`) the test statistic value, p value and cutline. The corresponding colors are actually only made transparent when `blank = TRUE`, so that the output is scaled exactly the same (this is useful and especially intended for step-by-step explanations).
`xmax`	A numeric including the maximum for the x-axis. Defaults to `"auto"`, which scales the plot automatically (optional).
`title`	A character or expression indicating a custom title for the plot (optional).
`xlabel`	A character or expression indicating a custom title for the x axis (optional).
`ylabel`	A character or expression indicating a custom title for the y axis (optional).
`fontfamily`	A character indicating the font family of all the titles and labels (e.g. `"serif"` (default), `"sans"`, `"Helvetica"`, `"Palatino"`, etc.) (optional).
`colormiddle`	A character indicating the color for the "middle" area under the curve (optional).
`colorsides`	A character indicating the color for the "side(s)" area(s) under the curve (optional).
`colormiddlecurve`	A character indicating the color for the "middle" part of the curve (optional).
`colorsidescurve`	A character indicating the color for the "side(s)" part of the curve (optional).
`colorcut`	A character indicating the color for the cut line at the observed test statistic (optional).
`colorplabel`	A character indicating the color for the label of the p-value (optional). By default, for color consistency, this color is the same as color of `colorright`.
`theme`	A character indicating one of the predefined color themes. The themes are `"default"` (light blue and red), `"blackandwhite"`, `"whiteandred"`, `"blueandred"`, `"greenandred"` and `"goldandblue"`) (optional). Supersedes `colormiddle` and `colorsides` if another argument than `"default"` is provided.
`signifdigitsz`	A numeric indicating the number of desired significant figures reported for the z label (optional).
`curvelinesize`	A numeric indicating the size of the curve line (optional).
`cutlinesize`	A numeric indicating the size of the cut line(s) (optional). By default, the size of the curve line is used.
`p_value_position`	A numeric vector of length 2, indicating the x and y coordinates of the p-value label. By default, the position is set to `"auto"`. Note that the absolute value is used, and the sign is ignored. The position is set to the right if the test statistic value is positive, to the left if the test statistic value is negative, and on both sides if a two tailed test is plotted.

Value

Returns a plot with the density of probability of z under the null hypothesis, annotated with the observed z statistic and the p-value.

Author(s)

Nils Myszkowski <[email protected]>

Examples

#Making a z test plot with a z value of 2.
plotztest(2)

#The same plot without the z or p value
plotztest(2, blank = TRUE)

#Plotting a one-tailed test using the "tails" parameter.
plotztest(z = 2, tails = "one")

#Making a z test plot with a z value of 2.
plotztest(2)

#The same plot without the z or p value
plotztest(2, blank = TRUE)

#Plotting a one-tailed test using the "tails" parameter.
plotztest(z = 2, tails = "one")

Package 'nhstplot'

Help Index

Illustrate a χ2\chi^2χ2 test graphically.

Description

Usage

Arguments

Value

Author(s)

Examples

Illustrate an F Test graphically.

Description

Usage

Arguments

Value

Author(s)

Examples

Illustrate a one- or two-tailed t test graphically.

Description

Usage

Arguments

Value

Author(s)

Examples

Illustrate a one- or two-tailed z test graphically.

Description

Usage

Arguments

Value

Author(s)

Examples

Illustrate a $\chi^2$ test graphically.