gog 0.0.3

A Grammar of Graphics — one engine, spoken from Python

gog for Python

Draw a plot by describing it. You name a table, a shape to draw, and which column goes to which part of the picture. gog turns that description into an SVG.

One engine, written in Rust, does the drawing for R, Python, Julia and JavaScript. Each language writes the plot in its own idiom and gets back the same picture, to the byte.

Why you might want this

One vocabulary instead of a hundred chart types. There is no histogram() to look up, and no arguments that belong to it alone. The whole vocabulary fits on one page, and the combinations are the chart types: a histogram is bar * bin, a bar shape plus a binning statistic. Keep the statistic and change the shape, and the same counts draw a line, an area or a step. You learn the words once and they keep working.

It says no, and says what to write instead. Ask for something the grammar cannot mean and you get a refusal that names the fix. Nothing is accepted and then quietly dropped, so a plot that draws is a plot that means what you wrote.

The same picture from four languages. A colleague working in R, Julia or JavaScript writes the same sentence in their own idiom and gets the same file, to the byte. A team that does not share a language can still share a plot.

A plot is data, not code. What you build is a description that the engine draws, so it can be saved, compared, generated by another program, or sent over a network. That is awkward when a plot is a live object inside a session.

Things that usually need a second package are already here — three dimensions, animation, circular layouts, treemaps and contour maps are part of the same vocabulary rather than add-ons with a syntax of their own.

Install

pip install gog

The wheel carries the drawing engine, so there is nothing else to install and no Rust toolchain to set up.

Your first plot

from gog import *

gm = {"gdp": [1000, 8000, 30000],
      "life": [52, 68, 79],
      "continent": ["Africa", "Asia", "Europe"]}

(data(gm) + point + x(col.gdp, scale="log") + y(col.life)
 + color(col.continent)).save("life.svg")

Read that aloud: "Given gm: points, x is gdp on a log scale, y is life, color by continent." That is the whole idea. A plot is a sentence, and you can say it before you can write it.

A table is a dict of columns, or anything with .columns and df[name] — a pandas or polars frame works, and neither is required.

What you can draw

Shapes — points, lines, bars, areas, steps, error bars, boxes, ribbons, text, paths, reference lines, shaded regions, and surfaces in three dimensions.

Ways to show a column — position, color, size, shape, texture, transparency, or a split into one series per group.

Statistics, written into the sentence — binning, counting, sums, averages, medians, ranges, smoothing curves and density estimates. You do not calculate them beforehand.

Arrangements — small multiples in rows or columns, several plots on one page, a circular layout, a third dimension, and animation over a column.

There are no chart-type functions. A histogram is bar * bin, a pie is a bar chart in a circle, and a violin is a density drawn as a ribbon. Learn the words once and they combine.

When a plot cannot be drawn, gog says so and names what to write instead. It never quietly ignores part of what you asked for.

Two things Python needs

A column is col.name. Python has no bare names, and here a plain string is a value, as in style(color="tomato"). Writing x("gdp") is refused, with the correct spelling named. Use col["life exp"] for a name with a space in it.

from gog import * replaces five builtins — bin, sum, min, max and range are statistics here. If you need the originals in the same file, use import gog and write gog.point, or take one back with from builtins import sum.

Examples

The manual is a book, and every plot in it is drawn by the engine while the page is being built. Nothing in it is a screenshot.

https://psychometrician.github.io/gog-book/

It is written in R, and every sentence translates by the two rules above. The book's Python chapter is the difference list, about a page long.

License

Apache License 2.0. See LICENSE and NOTICE, which ship inside the package.