# How GoldenVizR Checks Work

GoldenVizR checks `ggplot2` objects by reading plot metadata and built plot data. It does not inspect a rendered chart image with computer vision.

The goal is to catch common issues early and make review more systematic. The result is still heuristic: some visualization decisions require human judgment.

## Inspection pipeline

When you call `analyze_plot(plot)`, GoldenVizR:

1. Confirms that `plot` is a `ggplot2` plot.
2. Builds the plot with `ggplot2` internals so layer data can be inspected.
3. Extracts labels, titles, captions, scales, guides, layers, geoms, facets, coordinates, theme hints, and plotted data summaries.
4. Converts those observations into an inspection list.
5. Runs the 25 ordered GoldenVizR rule checks.
6. 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.