viz
The viz collection draws charts from tables, maps from rasters and vector layers, and renders reports to HTML and PDF. Every block runs without network and produces the same bytes from the same inputs, so a rerun with nothing changed hits the cache all the way down.
Charts🔗
| Block | Description |
|---|---|
viz.histogram | Distribution of a numeric column |
viz.bar | A value per category, stacked or grouped |
viz.line | A value over an ordered column, one line per group |
viz.scatter | Two numeric columns, with an optional trend line |
viz.box | Distribution per category |
viz.heatmap | A value over two categories |
viz.vegalite | Any Vega-Lite chart, from a spec |
The typed charts take a table and a few column names. Each also outputs the Vega-Lite spec it built: when you need something the form does not offer, take that spec, edit it, and render it with viz.vegalite -- or have ai.viz write one.
A spec for viz.vegalite names its data the way SQL does -- {"data": {"name": "t0"}} for the first connected table -- and gets data from the connected tables only. Specs with data.url, inline data.values, image marks or links are refused before anything renders.
Every chart renders as png, svg, or html (a static page with the SVG inline; it runs no script and loads nothing).
Maps🔗
| Block | Description |
|---|---|
viz.raster_map | A raster as a map: one band with a colour map, or three as RGB, optionally over a hillshade |
viz.raster_histogram_plot | The distribution of a raster band's values |
viz.choropleth | Vector features shaded by a column, in classes |
viz.raster_map reads the raster at the size it will be drawn -- from its overviews when it has them -- so a statewide mosaic needs memory for the picture, not the data. gdal.add_overviews upstream makes that read cheap.
Galleries🔗
Inside a map, a chart block runs once per item. Gather the charts with a reduce:
| Block | Description |
|---|---|
viz.contact_sheet | A labelled grid of the charts, one PNG |
viz.pages | The charts one per page, as a PDF |
Each chart is labelled with its item's key -- the state, the year -- with no extra wiring. Use ${item.key} in a chart's title to label the charts themselves.
Reports🔗
| Block | Description |
|---|---|
viz.report_html | Render a report to sanitized, self-contained HTML |
viz.report_pdf | Print that HTML to PDF |
A report is a directory: report.md (Markdown with tables; no HTML), optionally specs/<name>.vl.json charts and stats.json named statistics. It is written by ai.report or by you, and the data it cites comes from a base.bundle.
- Numbers come from statistics.
{{stat:mean_biomass}}in the text is replaced by the value of a query instats.json, run by the renderer over the bundle's tables -- so every number in the report traces to a computation. - Figures are
for an image in the bundle, orfor a chart inspecs/. Any other image -- a path, a URL -- fails the render. - The page is safe to open. HTML in the Markdown is shown as text, the result is sanitized, every image is inline, and the page loads nothing from anywhere. The PDF is printed from that same page.
See Writing reports for a walk-through.
Installation🔗
spade install file:///path/to/blocks/vizviz.vegalite
Render a Vega-Lite spec over the connected tables.
Read →viz.histogram
Histogram of a numeric column.
Read →viz.bar
Bar chart of a value per category.
Read →viz.line
Line chart of a value over an ordered column (time, distance, year).
Read →viz.scatter
Scatter plot of two numeric columns, with an optional trend line.
Read →viz.box
Box plot of a value per category.
Read →viz.heatmap
Heat map of a value over two category columns.
Read →viz.raster_map
Draw a raster as a map: one band with a colour map, or three bands as RGB, optionally over a hillshade.
Read →viz.raster_histogram_plot
Draw the distribution of a raster band's values.
Read →viz.choropleth
Shade vector features by a column's value, in classes.
Read →viz.contact_sheet
Lay a collection of PNG charts out in a labelled grid.
Read →viz.pages
Put a collection of PNG charts one per page into a PDF.
Read →viz.report_html
Render a report -- report.md, specs/ and stats.json, from ai.report or written by hand -- to sanitized, self-contained HTML.
Read →viz.report_pdf
Print a report from viz.report_html to PDF.
Read →