viz.md

viz

Generate interactive charts (bar, line, scatter, histogram, box, pie, heatmap, candlestick/ohlc, sankey, radar) and an auto-dashboard (viz smart) from CSV data using plotly. viz smart "automagically" picks an appropriate chart per column from the dataset's statistics & frequency distributions (box plots for continuous columns from precomputed quartiles; frequency bars for low-cardinality/boolean columns; a correlation heatmap when there are 2+ eligible continuous numeric columns). Outputs self-contained, interactive HTML (works offline) - or static PNG/SVG/PDF/JPEG/WebP with the viz_static feature - and can --open the result in your browser.

Table of Contents | Source: src/cmd/viz.rs | 🪄👆

Description | Examples | Usage | Viz Options | Smart Options | Common Options

Description ↩

Generate charts from CSV data using the plotly charting library.

Produces a self-contained, interactive HTML chart (the plotly.js runtime is embedded, so the output works offline). With a qsv build that includes the viz_static feature, charts can also be exported as static PNG/SVG/PDF/JPEG/WebP images (this requires a Chromium/Firefox browser at runtime - a webdriver is auto-managed by plotly).

The output format is inferred from the --output file extension (.html is the default). Interactive HTML is written to stdout when --output is not given; image formats always require --output. Use --open to view the result in your default browser/viewer.

Chart types (subcommands):
smart Auto-dashboard. Picks an appropriate chart per column from the dataset's statistics & frequency distribution (no --x/--y needed). bar Bar chart. --x = category column, --y = value column. line Line chart. --x = x column, --y = y column. scatter Scatter plot. --x = x column, --y = y column. histogram Distribution. --x = numeric column to bin. box Box plot. --y = value column, optional --x = group column. pie Proportions. --x = label column, optional --y = value column. heatmap Color grid. Correlation matrix of numeric columns (default; an optional column subset via --cols), or a category x category pivot with --x/--y/--z. candlestick Financial OHLC. --x = date column, plus --ohlc-open/--high/--low/--close. ohlc Financial OHLC bars (same inputs as candlestick). sankey Flow diagram. --source, --target, optional --value column. radar Polar/radar chart of numeric --cols, optional --series per trace.

qsv viz smart builds a one-page dashboard of subplots by reusing qsv's stats and frequency caches: continuous numeric columns become box plots (drawn from precomputed quartiles, so no data is re-scanned), and low-cardinality / boolean columns become frequency bar charts. ID-like (near-unique) and all-empty columns are skipped. When the dataset has two or more continuous numeric columns, a correlation heatmap panel is added (this one panel does a single extra data pass to compute Pearson correlations). The first run computes & caches stats; subsequent runs are fast.

Examples ↩

Auto-dashboard for a dataset, opened in the browser

qsv viz smart data.csv --open

Auto-dashboard, at most 6 panels in a 3-column grid, top-5 categories per bar

qsv viz smart data.csv --max-charts 6 --grid-cols 3 --limit 5 -o dashboard.html

Bar chart of fruit prices, opened in the browser

qsv viz bar fruits.csv --x Fruit --y Price --title "Fruit prices" --open

Aggregate (sum) sales by region into a bar chart

qsv viz bar sales.csv --x region --y amount --agg sum -o sales.html

Scatter plot with a separate series (trace) per category

qsv viz scatter data.csv --x age --y income --series gender -o scatter.html

Histogram of a numeric column with 30 bins

qsv viz histogram data.csv --x value --bins 30 -o hist.html

Box plot of a value column grouped by a category, exported to PNG (needs viz_static)

qsv viz box data.csv --y measurement --x group -o box.png

Pie chart of category proportions (counts), as a donut

qsv viz pie data.csv --x category --donut -o pie.html

Correlation heatmap over all numeric columns

qsv viz heatmap data.csv -o corr.html

Heatmap pivot: average value per (region x product)

qsv viz heatmap sales.csv --x region --y product --z amount -o pivot.html

Candlestick chart from a date column and OHLC price columns

qsv viz candlestick prices.csv --x date --ohlc-open open --high high --low low --close close -o ohlc.html

Sankey flow diagram of source -> target weighted by value

qsv viz sankey flows.csv --source from --target to --value weight -o sankey.html

Radar chart comparing numeric metrics, one trace per team

qsv viz radar teams.csv --cols speed,power,range,accuracy --series team -o radar.html

For more examples, see tests.

Usage ↩

qsv viz smart       [options] <input>
qsv viz bar         [options] <input>
qsv viz line        [options] <input>
qsv viz scatter     [options] <input>
qsv viz histogram   [options] <input>
qsv viz box         [options] <input>
qsv viz pie         [options] <input>
qsv viz heatmap     [options] <input>
qsv viz candlestick [options] <input>
qsv viz ohlc        [options] <input>
qsv viz sankey      [options] <input>
qsv viz radar       [options] <input>
qsv viz --help

Viz Options ↩

Option	Type	Description	Default
‑x, ‑‑x	string	Column for the x-axis / category / bin / group.
‑y, ‑‑y	string	Column for the y-axis / value.
‑z, ‑‑z	string	Value column for a heatmap pivot (with --x and --y).
‑‑cols	string	Columns to use. For heatmap: numeric columns for the correlation matrix (default: all numeric). For radar: the numeric axes to plot.
‑‑series	string	Column to split into multiple series (one trace per distinct value). Applies to bar/line/scatter/radar.
‑‑donut	flag	Render a pie chart as a donut (with a center hole).
‑‑ohlc‑open	string	Open-price column for candlestick/ohlc charts.
‑‑high	string	High-price column for candlestick/ohlc charts.
‑‑low	string	Low-price column for candlestick/ohlc charts.
‑‑close	string	Close-price column for candlestick/ohlc charts.
‑‑source	string	Source node column for a sankey diagram.
‑‑target	string	Target node column for a sankey diagram.
‑‑value	string	Flow value column for a sankey diagram. When omitted, each row counts as a flow of 1.
‑‑bins	integer	Number of bins for the histogram. (default: auto)
‑‑agg	string	For bar/line, aggregate the y values when the x value repeats. One of: sum, mean, count, min, max.

Smart Options ↩

Option	Type	Description	Default
‑‑max‑charts	integer	Maximum number of panels in the dashboard. 0 (the default) means auto: draw as many panels as the data warrants. For HTML that's every eligible column (up to 64); for static image export (png/svg/pdf/...) it's 8. Up to 8 panels render as one subplot grid (plotly's typed subplot-axis limit); HTML beyond 8 switches to an inline-div grid of independent plots. Set a positive to cap the panel count instead. Eligible columns beyond the cap are reported but not drawn.	0
‑‑grid‑cols	integer	Number of columns in the dashboard grid.	2
‑‑limit	integer	Top-N categories per frequency bar chart.	10
‑‑title	string	Chart title.
‑‑x‑title	string	X-axis title. (defaults to the x column name)
‑‑y‑title	string	Y-axis title. (defaults to the y column name)
‑‑width	integer	Image width in pixels for static export. Default 1000; for smart, auto-scaled to the grid's column count.
‑‑height	integer	Image height in pixels for static export. Default 600; for smart, auto-scaled to the number of panel rows.
‑‑scale	float	Image scale factor (static export).	1.0
‑‑open	flag	Open the generated chart in the default browser/viewer.

Common Options ↩

Option	Type	Description	Default
‑h, ‑‑help	flag	Display this message
‑o, ‑‑output	string	Write output to instead of stdout. The chart format is inferred from the extension: .html (default), .png, .svg, .pdf, .jpeg, .webp.
‑d, ‑‑delimiter	string	The field delimiter for reading CSV data. Must be a single character. (default: ,)
‑n, ‑‑no‑headers	flag	When set, the first row will not be interpreted as headers. Columns can then only be selected by index.

---

Source: src/cmd/viz.rs | Table of Contents | README