How GoldenVizR Checks Work

Inspection pipeline

When you call analyze_plot(plot), GoldenVizR:

Confirms that plot is a ggplot2 plot.
Builds the plot with ggplot2 internals so layer data can be inspected.
Extracts labels, titles, captions, scales, guides, layers, geoms, facets, coordinates, theme hints, and plotted data summaries.
Converts those observations into an inspection list.
Runs the 25 ordered GoldenVizR rule checks.
Returns a goldenviz_report with plot_summary, rule_results, status_counts, and summary.

Status logic

Each rule returns one status:

Status	Meaning
`PASS`	The available inspection data satisfied the rule.
`WARNING`	GoldenVizR found a likely issue or improvement opportunity.
`FAIL`	GoldenVizR found a stronger integrity, accessibility, scale, or encoding issue.
`INFO`	GoldenVizR did not have enough evidence to make a responsible judgment.

The report-level status is derived from the rule statuses:

Report status	How it is chosen
`fail`	At least one rule returned `FAIL`.
`warning`	No failures, but at least one rule returned `WARNING`.
`pending_checks`	No failures or warnings, but at least one rule returned `INFO`.
`pass`	All assessed rules returned `PASS`.

Evidence used by the rules

GoldenVizR uses evidence that can be read from a ggplot2 object, including:

title, subtitle, caption, axis labels, and scale labels
mapped aesthetics such as x, y, colour, fill, shape, size, and linetype
layer count, geom types, visible data rows, point count, and missing values
legend mappings, guide settings, legend titles, and legend labels
theme hints such as text size, grid visibility, and legend position
coordinate and scale hints, including zero-baseline situations
data summaries that can indicate overplotting, outliers, dense encodings, or limited context

GoldenVizR is conservative. If the plot object does not expose enough evidence, the rule should return INFO instead of pretending to know.

Current rule behavior

The table below documents the current implemented behavior. It describes the evidence GoldenVizR uses and the normal conditions that lead to each status.

Completeness

Rule	Evidence inspected	PASS	WARNING	FAIL	INFO
R1 Clear title	`title` label	PASS Title text is present.	WARNING Title field exists but is empty.	FAIL Not used.	INFO Title field is unavailable.
R2 Axis labels	`x_label`, `y_label`	PASS Both axis labels are present.	WARNING One or both labels appear missing.	FAIL Not used.	INFO Axis label fields are unavailable.
R3 Missing values and gaps	Missing-value and gap signals from built data	PASS No missing values or gaps were reported.	WARNING Missing values or gaps were found.	FAIL Not used.	INFO Missing-value information is unavailable.
R4 Legend clarity	Mapped legend aesthetics, guide settings, legend title, legend labels	PASS A legend appears to have usable title or label text.	WARNING A legend is present but lacks clear text.	FAIL Not currently used.	INFO No legend evidence is available. This can mean no legend is needed, or that the current metadata does not expose enough legend information.
R5 Source and context	Caption, subtitle-like context, source fields	PASS A caption or source/context field is present.	WARNING Not currently used.	FAIL Not used.	INFO No source/context field is available.
R6 Annotation for key message	Annotation layers and key-message need signals	PASS Annotation is present, or no annotation need was reported.	WARNING A key-message annotation appears needed but missing.	FAIL Not used.	INFO Annotation need cannot be determined.

Readability

Rule	Evidence inspected	PASS	WARNING	FAIL	INFO
R7 Readable text	Theme text size and related text metadata	PASS Text size appears readable.	WARNING Explicit text size appears small.	FAIL Not used.	INFO Text-size information is unavailable.
R8 Accessible color choices	Color count and palette accessibility signals	PASS Palette is reported accessible.	WARNING Many colors are used and should be reviewed.	FAIL Palette is reported inaccessible.	INFO Color accessibility cannot be assessed.
R9 Avoid clutter	Layer count, mark count, clutter score	PASS No high clutter signal was reported.	WARNING Many layers, marks, or clutter signals are present.	FAIL Not used.	INFO Clutter evidence is unavailable.
R10 Grid and guide balance	Gridline and guide metadata	PASS Grid/guide information appears acceptable.	WARNING Grid or guide balance may need review.	FAIL Not used.	INFO Grid/guide evidence is unavailable.
R11 Consistent formatting	Formatting consistency signal	PASS Formatting is reported consistent.	WARNING Formatting is reported inconsistent.	FAIL Not used.	INFO Formatting consistency cannot be assessed.
R12 Appropriate chart type	Geom type, mapped data, chart-type plausibility signal	PASS Chart type information appears plausible or available.	WARNING Chart type is reported potentially inappropriate.	FAIL Not used.	INFO Chart-type evidence is unavailable.
R13 Readable scale labels	Scale labels and scale readability signal	PASS Scale labels appear readable.	WARNING Scale labels are reported hard to read.	FAIL Not used.	INFO Scale-label evidence is unavailable.
R14 Overplotting management	Point count and overplotting signal	PASS No overplotting signal was reported.	WARNING Dense point layers may need transparency, aggregation, jitter, or binning.	FAIL Not used.	INFO Overplotting evidence is unavailable.
R15 Direct labeling when useful	Legend size, direct-label signal, direct-label usefulness signal	PASS Direct labels are reported.	WARNING Direct labels may improve readability.	FAIL Not used.	INFO Direct-labeling need cannot be determined.
R16 Visual hierarchy	Title/text hierarchy and hierarchy signal	PASS Visual hierarchy information is supplied and not weak.	WARNING Visual hierarchy is reported weak.	FAIL Not used.	INFO Hierarchy evidence is unavailable.

Integrity

Rule	Evidence inspected	PASS	WARNING	FAIL	INFO
R17 Truthful scale	Scale truthfulness signal	PASS Scale is reported truthful.	WARNING Not currently used.	FAIL Scale is reported potentially untruthful.	INFO Scale truthfulness cannot be assessed.
R18 No distorted baseline	Baseline requirement and zero-baseline signal	PASS Required baseline is present, or no zero baseline is required.	WARNING Not currently used.	FAIL A zero baseline appears required but missing.	INFO Baseline requirement cannot be assessed.
R19 Avoid misleading encodings	Encoding integrity signal	PASS No misleading encoding was reported.	WARNING Not currently used.	FAIL A misleading encoding was reported.	INFO Encoding integrity cannot be assessed.
R20 Handle outliers honestly	Outlier detection and outlier handling signal	PASS No outliers are reported, or outliers appear handled.	WARNING Outliers are present without handling context.	FAIL Not used.	INFO Outlier evidence is unavailable.
R21 Proportional areas	Area encoding and proportionality signal	PASS Area encoding is proportional, or no area encoding is used.	WARNING Not currently used.	FAIL Area encoding is reported non-proportional.	INFO Area-encoding evidence is unavailable.
R22 Uncertainty when needed	Uncertainty need and uncertainty layer signals	PASS Uncertainty is shown when needed, or no uncertainty need is reported.	WARNING Uncertainty appears needed but missing.	FAIL Not used.	INFO Uncertainty need cannot be assessed.
R23 Avoid cherry picking	Scale limits, data selection, and context signals	PASS No cherry-picking risk is reported, or full context is supplied.	WARNING Data selection context may be incomplete.	FAIL Not used.	INFO Data-selection context is unavailable.
R24 Respect data granularity	Data granularity and geom/data compatibility signal	PASS Data granularity is respected.	WARNING Visual form may mismatch the data granularity.	FAIL Not used.	INFO Granularity evidence is unavailable.
R25 Neutral framing	Title/subtitle wording and framing signal	PASS Framing is reported neutral.	WARNING Framing is reported non-neutral.	FAIL Not used.	INFO Framing evidence is unavailable.

How legend clarity is interpreted

Rule 4 deserves special care because legends are sometimes necessary and sometimes redundant.

GoldenVizR treats a legend as potentially needed when a variable is mapped to a legend-producing aesthetic, such as colour, fill, shape, linetype, alpha, or size. A constant setting outside aes(), such as colour = "red", does not by itself require a legend.

Current behavior:

Situation	Current likely status
No legend evidence is available	`INFO`
Legend exists and title or labels are available	`PASS`
Legend exists but no useful title or labels are available	`WARNING`

Important limitation: the current Rule 4 implementation does not yet fully judge whether a legend title such as factor(cyl) is semantically weak. That kind of wording may be technically available but still poor for readers. This is a good target for future improvement.

Why some rules return INFO

Some rules depend on evidence that is not always present in a ggplot2 object. For example, a plot object may not reveal the author’s intent, the full data collection scope, the intended audience, or whether a missing uncertainty band is scientifically required.

In those cases, GoldenVizR returns INFO rather than making a false claim.

Practical interpretation

Use the report as an early review assistant:

Start with FAIL and WARNING rows.
Review INFO rows when the chart is important or publication-facing.
Treat PASS as “no issue detected from available evidence,” not as a guarantee that the chart is perfect.
Apply human judgment for context, audience, domain meaning, and ethics.