Powered by AppSignal & Oban Pro

Strip labels: labeller

notebooks/labeller.livemd

Strip labels: labeller

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

alias Giggly.Plot

mtcars = Giggly.Datasets.mtcars()
msleep = Giggly.Datasets.msleep()

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 labeller(), 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.

A labeller writes the labels in a facet's strips from the values of its columns. labeller() builds one from a labeller for each column, or one for all the rows' strips and one for all the columns', and a default for the rest; each may be a labeller function, a function on strings, or a lookup table of the labels to show in place of the values. The result goes to the labeller argument of facet_grid() or facet_wrap(). Giggly's Giggly.Plot.facet_grid/2 and Giggly.Plot.facet_wrap/3 take a labeller: option, and what labeller() builds is a keyword list there: columns: a labeller for each column it names, rows: and cols: one for each side, and default: one for the rest. A labeller is :value, :both, :context or :wrap, R's label_value(), label_both(), label_context() and label_wrap_gen(), a function handed each label, or a map of labels. 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; and Giggly.Datasets.msleep/0, ggplot2's msleep: the sleep of 83 mammals, which the setup cell binds to mtcars and msleep, R's names for them.

A labeller for each column

p1 <- ggplot(mtcars, aes(x = mpg, y = wt)) + geom_point()

# You can assign different labellers to variables:
p1 + facet_grid(
  vs + am ~ gear,
  labeller = labeller(vs = label_both, am = label_value)
)

Giggly gives the facet's rows as rows: and its columns as cols:, and the labellers of vs and am under columns:.

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

p1
|> Plot.facet_grid(
  rows: [:vs, :am],
  cols: :gear,
  labeller: [columns: [vs: :both, am: :value]]
)
|> render.()

A labeller for the rows and one for the columns

# Or whole margins:
p1 + facet_grid(
  vs + am ~ gear,
  labeller = labeller(.rows = label_both, .cols = label_value)
)
p1
|> Plot.facet_grid(
  rows: [:vs, :am],
  cols: :gear,
  labeller: [rows: :both, cols: :value]
)
|> render.()

A function on strings

capitalize() upper-cases the first letter of each label. The strips of the animals whose diet msleep lacks show NA, and a missing value is never handed to the function.

# You can supply functions operating on strings:
capitalize <- function(string) {
  substr(string, 1, 1) <- toupper(substr(string, 1, 1))
  string
}
p2 <- ggplot(msleep, aes(x = sleep_total, y = awake)) + geom_point()
p2 + facet_grid(vore ~ conservation, labeller = labeller(vore = capitalize))

Giggly's capitalize upper-cases the first letter and keeps the rest, as R's does; String.capitalize/1 would also lower-case the rest.

capitalize = fn string ->
  {first, rest} = String.split_at(string, 1)
  String.upcase(first) <> rest
end

p2 =
  msleep
  |> Plot.new(%{x: :sleep_total, y: :awake})
  |> Plot.geom_point()

p2
|> Plot.facet_grid(rows: :vore, cols: :conservation, labeller: [columns: [vore: capitalize]])
|> render.()

A lookup table

The named vector gives each conservation code its long form, and capitalize() labels the other strips. Giggly's lookup table is a map.

# Or use character vectors as lookup tables:
conservation_status <- c(
  cd = "Conservation Dependent",
  en = "Endangered",
  lc = "Least concern",
  nt = "Near Threatened",
  vu = "Vulnerable",
  domesticated = "Domesticated"
)
## Source: http://en.wikipedia.org/wiki/Wikipedia:Conservation_status

p2 + facet_grid(vore ~ conservation, labeller = labeller(
  .default = capitalize,
  conservation = conservation_status
))
conservation_status = %{
  "cd" => "Conservation Dependent",
  "en" => "Endangered",
  "lc" => "Least concern",
  "nt" => "Near Threatened",
  "vu" => "Vulnerable",
  "domesticated" => "Domesticated"
}

p2
|> Plot.facet_grid(
  rows: :vore,
  cols: :conservation,
  labeller: [default: capitalize, columns: [conservation: conservation_status]]
)
|> render.()

Wrapping long labels

# In the following example, we rename the levels to the long form,
# then apply a wrap labeller to the columns to prevent cropped text
idx <- match(msleep$conservation, names(conservation_status))
msleep$conservation2 <- conservation_status[idx]

p3 <- ggplot(msleep, aes(x = sleep_total, y = awake)) + geom_point()
p3 +
  facet_grid(vore ~ conservation2,
    labeller = labeller(conservation2 = label_wrap_gen(10))
  )

The first two lines give each animal its conservation status's long form, missing where its code is, as a new column conservation2; the cell does the same in Elixir, looking each code up in conservation_status. label_wrap_gen(10) is {:wrap, width: 10}, which breaks each label into lines shorter than 10 characters, between its words.

conservation2 =
  Enum.map(msleep[:conservation], fn code -> conservation_status[code] end)

msleep = Keyword.put(msleep, :conservation2, conservation2)

p3 =
  msleep
  |> Plot.new(%{x: :sleep_total, y: :awake})
  |> Plot.geom_point()

p3
|> Plot.facet_grid(
  rows: :vore,
  cols: :conservation2,
  labeller: [columns: [conservation2: {:wrap, width: 10}]]
)
|> render.()

One labeller for several plots

# labeller() is especially useful to act as a global labeller. You
# can set it up once and use it on a range of different plots with
# different facet specifications.

global_labeller <- labeller(
  vore = capitalize,
  conservation = conservation_status,
  conservation2 = label_wrap_gen(10),
  .default = label_both
)

p2 + facet_grid(vore ~ conservation, labeller = global_labeller)
p3 + facet_wrap(~conservation2, labeller = global_labeller)

A column the facet does not split on is passed over, so the one labeller serves both plots. Under default: :both the labels capitalize and the lookup give are written with their column's name, vore: Carni, while {:wrap, width: 10} writes its own, so conservation2's strips show the wrapped long forms alone.

global_labeller = [
  columns: [
    vore: capitalize,
    conservation: conservation_status,
    conservation2: {:wrap, width: 10}
  ],
  default: :both
]

p2
|> Plot.facet_grid(rows: :vore, cols: :conservation, labeller: global_labeller)
|> render.()
p3
|> Plot.facet_wrap(:conservation2, labeller: global_labeller)
|> render.()