Powered by AppSignal & Oban Pro

Labeller functions: labellers

notebooks/labellers.livemd

Labeller functions: labellers

Mix.install([
  {:giggly, path: Path.join(__DIR__, "..")},
  {:kino, "~> 0.19"}
  ])

alias Giggly.Plot

mtcars = Giggly.Datasets.mtcars()

render = fn plot ->
  plot
  |> Giggly.to_svg()
  |> IO.iodata_to_binary()
  |> Kino.Image.new(:svg)
end

About this notebook

This notebook follows the examples on ggplot2's reference page for label_value(), which covers label_both(), label_context(), label_parsed() and label_wrap_gen() too, in the order the page gives them. Each example shows ggplot2's code first and then Giggly's. An example Giggly cannot draw yet keeps its ggplot2 code and names what it is waiting for, so the page is also a list of what remains.

Labeller functions write the labels in the strips of facet_grid() and facet_wrap(). label_value(), the default, shows each value alone; label_both() shows the column's name and the value; label_context() shows the value alone when the strips are for one column, and both when they are for several; label_parsed() reads the labels as R's plotmath expressions; and label_wrap_gen() makes a labeller that wraps long labels. Giggly's Giggly.Plot.facet_grid/2 and Giggly.Plot.facet_wrap/3 take their counterparts as the labeller: option, :value, :both, :context and :wrap, each with its options as a tuple, such as {:wrap, width: 10}; Giggly has no label_parsed() and none of R's plotmath expressions. A plot is described with Giggly.Plot and drawn with Giggly.to_svg/2, which returns an SVG document. The setup cell aliases Giggly.Plot, so the cells write Plot.new/2, and defines render, which draws a plot and shows it below the cell with Kino.Image. The data is Giggly.Datasets.mtcars/0, R's mtcars: 32 cars from the 1974 Motor Trend US magazine, which the setup cell binds to mtcars, R's name for it.

The default, values alone

The first line makes cyl2, used further down: cyl's values 4, 6 and 8 renamed alpha, beta and gamma.

mtcars$cyl2 <- factor(mtcars$cyl, labels = c("alpha", "beta", "gamma"))
p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()

# The default is label_value
p + facet_grid(. ~ cyl, labeller = label_value)

The cell makes cyl2 as the first line does, a factor of the names with Giggly.Factor.new/2, its levels in the order of cyl's values, and adds it to mtcars. ggplot2's . ~ cyl is cols: :cyl.

names = %{4 => "alpha", 6 => "beta", 8 => "gamma"}
cyl2 = Enum.map(mtcars[:cyl], fn cylinders -> names[round(cylinders)] end)
mtcars = Keyword.put(mtcars, :cyl2, Giggly.Factor.new(cyl2, levels: ["alpha", "beta", "gamma"]))

p =
  mtcars
  |> Plot.new(%{x: :wt, y: :mpg})
  |> Plot.geom_point()

p
|> Plot.facet_grid(cols: :cyl, labeller: :value)
|> render.()

Names and values

# Displaying both the values and the variables
p + facet_grid(. ~ cyl, labeller = label_both)

:both writes each strip as cyl: 4 rather than 4.

p
|> Plot.facet_grid(cols: :cyl, labeller: :both)
|> render.()

Labels that depend on context

Here the column strips are for two columns, vs and cyl, so they show names and values, and the row strips, for am alone, show values.

# Displaying only the values or both the values and variables
# depending on whether multiple factors are facetted over
p + facet_grid(am ~ vs+cyl, labeller = label_context)
p
|> Plot.facet_grid(rows: :am, cols: [:vs, :cyl], labeller: :context)
|> render.()

Plotmath labels

With label_parsed(), the labels alpha, beta and gamma are drawn as the Greek letters α, β and γ.

# Interpreting the labels as plotmath expressions
p + facet_grid(. ~ cyl2)
p + facet_grid(. ~ cyl2, labeller = label_parsed)

Giggly draws the first plot, whose strips show cyl2's labels as they are.

p
|> Plot.facet_grid(cols: :cyl2)
|> render.()

Not in Giggly yet: label_parsed() and R's plotmath expressions.

A labeller's own options

\(x) is R's short form of an anonymous function; this one calls label_both() with sep = "=", which writes each strip as cyl=4. Giggly gives a labeller its options as a tuple, {:both, sep: "="}.

# Include optional argument in label function
p + facet_grid(. ~ cyl, labeller = \(x) label_both(x, sep = "="))
p
|> Plot.facet_grid(cols: :cyl, labeller: {:both, sep: "="})
|> render.()