Visualization

Visualization

Tier: Intermediate Commands covered: viz

Note

Per-command flag reference lives in /docs/help/viz.md. This page is the workflow layer — when to reach for each chart and how viz smart builds a dashboard for you.

viz turns a CSV/TSV straight into interactive Plotly charts — no notebook, no spreadsheet round-trip. Output is a self-contained HTML file (the Plotly runtime is embedded, so it works offline) written to --output or stdout. With a viz_static build you can export PNG / SVG / PDF / JPEG / WebP instead (needs a local Chrome/Firefox for Plotly's renderer). Pass --open to pop the result straight into your browser.

viz is behind the viz feature flag (✨) — it ships in the prebuilt qsv binaries but not in qsvlite or qsvdp. See Binary Variants.

Gallery

A single page rendering every chart type below, generated from the sample datasets in examples/viz/:

• ▶ View the gallery (rendered): https://raw.githack.com/dathere/qsv/master/examples/viz/gallery.html
• Raw HTML (downloads / shows source): https://raw.githubusercontent.com/dathere/qsv/master/examples/viz/gallery.html
• The datasets + a copy-paste command per chart: examples/viz/README.md

Tip

raw.githubusercontent.com serves .html as text/plain, so a browser shows the source instead of rendering it. The githack link above serves it with the correct text/html type so the charts render (it shows a one-click "External Content Notice" the first time). Avoid htmlpreview.github.io for this page — it can't load Plotly, so the charts come up blank.

Quick decision table

If you want to…	Use	Notes
A one-shot overview of an unfamiliar dataset	viz smart	Auto-picks a panel per column from the stats cache
Compare a measure across categories	viz bar	--agg sum|mean|count|min|max when x repeats
Show a trend over time / an ordered x	viz line	x is sorted numerically/temporally
Relate two numeric columns	viz scatter	optional --series to color by group
See the distribution of one numeric column	viz histogram	--bins (default auto)
Summarize spread (quartiles, outliers)	viz box	optional grouping x column
Show parts of a whole	viz pie	--donut for a ring; --y value or counts
Spot correlations across many numerics	viz heatmap	Pearson matrix (RdBu, −1…1) — no --x/--y/--z
Cross-tabulate two categories by a measure	viz heatmap	give --x, --y and --z (pivot mode)
Plot OHLC price action	viz candlestick / viz ohlc	--ohlc-open --high --low --close
Show flows between nodes	viz sankey	--source --target [--value]
Compare entities across many axes	viz radar	--cols a,b,c… + optional --series

viz smart — the auto-dashboard

smart profiles the dataset from qsv's stats cache (🪄) and lays out one panel per column in a grid:

• Correlation heatmap — a Pearson matrix when there are 2+ continuous numeric columns.
• Box plots — for continuous numeric columns (quartiles drawn straight from the cache).
• Frequency bars — for low-cardinality categoricals, booleans, and ratings.

ID-like (near-unique) and high-cardinality text columns are reported and skipped. By default the dashboard fits the data: HTML output draws every eligible column (laid out as an inline grid beyond 8 panels), while static image export is capped at 8 panels.

# auto-fit dashboard for an unfamiliar file
qsv viz smart sales_sample.csv -o dashboard.html

# cap panels, lay out 3 columns, top-5 categories per frequency bar
qsv viz smart sales_sample.csv --max-charts 6 --grid-cols 3 --limit 5 -o dashboard.html

The sample above uses sales_sample.csv (500 e-commerce orders, designed so the correlation heatmap spans the full red→blue scale).

Chart subcommands

Grab the sample datasets first:

curl -LO https://raw.githubusercontent.com/dathere/qsv/master/examples/viz/sales_sample.csv
curl -LO https://raw.githubusercontent.com/dathere/qsv/master/examples/viz/stock_prices.csv
curl -LO https://raw.githubusercontent.com/dathere/qsv/master/examples/viz/web_flows.csv
curl -LO https://raw.githubusercontent.com/dathere/qsv/master/examples/viz/product_ratings.csv

# bar — revenue by region (aggregated)
qsv viz bar sales_sample.csv --x region --y revenue --agg sum -o bar.html

# line — closing price over time
qsv viz line stock_prices.csv --x date --y close -o line.html

# scatter — units sold vs revenue
qsv viz scatter sales_sample.csv --x units_sold --y revenue -o scatter.html

# histogram — distribution of unit price
qsv viz histogram sales_sample.csv --x unit_price -o histogram.html

# box — spread of revenue
qsv viz box sales_sample.csv --y revenue -o box.html

# pie (donut) — revenue share by product category
qsv viz pie sales_sample.csv --x product_category --y revenue --donut -o pie.html

# heatmap (correlation) — Pearson matrix over all numeric columns
qsv viz heatmap sales_sample.csv -o heatmap_corr.html

# heatmap (pivot) — region x category grid of revenue (give --x, --y AND --z)
qsv viz heatmap sales_sample.csv --x region --y product_category --z revenue -o heatmap_pivot.html

# candlestick / ohlc — OHLC price action
qsv viz candlestick stock_prices.csv --x date --ohlc-open open --high high --low low --close close -o candlestick.html
qsv viz ohlc        stock_prices.csv --x date --ohlc-open open --high high --low low --close close -o ohlc.html

# sankey — session funnel (duplicate source→target pairs are aggregated)
qsv viz sankey web_flows.csv --source source --target target --value sessions -o sankey.html

# radar — multi-axis brand comparison (one polygon per --series value, per-axis mean)
qsv viz radar product_ratings.csv --cols battery,camera,performance,display,value,design --series brand -o radar.html

Note

--ohlc-open is spelled out (not --open) because --open already means "open the result in a browser".

Static image export

Any chart can be written as a static image instead of HTML — just change the extension. This needs a viz_static build (the prebuilt full binaries qualify) and a local Chrome/Firefox for Plotly's image renderer.

qsv viz scatter sales_sample.csv --x units_sold --y revenue -o scatter.png
qsv viz smart   sales_sample.csv -o overview.svg --width 1400 --height 900

See also

• docs/help/viz.md — full flag reference
• Metadata Profiling (profile) — the stats profiling viz smart builds on
• Stats Cache & Caching — why viz smart is fast
• Binary Variants — which builds include the viz feature
• Recipe: Inspect an Unknown CSV — pairs well with viz smart