Charts And Figures

---
name: charts-and-figures
description: "Choose, author, and troubleshoot Vizro charts, figures, tables,
  and visual-vocabulary patterns with Plotly/Vizro APIs."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Charts and Figures

Use this sub-skill when the task asks what chart to use, how to write a Vizro/Plotly figure, how to attach a figure/table to a dashboard, or how to debug visual output.

Route elsewhere when the task is mainly about:
- Dashboard/page skeleton: `../core-dashboard-build/SKILL.md`.
- Filters/data/actions around a figure: `../core-components-data-actions/SKILL.md`.
- Deprecated AI chart-agent code: `../legacy-ai-chart-agent/SKILL.md`.

## Preferred authoring pattern

Use Vizro's Plotly Express wrappers for standard charts:

```python
import vizro.models as vm
import vizro.plotly.express as px

fig = px.scatter(
    px.data.iris(),
    x="sepal_width",
    y="sepal_length",
    color="species",
)

page = vm.Page(title="Iris", components=[vm.Graph(figure=fig)])
```

When users supply data and a visual goal, first decide chart semantics, then write code:

1. Identify measures, dimensions, time fields, categorical fields, and intended comparison.
2. Choose chart type from visual-vocabulary principles.
3. Produce a small Plotly/Vizro snippet using explicit column names.
4. Wrap it in `vm.Graph` or the relevant table/grid component.
5. Add filters/selectors only after the base figure works.

## Chart selection heuristics

- Time trend: line/area; use bars only for few discrete periods.
- Category comparison: bar/column; sort intentionally.
- Distribution: histogram/box/violin depending on whether the user needs bins, summary, or group comparison.
- Relationship/correlation: scatter/bubble; add color/facet only when it clarifies.
- Part-to-whole: stacked bar or treemap/sunburst for hierarchy; avoid pie for many categories.
- Geospatial: map only when location is the analytic dimension; otherwise avoid decorative maps.
- Table: use when exact values, sorting/filtering, or row-level inspection matters more than visual pattern.

## Custom charts

Use custom chart callables when `vizro.plotly.express` wrappers do not cover the needed figure or the chart needs reusable parameters.

Keep custom chart functions:

- Pure and deterministic over input data/arguments.
- Returning a Plotly figure or Vizro-compatible figure object.
- Small enough to test independently.
- Free of server startup, file I/O, and network calls unless explicitly required.

## Tables and grids

- Choose a table/grid when users need exact values, drill-down, sorting/filtering, or row selection.
- For action-linked graph/table behavior, route to `core-components-data-actions` after selecting the visual representation.
- Validate table model fields with `scripts/inspect_vizro_schema.py --models Table AgGrid` because table field names evolve.

## Debug checklist

- Does the DataFrame contain each referenced column with the expected dtype?
- Does the chart render outside Vizro as a plain Plotly figure?
- Is the figure passed to `vm.Graph(figure=...)`, not accidentally to a text/card/table field?
- Are color/facet/category orders explicit enough for the user's narrative?
- Are filters using the same data source/columns as the chart?
- If a chart is generated by an agent, validate/execute the code locally before embedding in a dashboard.

## Evidence anchors

- `vizro-core/src/vizro/plotly/express.py`: wrapper API surface.
- `vizro-core/src/vizro/figures/library.py`: built-in figure helpers.
- `vizro-core/src/vizro/models/types.py`: figure typing.
- `vizro-core/docs/pages/user-guides/custom-charts.md` and `table.md`.
- `vizro-core/examples/visual-vocabulary/README.md`.
- `vizro-e2e-flow/skills/selecting-vizro-charts/references/chart-best-practices.md`.