vizdesk

A terminal app for data visualization work. Point it at a CSV or Excel file and it will:

1. Profile every column: numbers, categories (including ordered ones such as class 1/2/3), dates, years, IDs and codes, free text, comma-separated lists, "number + unit" values such as 90 min, gaps, outliers, skew and capped values.
2. Suggest cleaning and normalization, each with a plain reason (for example "TotalCharges is stored as text and 11 values are only spaces").
3. Find the target (churn, survived, price ...) or let you pick one, and suggest charts for your goal, the way popular Kaggle EDA notebooks do: the target rate per category, a histogram of every numeric column, top-N rankings, trends, maps, hierarchies.
4. Draw PNG figures with the grid, size, DPI and padding you choose, in a colorblind-safe palette by default.
5. Save four files per figure: the PNG, a recipe to reopen and redraw it, a Python script that recreates it in a notebook, and alt text describing it.

All suggestions come from fixed rules and statistics computed on your data. No LLM and no internet connection are used.

The chart catalog (66 techniques, each with a description, the data it needs, when to use it and its limits) comes from the Data Scientists Handbook chart catalog, which is based on the Data Visualisation Catalogue (datavizcatalogue.com). vizdesk can draw all 66.

Install

Python 3.10 or newer is required (npm and Homebrew set that up for you).

Quick start

vizdesk                                   # open the terminal UI
vizdesk churn.csv                         # open the UI with a file loaded
vizdesk auto data/ --goal target --show   # no UI: every CSV/Excel file in data/ to PNGs, previewed in the terminal

The terminal UI

Your original files are never changed. Figures go to ./vizdesk-output unless you pass -o.

Command line

vizdesk catalog part whole                  # search the catalog
vizdesk catalog --show sankey_diagram       # full details of one technique
vizdesk goals                               # the goals suggestions can target
vizdesk scan churn.csv --goal target        # profile, cleaning and chart suggestions, printed
vizdesk scan housing.csv --target median_house_value

# auto: safe cleaning, top suggestions, split into 2x3 grids, no padding, 300 dpi
vizdesk auto sales.csv --goal explore --count 12 --rows 2 --cols 3 --width 15 --height 9 --dpi 300 --no-padding

# manual: choose every chart yourself
vizdesk draw sales.csv \
  --panel chart=bar_chart,x=region,y=revenue,agg=sum \
  --panel chart=sunburst_diagram,columns=Category+Sub-Category,y=Sales \
  --panel chart=line_graph,x=date,y=close,filter=Name=AAPL,rolling=50 \
  --rows 1 --cols 3 --width 18 --height 5 -o out/sales.png

# redraw: change panel 1, add a panel, widen the grid
vizdesk redraw out/sales.png --set 1:chart=violin_plot,y=revenue --add-panel chart=pie_chart,x=channel --cols 3

# preview in the terminal (Kitty, Ghostty, iTerm2, WezTerm, sixel, or coloured blocks anywhere)
vizdesk show out/sales.png

Panel fields: chart, x, y, hue (colour), size, columns=a+b+c (multi-column charts), agg (auto, count, sum, mean, median, min, max), title, top_n, bins, log_y. agg=auto sums columns whose names look like totals (sales, revenue, units ...) and averages the rest.

Any other key=value is a chart option. Options every chart understands:

Some charts read their own options, for example rolling=50 (line), reversal=4% (kagi), box=1; reversal=3 (point and figure), last=120 (candlestick), geojson=regions.geojson; key=name (maps). The Compose tab shows the options of the selected chart.

Goals

Maps appear when there are longitude and latitude columns; word charts appear for free text.

The four files of a figure

How it was checked

The rules were tuned against 7 popular Kaggle datasets (Telco churn, Titanic, California housing, Netflix, Superstore, S&P 500 stocks, Wine reviews) and the EDA charts of their top-voted notebooks. tests/test_kaggle_shapes.py keeps each fix as a regression test on a small table of the same shape, and runs on the real files too when they are in datasets/kaggle/.

Development

uv venv && uv pip install -e '.[dev]'
python examples/make_examples.py   # messy sample data
pytest

To refresh the catalog from the handbook: python scripts/build_catalog.py path/to/_chart_catalog_reference.md.

See PACKAGING.md for releasing to PyPI, npm and Homebrew.