AlgebraOfGraphics.AbstractAlgebraic
— TypeAbstractAlgebraic <: AbstractDrawable
Abstract type encoding objects that can be combined together using +
and *
.
AlgebraOfGraphics.AbstractDrawable
— TypeAbstractDrawable
Abstract type encoding objects that can be drawn via AlgebraOfGraphics.draw
.
AlgebraOfGraphics.AxisEntries
— TypeAxisEntries(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
.
AlgebraOfGraphics.Entry
— TypeEntry(plottype::PlotType, positional::Arguments, named::NamedArguments)
Define plottype as well as positional and named arguments for a single plot.
AlgebraOfGraphics.Layer
— TypeLayer(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.
AlgebraOfGraphics.Layers
— TypeLayers(layers::Vector{Layer})
Algebraic object encoding a list of AlgebraOfGraphics.Layer
objects. Layers
objects can be added or multiplied, yielding a novel Layers
object.
AlgebraOfGraphics.ProcessedLayer
— MethodProcessedLayer(layer::Layer)
Output of processing a layer
. A ProcessedLayer
encodes
- plot type,
- grouping arguments,
- positional and named arguments for the plot,
- labeling information,
- visual attributes.
AlgebraOfGraphics.ProcessedLayers
— TypeProcessedLayers(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.
AlgebraOfGraphics.aog_theme
— Methodaog_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!
.
AlgebraOfGraphics.choropleth
— Methodchoropleth(geometries; transformation, attributes...)
Choropleth map, where regions are defined by geometries
. Use transformation
to transform coordinates (see Proj.jl for more information).
The transformation
keyword argument is experimental and could be deprecated (even in a non-breaking release) in favor of a different syntax.
Attributes
Available attributes and their defaults for MakieCore.Plot{AlgebraOfGraphics.choropleth}
are:
alpha 1.0
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
strokecolor :black
strokecolormap :viridis
strokewidth 0
transparency false
visible true
AlgebraOfGraphics.colorbar!
— Methodcolorbar!(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
.
AlgebraOfGraphics.compute_attributes
— Methodcompute_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
(implementingalpha
transparency), - customize behavior of bar
width
(default to one unit when not specified), - set correct
colorrange
.
Return computed attributes.
AlgebraOfGraphics.contours
— Methodcontours(; 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.
AlgebraOfGraphics.data
— Methoddata(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(...)
AlgebraOfGraphics.datetimeticks
— Methoddatetimeticks(datetimes::AbstractVector{<:TimeType}, labels::AbstractVector{<:AbstractString})
Generate ticks matching datetimes
to the corresponding labels
. The result can be passed to xticks
, yticks
, or zticks
.
AlgebraOfGraphics.datetimeticks
— Methoddatetimeticks(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
.
AlgebraOfGraphics.density
— Methoddensity(; 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
).
AlgebraOfGraphics.direct
— Methoddirect(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.
AlgebraOfGraphics.draw
— Functiondraw(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. For finer control, use draw!
, legend!
, and colorbar!
independently.
AlgebraOfGraphics.draw!
— Functiondraw!(fig, d::AbstractDrawable, scales::Scales = scales(); [axis, facet, legend, colorbar])
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
, facet
, legend
or colorbar
keywords.
AlgebraOfGraphics.draw
— Methoddraw(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)
.
AlgebraOfGraphics.draw
— Methoddraw(p::PaginatedLayers; kws...)
Draw each element of PaginatedLayers
p
and return a Vector{FigureGrid}
. Keywords kws
are passed to the underlying draw
calls.
AlgebraOfGraphics.expectation
— Methodexpectation()
Compute the expected value of the last argument conditioned on the preceding ones.
AlgebraOfGraphics.filled_contours
— Methodfilled_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.
AlgebraOfGraphics.frequency
— Methodfrequency()
Compute a frequency table of the arguments.
AlgebraOfGraphics.histogram
— Methodhistogram(; 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
).
Normalizations are computed withing groups. For example, in the case of normalization=:pdf
, sum of weights within each group will be equal to 1
.
AlgebraOfGraphics.legend!
— Methodlegend!(figpos, grid; kwargs...)
Compute legend for grid
(which should be the output of draw!
) and draw it in position figpos
. Attributes allowed in kwargs
are the same as MakieLayout.Legend
.
AlgebraOfGraphics.linear
— Methodlinear(; 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
).
AlgebraOfGraphics.linesfill
— Methodlinesfill(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()
AlgebraOfGraphics.mapping
— Methodmapping(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
)
AlgebraOfGraphics.nonnumeric
— Methodnonnumeric(x)
Transform x
into a non numeric type that is printed and sorted in the same way.
AlgebraOfGraphics.paginate
— Methodpaginate(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
AlgebraOfGraphics.plottypes_attributes
— Methodplottypes_attributes(entries)
Return plottypes and relative attributes, as two vectors of the same length, for the given entries
.
AlgebraOfGraphics.pregrouped
— Methodpregrouped(positional...; named...)
Equivalent to data(Pregrouped()) * mapping(positional...; named...)
. Refer to mapping
for more information.
AlgebraOfGraphics.renamer
— Methodrenamer(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 Pair
s, 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
AlgebraOfGraphics.scale
— Methodscale(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.
AlgebraOfGraphics.scales
— Methodscales(; 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 Symbol
s as keys (such as NamedTuple
s).
AlgebraOfGraphics.scientific_eltype
— Methodscientific_eltype(v)
Determine whether v
should be treated as a continuous, geometrical, or categorical array.
AlgebraOfGraphics.scientific_type
— Methodscientific_type(T::Type)
Determine whether T
represents a continuous, geometrical, or categorical variable.
AlgebraOfGraphics.set_aog_theme!
— Methodset_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",)
)
AlgebraOfGraphics.smooth
— Methodsmooth(; 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
AlgebraOfGraphics.sorter
— Methodsorter(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.
AlgebraOfGraphics.verbatim
— Methodverbatim(x)
Signal that x
should not be rescaled, but used in the plot as is.
AlgebraOfGraphics.visual
— Functionvisual(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.