Interface Lab
Login
Back to knowledge
Data Visualization

Visualization Transform Provenance

Charts must record filter, aggregate, bin, timeUnit, join, missing-value, and sorting logic; otherwise users cannot audit why the chart looks the way it does.

data-transformprovenancechartsdashboard

Design Principle

Data-visualization trust comes not only from graphics but also from an explainable transform chain. Every aggregation, filter, and derived field should be traceable.

Large Theory

The same raw data can produce very different chart conclusions after filter, aggregate, bin, timeUnit, join, stack, sort, and missing-value handling. If an agent-generated dashboard only saves the final array or SVG, future maintainers cannot know whether the correct time window was used, whether null became zero, or whether the wrong dimension was aggregated. Visualization entries need transform provenance just like code.

Small Points

  1. Filters record field, condition, default value, user-visible state, and URL/query state; hidden filters damage trust.
  2. Aggregation records groupBy, measure, function, count/sum/avg/median/max/min, weighting, and deduplication.
  3. Bin/timeUnit changes reading granularity; daily, weekly, and monthly aggregation must state timezone and week-start day.
  4. Missing value should not casually become zero; distinguish unknown, not applicable, zero, filtered out, and data delayed.
  5. Sort implies priority, so sort field, direction, and tie-breaker should be explainable.
  6. Frontend library spec, SQL, API parameters, and chart copy should share the same transform definition.

Design Judgment

A chart is auditable when nearby UI or details explain where the data came from, how it was filtered and aggregated, when it was updated, which values are missing, and how user filters affect results. A chart whose transform chain cannot be explained should not drive decisions.

Implementation Notes

Create a transform record for each chart: source, query/filter, groupBy, aggregate, bin/timeUnit, calculated fields, join, missingValuePolicy, sort, sampleSize, updatedAt, owner, specHref, and validation notes. When using Vega-Lite or Observable Plot, preserve the readable spec. For hand-written D3/React charts, write transforms as testable pure functions and expose a short methodology in the UI.

Counterexamples/Risks

The API returns pre-aggregated data but the frontend does not know the definition, null values are broken lines or zeros with no explanation, filter URL and chart data disagree, year-over-year calculation crosses time zones incorrectly, unstable sort tie-breakers make screenshots jump, and exported CSV does not match the chart data.

Case Study

Vega-Lite documents view-level transforms and encoding field transforms, including aggregate, filter, bin, timeUnit, sort, and stack. Observable Plot focuses on tabular data and exploratory analysis through marks, scales, and a layered grammar. The reusable lesson is that transforms should be readable specs or testable functions so charts can be reviewed, reproduced, and safely modified by agents.

Source Links

Vega-Lite Transformation: https://vega.github.io/vega-lite/docs/transform.html Vega-Lite Aggregate: https://vega.github.io/vega-lite/docs/aggregate.html Vega-Lite Filter: https://vega.github.io/vega-lite/docs/filter.html Observable Plot What is Plot: https://observablehq.com/plot/what-is-plot USWDS Data Visualizations: https://designsystem.digital.gov/components/data-visualizations/

Agent Directive

Before generating charts, output transform provenance covering filter, aggregate, timeUnit/bin, missing value, sort, and source; do not save only the final graphic or style.