f_stat_wizard: Statistical Test Wizard

In rfriend: Provides Batch Functions and Visualisation for Basic Statistical Procedures

Statistical Test Wizard

Description

Analyzes your data structure based on a formula and recommends the appropriate statistical test. Checks variable types, normality of residuals, homogeneity of variance, and checks if f_boxcox transformation can fix non-normality. Recommends rfriend functions as primary code, with base R alternatives shown as fallback.

Supports standard formulas including y ~ ., y ~ as.factor(x), and interaction terms. Formulas with random effects (e.g. (1|ID)) are detected and handled separately. Multivariate responses (e.g. cbind(y1, y2) ~ x) and transformed responses (e.g. log(y) ~ x) are not supported.

Usage

f_stat_wizard(x, ...)

## S3 method for class 'formula'
f_stat_wizard(
  formula,
  data,
  id_col = NULL,
  run = FALSE,
  plots = FALSE,
  output_type = "word",
  interactive = FALSE,
  data_name = NULL,
  ...
)

## S3 method for class 'data.frame'
f_stat_wizard(
  x,
  formula,
  id_col = NULL,
  run = FALSE,
  plots = FALSE,
  output_type = "word",
  interactive = FALSE,
  data_name = NULL,
  ...
)

Arguments

x	A formula (e.g., y ~ x) or a data frame. When a formula is provided, data must also be supplied. When a data frame is provided, formula must be supplied as the second argument.
...	Additional arguments (currently unused).
formula	A formula specifying the relationship (used with the data.frame method).
data	A data frame containing the variables referenced in the formula.
id_col	Character string. Name of the column identifying subjects/blocks for paired or repeated-measures designs. When supplied, the wizard (a) verifies the pairing structure (each subject should appear in every group exactly once), (b) treats the design as paired/repeated measures, and (c) embeds the real column name into the generated code. Omit for independent-samples designs. Default NULL.
run	Logical. If TRUE, the wizard attempts to execute the recommended rfriend function and stores the result in $run_result. Only works for unambiguous single-function recommendations (not multi-step or external packages). Default FALSE.
plots	Logical. If TRUE, generates diagnostic plots using f_hist() (histogram of the response) and f_qqnorm() (QQ-plot of model residuals). Plots are stored in the result as $histogram and $qqplot (recordedplot objects) and displayed by the print method. Default FALSE.
output_type	Character string specifying the output format of the recommended rfriend function (when run=TRUE) and the displayed code strings. Passed through to f_aov(), f_t_test(), f_glm(), etc. Valid values match those of the underlying function ("word", "pdf", "excel", "console", "default", "rmd"). Default "word".
interactive	Logical. If TRUE, asks the user questions about study design. Default FALSE.
data_name	Character string to name the data base used. Default NULL, which automatically derives the data name from the data frame used as input.

Value

An object of class "f_stat_wizard": a list containing:

formula

The formula used.

formula_text

Character string of the formula.

data_name

Name of the data object as passed by the user.

n

Effective sample size (after NA removal).

n_dropped

Number of rows removed due to missing values.

paired

Logical. Whether a paired/repeated-measures design was detected (via id_col).

id_col

Character. Name of the subject/block column supplied, or NULL.

y_var

Name of the response variable.

y_type

Detected type of the response: "binary", "count", "multinomial", "ratio_normal", "ratio_non_normal", "ratio_unknown", or "unsupported".

x_vars

Character vector of explanatory variable names.

x_types

Character vector of detected types ("nominal", "ordinal", "ratio").

n_groups

Number of groups (for single categorical X), or NULL.

group_sizes

Table of per-group sample sizes, or NULL.

is_ancova

Logical. TRUE if the model mixes nominal and ratio predictors.

has_interaction

Logical. TRUE if interaction terms were detected.

normality

A list with p_value (Shapiro-Wilk) and is_normal (logical or NA).

variance

A list with test_used ("Levene" or "Bartlett"), p_value, and is_equal (logical).

boxcox

A list with attempted (logical), can_fix (logical), and p_value_after (numeric or NA).

overdispersion

A list with is_overdispersed (logical, from DHARMa dispersion test) and p_value. Only meaningful for count data.

recommended_call

A language object representing the rfriend function call, or NULL if no single function could be determined.

run_result

The result of executing the recommended test (when run=TRUE), or NULL.

histogram

A recordedplot from f_hist() (when plots=TRUE), or NULL.

qqplot

A recordedplot from f_qqnorm() of model residuals (when plots=TRUE and Y is continuous), or NULL.

report

Character vector of the human-readable report lines (used by print.f_stat_wizard).

Examples

# Formula interface (recommended)
f_stat_wizard(Sepal.Length ~ Species, data = iris)

# Data-first interface (backward compatible)
f_stat_wizard(iris, Sepal.Length ~ Species)

# Paired design -- supply the id_col that identifies matched subjects
f_stat_wizard(extra ~ group, data = sleep, id_col = "ID")

# With diagnostic plots
f_stat_wizard(Sepal.Length ~ Species, data = iris, plots = TRUE)

# Run the recommended test directly
result <- f_stat_wizard(Sepal.Length ~ Species, data = iris, run = TRUE)
result$run_result

# Inspect metadata
result <- f_stat_wizard(Sepal.Length ~ Species, data = iris)
result$y_type
result$normality
result$group_sizes

rfriend documentation built on July 7, 2026, 1:06 a.m.