| Title: | Rule-Based Quality Checks for 'ggplot2' Visualizations Based on the 25 Golden Rules of Data Visualization |
|---|---|
| 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. |
| Authors: | Wajdi Ben Saad [aut, cre] (ORCID: <https://orcid.org/0000-0002-0939-016X>) |
| Maintainer: | Wajdi Ben Saad <[email protected]> |
| License: | AGPL (>= 3) |
| Version: | 0.1.0 |
| Built: | 2026-10-04 09:59:36 UTC |
| Source: | https://github.com/wajdibensaad/goldenviz_r |
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.
analyze_plot(plot)analyze_plot(plot)
plot |
A |
A goldenviz_report object. See goldenviz_report for the report
schema and status definitions.
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") }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") }
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.
goldenviz_check_rules(info = list())goldenviz_check_rules(info = list())
info |
A named list produced by a plot inspection layer. Missing fields
are allowed. Common fields include plot labels ( |
A data frame with columns id, family, rule, status, and
message. Exactly 25 rows are returned.
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.
# 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", ]# 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", ]
A goldenviz_report is the structured result returned by analyze_plot().
It is a list with stable top-level fields intended for programmatic use.
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-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.
Returns the current 25-rule structure used by GoldenViz, grouped into Completeness, Readability, and Integrity.
goldenviz_rules()goldenviz_rules()
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.
rules <- goldenviz_rules() rules split(rules[, c("id", "rule")], rules$family)rules <- goldenviz_rules() rules split(rules[, c("id", "rule")], rules$family)
Render a GoldenViz report as HTML
render_report(report, include_passed = TRUE)render_report(report, include_passed = TRUE)
report |
A |
include_passed |
Whether passed checks should be included. |
An htmltools browsable tag object.
Save a GoldenViz report as standalone HTML
save_report(report, path = "goldenviz-report.html", include_passed = TRUE)save_report(report, path = "goldenviz-report.html", include_passed = TRUE)
report |
A |
path |
Output HTML path. |
include_passed |
Whether passed checks should be included. |
Invisibly returns path.
View a GoldenViz report
view_report(report, include_passed = TRUE)view_report(report, include_passed = TRUE)
report |
A |
include_passed |
Whether passed checks should be included. |
Invisibly returns the rendered report.