Rule-Based Quality Checks for 'ggplot2' Visualizations Based on the 25 Golden Rules of Data Visualization

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.

GoldenVizR

GoldenVizR is an early-stage R package for reviewing data visualizations against the GoldenViz rules.

It is designed as a visual QA and teaching layer. GoldenVizR does not create charts for you; it inspects charts you already made and returns structured feedback that helps identify common problems before a chart is used in a notebook, report, dashboard, paper, or presentation.

GoldenVizR is part of the GoldenViz project. The official project site is goldenviz.org.

Why GoldenVizR exists

Generating a chart is rarely the hardest part of data visualization. The harder part is judging whether the chart is clear, honest, readable, and useful.

A chart is not finished when it renders. It is finished when a reader can understand the message quickly, trust the encoding, and spot the important pattern without unnecessary effort.

GoldenVizR turns common visualization judgment checks into repeatable feedback. The goal is not to replace the analyst or designer. The goal is to catch common mistakes early and make good visualization habits easier to apply.

What GoldenVizR checks

GoldenVizR is organized around 25 practical rules covering:

chart purpose, titles, and required context
axes, units, scales, baselines, and data encoding
readability, text, legends, labels, and visual clutter
color accessibility and deliberate use of emphasis
category handling, sorting, overplotting, uncertainty, precision, dates, and visual economy

The rules are grouped into three families:

Completeness: whether the chart includes the information a reader needs.
Readability: whether the chart can be read efficiently and without unnecessary effort.
Integrity: whether the chart represents the data honestly and avoids misleading choices.

GoldenVizR does not enforce one visual style. It encourages charts that are readable, honest, and useful.

Current status

The current implementation targets ggplot2 charts. It provides the public package structure, the 25-rule registry, a structured analyze_plot() API, and heuristic checks that inspect available plot metadata and built plot data.

The analyzer is useful for early review signals, but it is not a full visual inspection engine. For a well-described ggplot2 chart, analyze_plot() can now return implemented outcomes for all 25 rules.

Current limitations:

Checks are heuristic and metadata-based; GoldenVizR does not visually inspect rendered chart images.
Some rules are judgment-heavy; when the plot object lacks required evidence, those rules may still return INFO.
Results can include false positives or false negatives and should be reviewed by a human.
Non-ggplot2 chart objects are not supported yet.

Installation

After CRAN release, install GoldenVizR with:

install.packages("GoldenVizR")

During active development, install the development version from GitHub:

install.packages("remotes")
remotes::install_github("WajdiBenSaad/GoldenViz_R")

Development

install.packages(c("devtools", "roxygen2", "testthat", "ggplot2", "pkgdown", "lintr", "styler"))
devtools::load_all()
devtools::test()

Example

library(ggplot2)
library(GoldenVizR)

p <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
  geom_point() +
  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
#>   checked_rules implemented_checks pass warning fail info         status
#> 1            25                 25   24       1    0    0        warning

HTML reports

GoldenVizR can turn the structured output from analyze_plot() into an HTML report for notebooks, review handoffs, or local files.

report <- analyze_plot(p)

html_report <- render_report(report)
html_report

The rendered object is suitable for display in R Markdown and other htmltools-aware contexts. To write the report to disk:

save_report(report, "goldenviz-report.html")

If available in your installed version, view_report() opens a temporary HTML report for local inspection:

view_report(report)

Expected report structure:

names(report)
#> [1] "plot_summary"  "rule_results"  "status_counts" "summary"

License

GoldenVizR is free and open source software licensed under the GNU Affero General Public License version 3 or later (AGPL-3.0-or-later).

Commercial licensing, enterprise use cases, hosted services, or integrations that require terms different from AGPLv3 may be available by separate written agreement.