visstat: Wrapper for visstat_core Allowing Three Different Input Styles

Description

visstat() is a wrapper around visstat_core that provides three input styles and dispatches to one of four analysis routes. Route 1 handles a numeric response with a categorical predictor. By default, Route 1 uses residual-based assumption diagnostics: the Shapiro--Wilk test gates mean-based versus rank-based analysis, and the Levene test then gates equal-variance versus Welch-type mean tests. Above 5000 observations, where shapiro.test() is undefined, the Anderson--Darling test takes over as the residual-normality gate. If the group sizes are unbalanced, the largest group standard deviations occur in the smallest groups, and the selected route is the equal-variance test or a rank-based test, the default route warns and points at group_test = "welch", because those two routes can exceed the nominal significance level in that configuration. Alternatively, group_test = "welch" keeps Route 1 on the mean scale and forces Welch-type tests, while group_test = "rank" forces Wilcoxon/Kruskal--Wallis rank tests. Route 2 handles ordered responses with Wilcoxon/Kruskal--Wallis tests. Route 3 handles two numeric variables with linear regression by default, or Spearman correlation when correlation = TRUE. Route 4 handles two unordered factors with Pearson's \(\chi^2\) test or Fisher's exact test.

Usage

visstat(
  x,
  y,
  ...,
  data = NULL,
  conf.level = 0.95,
  correlation = FALSE,
  numbers = TRUE,
  minpercent = 0.05,
  group_test = NULL,
  graphicsoutput = NULL,
  plotName = NULL,
  plotDirectory = getwd()
)

Value

An object of class "visstat" containing the results of the automatically selected statistical test. The specific contents depend on which test was performed. Additionally, the returned object includes two attributes:

plot_paths: Character vector of file paths where plots were saved (if graphicsoutput was specified)
captured_plots: List of captured plot objects for programmatic access

In case of insufficient data, returns a list with an error element and basic input summary information.

Arguments

x: For the formula interface: a formula of the form y ~ x, where y is the response variable and x is the predictor or grouping variable (requires data argument). For the standardised form: a vector of class "numeric", "integer", or "factor" representing the predictor or grouping variable. For the backward-compatible form: a data.frame containing the relevant columns.
y: For the formula interface: not used (variables are extracted from the formula). For the standardised form: a vector of class "numeric", "integer", or "factor" representing the response variable. For the backward-compatible form: a character string specifying the name of the response variable column in x.
...: Named graphical arguments are forwarded to the plots selected by the analysis route for all three input forms. Only in the backward-compatible form, the first unnamed extra argument must specify the predictor or grouping column name in x. Ignored otherwise.
data: A data.frame containing the variables specified in the formula. Required when using the formula interface. Ignored for other input styles.
conf.level: Confidence level for statistical inference; default is 0.95.
correlation: Logical. If FALSE (default), performs simple linear regression analysis with confidence and prediction bands when both variables are numeric. If TRUE, performs Spearman correlation analysis with trend line only (no regression interpretation).
numbers: Logical. Whether to annotate plots with numeric values.
minpercent: Number between 0 and 1 indicating minimal fraction of total count data of a category to be displayed in mosaic count plots.
group_test: Optional character. For a numeric response and factor predictor, NULL keeps the default assumption gates, "welch" forces Welch-type mean tests, but still displays the assumption-diagnostic plot and warns when residual normality is rejected, whereas "rank" forces Wilcoxon/Kruskal-Wallis rank tests without assessing the assumptions.
graphicsoutput: Saves plot(s) of type "png", "jpeg", "pdf", "svg", "ps" or "tiff" in directory specified in plotDirectory. If NULL, no plots are saved. Any other value is not supported by Cairo(): it triggers a warning, no file is written, and no plot_paths attribute is returned.
plotName: Graphical output is stored following the naming convention "plotName.graphicsoutput" in plotDirectory. Without specifying this parameter, plotName is automatically generated following the convention "statisticalTestName_varsample_varfactor".
plotDirectory: Specifies directory where generated plots are stored. Default is current working directory.

Details

This wrapper supports three input formats:

(1) Formula interface: visstat(y ~ x, data = df), where the formula specifies the response (y) and predictor (x) variables, and data is a data frame containing these variables.

(2) Standardised form: visstat(x, y), where both x and y are vectors of class "numeric", "integer", or "factor". Here x is the predictor or grouping variable and y is the response variable.

(3) Backward-compatible form: visstat(dataframe, "name_of_y", "name_of_x"), where the first character string refers to the response variable and the second to the predictor or grouping variable. Both must be column names in dataframe. This form gives a warning and may be removed in a future version.

The interpretation of x and y depends on the variable classes. Throughout, data of class numeric or integer are referred to as numeric, while data of class factor are referred to as categorical:

If one variable is numeric and the other a factor, the numeric vector is the response (y) and the factor is the grouping variable (x). This is Route 1: residual normality and residual variance diagnostics select between Student/Welch mean tests and Wilcoxon/Kruskal--Wallis rank tests, unless group_test explicitly forces "welch" or "rank".

If both variables are numeric, a linear model is fitted with y as the response and x as the predictor, unless correlation = TRUE, which requests Spearman rank correlation.

If both variables are factors, unordered factors enter the Pearson-\(\chi^2\)/Fisher exact association route. Ordered responses with categorical predictors are analysed as rank-based group comparisons; if both variables are ordered and correlation = TRUE, Kendall's \(\tau_b\) is used.

This wrapper standardises the input and calls visstat_core, which selects and executes the appropriate test with visual output and assumption diagnostics.

The Q-Q envelopes in the assumption diagnostics are simulated (see qq_lm_envelope). The number of simulated refits is taken from the option visStatistics.qq_nsim and defaults to 5000. As visstat() has no corresponding argument, this option is the only way to change it here; lower it to trade precision for speed, for instance options(visStatistics.qq_nsim = 1000L). Use vis_lm_assumptions or qq_lm_envelope directly if you prefer to set the number of refits per call.

Examples

Run this code

old_qq_nsim <- getOption("visStatistics.qq_nsim")
options(visStatistics.qq_nsim = 100L)

# Formula interface
mtcars$am <- as.factor(mtcars$am)
visstat(mpg ~ am, data = mtcars)

# Standardised usage
visstat(mtcars$am, mtcars$mpg)

## Student's t-test (equal variances, two groups)
# When residuals are normally distributed and Levene's test indicates
# homoscedasticity, the classic Student's t-test with pooled variance is used
df <- droplevels(subset(PlantGrowth, group %in% c("ctrl", "trt1")))
visstat(df$group, df$weight)

## Welch's t-test (unequal variances, two groups)
# When residuals are normally distributed but Levene's test indicates
# heteroscedasticity, Welch's t-test is used
visstat(mtcars$am, mtcars$mpg)

## Wilcoxon rank sum test (non-normal, two groups)
# When residuals are not normally distributed
grades_gender <- data.frame(
  Sex = as.factor(c(rep("Girl", 20), rep("Boy", 20))),
  Grade = c(
    19.3, 18.1, 15.2, 18.3, 7.9, 6.2, 19.4, 20.3, 9.3, 11.3,
    18.2, 17.5, 10.2, 20.1, 13.3, 17.2, 15.1, 16.2, 17.3, 16.5,
    5.1, 15.3, 17.1, 14.8, 15.4, 14.4, 7.5, 15.5, 6.0, 17.4,
    7.3, 14.3, 13.5, 8.0, 19.5, 13.4, 17.9, 17.7, 16.4, 15.6
  )
)
visstat(grades_gender$Sex, grades_gender$Grade)

## Fisher's ANOVA (equal variances, >2 groups)
# When residuals are normally distributed and Levene's test indicates
# homoscedasticity, classic Fisher's ANOVA with TukeyHSD post-hoc is used.
# Different green letters indicate significant differences between groups.
visstat(PlantGrowth$group, PlantGrowth$weight)

## Welch's one-way ANOVA (unequal variances, >2 groups)
set.seed(123)
values <- c(rnorm(20, 10, 1), rnorm(20, 15, 5), rnorm(20, 12, 2))
groups <- factor(rep(c("A", "B", "C"), each = 20))
visstat(groups, values)
## Kruskal-Wallis (non-normal, >2 groups)
# When residuals are not normally distributed, kruskal.test() is followed by
# pairwise.wilcox.test.
visstat(iris$Species, iris$Petal.Width)

## Simple linear regression (both numeric)
visstat(trees$Height, trees$Girth, conf.level = 0.99)

## Pearson's Chi-squared test (both factors, large expected counts)
HairEyeColorDataFrame <- counts_to_cases(as.data.frame(HairEyeColor))
visstat(HairEyeColorDataFrame$Eye, HairEyeColorDataFrame$Hair, cex = 0.7)

## Fisher's exact test (both factors, small expected counts)
HairEyeColorMaleFisher <- HairEyeColor[, , 1]
blackBrownHazelGreen <- HairEyeColorMaleFisher[1:2, 3:4]
blackBrownHazelGreen <- counts_to_cases(as.data.frame(blackBrownHazelGreen))
visstat(blackBrownHazelGreen$Eye, blackBrownHazelGreen$Hair)

## Save PNG
visstat(blackBrownHazelGreen$Hair, blackBrownHazelGreen$Eye,
        graphicsoutput = "png", plotDirectory = tempdir())

## Custom plot name
visstat(iris$Species, iris$Petal.Width,
        graphicsoutput = "pdf", plotName = "kruskal_iris", plotDirectory = tempdir())

options(visStatistics.qq_nsim = old_qq_nsim)