[0.1 draft] [guide 15 · spec 15 pages]

guide/charts

Charts (chart)

Once columns have types and roles, suggesting how to look at them is one line:

txtab

# column name=category type=string role=dimension
# column name=amount type=decimal role=measure agg=sum unit=USD
# column name=date type=date role=time
# chart type=bar name=top_categories x=category y=amount sort=desc limit=10
# chart type=line name=amount_over_time x=date y=amount
# chart type=arc name=spend_share theta=amount color=category hole=0.5

A chart is a suggestion, not a command: "these columns are meant to be seen together, like this". Ignore it and the file is just as valid.

  • type is the mark: bar, line, area, point, arc (pie/donut), rect (heatmap), boxplot, sparkline, …
  • name lets a tool pick one chart among several.
  • Channels (x, y, color, theta, size, …) name columns of the same table. count() means "number of rows": x=category y=count().
  • Modifiers adjust one chart: aggregate=avg, bin=20 for a histogram, stack=1, sort=desc, limit=10, title="…".

Orientation follows the columns: x=<dimension> y=<measure> draws vertical bars, swap them for horizontal.

For anything the compact form can't say, there's an escape hatch with a full Vega-Lite spec:

txtab

# chart-vega {"mark":"arc","encoding":{"theta":{"field":"amount","aggregate":"sum","type":"quantitative"},"color":{"field":"category","type":"nominal"}}}

In a terminal

Charts are drawable as plain text — in a terminal, a CI log, a diff, a model's context window:

bash

txtab chart data.txtab --table orders --name top_categories

Charts belong to one table. Charts across tables aren't defined yet.

guide/charts.md on GitHub