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...)

Compute colorbar for grid (which should be the output of draw!) and draw it in position figpos. Attributes allowed in kwargs are the same as MakieLayout.Colorbar.

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

Theming

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)

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.

Example:

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

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

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