f_scan: Perform a visual check on your data

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

Perform a visual check on your data

Description

Creates a 3-panel diagnostic dashboard to check data distribution and assumptions. It can also output a data summary table and identify outliers.

Usage

f_scan(x, ...)

## S3 method for class 'formula'
f_scan(formula, data = NULL, ...)

## S3 method for class 'numeric'
f_scan(x, ...)

## S3 method for class 'integer'
f_scan(x, ...)

## S3 method for class 'data.frame'
f_scan(
  x,
  columns = NULL,
  group_vars = NULL,
  summary = TRUE,
  outliers = TRUE,
  coef = 1.5,
  limit_columns = 7,
  fancy_names = NULL,
  advice = FALSE,
  close_generated_files = FALSE,
  open_generated_files = interactive(),
  output_type = "default",
  save_as = NULL,
  save_in_wdir = FALSE,
  digits = NULL,
  ...
)

Arguments

x	A data.frame or formula (dispatches to the right method).
...	Further arguments forwarded to f_scan.data.frame.
formula	A formula specifying the columns (right hand side) to be summarized by maximal 3 groups (left hand side). More columns or groups can be added using - or + (e.g., col1 + col2 ~ group1 + group2) to do a sequential summary for each column parameter.
data	A 'data.frame', 'data.table', or 'tibble'.
columns	The numerical column(s) to summarize if no formula is used. Can be entered as a single character string (e.g., "weight") or as a character vector c("weight", "length"). When omitted, defaults to all numeric columns in data (excluding any columns named in group_vars).
group_vars	Character vector of up to 3 grouping variables (e.g., c("species", "fertilizer")).
summary	Logical. Show a summary table of the data. Default is TRUE.
outliers	Logical. If TRUE, scans for outliers using Tukey's fences and if they exist, adds them to the result object. Default TRUE.
coef	Numeric. The multiplier for the Interquartile Range (IQR) used for outlier detection. Default 1.5.
limit_columns	Integer or NULL. Defines the number of columns shown in the outlier table. Default = 7. NULL = all columns are shown.
fancy_names	Named character vector or NULL. Optional mapping of column names to more readable names for display in plots and legends.
advice	Logical. If TRUE, runs f_stat_wizard() on each response column and appends the recommendation to the result. The advice is accessible via result[["column_name"]]$advice and is printed automatically. Default FALSE.
close_generated_files	Logical. Closes open Excel or Word (NOT pdf) files before writing, depending on the output format. Works on Windows (taskkill), macOS (pkill) and Linux (pkill/soffice). Default FALSE. WARNING: Always save your work before using this option!!
open_generated_files	Logical. Whether to open the generated output files after creation. Defaults to TRUE in an interactive R session and FALSE otherwise (e.g. in scripts or automated pipelines). Set to TRUE or FALSE to override this behaviour explicitly.
output_type	Character string specifying the output format. Default is "default". "default": Returns the object and lets R decide whether to print; auto-prints if unassigned, silent if assigned to a variable. Use print(result) or plot(result) to display the returned object. "console": Forces immediate printing to the console regardless of object assignment. "pdf", "word", "excel": Saves results to a file of the corresponding format. See save_as, save_in_wdir, and open_generated_files for file path and opening behavior. "rmd": Stores the raw markdown string inside the returned object for use in R Markdown documents.
save_as	Character string specifying the output file path (without extension). If a full path is provided, output is saved to that location. If only a filename is given, the file is saved in tempdir(). If only a directory is specified (providing an existing directory with trailing slash), the file is named "dataname_fscan" in that directory. If an extension is provided the output format specified with option "output_type" will be overruled. Defaults to file.path(tempdir(), "dataname_fscan.pdf").
save_in_wdir	Logical. If TRUE, saves the file in the working directory. Default is FALSE, this avoid unintended changes to the global environment. If save_as location is specified save_in_wdir is overwritten by save_as.
digits	Integer. Decimal places for printed tables in 'pdf' and 'Word' output files. Default 3.

Details

f_scan automatically adapts the visualization based on the number of grouping variables provided:

• 0 groups: Univariate analysis (Single density/boxplot).

• 1 group : Main grouping variable (X-axis and Color).

• 2 groups: Adds Facet Wrapping.

• 3 groups: Adds Facet Grid (Row vs Column).

This function requires [Pandoc](https://github.com/jgm/pandoc/releases/tag) (version 1.12.3 or higher), a universal document converter.

• Windows: Install Pandoc and ensure the installation folder.
  (e.g., "C:/Users/your_username/AppData/Local/Pandoc") is added to your system PATH.

• macOS: If using Homebrew, Pandoc is typically installed in "/usr/local/bin". Alternatively, download the .pkg installer and verify that the binary's location is in your PATH.

• Linux: Install Pandoc through your distribution's package manager (commonly installed in "/usr/bin" or "/usr/local/bin") or manually, and ensure the directory containing Pandoc is in your PATH.

• If Pandoc is not found, this function may not work as intended.

Value

A list of class f_scan containing plots, the summary table, and the outlier table. Using the option "output_type", it can also generate output in the form of: R Markdown code, 'Word', 'pdf', or 'Excel' files. Includes print, summary and plot methods for 'f_scan' objects.

Examples

# 1. Non-formula | No groups | Default output (default)
result <- f_scan(iris, columns = "Sepal.Length")
print(result)

# 2. Non-formula | 1 group | Console output
result <- f_scan(
  mtcars,
  columns   = "mpg",
  group_vars = "cyl",
  output_type = "console"
)


# 3. Non-formula | 2 groups | Multiple columns | Excel output
 result <- f_scan(
   mtcars,
   columns    = c("mpg", "hp"),
   group_vars = c("cyl", "am"),
   outliers   = TRUE,
   coef       = 1.5,
   output_type = "excel",
   save_as    = "mtcars_scan"
 )

# 4. Formula | 1 group | Strict outlier detection | Word output
result <- f_scan(
  Sepal.Width ~ Species,
  data        = iris,
  outliers    = TRUE,
  coef        = 3.0,
  output_type = "word",
  save_as     = "iris_scan"
 )

# 5. Formula | 2 groups | Multiple columns | Fancy names
result <- f_scan(
 mpg + hp + wt ~ vs + am,
 data        = mtcars,
 fancy_names = c(mpg = "Fuel Efficiency", hp = "Horsepower",
                 wt  = "Weight",          vs = "Engine Type",
                 am  = "Transmission"),
 summary     = TRUE
)
print(result)


#Create a small reproducible dataset with 3 grouping variables
set.seed(42)
plant_data <- data.frame(
  weight    = c(rnorm(60, 10, 2), rnorm(60, 14, 2)),
  species   = rep(c("A", "B"), each = 60),
  treatment = rep(rep(c("control", "treated"), each = 30), 2),
  batch     = factor(rep(c("1", "2", "3"), 40))
 )

# 6. Formula | 3 groups | Facet Grid
result <- f_scan(
  weight ~ species + treatment + batch,
  data         = plant_data,
  coef         = 2.0,
  digits       = 2,
  output_type  = "word"
)
print(result)

# 7. With statistical advice
result <- f_scan(
  Sepal.Length ~ Species,
  data    = iris,
  advice  = TRUE
)
#' print(result)
result[["Sepal.Length"]]$advice$y_type


# 8. Vector input | Single numeric vector (no formula, no data.frame)
# When you only have loose vectors in your workspace, pass one
# directly to f_scan(). The vector's name is used as the column label
# in the dashboard and outlier table.
disp1 <- mtcars$disp
result <- f_scan(disp1)
print(result)

# 9. Formula on vectors | Multiple responses | One grouping vector
# f_scan() also accepts a formula built from bare vectors, i.e.
# no `data =` argument is needed. Multiple
# response variables are combined with `+` on the
# left hand side of the formula, exactly as
# in the data.frame form.
disp1 <- mtcars$disp
hp1   <- mtcars$hp
cyl1  <- factor(mtcars$cyl)
result <- f_scan(disp1 + hp1 ~ cyl1)
print(result)

# 10. Positional vector form: equivalent to f_scan(disp1 ~ cyl1).
# The first vector is the response, the rest are grouping variables.
disp1 <- mtcars$disp
cyl1  <- factor(mtcars$cyl)
f_scan(disp1, cyl1)

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