Labels: labs

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 labs(), which covers xlab(), ylab(), ggtitle() and get_labs() 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.

labs() sets the text of a plot's labels: the title of each axis or legend, named by its aesthetic, and the plot's title, subtitle, caption and tag. xlab(), ylab() and ggtitle() are older shortcuts for some of them, and get_labs() returns the labels a plot ends up with. Giggly has Giggly.Plot.labs/2, which sets every one of these labels; unset, an axis is titled by the column mapped to it, or count for counted bars, a legend or colour bar by its column, and a plot has no title, subtitle, caption or tag. ggplot2 has superseded xlab(), ylab() and ggtitle() with labs(), so Giggly has labs/2 alone. It has no get_labs(). 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 in these examples 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.

Renaming a legend or an axis

p <- ggplot(mtcars, aes(mpg, wt, colour = cyl)) + geom_point()
p + labs(colour = "Cylinders")
p + labs(x = "New x label")

A label is named by the aesthetic it titles: colour titles the colour bar, which would otherwise be titled cyl, and x the x axis, otherwise mpg.

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

p
|> Plot.labs(colour: "Cylinders")
|> render.()

p
|> Plot.labs(x: "New x label")
|> render.()

Labels by column

A dictionary relabels by column rather than by aesthetic: a label that is a column's name, here mpg, wt or cyl, becomes that column's entry. The plot does not use disp, so its entry changes nothing.

# Set labels by variable name instead of aesthetic
p + labs(dictionary = c(
  disp = "Displacment", # Not in use
  cyl  = "Number of cylinders",
  mpg  = "Miles per gallon",
  wt   = "Weight (1000 lbs)"
))

Not in Giggly yet: labs()'s dictionary option.

A title and subtitle

# The plot title appears at the top-left, with the subtitle
# display in smaller text underneath it
p + labs(title = "New plot title")
p + labs(title = "New plot title", subtitle = "A subtitle")

p
|> Plot.labs(title: "New plot title")
|> render.()

p
|> Plot.labs(title: "New plot title", subtitle: "A subtitle")
|> render.()

A caption

# The caption appears in the bottom-right, and is often used for
# sources, notes or copyright
p + labs(caption = "(based on data from ...)")

p
|> Plot.labs(caption: "(based on data from ...)")
|> render.()

A tag

# The plot tag appears at the top-left, and is typically used
# for labelling a subplot with a letter.
p + labs(title = "title", tag = "A")

p
|> Plot.labs(title: "title", tag: "A")
|> render.()

Removing a label

# If you want to remove a label, set it to NULL.
p +
 labs(title = "title") +
 labs(title = NULL)

The second labs() removes the title the first one set. Giggly writes R's NULL as :none, which also takes away the room the title took.

p
|> Plot.labs(title: "title")
|> Plot.labs(title: :none)
|> render.()