Quickstart

Basic workflow

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

What the report contains

A GoldenVizR report is a list with four stable fields:

Inspect rules that need attention:

subset(report$rule_results, status != "PASS")

##    rule_id      family                        rule  status
## 15     R15 Readability Direct labeling when useful WARNING
##                                   message suggestion
## 15 Direct labels may improve readability.       <NA>

Manual analysis

Manual analysis means passing a specific ggplot2 object to analyze_plot() and inspecting the returned report yourself. This is useful in notebooks, teaching material, package tests, dashboards, or review workflows where you want explicit control over which chart is checked.

manual_plot <- ggplot(mtcars, aes(factor(cyl), mpg)) +
  geom_boxplot() +
  labs(
    title = "Fuel economy by cylinder count",
    x = "Cylinders",
    y = "Miles per gallon",
    caption = "Source: mtcars"
  )

manual_report <- analyze_plot(manual_plot)
manual_report$summary

##   checked_rules implemented_checks pass warning fail info  status
## 1            25                 23   22       1    0    2 warning

Inspect the full rule table:

manual_report$rule_results

##    rule_id       family                        rule  status
## 1       R1 Completeness                 Clear title    PASS
## 2       R2 Completeness                 Axis labels    PASS
## 3       R3 Completeness     Missing values and gaps    PASS
## 4       R4 Completeness              Legend clarity    INFO
## 5       R5 Completeness          Source and context    PASS
## 6       R6 Completeness  Annotation for key message    PASS
## 7       R7  Readability               Readable text    PASS
## 8       R8  Readability    Accessible color choices    PASS
## 9       R9  Readability               Avoid clutter    PASS
## 10     R10  Readability      Grid and guide balance    PASS
## 11     R11  Readability       Consistent formatting    PASS
## 12     R12  Readability      Appropriate chart type    PASS
## 13     R13  Readability       Readable scale labels    PASS
## 14     R14  Readability     Overplotting management    PASS
## 15     R15  Readability Direct labeling when useful    INFO
## 16     R16  Readability            Visual hierarchy    PASS
## 17     R17    Integrity              Truthful scale    PASS
## 18     R18    Integrity       No distorted baseline    PASS
## 19     R19    Integrity  Avoid misleading encodings    PASS
## 20     R20    Integrity    Handle outliers honestly    PASS
## 21     R21    Integrity          Proportional areas    PASS
## 22     R22    Integrity     Uncertainty when needed WARNING
## 23     R23    Integrity        Avoid cherry picking    PASS
## 24     R24    Integrity    Respect data granularity    PASS
## 25     R25    Integrity             Neutral framing    PASS
##                                             message suggestion
## 1                            Title text is present.       <NA>
## 2                     Both axis labels are present.       <NA>
## 3          No missing values or gaps were reported.       <NA>
## 4               No legend information was supplied.       <NA>
## 5          Source or contextual caption is present.       <NA>
## 6                  No annotation need was reported.       <NA>
## 7                       Text size appears readable.       <NA>
## 8        Color choices were reported as accessible.       <NA>
## 9              No high clutter signal was reported.       <NA>
## 10          Grid or guide information was supplied.       <NA>
## 11           Formatting was reported as consistent.       <NA>
## 12             Chart type information was supplied.       <NA>
## 13        Scale label information appears readable.       <NA>
## 14             No overplotting signal was reported.       <NA>
## 15           Direct-labeling need was not supplied.       <NA>
## 16       Visual hierarchy information was supplied.       <NA>
## 17                  Scale was reported as truthful.       <NA>
## 18       No zero-baseline requirement was reported.       <NA>
## 19             No misleading encoding was reported.       <NA>
## 20                       No outliers were reported.       <NA>
## 21                   No area encoding was reported.       <NA>
## 22 Uncertainty appears needed but was not reported.       <NA>
## 23             No cherry-picking risk was reported.       <NA>
## 24      Data granularity was reported as respected.       <NA>
## 25                 Framing was reported as neutral.       <NA>

Most workflows start by filtering to rows that are not PASS:

subset(manual_report$rule_results, status != "PASS")

##    rule_id       family                        rule  status
## 4       R4 Completeness              Legend clarity    INFO
## 15     R15  Readability Direct labeling when useful    INFO
## 22     R22    Integrity     Uncertainty when needed WARNING
##                                             message suggestion
## 4               No legend information was supplied.       <NA>
## 15           Direct-labeling need was not supplied.       <NA>
## 22 Uncertainty appears needed but was not reported.       <NA>

You can also inspect a specific rule family:

subset(manual_report$rule_results, family == "Integrity")

##    rule_id    family                       rule  status
## 17     R17 Integrity             Truthful scale    PASS
## 18     R18 Integrity      No distorted baseline    PASS
## 19     R19 Integrity Avoid misleading encodings    PASS
## 20     R20 Integrity   Handle outliers honestly    PASS
## 21     R21 Integrity         Proportional areas    PASS
## 22     R22 Integrity    Uncertainty when needed WARNING
## 23     R23 Integrity       Avoid cherry picking    PASS
## 24     R24 Integrity   Respect data granularity    PASS
## 25     R25 Integrity            Neutral framing    PASS
##                                             message suggestion
## 17                  Scale was reported as truthful.       <NA>
## 18       No zero-baseline requirement was reported.       <NA>
## 19             No misleading encoding was reported.       <NA>
## 20                       No outliers were reported.       <NA>
## 21                   No area encoding was reported.       <NA>
## 22 Uncertainty appears needed but was not reported.       <NA>
## 23             No cherry-picking risk was reported.       <NA>
## 24      Data granularity was reported as respected.       <NA>
## 25                 Framing was reported as neutral.       <NA>

Because the report is structured, it can be used programmatically:

any(manual_report$rule_results$status == "FAIL")

## [1] FALSE

manual_report$status_counts

##    PASS WARNING    FAIL    INFO 
##      22       1       0       2

Render an HTML report

Use render_report() when you want a formatted HTML version of the same structured review.

html_report <- render_report(report)
html_report

In an R Markdown document, the rendered report can be printed from a code chunk. To save the same report as a standalone HTML file, use save_report():

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

If your installed version includes view_report(), use it for quick local inspection:

view_report(report)

The HTML report is expected to include the same core sections as the structured object:

names(report)

## [1] "plot_summary"  "rule_results"  "status_counts" "summary"

The report can also be embedded directly inside documentation, notebooks, and HTML reports:

The main areas of the report are annotated below:

How to read statuses

GoldenVizR is intentionally heuristic. It helps catch common issues early, but it does not replace human judgment.