Reference Sheet

Key Points

• To use AlgebraOfGraphics.jl (AoG.jl), it is necessary to load a Makie.jl backend, with CairoMakie.jl being the one that most users will likely want to use.
• A plot in AoG.jl is constructed by combining three layers: data, mapping, and visual.
• The draw function is used to display a plot.
• You can save a plot using the save function, which supports creating images in PNG, SVG and PDF formats when CairoMakie.jl is being used. The function is called as save(<filename>, <result from draw>), where the file format is specified as part of the file name (e.g. name.png or name.svg).
• The save function allows customizing the figure's resolution through the px_per_unit and pt_per_unit keyword arguments. px_per_unit should be used when creating PNG files, while pt_per_unit should be used for SVG files.
• The plot navigator in VS Code (in JuliaHub) allows users to preview and save the plots generated by a draw call.
• The mapping function enables the incorporation of additional variables into a plot through styling elements such as color or marker shape.
• When dealing with a categorical variable that uses numbers for encoding in mapping's keyword arguments (color, marker, etc.), the nonnumeric function should be used to instruct AoG.jl to interpret it as a categorical variable; otherwise, it will treat it as a continuous variable or throw an error.
• Subplots can be created from a categorical variable (faceting) using the keyword arguments col, row, and layout within a mapping call.
• AoG.jl supports various types of plots (geometries), which can be found in Makie.jl's documentation.
• AoG.jl provides built-in functions that reduce the need for data wrangling or additional operations to generate commonly used plots. Examples include histogram, used to create histograms, and linear, used to perform a linear regression and plot the results.
• Some of the built-in function names collide with those exported by Pumas and Makie.jl (e.g. linear is also exported by Pumas). When that happens, you must qualify the function as AlgebraOfGraphics.<function name> (e.g. AlgebraOfGraphics.linear()).
• The + operator can be used to superimpose layers in plots.
• Both * and + adhere to the distributive law, enabling the creation of complex plots with a concise syntax. For instance, you can define multiple visuals for the same data and mapping with data_layer * mapping_layer * (visual1 + visual2 + visual3) instead of defining the three plots separately and then adding them together.
• By default, AoG.jl uses the column names from the dataset as axis labels, but users can customize them within the mapping call using the Pair syntax (e.g., :column_name => "display name"). The same customization can be applied for legend and faceting titles.
• Axis customization options can be passed through the axis keyword argument of draw. axis can take any of the customization options for the Axis object of Makie.jl as a NamedTuple (e.g., axis = (; kwarg1=val1, kwarg2=val2, ...)).
• Customization options for Figure can also be specified through a NamedTuple and the figure keyword argument from draw. Legends can be customized using the legend keyword argument.
• Users can specify a custom color palette for plots using the palettes keyword argument in the draw function.
• Specific customization options for a particular geometry can be applied inside a visual call by passing supported keyword arguments for that geometry (e.g., visual(Lines; linestyle=:dash, color=:red)). While some keyword arguments like color are supported by many geometries, others are specific to certain types of plots, such as show_notch for box plots.
• The renamer function allows users to customize the display values used to encode a categorical variable. When using renamer, nonnumeric is not needed.

Summary of Basic Commands

Action	Command	Observations
Create a data layer	data	Used to specify the dataset that will be used to generate the plot. Usually used as data(<DataFrame>)
Create a mapping layer	mapping	Determines how the data will be used in the plot
Create a visual layer	visual	Determines the type of plot that will be created
Combine several AoG.jl layers	*	Layers are combined by "multiplying" them (e.g., plt = data_layer * mapping_layer * visual_layer)
Display an AoG.jl plot	draw	draw can also contain many important customization options, such as figure and axis
Save a plot	save(<filename>, <result from draw>)	The filename must contain an appropriate file format, such as PNG, SVG or PDF when using CairoMakie.jl. You can also customize the image resolution using the px_per_unit (for PNG) and pt_per_unit (for SVG) keyword arguments
Avoid that a categorical variable encoded with numbers will be interpreted as a continuous variable	nonnumeric	Used inside of a mapping call with Pair syntax (e.g., kwarg = :column_name => nonnumeric)
Apply faceting by columns	col	Used as a keyword argument inside of a mapping call
Apply faceting by rows	row	Used as a keyword argument inside of a mapping call
Create a grid of subplots	layout	Used as a keyword argument inside of a mapping call
Specify a geometry for a plot	visual(<geometry>)	Makie.jl supports an extensive list of geometries, which can be found in their documentation
Superimpose layers	+	Used in the same way as when adding numbers (e.g., plt = plt1 + plt2)
Customize the display name for axis labels and legend and faceting titles	:column_name => "display name"	Used inside of a mapping call
Use a custom color palette	palettes = (; color=[<list of colors>])	You can use one of Julia's named colors or specify them in a variety of formats such as RGB and Hex codes
Change a categorical variable's encoding values (just for display)	renamer	renamer can receive a series of Pairs specifying the dataset encoding value and the desired display name (e.g., renamer(:val1 => "display value 1", :val2 => "display value 2"))
Add customization options specific to a geometry	visual(<geometry>; kwargs)	The accepted values for kwargs will depend on the type of plot that is being customized

Comparison between ggplot2 and AoG.jl

action	ggplot2	AoG.jl
Input data	ggplot(df)	data(df)
Map aesthetics	aes(...)	mapping(...)
Add geometries	geom_*(...)	visual(...)
Combine layers	+	*
Facetting	facet_[wrap\|grid](~ column)	mapping(...; [row\|col\|layout]=:column)
Customize scales	scale_*_manual()	renamer(...)
Themes	theme_*(...)	set_theme!(theme_*()); draw(plt)
Customize axes labels	[x\|y]lab("...")	draw(plt, axis=(; [x\|y]label="..."))
Customize color	scale_[fill\|color]_*(...)	draw(plt, palettes=(; color=...)) or visual(..., colormap=...")
Save plot	ggsave("file.[png\|svg]")	save("file.[png\|svg]", draw(plt))
Frequency	geom_bar() or stat_count()	frequency()
Histogram	geom_histogram or stat_bin()	histogram()
Density	geom_density or stat_density()	density()
Expectation/Mean	stat_summary(fun = "mean")	expectation()
Smooth trend	stat_smooth or geom_smooth()	(visual(...) + smooth())
Linear trend	stat_smooth(method = "lm") or geom_smooth(method = "lm")	(visual(...) + linear())
Log scale	scale_[x\|y]_log10()	draw(plt; axis=(; [x\|y]scale=log10))

Glossary

Makie.jl

A popular and powerful data visualization backend written in Julia. It enables the creation of a wide range of visualizations, including publication-quality vector graphics. We consider Makie.jl to be the present and future of plotting in Julia. Many tools, such as AlgebraOfGraphics.jl, are being developed with Makie.jl as their foundation.

Cairo and CairoMakie.jl

Cairo is an open-source graphics library used by Makie.jl via the CairoMakie.jl package. CairoMakie.jl is one of the interfaces supported by Makie.jl, alongside GLMakie.jl and WebGLMakie.jl. This interface allows the creation of static plots, primarily in formats like SVG and PNG. This is the interface that most Pumas users will want to use and the one you should choose if unsure.

OpenGL and GLMakie.jl

OpenGL, short for Open Graphics Library, is another interface supported by Makie.jl. It facilitates rendering visualizations on a standalone screen with support for interactivity such as clicking, dragging, and zooming. The GLMakie.jl package provides access to this interface. Keep in mind that plots generated with GLMakie.jl will not be displayed in VS Code or Pluto notebooks.

Grammar of Graphics (check Wilkinson, Leland. The grammar of graphics. Springer Berlin Heidelberg, 2012.)

The Grammar of Graphics is a versatile approach to data visualization, where plots are constructed using algebraic expressions. It allows for flexible creation of visuals by specifying data, aesthetics, and geometric elements as modular components.

AlgebraOfGraphics.jl (AoG.jl)

A plotting library built on top of Makie.jl that aims to provide a simple language for data visualization. Its syntax is inspired by the Grammar of Graphics concept and is similar to R's ggplot2.

Layer

The building blocks of an AoG.jl plot, which commonly includes three layers: data, mapping, and visual.

Faceting

A term used to refer to the act of splitting a plot into several subplots. AoG.jl supports faceting by columns, rows, and creating a grid of subplots automatically.

Geometries

The different types of plots that can be created with AoG.jl, such as scatter plots, bar plots, violin plots, etc.

Get in touch

If you have any suggestions or want to get in touch with our education team, please send an email to training@pumas.ai.

License

This content is licensed under Creative Commons Attribution-ShareAlike 4.0 International.