Package {GoldenVizR}

Type:	Package
Title:	Rule-Based Quality Checks for 'ggplot2' Visualizations Based on the 25 Golden Rules of Data Visualization
Version:	0.1.0
Description:	Quality-checking tools for reviewing R data visualizations built with the 'ggplot2' library against the 25 GoldenViz rules described at https://goldenviz.org/. The package provides a visual QA and teaching layer that helps users identify common chart clarity, readability, and integrity issues.
License:	AGPL (≥ 3)
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 4.1)
Imports:	ggplot2, htmltools
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, roxygen2
VignetteBuilder:	knitr
Config/testthat/edition:	3
URL:	https://github.com/WajdiBenSaad/GoldenViz_R
BugReports:	https://github.com/WajdiBenSaad/GoldenViz_R/issues
Config/Needs/website:	pkgdown
Config/Needs/development:	lintr, styler
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-07-21 12:24:45 UTC; dix
Author:	Wajdi Ben Saad [aut, cre]
Maintainer:	Wajdi Ben Saad <wajdi@goldenviz.org>
Repository:	CRAN
Date/Publication:	2026-07-30 16:40:08 UTC

Analyze a ggplot object with GoldenViz

Description

Analyze a ggplot object and return structured GoldenViz feedback. The current implementation returns a plot-level summary and 25 ordered heuristic rule results with status counts.

Usage

analyze_plot(plot)

Arguments

Value

A goldenviz_report object. See goldenviz_report for the report schema and status definitions.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  p <- ggplot2::ggplot(
    mtcars,
    ggplot2::aes(wt, mpg, colour = factor(cyl))
  ) +
    ggplot2::geom_point() +
    ggplot2::labs(
      title = "Fuel economy by weight",
      subtitle = "Motor Trend cars",
      x = "Weight",
      y = "Miles per gallon",
      colour = "Cylinders",
      caption = "Source: mtcars"
    )

  report <- analyze_plot(p)
  report$summary
  subset(report$rule_results, status != "PASS")
}

Run GoldenViz heuristic rule checks

Description

Evaluates the 25 GoldenViz rules using a lightweight inspection list. The function is intentionally tolerant of missing fields: rules that cannot be assessed from the supplied info return INFO rather than failing.

Usage

goldenviz_check_rules(info = list())

Arguments

Value

A data frame with columns id, family, rule, status, and message. Exactly 25 rows are returned.

Status values

Rule statuses are:

• PASS: the supplied info satisfied the rule.

• WARNING: a potential issue was detected.

• FAIL: a stronger integrity or accessibility issue was detected.

• INFO: the rule could not be assessed from the supplied info.

Examples

# Advanced use: provide an inspection-like list directly.
# Most users should call analyze_plot() instead.
checks <- goldenviz_check_rules(list(
  title = "Fuel economy by weight",
  x_label = "Weight",
  y_label = "Miles per gallon",
  missing_values = FALSE,
  text_size = 11,
  scale_truthful = TRUE,
  framing_neutral = TRUE
))

checks[checks$status != "PASS", ]

GoldenViz report objects

Description

A goldenviz_report is the structured result returned by analyze_plot(). It is a list with stable top-level fields intended for programmatic use.

Report schema

A report contains:

• plot_summary: a named list of plot metadata, including labels, layer count, geom names, data dimensions, facet class, and coordinate class.

• rule_results: a data frame with one row per GoldenViz rule and columns rule_id, family, rule, status, message, and suggestion. The rule_id column is the public rule identifier.

• status_counts: a named integer vector with counts for PASS, WARNING, FAIL, and INFO.

• summary: a one-row data frame with aggregate counts and the current report-level status.

Rule result statuses

Rule-level status values are:

• PASS: the available inspection data satisfied the rule.

• WARNING: the rule found a potential issue to review.

• FAIL: the rule found a stronger integrity or accessibility issue.

• INFO: the rule could not be assessed from the available inspection data.

Report-level summary$status values are derived from rule-level statuses: fail if any rule fails, warning if any rule warns, pending_checks if any rule remains informational, and pass otherwise.

GoldenViz rule registry

Description

Returns the current 25-rule structure used by GoldenViz, grouped into Completeness, Readability, and Integrity.

Usage

goldenviz_rules()

Value

A data frame with one row per rule and columns:

• id: stable rule identifier, currently R1 through R25.

• family: rule family, one of Completeness, Readability, or Integrity.

• rule: human-readable rule label.

Examples

rules <- goldenviz_rules()
rules

split(rules[, c("id", "rule")], rules$family)

Render a GoldenViz report as HTML

Description

Render a GoldenViz report as HTML

Usage

render_report(report, include_passed = TRUE)

Arguments

Value

An htmltools browsable tag object.

Save a GoldenViz report as standalone HTML

Description

Save a GoldenViz report as standalone HTML

Usage

save_report(report, path = "goldenviz-report.html", include_passed = TRUE)

Arguments

Value

Invisibly returns path.

View a GoldenViz report

Description

View a GoldenViz report

Usage

view_report(report, include_passed = TRUE)

Arguments

Value

Invisibly returns the rendered report.