Explicit aesthetics / scales

.github/workflows/ci.yml

@@ -1,7 +1,18 @@
 name: CI
 on:
-  - push
-  - pull_request
+  pull_request:
+    branches:
+      - master
+  push:
+    tags:
+      - '*'
+    branches:
+      - master
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}

NEWS.md

@@ -1,36 +1,64 @@
-# AlgebraOfGraphics.jl v0.6 Release Notes
+# Release Notes
 
-## Breaking Changes
+## v0.7
+
+### Breaking Changes
+
+- The `palette` keyword of `draw` linking palettes to keyword arguments was removed. Instead, palettes need to be passed to specific scales like `draw(..., scales(Color = (; palette = :Set1_3)))`
+- All recipes need to have the new function `aesthetic_mapping` defined for all sets of positional arguments that should be supported, as can be seen in `src/aesthetics.jl`. This breaks usage of all custom recipes. Additionally, not all Makie plots have been ported to the new system yet. If you encounter missing plots, or missing attributes of already ported plots, please open an issue.
+- All custom recipes that should be displayed in a legend, need to have `legend_elements(P, attributes, scale_args)` defined as can be seen in `src/guides/legend.jl`. AlgebraOfGraphics cannot use the same default mechanism as Makie, which can create a legend from an existing plot, because AlgebraOfGraphics needs to create the legend before the plot is instantiated.
+- Pregrouped data cannot be passed anymore to the plain `mapping(...)` without any `data(tabular)`. Instead, you should use `pregrouped(...)` which is a shortcut for `data(Pregrouped()) * mapping(...)`.
+- `Contour` and `Contourf` generally do not work anymore with `visual()`. Instead, the `contours()` and `filled_contours()` analyses should be used. `Contour` can still be used with categorical colors, but not with continuous ones.
+- All colormap properties for continuous color scales need to be passed via `scales` now, and not through `visual`. This is to have central control over the scale as it can be used by multiple `visual`s simultaneously.
+
+### New Features
+
+- Horizontal barplots, violins, errorbars, rangebars and other plot types that have two different orientations work correctly now. Axis labels switch accordingly when the orientation is changed.
+- Plotting functions whose positional arguments don't correspond to X, Y, Z work correctly now. For example, `HLines` (1 => Y) or `rangebars` (1 => X, 2 => Y, 3 => Y).
+- It is possible to add categories beyond those present in the data with the `categories` keyword within a scale's settings. It is also possible to reorder or otherwise transform the existing categories by passing a function to `categories`.
+- The supported attributes are not limited anymore to a specific set of names, for example, `strokecolor` can work the same as `color` did before, and the two can share a scale via their shared aesthetic type.
+- There can be multiple scales of the same aesthetic now. This allows to have separate legends for different plot types using the same aesthetics. Scale separation works by pairing a variable in `mapping` with a `scale(id_symbol)`.
+- Legend entries can be reordered using the `legend = (; order = ...)` option in `draw`. Specific scales can opt out of the legend by passing `legend = false` in `scales`.
+- Labels can now be anything that Makie supports, primarily `String`s, `LaTeXString`s or `rich` text.
+- Legend elements now usually reflect all attributes set in their corresponding `visual`.
+- Simple column vectors of data can now be passed directly to `mapping` without using `data` first. Additionally, scalar values are accepted as a shortcut for columns with the same repeated value.
+- Columns from outside a table source in `data` can now be passed to `mapping` by wrapping them in the `direct` function. Scalar values are accepted as a shortcut for columns with the same repeated value. For example, to create a label for columns `x` and `y` from a dataframe passed to `data`, one could now do `mapping(:x, :y, color = direct("label"))` without having to create a column full of `"label"` strings first.
+- The numbers at which categorical values are plotted on x and y axis can now be changed via `scales(X = (; palette = [1, 2, 4]))` or similar.
+- Continuous marker size scales can now be shown in the legend. Numerical values are proportional to area and not diameter now, which makes more sense with respect to human perception. The min and max marker size can be set using the `sizerange` property for the respective scale in `scales`.
+
+## v0.6
+
+### Breaking Changes
 
 - Default axis linking behavior has changed: now only axes corresponding to the same variable are linked. For consistency with `row`/`col`, `layout` will hide decorations of linked axes and span axis labels if appropriate.
 
-## New Features
+### New Features
 
 - Customizable axis linking behavior.
 - Customizable legend and colorbar position and look.
 - In v0.6.1, support `level` in `linear` analysis for confidence interval.
 - In v0.6.8, added `choropleth` recipe to supersede `geodata` for geographical data.
 - In v0.6.11, added `paginate` for pagination of large facet plots. 
 
-## Internal changes
+### Internal changes
 
 - In v0.6.1, replaced tuples and named tuples in `Layer` and `Entry` with dictionaries from [Dictionaries.jl](https://github.com/andyferris/Dictionaries.jl).
 - In v0.6.1, split internal `Entry` type into `ProcessedLayer` (to be used for analyses) and `Entry` (to be used for plotting).
 
-# AlgebraOfGraphics.jl v0.5 Release Notes
+## v0.5
 
-## Breaking Changes
+### Breaking Changes
 
 - `Axis(ae)` has been replaced by `ae.axis`.
 - `Legend(fg)` has been replaced by `legend!(fg)` and `colorbar!(fg)`.
 
-## New Features
+### New Features
 
 - `legend!` and `colorbar!` API allows for custom legend placement.
 
-# AlgebraOfGraphics.jl v0.4 Release Notes
+## v0.4
 
-## Breaking Changes
+### Breaking Changes
 
 - Removed deprecations for `style` and `spec` (now only `mapping` and `visual` are allowed).
 - Analyses now require parentheses (i.e. `linear()` instead of `linear`).

Project.toml

@@ -12,10 +12,12 @@ GLM = "38e38edf-8417-5370-95a0-9cbb8c7f171a"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
 GridLayoutBase = "3955a311-db13-416c-9275-1d80ed98e5e9"
+Isoband = "f1662d9f-8043-43de-a69a-05efc1cc6ff4"
 KernelDensity = "5ab0869b-81aa-558d-bb23-cbf5423bbe9b"
 Loess = "4345ca2d-374a-55d4-8d30-97f9976e7612"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 PlotUtils = "995b91a9-d308-5afd-9ec6-746e21dbc043"
+PolygonOps = "647866c9-e3ac-4575-94e7-e3d426903924"
 PooledArrays = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"
 PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 RelocatableFolders = "05181044-ff0b-4ac5-8273-598c1e38db00"
@@ -44,10 +46,13 @@ Tables = "1.4"
 julia = "1.6"
 
 [extras]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
+ImageInTerminal = "d8c32880-2388-543b-8c61-d9f865259254"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Shapefile = "8e980c4a-a4fe-5da2-b3a7-4b4b0353a2f4"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Random", "Shapefile", "Statistics", "Test"]
+test = ["Random", "Shapefile", "Statistics", "Test", "CairoMakie", "DelimitedFiles", "ImageInTerminal"]

docs/gallery/gallery/data manipulations/no_data.jl

@@ -0,0 +1,29 @@
+# ---
+# title: "Using mapping without tabular data"
+# cover: assets/no_data.png
+# description: "Passing columnar data directly to `mapping`."
+# author: "[Julius Krumbiegel](https://github.com/jkrumbiegel)"
+# ---
+
+# Sometimes it's easier to specify columnar data directly within `mapping`
+# rather than first storing it in some tabular `data` source and accessing it by
+# column name. Note that you can also use scalar values which will be treated
+# like columns with repeated elements. In the example below, we specify `color = "marker"`
+# instead of the more verbose `color = fill("marker", 3)`.
+
+using AlgebraOfGraphics, CairoMakie
+set_aog_theme!() #src
+
+x = 1:100
+y = sin.(range(0, 2pi, length = 100))
+
+plt = mapping(x, y, color = repeat(["high", "low"], inner = 50)) *
+    visual(Lines) +
+    mapping([20, 28, 51], color = "marker" => scale(:secondary)) *
+    visual(VLines, linestyle = :dash)
+
+fg = draw(plt, scales(secondary = (; palette = [:gray80])))
+
+# save cover image #src
+mkpath("assets") #src
+save("assets/no_data.png", fg) #src

docs/gallery/gallery/data manipulations/pre_grouped_data.jl

@@ -9,27 +9,27 @@ using AlgebraOfGraphics, CairoMakie
 set_aog_theme!() #src
 
 
-x = [rand(10) for i in 1:3]
-y = [rand(10) for i in 1:3]
-z = [rand(10) for i in 1:3]
+x = [rand(10) .+ i for i in 1:3]
+y = [rand(10) .+ i for i in 1:3]
+z = [rand(10) .+ i for i in 1:3]
 c = ["a", "b", "c"]
 
-m = mapping(x, y, color=c => (t -> "Type " * t ) => "Category")
+m = pregrouped(x, y, color=c => (t -> "Type " * t ) => "Category")
 draw(m)
 
 #
 
-m = mapping(x, (y, z) => (+) => "sum", color=c => (t -> "Type " * t ) => "Category")
+m = pregrouped(x, (y, z) => (+) => "sum", color=c => (t -> "Type " * t ) => "Category")
 draw(m)
 
 #
 
-m = mapping(x, [y z], color=dims(1) => renamer(["a", "b", "c"]))
+m = pregrouped(x, [y z], color=dims(1) => renamer(["a", "b", "c"])) * visual(Scatter)
 draw(m)
 
 #
 
-m = mapping(x, [y z], color=["1" "2"])
+m = pregrouped(x, [y z], color=["1" "2"])
 layers = visual(Scatter) + linear()
 fg = draw(m * layers)
 

docs/gallery/gallery/layout/faceting.jl

@@ -53,7 +53,7 @@ draw(plt, facet=(; linkxaxes=:none, linkyaxes=:none))
 
 # ## Facet wrap with specified layout for rows and cols
 
-draw(plt, palettes=(layout=[(1, 1), (1, 2), (2, 1), (2, 2), (3, 1)],))
+draw(plt, scales(Layout = (; palette = [(1, 1), (2, 1), (3, 1), (1, 2), (2, 2)])))
 
 # ## Adding traces to only some subplots
 

docs/gallery/gallery/scales/config.json

@@ -1,4 +1,4 @@
 {
     "description": "Some advanced keywords to tweak the plot",
-    "order": ["discrete_scales.jl", "continuous_scales.jl", "custom_scales.jl", "multiple_color_scales.jl", "prescaled_data.jl", "legend_merging.jl"]
+    "order": ["discrete_scales.jl", "continuous_scales.jl", "custom_scales.jl", "secondary_scales.jl", "multiple_color_scales.jl", "prescaled_data.jl", "legend_merging.jl"]
 }

docs/gallery/gallery/scales/custom_scales.jl

@@ -34,13 +34,13 @@ c=rand(Bool, length(x))
 d=rand(Bool, length(x))
 df = (; x, y, u, v, c, d)
 colors = [colorant"#E24A33", colorant"#348ABD"]
-heads = ['▲', '●']
+heads = ['◮', '◭']
 plt = data(df) *
     mapping(:x, :y, :u, :v) *
-    mapping(arrowhead=:c => nonnumeric) *
-    mapping(arrowcolor=:d => nonnumeric) *
-    visual(Arrows, arrowsize=10, lengthscale=0.3)
-draw(plt; palettes=(arrowcolor=colors, arrowhead=heads))
+    mapping(arrowhead = :c => nonnumeric) *
+    mapping(color = :d => nonnumeric) *
+    visual(Arrows, arrowsize=10, lengthscale=0.4, linewidth = 1)
+fg = draw(plt, scales(Marker = (; palette = heads), Color = (; palette = colors)))
 
 # To associate specific attribute values to specific data values, use pairs.
 # Missing keys will cycle over values that are not pairs.
@@ -50,8 +50,8 @@ y = rand(100)
 z = rand(["a", "b", "c", "d"], 100)
 df = (; x, y, z)
 plt = data(df) * mapping(:x, :y, color=:z)
-colors = ["a" => colorant"#E24A33", "c" => colorant"#348ABD", colorant"#988ED5", colorant"#777777"]
-draw(plt; palettes=(color=colors,))
+colors = ["a" => :tomato, "c" => :lime, colorant"#988ED5", colorant"#777777"]
+draw(plt, scales(Color = (; palette = colors)))
 
 # Categorical color gradients can also be passed to `palettes`.
 
@@ -61,7 +61,7 @@ z = rand(["a", "b", "c", "d", "e", "f", "g", "h"], 200)
 df = (; x, y, z)
 plt = data(df) * mapping(:x, :y, color=:z)
 colors = cgrad(:cividis, 8, categorical=true)
-fg = draw(plt; palettes=(color=colors,))
+draw(plt, scales(Color = (; palette = colors)))
 
 # save cover image #src
 mkpath("assets") #src

docs/gallery/gallery/scales/discrete_scales.jl

@@ -10,23 +10,48 @@ set_aog_theme!() #src
 
 # By default categorical ticks, as well as names from legend entries, are taken from the 
 # value of the variable converted to a string. Scales can be equipped with labels to
-# overwrite that
+# overwrite that. You can either use the `renamer` function to apply relabeling or reordering to
+# some column on the fly, or you use the `categories` keyword for the respective scale
+# in the `draw` call.
+#
+# !!! note
+#       The `categories` keyword (added in v0.7) also allows adding categories not present in the data.
 
 df = (x=rand(["a", "b", "c"], 100), y=rand(100))
 plt = data(df) * mapping(:x, :y) * visual(BoxPlot)
 draw(plt)
 
 #
 
-df = (x=rand(["a", "b", "c"], 100), y=rand(100))
+plt = data(df) * mapping(:x, :y) * visual(BoxPlot)
+draw(plt, scales(X = (;
+    categories = ["a" => "label1", "b" => "label2", "c" => "label3"]
+)))
+
+# The same operation can be done with `renamer` as well which modifies the input data
+
 plt = data(df) *
     mapping(
         :x => renamer("a" => "label1", "b" => "label2", "c" => "label3"),
         :y
     ) * visual(BoxPlot)
 draw(plt)
 
-# The order can also be changed by tweaking the scale
+# With `categories`, you can add further categories that might be missing from your data
+
+plt = data(df) * mapping(:x, :y) * visual(BoxPlot)
+draw(plt, scales(X = (;
+    categories = ["a", "missing", "b", "c"]
+)))
+
+# The order can also be changed:
+
+plt = data(df) * mapping(:x, :y) * visual(BoxPlot)
+draw(plt, scales(X = (;
+    categories = ["b" => "label b", "a" => "label a", "c" => "label c"]
+)))
+
+# Or with `renamer`:
 
 plt = data(df) *
     mapping(
@@ -35,6 +60,45 @@ plt = data(df) *
     ) * visual(BoxPlot)
 fg = draw(plt)
 
+# When categories come from different datasets, you can either apply the same `renamer` to multiple mappings,
+# or set the ordering at one place in `categories`:
+
+df1 = (; x = rand(["one", "two"], 100), y = randn(100))
+df2 = (; x = rand(["three", "four"], 50), y = randn(50))
+plt = (data(df1) + data(df2)) * mapping(:x, :y) * visual(BoxPlot)
+draw(plt)
+
+#
+
+draw(plt, scales(X = (;
+    categories = ["one", "two", "three", "four"]
+)))
+
+# You can also pass a function to `categories`, which has to return a vector with
+# (optionally labelled) categories in the desired order.
+# For example, strings are by default ordered alphabetically:
+
+df = (; name = ["Anna Coolidge", "Berta Bauer", "Charlie Archer"], age = [34, 79, 58])
+plt = data(df) * mapping(:name, :age) * visual(BarPlot)
+draw(plt)
+
+# Instead of specifying the order manually, we could use a function to order by last name:
+
+draw(plt, scales(X = (;
+    categories = cats -> sort(cats; by = name -> split(name)[2])
+)))
+
+# Or even combine this with a relabeling function that shortens the first name to the initial:
+
+function initialed(name)
+    a, b = split(name)
+    return name => "$(first(a)). $b"
+end
+
+draw(plt, scales(X = (;
+    categories = cats -> initialed.(sort(cats; by = name -> split(name)[2]))
+)))
+
 # save cover image #src
 mkpath("assets") #src
 save("assets/discrete_scales.png", fg) #src

docs/gallery/gallery/scales/multiple_color_scales.jl

@@ -8,8 +8,7 @@
 using AlgebraOfGraphics, CairoMakie
 set_aog_theme!() #src
 
-# Normally, a unique scale is associated to each given attribute. Color is an important
-# exception: continuous and discrete color scales can coexist in the same plot.
+# Continuous and discrete color scales can coexist in the same plot.
 # This should be used sparingly, as it can make the plot harder to interpret.
 
 x = range(-π, π, length=100)