---
title: "normality"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{normality}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup}
library(normality)
```
# 1. Overview
The `normality` R package provides a collection of statistical tools for assessing whether a
sample is consistent with a normal distribution. It includes:
- empirical distribution function (EDF)-based tests;
- moment-based tests;
- Shapiro-family tests;
- skewness and kurtosis assessments;
- high-level automatic normality assessment
# 2. Installation
Install the released version from [CRAN](https://cran.r-project.org/package=normality):
```{r eval=FALSE}
install.packages("normality")
```
or the development version from [GitHub](https://github.com/P10911004-NPUST/normality):
```{r eval=FALSE}
if (!require("pak")) install.packages("pak")
pak::pak("P10911004-NPUST/normality")
```
Then load the package:
```{r}
library(normality)
# For reproducibility
set.seed(123)
```
# 3. Quick start
The simplest way to assess a numeric vector is with `is_normal()`.
```{r}
x <- rnorm(30)
is_normal(x)
```
For a more detailed result:
```{r}
is_normal(x, summary = TRUE)
```
**If you only require a quick check for data normality, use `is_normal` and feel free to skip the
remainder of this guide.**
For explicit test selection, use `check_normality()`:
```{r}
check_normality(x, method = "SWR")
```
# 4. Understanding normality testing
Most formal normality tests use:
$$H_0: X \sim N(\mu, \sigma^2)$$
versus
$$H_1: X \not\sim N(\mu, \sigma^2)$$
A small p-value provides evidence against normality. A large p-value indicates that the test did
not detect sufficient evidence of departure from normality.
A large p-value does **not** prove that the data are normally distributed.
Different tests are sensitive to different forms of departure. For example, skewness-based
procedures focus on asymmetry, kurtosis-based procedures focus on tail weight, and EDF
procedures compare the empirical and theoretical distributions.
# 5. Available tests
| Method | Function | Sample-size |
| - | ---------- | ---- |
| AD | `Anderson_Darling_test()` | ≥ 8 |
| CVM | `Cramer_von_Mises_test()` | ≥ 8 |
| LF | `Lilliefors_test()` | ≥ 8 |
| DAP | `D.Agostino_Pearson_test()` | ≥ 20 |
| JB | `Jarque_Bera_test()` | ≥ 20 |
| SW | `Shapiro_Wilk_test(method = "SW")` | 3--50 |
| SF | `Shapiro_Wilk_test(method = "SF")` | 5--5000 |
| SWR | `Shapiro_Wilk_test(method = "SWR")` | 3--5000 |
## 5.1. Anderson--Darling test
The Anderson--Darling test is an EDF-based goodness-of-fit test that places greater emphasis on
discrepancies in the tails.
```{r}
ad <- Anderson_Darling_test(x)
```
The summary table is available with:
```{r}
ad$summary
```
## 5.2. Cramér--von Mises test
The Cramér--von Mises test is also EDF-based and evaluates discrepancies throughout the distribution.
```{r}
cvm <- Cramer_von_Mises_test(x)
```
Conceptually, Anderson--Darling emphasizes the tails more strongly, whereas Cramér--von Mises
gives more uniform weight to discrepancies.
## 5.3. Lilliefors test
The Lilliefors test is an EDF-based procedure derived from the Kolmogorov--Smirnov framework and
adapted for testing normality when the population mean and standard deviation are estimated from
the sample.
```{r}
lf <- Lilliefors_test(x)
```
## 5.4. D'Agostino--Pearson test
The D'Agostino--Pearson test is an omnibus moment-based test combining information from skewness
and kurtosis.
```{r}
dap <- D.Agostino_Pearson_test(x)
```
The `alternative` argument can be used for component skewness and kurtosis assessments:
```{r eval=FALSE}
D.Agostino_Pearson_test(x, alternative = "two.sided")
```
## 5.5. Jarque--Bera test
The Jarque--Bera test is another moment-based omnibus normality test.
```{r}
jb <- Jarque_Bera_test(x)
```
## 5.6. Shapiro-family tests
The Shapiro-family tests are generally the most powerful. However, they are limited by ties in
the data and provide no numerical indication of the nature of non-normality as a by-product
([D’Agostino, 1986](https://doi.org/10.1201/9780203753064); Section 9.5).
`Shapiro_Wilk_test()` provides three related procedures:
- `SW`: Shapiro--Wilk;
- `SF`: Shapiro--Francia;
- `SWR`: Shapiro--Wilk with Royston's modifications (default).
### Original Shapiro--Wilk
```{r}
sw <- Shapiro_Wilk_test(x, method = "SW")
```
### Shapiro--Francia
```{r}
sf <- Shapiro_Wilk_test(x, method = "SF")
```
### Shapiro--Wilk with Royston's modifications
```{r}
# Equivalent to Shapiro_Wilk_test(x)
swr <- Shapiro_Wilk_test(x, method = "SWR")
```
### Very large samples
The Shapiro-family procedures have finite sample-size limits in their direct implementations. `Shapiro_Wilk_test()` applies an re-sampling mechanism by default for observations above the
maximum supported sample size.
```{r eval=FALSE}
x_large <- rnorm(10000)
Shapiro_Wilk_test(x_large, resampling = TRUE)
```
# 6. Testing multiple groups
The high-level functions support data frames and formulas.
```{r}
data("iris")
check_normality(iris, Sepal.Length ~ Species, method = "SWR")
```
The formula has the form:
```text
response ~ group
```
The same interface is available in `is_normal()`:
```{r}
out <- is_normal(iris, Sepal.Length ~ Species, summary = TRUE)
```
For samples fewer than 8 observations, the automatic assessment relies on Shapiro--Wilk--Royston.
For samples from 8 through 19 observations, it combines:
- Shapiro--Wilk--Royston;
- skewness; and
- Anderson--Darling.
For samples of at least 20 observations, it combines:
- Shapiro--Wilk--Royston;
- D'Agostino--Pearson; and
- Anderson--Darling.
The `sensitivity` argument controls how many component assessments must support normality.
Its allowed range is 1 to 3. A larger value makes the criterion more conservative.
```{r}
set.seed(123)
x1 <- c(rnorm(20), runif(10))
for (i in 1:3)
{
res <- is_normal(x1, sensitivity = i)
print(sprintf("When sensitivity is %i: %s", i, res))
}
```
# 7. Skewness
The `skewness()` function assesses distributional asymmetry. Three estimators (`G1`, `b1`, `g1`)
are available ([Joanes & Gill, 1998](https://doi.org/10.1111/1467-9884.00122),
[Wright & Herrington, 2011](https://doi.org/10.3758/s13428-010-0044-x)).
```{r}
skewness(x, method = "G1")
skewness(x, method = "b1")
skewness(x, method = "g1")
```
# 8. Kurtosis
The `kurtosis()` function assesses tail-related distributional characteristics. Three estimators
(`G2`, `b2`, `g2`) are available ([Joanes & Gill, 1998](https://doi.org/10.1111/1467-9884.00122),
[Wright & Herrington, 2011](https://doi.org/10.3758/s13428-010-0044-x)).
```{r}
kurtosis(x, method = "G2")
kurtosis(x, method = "b2")
kurtosis(x, method = "g2")
```
# 9. Interpreting results
**If a test produces a p-value of 0.12**, the appropriate conclusion is:
> The test did not provide sufficient evidence to reject the null hypothesis of normality.
**If the p-value is 0.003:**
> The test provided evidence against the assumption of normality.
The next step should be to investigate the nature and practical importance of the departure.
# Summary
The **normality** package provides a unified toolkit for assessing departures from normality.
The main functions are:
- `is_normal()` for high-level automatic assessment;
- `check_normality()` for selecting a specific normality test;
- `Shapiro_Wilk_test()` for Shapiro-family procedures;
- `Anderson_Darling_test()` for tail-sensitive EDF testing;
- `Cramer_von_Mises_test()` for overall EDF discrepancy;
- `Lilliefors_test()` for KS-type normality assessment;
- `D.Agostino_Pearson_test()` and `Jarque_Bera_test()` for moment-based tests;
- `skewness()` for distributional asymmetry; and
- `kurtosis()` for tail-related characteristics.
Formal tests are most informative when considered together with sample size, graphical diagnostics,
and the assumptions of the statistical method that will subsequently be applied.
# References
Anderson, T.W., & Darling, D.A. (1954). A test of goodness of fit.
*Journal of the American Statistical Association*, 49, 765--769.
D'Agostino, R.B. (1986). Goodness-of-Fit-Techniques (1st ed.). Routledge.
D'Agostino, R.B., Belanger, A., & D'Agostino, R.B. (1990). A suggestion for using powerful
and informative tests of normality. *The American Statistician*, 44, 316--321.
Jarque, C.M., & Bera, A.K. (1987). A test for normality of observations
and regression residuals. *International Statistical Review*, 55, 163--172.
Joanes, D.N., Gill, C.A. (1998). Comparing measures of sample skewness and kurtosis.
*Journal of the Royal Statistical Society: Series D (The Statistician)*, 47, 183–189.
Molin, P. & Abdi, H. (1998). New table and numerical approximations for
Kolmogorov-Smirnov/Lilliefors/Van Soest normality test. Technical report, University of Bourgogne.
Royston, P. (1992). Approximating the Shapiro--Wilk W-test for non-normality.
*Statistics and Computing*, 2, 117--119.
Royston, P. (1993). A pocket-calculator algorithm for the Shapiro--Francia test for non-normality:
an application to medicine. *Statistics in Medicine*, 12, 181--184.
Shapiro, S.S. & Francia, R.S. (1972). An approximate analysis of variance test for normality.
*Journal of the American Statistical Association*, 67, 215--216.
Shapiro, S.S. & Wilk, M.B. (1965). An analysis of variance test for normality (complete samples).
*Biometrika*, 52, 591--611.
Thode, H.C. (2002). Testing For Normality (1st ed.). CRC Press.
Wright, D.B. & Herrington, J.A. (2011).
Problematic standard errors and confidence intervals for skewness and kurtosis.
*Behavior Research Methods*, 43, 8–17.