AlgebraOfGraphics.jl builds plots by composing data, mappings and layers with algebra

What the algebra actually is

AlgebraOfGraphics is an algebraic spin on the grammar of graphics idea known from R's ggplot2 package, and the whole library is built on two operators.

Visualizations are powered by Makie and you have its full capabilities available to tweak figures produced by AlgebraOfGraphics.

The building blocks are a few simple things composed using `+` and `*`. A `data` call names the source, a `mapping` assigns data columns to visual channels, a `layer` such as `linear()` or `visual(alpha = 0.3)` says what to draw, and `+` combines layers while `*` combines a specification with a mapping or a layer.

So a plot is an expression rather than a configuration object. The penguin example in the README is the whole thing.

using AlgebraOfGraphics, CairoMakie

penguins = AlgebraOfGraphics.penguins()

set_aog_theme!()
update_theme!(Axis = (; width = 150, height = 150))

spec = data(penguins) * mapping(:bill_length_mm, :bill_depth_mm)

draw(spec)

That is the shape of the whole approach. You build a specification, and you draw it.

The generator is worth noting because it is a convenience rather than a core feature. `AlgebraOfGraphics.penguins()` returns a built-in dataset, and it exists so that the README example can run without a data file, not because the library has any opinion about where your data comes from.

Adding a mapping, adding a layer, adding a facet

The example builds up one figure in four steps, and the sequence shows how the algebra composes.

Adding a mapping multiplies the existing specification by a new one, and the new mapping assigns a data column to a visual channel.

by_color = spec * mapping(color = :species)

draw(by_color)

Adding a layer uses plus, because layers are alternatives and combinations rather than a multiplication of independent things.

with_regression = by_color * (linear() + visual(alpha = 0.3))

draw(with_regression)

The parenthesised sum is the interesting part. A regression line and a translucent point cloud are two separate layers in one expression, and the alpha on the points is what keeps the line readable through them. Whether the visual channel argument names a colour or an alpha is decided by the layer, not by the mapping.

Facetting is another multiplication, with a mapping onto the column variable.

facetted = with_regression * mapping(col = :sex)

draw(facetted)

And the final draw call adds a scale specification rather than changing the data.

draw(facetted, scales(Color = (; palette = :Set1_3)))

So the scales argument takes a named set of scale settings, here a colour palette, and the naming follows the Makie convention of capitalised channel names. That is the point at which the abstraction begins to leak, and it is also the point at which you get access to everything Makie can do.

Where the analysis comes from, and what is transcribed

The acknowledgements section names the statistical packages the analysis relies on: StatsBase.jl, Loess.jl, KernelDensity.jl and GLM.jl, and it notes that some of their documentation is transcribed here.

That last clause matters for anyone using the package for anything beyond a scatter plot. The layers are not just drawing primitives, they are statistical transformations. A linear layer is a regression, the loess machinery gives you smooth curves, the kernel density machinery gives you distributions, and GLM gives you generalised linear models.

So the algebra is doing two jobs at once, deciding the visual encoding and computing the statistics behind it. That is what makes the library short to write and what makes it different from a plotting API, where the statistics are your problem.

The transcription note is a practical warning too. If the documentation for a statistical transformation in the AlgebraOfGraphics manual is a copy of the upstream package's documentation, then the upstream package's documentation is where the caveats live, and it will move independently of this repository.

The repository is MIT licensed with the LICENSE file at the root, and it has a Journal of Open Source Software paper with a DOI, which is the usual marker of a package that wants to be cited rather than just used.

Citing it, and the package layout

The README asks that if you use AlgebraOfGraphics for a scientific publication you acknowledge and support the work by citing the JOSS paper, and it gives the citation in plain form.

Krumbiegel & Vertechi, (2026). AlgebraOfGraphics.jl: A Makie-powered algebraic grammar of graphics for Julia. Journal of Open Source Software, 11(123), 10894, https://doi.org/10.21105/joss.10894

The BibTeX entry is also available and there is a CITATION.bib file to download, plus a CITATION.cff for the newer citation format.

The repository layout tells you what kind of package this is. There is src/ for the package source, test/ for the tests, docs/ for the documentation with its own public assets, examples/ with a Project.toml and a gui.jl, ext/ for Julia package extensions, and tooling/ for the development tooling. The _readme/ directory holds the README fragments that get assembled into the main README, which is why the example code appears in fragments with images interleaved.

There is an AGENTS.md and a CLAUDE.md at the root, a CHANGELOG.md, a .codecov.yml, a .git-blame-ignore-revs file for the reformatting commits, and an assets/ directory for branding. The docs are published at aog.makie.org with separate stable and dev builds, and the project site is aog.makie.org too.

The release history shows a project in active development with a 0.x version. The listed releases are v0.13.2 from 2026-09-04, v0.13.1 from 2026-07-22 and v0.13.0 from 2026-06-25, and the last push to the repository was on 2026-09-04.

Where AlgebraOfGraphics is the wrong choice

Three cases argue against it.

The first is if you want one package that does everything. AlgebraOfGraphics is a layer over Makie, and when a figure needs something the algebraic specification does not express, you drop to Makie and the result is a Makie figure. That is a feature when you know Makie and a problem when you wanted a self-contained plotting dependency.

The second is if you are coming from ggplot2 expecting the same semantics. The vocabulary is deliberately algebraic, so `*` combines a specification with a mapping or a layer and `+` combines layers, and the layer names are things like linear() and visual(). A ggplot2 user will find the idea familiar and the syntax different, and the docs are a Julia package's docs rather than a port of the ggplot2 documentation.

The third is if your work is exploratory and quick rather than declarative. The specification style pays off when a figure is described once and re-described, and it costs you when you want to look at something and change it, because each change means rewriting an expression.

The alternative in the same direction is plain Makie, which is the same backend without the algebraic layer, or DataFrames.jl's or Gadfly's plotting. The difference in approach is that AlgebraOfGraphics owns the statistical transformations as well as the encoding, so a layer is a model and a plot rather than a set of points to draw, and the price is that you inherit the vocabulary and the abstraction cost. For a scientific workflow where the same analysis is redrawn with different encodings, the algebra is the better deal. For one-off plots, plain Makie is less ceremony.

Editorial conclusion

AlgebraOfGraphics fits a Julia analyst who wants to describe a plot declaratively and then adjust it with Makie when the default is not enough, since the two compose rather than compete. It does not fit a team that wants a single self-contained plotting package, because the output is a Makie figure and you need Makie to finish it. Add it alongside CairoMakie, build a specification with `data(penguins) * mapping(:bill_length_mm, :bill_depth_mm)`, and read the Makie documentation before you need to change an axis, since that is where the escape hatch lives.

Frequently asked questions

Official sources

1. License: MIT
2. MakieOrg/AlgebraOfGraphics.jl on GitHub
3. Project website
4. README
5. Releases