Query and chart data
Summarize a table in charts: marks that count and group the source data for you, small multiples that share their scales, and gestures that ask the data again.
Tabular data
A table is a DataHandle. Bytes:csv and Bytes:parquet make one
from any bytes: a granted file, a file in your package, or a string.
DataHandle:query asks a table a question in SQL, and returns the
answer as a new DataHandle at once. In the SQL, the table is called
data. A list after the SQL fills its ? marks in order: a
DataHandle in the list stands for a table to join, and a Dir or
File for a location inside its grant.
local bytes = datumhue.bytes
local orders = bytes([[
item,qty
Bread,3
Cake,1
Bread,2
Buns,6
]]):csv()
local prices = bytes([[
item,price
Bread,2.5
Buns,1.5
Cake,4.0
]]):csv()
local sql = [[
SELECT o.item, SUM(o.qty * p.price) AS total
FROM data o JOIN ? p ON o.item = p.item
WHERE o.qty >= ?
GROUP BY o.item
ORDER BY total DESC
]]
local bill = orders:query(sql, { prices, 2 })
for _, batch in bill:batches() do
local item = batch:column("item")
local total = batch:column("total")
for i = 1, batch:len() do
print(item:get(i), total:get(i))
end
end
In this example: datumhue.bytes Bytes:csv DataHandle:query DataHandle:batches DataBatch:column
It prints Bread 12.5, then Buns 9.0: qty >= 2 leaves out the
cake, an order of one.
The query runs the first time something reads the answer, and keeps
the result for every later reader. To read an answer in Lua,
DataHandle:rows gives one table per row, and DataHandle:batches
gives the columns of a batch of rows at a time. DataHandle:schema
names the columns and their types, and DataHandle:encode_csv and
DataHandle:encode_parquet turn a table back into bytes to save.
To show a table, bind it to UiElement:table or to a chart mark
rather than reading it into Lua: they read only what they show.
Marks that summarize
Some marks summarize the data they are given. PlotArea:histogram
counts values into bins, PlotArea:histogram2d counts pairs of
numbers into a grid, PlotArea:heatmap colors a cell per pair of
categories, PlotArea:box draws each category's spread, and
PlotArea:bars sums or counts a column per category. They work on the
source data, so none of its rows passes through Lua. A zoomed
histogram bins again over the values in view.
local chart = datumhue.chart
local color = datumhue.color
-- 400 loaves, each a little over or under 800 g.
local rng = datumhue.random.new(7)
local lines = { "grams" }
for i = 2, 401 do
local spread = rng:next() + rng:next() + rng:next() - 1.5
lines[i] = string.format("%.1f", 800 + spread * 30)
end
local loaves = datumhue.bytes(table.concat(lines, "\n")):csv()
local canvas = datumhue.draw.new({})
canvas:mount({ width = "100%", height = "100%", auto_size = true })
local grams = chart.scale.linear({ nice = true })
local count = chart.scale.linear({ nice = true })
local plot = canvas:chart({
margin = { left = 56, right = 24, top = 40, bottom = 48 },
x_scale = grams,
y_scale = count,
})
plot:title({ text = "Loaf weights", font_size = 18 })
plot:axis({ scale = grams, side = "bottom", label = "grams" })
plot:axis({ scale = count, side = "left", grid = true })
plot:histogram({
data = loaves,
column = "grams",
bins = 20,
color = color("#a7c080"),
})
plot:pan_zoom({ y = false })
plot:crosshair()
In this example: datumhue.color datumhue.random.new Rng:next datumhue.bytes Bytes:csv datumhue.draw.new DrawCanvas:mount datumhue.chart.scale.linear DrawCanvas:chart PlotArea:title PlotArea:axis PlotArea:histogram PlotArea:pan_zoom PlotArea:crosshair
PlotArea:crosshair follows the pointer with guide lines and a
readout of the value under it. Chart marks draw in fixed layers, which
DrawCanvas:chart lists, so a later mark never hides an axis.
Small multiples
DrawCanvas:charts lays out a grid of plot areas on one canvas, and
returns them in reading order. Give every cell the same scale and they
stay aligned: panning or zooming one cell moves them all. Here each
oven's loaves get a cell, from one query per oven:
local chart = datumhue.chart
local color = datumhue.color
local vec3 = datumhue.math.vec3
-- 600 loaves from three ovens, each a little heavier than the last.
local ovens = { "North", "Middle", "South" }
local rng = datumhue.random.new(11)
local lines = { "oven,grams" }
for i = 1, 600 do
local n = i % 3 + 1
local spread = rng:next() + rng:next() + rng:next() - 1.5
local grams = 784 + n * 8 + spread * 24
lines[#lines + 1] = string.format("%s,%.1f", ovens[n], grams)
end
local loaves = datumhue.bytes(table.concat(lines, "\n")):csv()
local W, H = 900, 400
local canvas = datumhue.draw.new({ width = W, height = H })
canvas:mount({ width = "100%", height = "100%", fit = "contain" })
local grams = chart.scale.linear({ domain = { min = 760, max = 860 } })
local count = chart.scale.linear({ domain = { min = 0, max = 60 } })
local cells = canvas:charts({
rows = 1,
columns = 3,
pos = vec3(-W / 2, -H / 2, 0),
width = W,
height = H,
margin = { left = 40, right = 24, top = 32, bottom = 28 },
x_scale = grams,
y_scale = count,
})
local one_oven = "SELECT grams FROM data WHERE oven = ?"
for i, cell in ipairs(cells) do
cell:title({ text = ovens[i], font_size = 16 })
cell:axis({ scale = grams, side = "bottom", ticks = 4 })
cell:axis({ scale = count, side = "left", grid = true })
cell:histogram({
data = loaves:query(one_oven, { ovens[i] }),
column = "grams",
bin_width = 5,
color = color("#7fbbb3"),
})
cell:pan_zoom({ y = false })
end
In this example: datumhue.color datumhue.math.vec3 datumhue.random.new Rng:next datumhue.bytes Bytes:csv datumhue.draw.new DrawCanvas:mount datumhue.chart.scale.linear DrawCanvas:charts PlotArea:title PlotArea:axis PlotArea:histogram DataHandle:query PlotArea:pan_zoom
The canvas has a fixed size here, since the grid is laid out in canvas
units, and fit = "contain" scales it to the window.
Interaction
Gestures are calls on the plot area. PlotArea:pan_zoom,
PlotArea:crosshair and PlotArea:brush each return a handle that
changes or removes the gesture later.
PlotArea:pan_zoom: drag to pan, scroll to zoom, drag a box with the right button to zoom into it, double-click to reset.PlotArea:crosshair: guide lines and a readout under the pointer.PlotArea:brush: drag to select a range, whichon_brushreceives in data units. Run a new query on the range and give a mark the answer withMark:replace_data, and one chart filters another, as Chart the answer shows.PlotArea:on_hoverandPlotArea:on_clickreport the pointer in data units, andMark:nearestfinds the row closest to it.
To move a chart yourself, Scale:animate eases a scale to a new
domain, and Scale:on_change tells you each time a domain changes,
whoever changed it.
See also
- Load a table, the first step of a tutorial that builds a small data view.
- SQL functions, for every function a query can call.
- Open, pick and save files, for the files a table comes from.
Reference used on this page: datumhue.bytes Bytes:csv DataHandle:query DataHandle:batches DataBatch:column datumhue.color datumhue.random.new Rng:next datumhue.draw.new DrawCanvas:mount datumhue.chart.scale.linear DrawCanvas:chart PlotArea:title PlotArea:axis PlotArea:histogram PlotArea:pan_zoom PlotArea:crosshair datumhue.math.vec3 DrawCanvas:charts Bytes:parquet DataHandle:rows DataHandle:schema DataHandle:encode_csv DataHandle:encode_parquet UiElement:table PlotArea:histogram2d PlotArea:heatmap PlotArea:box PlotArea:bars PlotArea:brush Mark:replace_data PlotArea:on_hover PlotArea:on_click Mark:nearest Scale:animate Scale:on_change