Functions

Drawing functions

AlgebraOfGraphics.draw Function

draw(d, scales::Scales = scales(); [axis, figure, facet, legend, colorbar])

Draw a AlgebraOfGraphics.AbstractDrawable object d. In practice, d will often be a AlgebraOfGraphics.Layer or AlgebraOfGraphics.Layers. Scale options can be passed as an optional second argument. The output can be customized by passing named tuples or dictionaries with settings via the axis, figure, facet, legend or colorbar keywords. Legend and colorbar are drawn automatically unless show = false is passed to the keyword arguments of either legend or colorbar.

For finer control, use draw!, legend!, and colorbar! independently.

Figure options

AlgebraOfGraphics accepts the following special keywords under the figure keyword, the remaining attributes are forwarded to Makie's Figure constructor. The title, subtitle and footnotes arguments accept objects of any kind that Makie's Label or text function can handle, such as rich text.

• title

• subtitle

• titlesize::Union{Nothing,Float64}

• subtitlesize::Union{Nothing,Float64}

• titlealign::Union{Nothing,Symbol}

• titlecolor

• subtitlecolor

• titlefont

• subtitlefont

• titlelineheight

• subtitlelineheight

• footnotes::Union{Nothing,Vector{Any}}

• footnotesize::Union{Nothing,Float64}

• footnotefont

• footnotecolor

• footnotealign

• footnotelineheight

source

draw(p::Pagination; kws...)

Draw each element of Pagination p and return a Vector{FigureGrid}. Keywords kws are passed to the underlying draw calls.

source

draw(p::Pagination, i::Int; kws...)

Draw the ith element of Pagination p and return a FigureGrid. Keywords kws are passed to the underlying draw call.

You can retrieve the number of elements using length(p).

source

AlgebraOfGraphics.draw! Function

draw!(fig, d::AbstractDrawable, scales::Scales = scales(); [axis, facet])

Draw a AlgebraOfGraphics.AbstractDrawable object d on fig. In practice, d will often be a AlgebraOfGraphics.Layer or AlgebraOfGraphics.Layers. fig can be a figure, a position in a layout, or an axis if d has no facet specification. The output can be customized by passing named tuples or dictionaries with settings via the axis or facet keywords.

source

AlgebraOfGraphics.colorbar! Function

colorbar!(figpos, grid; kwargs...)::Vector{Colorbar}

Compute zero or more colorbars for grid (which should be the output of draw!) and draw them in a nested GridLayout in position figpos. One colorbar will be drawn for each applicable scale. Attributes allowed in kwargs are the same as MakieLayout.Colorbar.

Note

Before AlgebraOfGraphics v0.10, this function returned Union{Nothing,Colorbar} because multiple colorbars in a single figure were not supported. The name of the function was kept singular colorbar to be less breaking.

source

AlgebraOfGraphics.legend! Function

legend!(figpos, grid; order = nothing, kwargs...)

Compute legend for grid (which should be the output of draw!) and draw it in position figpos. All kwargs are forwarded to Makie's Legend constructor.

The order of scales represented in the legend can be changed with the order keyword. By default, legend sections are ordered the same as they appear in the plot specification. Assuming three scales Color, MarkerSize and custom exist in a spec, you can pass a vector to reorder them like [:MarkerSize, :custom, :Color], or merge multiple entries together with a nested vector like [[:MarkerSize, :custom], :Color], or give merged sections a title with the pair syntax [[:MarkerSize, :custom] => "Merged group", :Color].

source

AlgebraOfGraphics.paginate Function

paginate(l, sc = scales(); layout=nothing, row=nothing, col=nothing)

Paginate l, the Layer or Layers object created by an AlgebraOfGraphics spec, to create a Pagination object.

Info

The pages are created by internally starting with one big facet plot first which includes all the input data, and then splitting it into pages. All scales are fit to the full data, not just the data that is visible on a given page, so a color legend, for example, will show all the categories and not just the ones that happen to be visible on the current page. This behavior changed with version 0.9 - before, each page had separately fit scales. The old behavior had the drawback that palettes were not guaranteed to be consistent across pages, for example, the same category could have different colors on two separate pages.

The Pagination object can be passed to draw which will return a Vector{FigureGrid} rather than a single figure.

The keywords that limit the number of subplots on each page are the same that are used to specify facets in mapping:

• layout: Maximum number of subplots in a wrapped linear layout.

• row: Maximum number of rows in a 2D layout.

• col: Maximum number of columns in a 2D layout.

Example

d = data((
    x = rand(1000),
    y = rand(1000),
    group1 = rand(string.('a':'i'), 1000),
    group2 = rand(string.('j':'r'), 1000),
))

layer_1 = d * mapping(:x, :y, layout = :group1) * visual(Scatter)
paginated_1 = paginate(layer_1, layout = 4)
figuregrids = draw(paginated_1)

layer_2 = d * mapping(:x, :y, row = :group1, col = :group2) * visual(Scatter)
paginated_2 = paginate(layer_2, row = 4, col = 3)
figuregrid = draw(paginated_2, 1) # draw only the first grid

source

AlgebraOfGraphics.scales Function

scales(; kwargs...)

Create a Scales object containing properties for aesthetic scales that can be passed to draw and draw!. Each keyword should be the name of a scale in the spec that is being drawn. That can either be a default one like Color, Marker or LineStyle, or a custom scale name defined in a mapping using the scale function.

The values attached to the keywords must be dict-like, with Symbols as keys (such as NamedTuples).

source

Mapping helpers

AlgebraOfGraphics.pregrouped Function

pregrouped(positional...; named...)

Equivalent to data(Pregrouped()) * mapping(positional...; named...). Refer to mapping for more information.

source

AlgebraOfGraphics.direct Function

direct(x)

Return DirectData(x) which marks x for direct use in a mapping that's used with a table-like data source. As a result, x will be used directly as data, without lookup in the table. If x is not an AbstractArray, it will be expanded like fill(x, n) where n is the number of rows in the data source.

source

AlgebraOfGraphics.renamer Function

renamer(arr::Union{AbstractArray, Tuple})

Utility to rename a categorical variable, as in renamer([value1 => label1, value2 => label2]). The keys of all pairs should be all the unique values of the categorical variable and the values should be the corresponding labels. The order of arr is respected in the legend.

Examples

julia> r = renamer(["class 1" => "Class One", "class 2" => "Class Two"])
AlgebraOfGraphics.Renamer{Vector{String}, Vector{String}}(["class 1", "class 2"], ["Class One", "Class Two"])

julia> println(r("class 1"))
Class One

Alternatively, a sequence of pair arguments may be passed.

julia> r = renamer("class 1" => "Class One", "class 2" => "Class Two")
AlgebraOfGraphics.Renamer{Tuple{String, String}, Tuple{String, String}}(("class 1", "class 2"), ("Class One", "Class Two"))

julia> println(r("class 1"))
Class One

If arr does not contain Pairs, elements of arr are assumed to be labels, and the unique values of the categorical variable are taken to be the indices of the array. This is particularly useful for dims mappings.

Examples

julia> r = renamer(["Class One", "Class Two"])
AlgebraOfGraphics.Renamer{Nothing, Vector{String}}(nothing, ["Class One", "Class Two"])

julia> println(r(2))
Class Two

source

AlgebraOfGraphics.sorter Function

sorter(ks)

Utility to reorder a categorical variable, as in sorter(["low", "medium", "high"]). A vararg method sorter("low", "medium", "high") is also supported. ks should include all the unique values of the categorical variable. The order of ks is respected in the legend.

source

AlgebraOfGraphics.nonnumeric Function

nonnumeric(x)

Transform x into a non numeric type that is printed and sorted in the same way.

source

AlgebraOfGraphics.verbatim Function

verbatim(x)

Signal that x should not be rescaled, but used in the plot as is.

source

AlgebraOfGraphics.scale Function

scale(id::Symbol)

Create a ScaleID object that can be used in a mapping to assign a custom id to the mapped variable. This variable will then not be merged into the default scale for its aesthetic type, but instead be handled separately, leading to a separate legend entry.

source

AlgebraOfGraphics.presorted Function

presorted(x)

Use within a pair expression in mapping to signal that a categorical column from the data source should be used in the original order and not automatically sorted.

Example:

# normally, categories would be sorted a, b, c but with `presorted`
# they stay in the order b, c, a

data((; some_column = ["b", "c", "a"])) * mapping(:some_column => presorted)

source

AlgebraOfGraphics.dims Function

dims(args...)

Create a DimsSelector object which can be used in mapping to refer to the dimensions of the layer's shape.

Example:

mapping([:x1, :x2, :x3], col = dims(1))

In the normal case where only single columns are referenced in mapping, the shape of the layer is (1,). If, for example, the first mapping entry, let's say for the X scale, is a column vector with three column selectors, like [:x1, :x2, :x3], the shape becomes (3,). If there's additionally a second mapping entry for the Y scale with four column selectors in a row vector, like [:y1 :y2 :y3 :y4], which by itself has shape (1, 4), the overall shape becomes (3, 4). This means that 3 x 4 = 12 combinations of columns will be plotted together as X and Y in the same axis.

The dims selector can now be used to create what can be thought of as a categorical scale with as many entries as the product of the sizes of the selected dimensions. For example, if we have our shape (3, 4) and add color = dims(1), the data will be colored in three different shades, one for each column selector in the first dimension (the three columns passed to the X scale). If we set color = dims(1, 2), there will be 12 different shades, one for each combination of X and Y. If we set color = dims(2), there will be four different shades, one for each Y column.

With wide input data, it often makes sense to put each column into its own facet, in order not to overcrowd the visual space. Therefore, a common setting in the mapping in such scenarios could be row = dims(1), col = dims(2), for example.

source

Theming & Palettes

AlgebraOfGraphics.set_aog_theme! Function

set_aog_theme!(; kwargs...)

Set the current theme to a predefined and opinionated theme, as defined by the unexported internal function AlgebraOfGraphics.aog_theme.

To tweak the predefined theme, use the function Makie.update_theme!. See the example below on how to change, e.g., default fontsize, title, and markersize.

For more information about setting themes, see the Theming section of the Makie.jl docs.

Examples

julia> using CairoMakie, AlgebraOfGraphics

julia> set_aog_theme!()                # Sets a prefedined theme

julia> update_theme!(                  # Tweaks the current theme
           fontsize=30,
           markersize=40,
           Axis=(title="MyDefaultTitle",)
       )

source

AlgebraOfGraphics.aog_theme Function

aog_theme(; fonts=[firasans("Medium"), firasans("Light")])

Return a NamedTuple of theme settings. Intended for internal use. The provided functionality is exposed to the user by the function set_aog_theme!.

source

AlgebraOfGraphics.from_continuous Function

from_continuous(x; relative = true)

Mark a colormap as continuous such that AlgebraOfGraphics will sample a categorical palette from start to end in n steps, and not by using the first n colors.

You could also use cgrad(colormap, n; categorical = true), however, this requires you to specify how many levels there are, which from_continuous detects automatically.

The relative option applies only when the datavalues of the palette are of type Bin. In this case, if relative = true, the continuous colormap is sampled at the relative midpoints of the bins, which means that neighboring bins that are smaller have more similar colors because their midpoints are closer together. If relative = false, the colormap is sampled evenly.

Example:

draw(scales(Color = (; palette = from_continuous(:viridis))))

source

AlgebraOfGraphics.wrapped Function

wrapped(; cols = automatic, rows = automatic, by_col = false)

Create an object that can be passed to the Layout scale palette which controls how many rows or columns are allowed at maximum in the wrapped layout. Only one of cols or rows may be set to an integer at the same time. If both are automatic, a squareish configuration is chosen. If by_col is to true, the layout is filled top to bottom first and then column by column.

source

AlgebraOfGraphics.clipped Function

clipped(palette; high = nothing, low = nothing)

Wrap a color palette such that, when used with a categorical scale made of ordered Bins, the end bins get the clip colors if they extend to plus/minus infinity. The inner bins then pick their colors from the wrapped palette.

source

Ticks helpers

AlgebraOfGraphics.datetimeticks Function

datetimeticks(datetimes::AbstractVector{<:TimeType}, labels::AbstractVector{<:AbstractString})

Generate ticks matching datetimes to the corresponding labels. The result can be passed to xticks, yticks, or zticks.

source

datetimeticks(f, datetimes::AbstractVector{<:TimeType})

Compute ticks for the given datetimes using a formatting function f. The result can be passed to xticks, yticks, or zticks.

source

Functions to be extended by other packages

AlgebraOfGraphics.mergeable Function

mergeable(plottype::Type{<: Plot}, primary::Dictionaries.AbstractDictionary)::Bool

Return whether the entries for the layer with plottype and primary should be merged. Merging means that all the data will be passed to a single plot call, instead of creating one plot object per scale.

Return true if they should be merged, and false if not (the default).

Extending packages should also extend this function on their own plot types if they deem it necessary. For example, beeswarm plots and violin plots need to be merged for correctness.

source

Utilities

AlgebraOfGraphics.show_aesthetics Function

show_aesthetics(T::Type{<:Makie.Plot})

Show the aesthetic mappings defined for Makie plot type T. The aesthetic mappings show which named attributes can be used in mapping with a given set of positional arguments and which aesthetic types the arguments are mapped to.

Note

This function uses reflection on the method table to determine the applicable methods and it might not catch all applicable methods in all circumstances.

Example

show_aesthetics(Lines)
show_aesthetics(Errorbars)

source

Internal functions

AlgebraOfGraphics.scientific_eltype Function

scientific_eltype(v)

Determine whether v should be treated as a continuous, geometrical, or categorical array.

source

AlgebraOfGraphics.scientific_type Function

scientific_type(T::Type)

Determine whether T represents a continuous, geometrical, or categorical variable.

source

AlgebraOfGraphics.plottypes_attributes Function

plottypes_attributes(entries)

Return plottypes and relative attributes, as two vectors of the same length, for the given entries.

source

AlgebraOfGraphics.compute_attributes Function

compute_attributes(pl::ProcessedLayer, categoricalscales, continuousscales_grid, continuousscales)

Process attributes of a ProcessedLayer. In particular,

• remove AlgebraOfGraphics-specific layout attributes,

• opt out of Makie cycling mechanism,

• customize behavior of color (implementing alpha transparency),

• customize behavior of bar width (default to one unit when not specified),

• set correct colorrange.

Return computed attributes.

source

Experimental functions

AlgebraOfGraphics.draw_to_spec Function

draw_to_spec(d, scales = scales(); [axis, facet])

Warning

This function is considered experimental. It can have breaking changes or be removed at any time.

Create a Makie SpecApi specification from a AlgebraOfGraphics.AbstractDrawable object d. Scale options can be passed as an optional second argument. The output can be customized by passing named tuples or dictionaries with settings via the axis or facet keywords.

Unlike draw, this function does not create or mutate a figure. Instead, it returns a Makie.SpecApi.GridLayout specification that can be used for reactive plotting with observables. This allows for creating plots that can be efficiently updated when the underlying data changes.

The returned specification includes axis configurations, plot specifications, facet layouts, legends, and colorbars as appropriate. It can be plotted using Makie.plot(spec) or used in more complex reactive plotting scenarios.

Example

using AlgebraOfGraphics, GLMakie

function random_frame()
    (
        x = randn(100),
        y = randn(100),
        color = randn(100),
        marker = rand(rand('A':'Z', 3), 100),
        layout = rand(rand(names(Base), 9), 100),
    )
end

df = Observable(random_frame())
specobs = lift(df) do df
    layer = data(df) * mapping(:x, :y, color = :color, marker = :marker, layout = :layout) *
        visual(Scatter)
    AlgebraOfGraphics.draw_to_spec(layer, scales(Color = (; colormap = rand(RGBf, 3))))
end
f = Figure()
plot(f[1, 1], specobs)
f

# later, the data observable can be updated

df[] = random_frame()

See also draw, draw!.

source