AbstractAlgebraic  <: AbstractDrawable

Abstract type encoding objects that can be combined together using + and *.

AbstractDrawable

Abstract type encoding objects that can be drawn via AlgebraOfGraphics.draw.

AxisEntries(axis::Union{Axis, Nothing}, entries::Vector{Entry}, categoricalscales, continuousscales)

Define all ingredients to make plots on an axis. Each categorical scale should be a CategoricalScale, and each continuous scale should be a ContinuousScale.

Entry(plottype::PlotType, positional::Arguments, named::NamedArguments)

Define plottype as well as positional and named arguments for a single plot.

Layer(transformation, data, positional::AbstractVector, named::AbstractDictionary)

Algebraic object encoding a single layer of a visualization. It is composed of a dataset, positional and named arguments, as well as a transformation to be applied to those. Layer objects can be multiplied, yielding a novel Layer object, or added, yielding a AlgebraOfGraphics.Layers object.

Layers(layers::Vector{Layer})

Algebraic object encoding a list of AlgebraOfGraphics.Layer objects. Layers objects can be added or multiplied, yielding a novel Layers object.

ProcessedLayer(l::Layer)

Process a Layer and return the resulting ProcessedLayer.

Note that this method should not be used anymore as processing a Layer can now potentially return multiple ProcessedLayer objects. Therefore, you should use the plural form ProcessedLayers(layer).

ProcessedLayers(layers::Vector{ProcessedLayer})

Object encoding a list of AlgebraOfGraphics.ProcessedLayer objects. ProcessedLayers objects are the output of the processing pipeline and can be drawn without further processing.

ProcessedLayers(layer::Layer)

Output of processing a layer. Each ProcessedLayer encodes

• plot type,
• grouping arguments,
• positional and named arguments for the plot,
• labeling information,
• visual attributes.

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

choropleth(geometries; transformation, attributes...)

Choropleth map, where regions are defined by geometries. Use transformation to transform coordinates (see Proj.jl for more information).

Attributes

Available attributes and their defaults for MakieCore.Plot{AlgebraOfGraphics.choropleth} are:

  alpha               1.0
  clip_planes         MakieCore.Automatic()
  color               RGBA{Float32}(0.0f0,0.0f0,0.0f0,0.6f0)
  colormap            :viridis
  colorrange          MakieCore.Automatic()
  colorscale          identity
  cycle               [:color => :patchcolor]
  depth_shift         0.0f0
  highclip            MakieCore.Automatic()
  inspectable         true
  inspector_clear     MakieCore.Automatic()
  inspector_hover     MakieCore.Automatic()
  inspector_label     MakieCore.Automatic()
  joinstyle           :miter
  linecap             :butt
  linestyle           "nothing"
  lowclip             MakieCore.Automatic()
  miter_limit         1.0471975511965976
  nan_color           :transparent
  overdraw            false
  shading             MakieCore.NoShading
  space               :data
  ssao                false
  stroke_depth_shift  -1.0f-5
  strokecolor         :black
  strokecolormap      :viridis
  strokewidth         0
  transparency        false
  visible             true

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.

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.

contours(; levels=5, kwargs...)

Create contour lines over the grid spanned over x and y by args 1 and 2 in the mapping, with height values z passed via arg 3.

You can pass the number of levels as an integer or a vector of levels. The levels are calculated across the whole z data if they are specified as an integer.

Note that visual(Contour) only works in a limited way with AlgebraOfGraphics since version 0.7, because the internal calculations it does are not compatible with the scale system. With visual(Contour), you can only have categorically-colored contours (for example to visualize contours of multiple categories). Alternatively, if you set the colormap attribute, you can get continuously-colored contours but the levels will not be known to AlgebraOfGraphics, so they won't be synchronized across facets and there will not be a colorbar.

All other keyword arguments are forwarded as attributes to the underlying Contour plot.

data(table)

Create a Layer with its data field set to a table-like object.

There are no type restrictions on this object, as long as it respects the Tables interface. In particular, any one of these formats should work out of the box.

To create a fully specified layer, the layer created with data needs to be multiplied with the output of mapping.

spec = data(...) * mapping(...)

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.

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.

density(; datalimits=automatic, kernel=automatic, bandwidth=automatic, npoints=200)

Fit a kernel density estimation of data.

Here, datalimits specifies the range for which the density should be calculated (it defaults to the extrema of the whole data). The keyword argument datalimits can be a tuple of two values, e.g. datalimits=(0, 10), or a function to be applied group by group, e.g. datalimits=extrema. The keyword arguments kernel and bandwidth are forwarded to KernelDensity.kde. npoints is the number of points used by Makie to draw the line

Weighted data is supported via the keyword weights (passed to mapping).

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.

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.

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.

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

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

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

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

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

expectation()

Compute the expected value of the last argument conditioned on the preceding ones.

filled_contours(; bands=automatic, levels=automatic)

Create filled contours over the grid spanned over x and y by args 1 and 2 in the mapping, with height values z passed via arg 3.

You can pass either the number of bands to bands or pass a vector of levels (the boundaries of the bands) to levels, but not both. The number of bands when levels is passed is length(levels) - 1. The levels are calculated across the whole z data if the number of bands is specified. If neither levels nor bands are specified, the default is bands = 10.

Note that visual(Contourf) does not work with AlgebraOfGraphics since version 0.7, because the internal binning it does is not compatible with the scale system.

frequency()

Compute a frequency table of the arguments.

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

histogram(; bins=automatic, datalimits=automatic, closed=:left, normalization=:none)

Compute a histogram.

The attribute bins can be an Integer, an AbstractVector (in particular, a range), or a Tuple of either integers or abstract vectors (useful for 2- or 3-dimensional histograms). When bins is an Integer, it denotes the approximate number of equal-width intervals used to compute the histogram. In that case, the range covered by the intervals is defined by datalimits (it defaults to the extrema of the whole data). The keyword argument datalimits can be a tuple of two values, e.g. datalimits=(0, 10), or a function to be applied group by group, e.g. datalimits=extrema. When bins is an AbstractVector, it denotes the intervals directly.

closed determines whether the the intervals are closed to the left or to the right.

The histogram can be normalized by setting normalization. Possible values are:

• :pdf: Normalize by sum of weights and bin sizes. Resulting histogram has norm 1 and represents a PDF.
• :density: Normalize by bin sizes only. Resulting histogram represents count density of input and does not have norm 1.
• :probability: Normalize by sum of weights only. Resulting histogram represents the fraction of probability mass for each bin and does not have norm 1.
• :none: Do not normalize.

Weighted data is supported via the keyword weights (passed to mapping).

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

linear(; interval=automatic, level=0.95, dropcollinear=false, npoints=200)

Compute a linear fit of y ~ 1 + x. An optional named mapping weights determines the weights. Use interval to specify what type of interval the shaded band should represent, for a given coverage level (the default 0.95 equates alpha = 0.05). Valid values of interval are :confidence, to delimit the uncertainty of the predicted relationship, and :prediction, to delimit estimated bounds for new data points. Use interval = nothing to only compute the line fit, without any uncertainty estimate. By default, this analysis errors on singular (collinear) data. To avoid that, it is possible to set dropcollinear=true. npoints is the number of points used by Makie to draw the shaded band.

Weighted data is supported via the keyword weights (passed to mapping).

linesfill(xs, ys; lower, upper, attributes...)

Line plot with a shaded area between lower and upper. If lower and upper are not given, shaded area is between 0 and ys.

Attributes

Available attributes and their defaults for MakieCore.Plot{AlgebraOfGraphics.linesfill} are:

  color       :black
  colormap    :viridis
  colorrange  MakieCore.Automatic()
  fillalpha   0.15
  linestyle   "nothing"
  linewidth   1.5
  lower       MakieCore.Automatic()
  upper       MakieCore.Automatic()

mapping(positional...; named...)

Create a Layer with positional and named selectors. These selectors will be translated into input data for the Makie plotting function or AlgebraOfGraphics analysis that is chosen to visualize the Layer.

A Layer created with mapping does not have a data source by default, you can add one by multiplying with the output of the data function.

The positional and named selectors of mapping are converted to actual input data for the plotting function that will be selected via visual. The translation from selector to data differs according to the data source.

Tabular data

When a mapping is combined with a data(tabular) where tabular is some Tables.jl-compatible object, each argument will be interpreted as a column selector. Additionally, it's allowed to specify columns outside of the dataset directly by wrapping the values in direct. The values can either be vectors that have to match the number of rows from the tabular data, or scalars that will be expanded as if they were a column filled with the same value.

mapping(
    :x,                        # column named "x"
    "a column";                # column named "a column"
    color = 1,                 # first column
    marker = direct("abc"),    # a new column filled with the string "abc"
    linestyle = direct(1:3),   # a new column, length must match the table
)

nothing

If no data is set, each entry of mapping should be an AbstractVector that specifies a column of data directly. Scalars like strings for example will be expanded as if they were a column filled with the same value. This is useful when a legend should be shown, but there's only one group.

mapping(
    1:3,               # a column with values 1 to 3
    [4, 5, 6],         # a column with values 4 to 6 
    color = "group 1", # a column with repeated value "group 1"         
)

Pregrouped

With data(Pregrouped()) * mapping(...) or the shortcut pregrouped(...), each element in mapping specifies input data directly, like with nothing. However, in this mode, data should be passed in pregrouped. Categorical variables should come as a vector of categories, while numerical variables should come as a vector of vectors of values, with as many inner vectors as there are groups in the categorical variables.

pregrouped(
    [[1, 2, 3], [4, 5]], # two grouped vectors, of length 3 and 2
    color = ["A", "B"]   # a vector with two categorical group values
)

nonnumeric(x)

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

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

Paginate l, the Layer or Layers object created by an AlgebraOfGraphics spec, to create a PaginatedLayers object. This contains a vector of layers where each layer operates on a subset of the input data.

The PaginatedLayers 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 = 9)
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

plottypes_attributes(entries)

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

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

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

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)

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

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.

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

scientific_eltype(v)

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

scientific_type(T::Type)

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

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",)
       )

smooth(; span=0.75, degree=2, npoints=200)

Fit a loess model. span is the degree of smoothing, typically in [0,1]. Smaller values result in smaller local context in fitting. degree is the polynomial degree used in the loess model. npoints is the number of points used by Makie to draw the line

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.

verbatim(x)

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

visual(plottype; attributes...)

Create a Layer that will cause a plot spec multiplied with it to be visualized with plot type plottype, together with optional attributes.

The available plotting functions are documented here. Refer to plotting functions using upper CamelCase for visual's first argument (e.g. visual(Scatter), visual(BarPlot)). See the documentation of each plotting function to discover the available attributes. These attributes can be passed as additional keyword arguments to visual, or as part of the mapping you define.

The visual function can in principle be used for any plotting function that is defined using the @recipe macro from Makie. AlgebraOfGraphics just needs method definitions for aesthetic_mapping, which define what arguments of the plotting function map to which visual aesthetics. And for legend support, legend_elements must be overloaded for custom recipes as well, as Makie's default legend mechanism relies on instantiated plot objects, while AlgebraOfGraphics must go by the type and attributes alone.

Depending on its aesthetic_mapping, a plot type and its attributes may change certain semantics of a given data(...) * mapping(...) spec. For example, visual(BarPlot) will show mapping 1 on the x axis and 2 on the y axis, while visual(BarPlot, direction = :x) shows mapping 1 on y and 2 on x.