Metadata-Version: 2.4
Name: gog
Version: 0.0.2
Summary: A Grammar of Graphics — one engine, spoken from Python
Project-URL: Homepage, https://psychometrician.github.io/gog-book/
Project-URL: Documentation, https://psychometrician.github.io/gog-book/
Project-URL: Source, https://github.com/psychometrician/gog
Project-URL: Issues, https://github.com/psychometrician/gog/issues
Author-email: psychometrician <psychometrician@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
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

```python
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][py-chapter] is the difference list, about a page long.

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE), which ship
inside the package.

[py-chapter]: https://psychometrician.github.io/gog-book/bindings/python.html
