# Interactive Data Visualisations

How PAIX Navigator turns a natural-language question into an interactive chart, what chart types it supports, and where to go next.

This is the hub for the visualisation feature. See also:

- **[Prompting for a plot](/prompting-for-a-plot/)** — how to ask for the chart you want.
- **[Datasets](/datasets/)** — which datasets you can explore and what each contains.

Ask a question in **Data Insight**. The agent writes SQL against the selected dataset, runs it, and - when a chart helps - renders an interactive **Plotly** figure inline. You don't pick a chart type from a menu; you describe what you want to see and the agent chooses (or you name the type in your prompt).

**12 chart types are supported**, and nothing outside that list can be produced.

## How it works

Visualisation is one step in the Dataset Explorer agent flow, not a separate mode:

```
You ask a question
      │
      ▼
DatasetExplorerAgent  ──►  ExplorerDatabaseTool   (writes + runs aggregating SQL)
      │                          │
      │                          ▼
      │                    query result (rows), held under a result_id
      ▼
ExplorerChartTool     ──►  renders a Plotly chart from that result
      │
      ▼
Interactive chart, streamed into the chat and persisted on the message
```

The chart is built from the **actual query result** - the agent names which result column fills each chart role (x-axis, series, values, …). The chart spec is persisted, so it re-renders on page reload. See the developer documentation (`docs/agentic-architecture.md` in the repository) for the full agent map.

Every chart is accompanied by an **auto-generated caption** (foldable under the figure) that records the cohort, sample sizes, data source, and any caveats - missing values, per-patient record selection, or statistical tests.

## Supported chart types

All 12 are defined in one place — the `chart_type` enum in `app/tools/explorer_chart_tool.rb` - and each is wired to a Plotly builder in `app/tools/chart_spec_builder.rb`.

| Chart type | Good for | Plotly trace |
|---|---|---|
| `bar` | Counts / values across categories | bar |
| `stacked_bar` | Composition of a whole across categories | bar (stacked) |
| `histogram` | Distribution of one numeric variable | histogram |
| `pie` | Share of a whole (few categories) | pie (donut) |
| `box` | Distribution + outliers across groups | box |
| `violin` | Distribution shape across groups | violin |
| `scatter` | Relationship between two numeric variables | scatter |
| `splom` | Pairwise relationships across 3–5 variables | splom |
| `heatmap` | A value across two categorical axes / a matrix | heatmap |
| `survival` | Kaplan–Meier survival over time, by group | scatter (step) |
| `radar` | One metric compared across several categories | scatterpolar |
| `parallel_categories` | Flow of records across categorical stages | parcats |

> The type is a **hard allow-list**. A request for a chart type outside this set (e.g. a UMAP embedding, a spatial slide overlay, a volcano plot) cannot be rendered.

Which datasets you can explore, and what each contains, lives on the dedicated **[Datasets](/datasets/)** page.

Interactive Data Visualisations

How PAIX Navigator turns a natural-language question into an interactive chart, what chart types it supports, and where to go next.

This is the hub for the visualisation feature. See also:

Prompting for a plot — how to ask for the chart you want.
Datasets — which datasets you can explore and what each contains.

Ask a question in Data Insight. The agent writes SQL against the selected dataset, runs it, and - when a chart helps - renders an interactive Plotly figure inline. You don’t pick a chart type from a menu; you describe what you want to see and the agent chooses (or you name the type in your prompt).

12 chart types are supported, and nothing outside that list can be produced.

How it works

Visualisation is one step in the Dataset Explorer agent flow, not a separate mode:

You ask a question
      │
      ▼
DatasetExplorerAgent  ──►  ExplorerDatabaseTool   (writes + runs aggregating SQL)
      │                          │
      │                          ▼
      │                    query result (rows), held under a result_id
      ▼
ExplorerChartTool     ──►  renders a Plotly chart from that result
      │
      ▼
Interactive chart, streamed into the chat and persisted on the message

The chart is built from the actual query result - the agent names which result column fills each chart role (x-axis, series, values, …). The chart spec is persisted, so it re-renders on page reload. See the developer documentation (docs/agentic-architecture.md in the repository) for the full agent map.

Every chart is accompanied by an auto-generated caption (foldable under the figure) that records the cohort, sample sizes, data source, and any caveats - missing values, per-patient record selection, or statistical tests.

Supported chart types

All 12 are defined in one place — the chart_type enum in app/tools/explorer_chart_tool.rb - and each is wired to a Plotly builder in app/tools/chart_spec_builder.rb.

Chart type	Good for	Plotly trace
`bar`	Counts / values across categories	bar
`stacked_bar`	Composition of a whole across categories	bar (stacked)
`histogram`	Distribution of one numeric variable	histogram
`pie`	Share of a whole (few categories)	pie (donut)
`box`	Distribution + outliers across groups	box
`violin`	Distribution shape across groups	violin
`scatter`	Relationship between two numeric variables	scatter
`splom`	Pairwise relationships across 3–5 variables	splom
`heatmap`	A value across two categorical axes / a matrix	heatmap
`survival`	Kaplan–Meier survival over time, by group	scatter (step)
`radar`	One metric compared across several categories	scatterpolar
`parallel_categories`	Flow of records across categorical stages	parcats

The type is a hard allow-list. A request for a chart type outside this set (e.g. a UMAP embedding, a spatial slide overlay, a volcano plot) cannot be rendered.

Which datasets you can explore, and what each contains, lives on the dedicated Datasets page.