document apply_palette

Project.toml

@@ -1,7 +1,7 @@
 name = "AlgebraOfGraphics"
 uuid = "cbdf2221-f076-402e-a563-3d30da359d67"
 authors = ["Pietro Vertechi <pietro.vertechi@veos.digital>"]
-version = "0.6.5"
+version = "0.7.0"
 
 [deps]
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"

docs/src/API/functions.md

@@ -32,6 +32,12 @@ AlgebraOfGraphics.aog_theme
 datetimeticks
 ```
 
+## Scale helpers
+
+```@docs
+AlgebraOfGraphics.apply_palette
+```
+
 ## Internal functions
 
 ```@docs

src/AlgebraOfGraphics.jl

@@ -7,7 +7,7 @@ using StructArrays: StructArrays, components, uniquesorted, GroupPerm, StructArr
 using GeometryBasics: AbstractGeometry, Polygon, MultiPolygon
 using GeoInterface: coordinates, geotype
 using Colors: RGB, RGBA, red, green, blue, Color
-using PlotUtils: optimize_datetime_ticks, AbstractColorList
+using PlotUtils: optimize_datetime_ticks
 using Makie
 using Makie: current_default_theme, to_value, automatic, Automatic, PlotFunc, ATTRIBUTES
 import Makie.MakieLayout: hidexdecorations!,

src/helpers.jl

@@ -6,6 +6,8 @@ const StringLike = Union{AbstractString, Symbol}
 to_string(s) = string(s)
 to_string(s::AbstractString) = s
 
+ispair(x) = x isa Pair
+
 struct Sorted{T}
     idx::UInt32
     value::T
@@ -80,7 +82,7 @@ Class Two
 ```
 """
 function renamer(arr::ArrayLike)
-    ispairs = all(x -> isa(x, Pair), arr)
+    ispairs = all(ispair, arr)
     k, v = ispairs ? (map(first, arr), map(last, arr)) : (nothing, arr)
     return Renamer(k, v)
 end

src/scales.jl

@@ -9,7 +9,7 @@ end
 
 function Cycler(p)
     defaults = vec(collect(Any, p))
-    pairs = splice!(defaults, findall(val -> val isa Pair, defaults))
+    pairs = splice!(defaults, findall(ispair, defaults))
     return Cycler(map(first, pairs), map(last, pairs), defaults, 0)
 end
 
@@ -24,10 +24,38 @@ function (c::Cycler)(u)
     end
 end
 
-# Use `Iterators.map` as `map` does not guarantee order
-apply_palette(p::Union{AbstractArray, AbstractColorList}, uv) = collect(Iterators.map(Cycler(p), uv))
+"""
+    apply_palette(p, uniquevalues)
+
+Apply the palette `p` to the sorted vector `uniquevalues` of unique values of a
+categorical variable.
+
+For each `value` in `uniquevalues`, look for a pair in `p` of the form `value => output`.
+If that exists, match `value` to `output`.
+Otherwise, match `value` to the first unusued non-pair entry in `p`.
+If all non-pair entries in `p` are used, cycle.
+
+Return matches for all entries in `uniquevalues`.
+
+# Examples
+
+```jldoctest
+julia> AlgebraOfGraphics.apply_palette([:red, :blue, :a => :green], [:a, :b, :c, :d])
+4-element Vector{Symbol}:
+ :green
+ :red
+ :blue
+ :red
+```
+
+!!! note
+    It is possible to overload `apply_palette(p::CustomType, uniquevalues)` to
+    implement custom palette behaviors that cannot be achieved with a list
+    of values and pairs.
+"""
+apply_palette(p, uv) = collect(Iterators.map(Cycler(p), uv))
+
 apply_palette(::Automatic, uv) = eachindex(uv)
-apply_palette(p, uv) = map(p, uv)
 
 # TODO: add more customizations?
 struct Wrap end